Allow beginning an upload from URL without creation

This is necessary to allow people to upload to Vimeo, see tus/tus-android-client#19

Author: Acconut

example/src/main/java/io/tus/java/example/Main.java

@@ -25,7 +25,7 @@ public static void main(String[] args) {
 
             // Configure tus HTTP endpoint. This URL will be used for creating new uploads
             // using the Creation extension
-            client.setUploadCreationURL(new URL("http://master.tus.io/files/"));
+            client.setUploadCreationURL(new URL("https://master.tus.io/files/"));
 
             // Enable resumable uploads by storing the upload URL in memory
             client.enableResuming(new TusURLMemoryStore());

src/main/java/io/tus/java/client/TusClient.java

@@ -186,15 +186,36 @@ public TusUploader createUpload(@NotNull TusUpload upload) throws ProtocolExcept
      * @throws IOException Thrown if an exception occurs while issuing the HTTP request.
      */
     public TusUploader resumeUpload(@NotNull TusUpload upload) throws FingerprintNotFoundException, ResumingNotEnabledException, ProtocolException, IOException {
-        if(!resumingEnabled) {
+        if (!resumingEnabled) {
             throw new ResumingNotEnabledException();
         }
 
         URL uploadURL = urlStore.get(upload.getFingerprint());
-        if(uploadURL == null) {
+        if (uploadURL == null) {
             throw new FingerprintNotFoundException(upload.getFingerprint());
         }
 
+        return beginOrResumeUploadFromURL(upload, uploadURL);
+    }
+
+    /**
+     * Begin an upload or alternatively resume it if the upload has already been started before. In contrast to
+     * {@link #createUpload(TusUpload)} and {@link #resumeOrCreateUpload(TusUpload)} this method will not create a new
+     * upload. The user must obtain the upload location URL on their own as this method will not send the POST request
+     * which is normally used to create a new upload.
+     * Therefore, this method is only useful if you are uploading to a service which takes care of creating the tus
+     * upload for yourself. One example of such a service is the Vimeo API.
+     * When called a HEAD request will be issued to find the current offset without uploading the file, yet.
+     * The uploading can be started by using the returned {@link TusUploader} object.
+     *
+     * @param upload The file for which an upload will be resumed
+     * @param uploadURL The upload location URL at which has already been created and this file should be uploaded to.
+     * @return Use {@link TusUploader} to upload the remaining file's chunks.
+     * @throws ProtocolException Thrown if the remote server sent an unexpected response, e.g.
+     * wrong status codes or missing/invalid headers.
+     * @throws IOException Thrown if an exception occurs while issuing the HTTP request.
+     */
+    public TusUploader beginOrResumeUploadFromURL(@NotNull TusUpload upload, @NotNull URL uploadURL) throws ProtocolException, IOException {
         HttpURLConnection connection = (HttpURLConnection) uploadURL.openConnection();
         connection.setRequestMethod("HEAD");
         prepareConnection(connection);

src/test/java/io/tus/java/client/TestTusClient.java

@@ -103,7 +103,7 @@ public void testCreateUploadWithMissingLocationHeader() throws IOException, Exce
     }
 
     @Test
-    public void testCreateUplaodWithRelativeLocation() throws Exception {
+    public void testCreateUploadWithRelativeLocation() throws Exception {
         // We need to enable strict following for POST requests first
         System.setProperty("http.strictPostRedirect", "true");
 
@@ -242,6 +242,30 @@ public void testResumeOrCreateUploadNotFound() throws IOException, ProtocolExcep
         assertEquals(uploader.getUploadURL(), new URL(mockServerURL + "/foo"));
     }
 
+    @Test
+    public void testBeginOrResumeUploadFromURL() throws IOException, ProtocolException {
+        mockServer.when(new HttpRequest()
+                .withMethod("HEAD")
+                .withPath("/files/fooFromURL")
+                .withHeader("Tus-Resumable", TusClient.TUS_VERSION))
+                .respond(new HttpResponse()
+                        .withStatusCode(204)
+                        .withHeader("Tus-Resumable", TusClient.TUS_VERSION)
+                        .withHeader("Upload-Offset", "3"));
+
+        TusClient client = new TusClient();
+        URL uploadURL = new URL(mockServerURL.toString() + "/fooFromURL");
+
+        TusUpload upload = new TusUpload();
+        upload.setSize(10);
+        upload.setInputStream(new ByteArrayInputStream(new byte[10]));
+
+        TusUploader uploader = client.beginOrResumeUploadFromURL(upload, uploadURL);
+
+        assertEquals(uploader.getUploadURL(), uploadURL);
+        assertEquals(uploader.getOffset(), 3);
+    }
+
     @Test
     public void testPrepareConnection() throws IOException {
         HttpURLConnection connection = (HttpURLConnection) mockServerURL.openConnection();