Usar tus-client en Java para transferir archivos eficientemente
El protocolo tus es un protocolo de código abierto que permite subidas de archivos reanudables por HTTP. Permite pausar y reanudar las subidas sin reiniciarlas, lo que resulta especialmente útil cuando trabajas con archivos grandes o con conexiones de red inestables. En este artículo, mostramos cómo implementar subidas de archivos reanudables en Java con la biblioteca tus-java-client.
Configurar tus-java-client
Incluye tus-java-client 0.5.1 en la configuración de compilación de tu proyecto. El ejemplo usa Java
9 o posterior para Map.of().
<dependency>
<groupId>io.tus.java.client</groupId>
<artifactId>tus-java-client</artifactId>
<version>0.5.1</version>
</dependency>
Uso básico
A continuación, se muestra un ejemplo completo que demuestra cómo configurar el cliente, preparar un archivo para subirlo y hacer seguimiento del progreso con reintentos automáticos mediante TusExecutor:
El servidor público de demostración del protocolo tus es solo para archivos de prueba no sensibles. Usa tu propio endpoint autenticado del protocolo tus para subidas privadas o de producción.
import io.tus.java.client.ProtocolException;
import io.tus.java.client.TusClient;
import io.tus.java.client.TusExecutor;
import io.tus.java.client.TusUpload;
import io.tus.java.client.TusUploader;
import io.tus.java.client.TusURLMemoryStore;
import java.io.File;
import java.io.IOException;
import java.net.URL;
import java.util.Map;
public class TusUploaderExample {
public static void main(String[] args) {
try {
// Create and configure the Tus client.
TusClient client = new TusClient();
client.setUploadCreationURL(new URL("https://tusd.tusdemo.net/files"));
// Enable resumable uploads with an in-memory store.
TusURLMemoryStore store = new TusURLMemoryStore();
client.enableResuming(store);
// Prepare the file for upload.
File file = new File("path/to/your/file.ext");
TusUpload upload = new TusUpload(file);
// Add metadata to the upload if required.
upload.setMetadata(Map.of(
"filename", file.getName(),
"filetype", "application/octet-stream"
));
// Use TusExecutor to handle automatic retries.
TusExecutor executor = new TusExecutor() {
@Override
protected void makeAttempt() throws ProtocolException, IOException {
// Resume or create a new upload.
TusUploader uploader = client.resumeOrCreateUpload(upload);
// Set the chunk size to 5 MB.
uploader.setChunkSize(5 * 1024 * 1024);
// Upload chunks with progress tracking.
do {
long totalBytes = upload.getSize();
long bytesUploaded = uploader.getOffset();
double progress = totalBytes == 0 ? 100 : (double) bytesUploaded / totalBytes * 100;
System.out.printf("Upload progress: %06.2f%% (%d/%d bytes)%n",
progress, bytesUploaded, totalBytes);
} while (uploader.uploadChunk() > -1);
uploader.finish();
System.out.println("Upload completed. URL: " + uploader.getUploadURL());
}
};
executor.makeAttempts();
} catch (ProtocolException e) {
System.err.println("Tus protocol error: " + e.getMessage());
e.printStackTrace();
} catch (IOException e) {
System.err.println("I/O error: " + e.getMessage());
e.printStackTrace();
} catch (Exception e) {
System.err.println("Unexpected error: " + e.getMessage());
e.printStackTrace();
}
}
}
Funciones avanzadas
El almacén de URL en memoria reanuda las transferencias solo mientras este proceso conserve el
almacén. Para reanudarlas después de reiniciar la aplicación, implementa un
TusURLStore persistente.
La biblioteca tus-java-client ofrece varias configuraciones avanzadas para casos de uso más especializados:
-
Compatibilidad con servidores personalizados: Si tu servidor no admite la extensión Creation, puedes reanudar las subidas usando una URL predefinida.
TusUploader uploader = client.beginOrResumeUploadFromURL(upload, new URL("https://tus.server.net/files/my_file")); -
Compatibilidad con proxy: Configura un proxy para enrutar tus solicitudes de subida.
client.setProxy(new java.net.Proxy(java.net.Proxy.Type.HTTP, new java.net.InetSocketAddress("proxy.example.com", 8080))); -
Configuración SSL personalizada: Extiende TusClient para aplicar tu propio SSLSocketFactory en conexiones seguras. Asegúrate de que tu SSLSocketFactory (por ejemplo, mySSLSocketFactory) esté configurado correctamente.
@Override public void prepareConnection(java.net.HttpURLConnection connection) { super.prepareConnection(connection); if (connection instanceof javax.net.ssl.HttpsURLConnection) { ((javax.net.ssl.HttpsURLConnection) connection).setSSLSocketFactory(mySSLSocketFactory); } }
Mejores prácticas
Ten en cuenta las siguientes mejores prácticas al integrar tus-java-client en tu aplicación:
- Define un tamaño de fragmento adecuado que equilibre el rendimiento y el uso de recursos.
- Monitorea el progreso de la subida y maneja las excepciones de forma controlada para garantizar la confiabilidad.
- Utiliza el mecanismo de reintento automático de TusExecutor para gestionar los problemas de red intermitentes.
- Revisa periódicamente cuál es la última versión de la biblioteca para beneficiarte de las correcciones de errores y las mejoras.
- Configura ajustes personalizados (por ejemplo, proxy o SSL) solo cuando sea necesario y pruébalos a fondo en tu entorno de despliegue.
Compatibilidad de plataformas
La biblioteca tus-java-client es compatible tanto con la plataforma estándar de Java como con Android. Para conocer las funciones y optimizaciones específicas de Android, consulta tus-android-client.
Para más detalles, visita la documentación de tus-java-client y el repositorio de GitHub.
En conclusión, implementar subidas de archivos reanudables en Java es sencillo con la biblioteca tus-java-client. Si sigues estas mejores prácticas, puedes crear un flujo de trabajo de transferencia de archivos robusto y eficiente.
Para obtener más información sobre soluciones avanzadas de transferencia de archivos, considera explorar la documentación de Transloadit.