tus-client in Java für effiziente Dateiübertragungen verwenden
Das tus-Protokoll ist ein Open-Source-Protokoll, das fortsetzbare Datei-Uploads über HTTP ermöglicht. Uploads lassen sich pausieren und fortsetzen, ohne neu zu starten, was besonders bei großen Dateien oder instabilen Netzwerkverbindungen nützlich ist. In diesem Beitrag zeigen wir, wie Sie fortsetzbare Datei-Uploads in Java mithilfe der tus-java-client-Bibliothek umsetzen.
tus-java-client einrichten
Binden Sie tus-java-client 0.5.1 in die Build-Konfiguration Ihres Projekts ein. Das Beispiel setzt
Java 9 oder neuer für Map.of() voraus.
<dependency>
<groupId>io.tus.java.client</groupId>
<artifactId>tus-java-client</artifactId>
<version>0.5.1</version>
</dependency>
Grundlegende Verwendung
Nachfolgend finden Sie ein vollständiges Beispiel, das zeigt, wie Sie den Client konfigurieren, eine Datei für den Upload vorbereiten und den Fortschritt mit automatischen Retries von TusExecutor verfolgen:
Der öffentliche tus-Demoserver ist ausschließlich für nicht sensible Testdateien gedacht. Verwenden Sie für private Uploads oder Uploads in der Produktion Ihren eigenen authentifizierten tus-Endpunkt.
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();
}
}
}
Erweiterte Funktionen
Der In-Memory-URL-Store setzt Übertragungen nur so lange fort, wie dieser Prozess den Store vorhält.
Um nach einem Neustart der Anwendung fortzusetzen, implementieren Sie eine persistente Variante von
TusURLStore.
Die tus-java-client-Bibliothek bietet mehrere erweiterte Konfigurationen für spezialisiertere Anwendungsfälle:
-
Unterstützung für eigene Server: Wenn Ihr Server die Creation-Erweiterung nicht unterstützt, können Sie Uploads mit einer vordefinierten URL fortsetzen.
TusUploader uploader = client.beginOrResumeUploadFromURL(upload, new URL("https://tus.server.net/files/my_file")); -
Proxy-Unterstützung: Konfigurieren Sie einen Proxy, um Ihre Upload-Anfragen zu leiten.
client.setProxy(new java.net.Proxy(java.net.Proxy.Type.HTTP, new java.net.InetSocketAddress("proxy.example.com", 8080))); -
Eigene SSL-Konfiguration: Erweitern Sie TusClient, um Ihre eigene SSLSocketFactory für sichere Verbindungen zu verwenden. Stellen Sie sicher, dass Ihre SSLSocketFactory (z. B. mySSLSocketFactory) korrekt konfiguriert ist.
@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); } }
Bewährte Verfahren
Beachten Sie die folgenden bewährten Verfahren, wenn Sie tus-java-client in Ihre Anwendung integrieren:
- Legen Sie eine passende Chunk-Größe fest, die Performance und Ressourcennutzung ausbalanciert.
- Überwachen Sie den Upload-Fortschritt und behandeln Sie Ausnahmen sauber, um Zuverlässigkeit sicherzustellen.
- Nutzen Sie den automatischen Retry-Mechanismus von TusExecutor, um zeitweilige Netzwerkprobleme abzufangen.
- Prüfen Sie regelmäßig, ob eine neuere Version der Bibliothek verfügbar ist, um von Fehlerbehebungen und Verbesserungen zu profitieren.
- Konfigurieren Sie eigene Einstellungen (z. B. Proxy oder SSL) nur bei Bedarf und testen Sie sie gründlich in Ihrer Deployment-Umgebung.
Plattformkompatibilität
Die tus-java-client-Bibliothek ist sowohl mit Standard-Java als auch mit Android-Plattformen kompatibel. Android-spezifische Funktionen und Optimierungen finden Sie im tus-android-client.
Weitere Details finden Sie in der tus-java-client-Dokumentation und im GitHub-Repository.
Fazit: Mit der tus-java-client-Bibliothek lassen sich fortsetzbare Datei-Uploads in Java unkompliziert umsetzen. Wenn Sie diese bewährten Verfahren befolgen, erstellen Sie einen robusten und effizienten Workflow für Dateiübertragungen.
Weitere Einblicke in fortgeschrittene Lösungen für Dateiübertragungen bietet die Dokumentation von Transloadit.