Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Upgrade to Spring boot 3 #50

Merged
merged 1 commit into from
Jul 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,24 @@
[![Build Status](https://travis-ci.com/tomdesair/tus-java-server.svg?branch=master)](https://travis-ci.com/github/tomdesair/tus-java-server) [![Test Coverage](https://coveralls.io/repos/github/tomdesair/tus-java-server/badge.svg)](https://coveralls.io/github/tomdesair/tus-java-server) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/d57e97c51d76419498fa69dd25e2bcee)](https://www.codacy.com/app/tom.desair/tus-java-server?utm_source=github.com&utm_medium=referral&utm_content=tomdesair/tus-java-server&utm_campaign=Badge_Grade) [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=me.desair.tus%3Atus-java-server&metric=bugs)](https://sonarcloud.io/dashboard?id=me.desair.tus%3Atus-java-server) [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=me.desair.tus%3Atus-java-server&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=me.desair.tus%3Atus-java-server) [![Duplicated Lines](https://sonarcloud.io/api/project_badges/measure?project=me.desair.tus%3Atus-java-server&metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=me.desair.tus%3Atus-java-server)

# tus-java-server
This library can be used to enable resumable (and potentially asynchronous) file uploads in any Java web application. This allows the users of your application to upload large files over slow and unreliable internet connections. The ability to pause or resume a file upload (after a connection loss or reset) is achieved by implementing the open file upload protocol tus (https://tus.io/). This library implements the server-side of the tus v1.0.0 protocol with [all optional extensions](#tus-protocol-extensions).
This library can be used to enable resumable (and potentially asynchronous) file uploads in any Java web application. This allows the users of your application to upload large files over slow and unreliable internet connections. The ability to pause or resume a file upload (after a connection loss or reset) is achieved by implementing the open file upload protocol tus (https://tus.io/). This library implements the server-side of the tus v1.0.0 protocol with [all optional extensions](#tus-protocol-extensions).

The Javadoc of this library can be found at https://tus.desair.me/. The following Java versions are supported: 7, 8, 9, 10 and 11.
The Javadoc of this library can be found at https://tus.desair.me/. The following Java versions are supported: 8,
9, 10, 11 and 17.

## Quick Start and Examples
The tus-java-server library only depends on Java Servlet API 3.1 and some Apache Commons utility libraries. This means that (in theory) you can use this library on any modern Java Web Application server like Tomcat, JBoss, Jetty... By default all uploaded data and information is stored on the file system of the application server (and currently this is the only option, see [configuration section](#usage-and-configuration)).
The tus-java-server library only depends on Jakarta Servlet API 6.0 and some Apache Commons utility libraries. This
means that (in theory) you can use this library on any modern Java Web Application server like Tomcat, JBoss, Jetty... By default all uploaded data and information is stored on the file system of the application server (and currently this is the only option, see [configuration section](#usage-and-configuration)).

You can add the latest stable version of this library to your application using Maven by adding the following dependency:

<dependency>
<groupId>me.desair.tus</groupId>
<artifactId>tus-java-server</artifactId>
<version>1.0.0-2.0</version>
<version>1.0.0-3.0-SNAPSHOT</version>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the version be 1.0.0-3.0, since this is a breaking change

</dependency>

The main entry point of the library is the `me.desair.tus.server.TusFileUploadService.process(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)` method. You can call this method inside a `javax.servlet.http.HttpServlet`, a `javax.servlet.Filter` or any REST API controller of a framework that gives you access to `HttpServletRequest` and `HttpServletResponse` objects. In the following list, you can find some example implementations:
The main entry point of the library is the `me.desair.tus.server.TusFileUploadService.process(jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse)` method. You can call this method inside a `jakarta.servlet.http.HttpServlet`, a `jakarta.servlet.Filter` or any REST API controller of a framework that gives you access to `HttpServletRequest` and `HttpServletResponse` objects. In the following list, you can find some example implementations:

* [Detailed blog post by Ralph](https://golb.hplar.ch/2019/06/upload-with-tus.html) on how to use this library in [Spring Boot in combination with the Tus JavaScript client](https://github.com/ralscha/blog2019/tree/master/uploadtus).
* [Resumable and asynchronous file upload using Uppy with form submission in Dropwizard (Jetty)](https://github.com/tomdesair/tus-java-server-dropwizard-demo)
Expand Down Expand Up @@ -56,7 +58,7 @@ The first step is to create a `TusFileUploadService` object using its constructo
For now this library only provides filesystem based storage and locking options. You can however provide your own implementation of a `UploadStorageService` and `UploadLockingService` using the methods `withUploadStorageService(UploadStorageService)` and `withUploadLockingService(UploadLockingService)` in order to support different types of upload storage.

### 2. Processing an upload
To process an upload request you have to pass the current `javax.servlet.http.HttpServletRequest` and `javax.servlet.http.HttpServletResponse` objects to the `me.desair.tus.server.TusFileUploadService.process()` method. Typical places were you can do this are inside Servlets, Filters or REST API Controllers (see [examples](#quick-start-and-examples)).
To process an upload request you have to pass the current `jakarta.servlet.http.HttpServletRequest` and `jakarta.servlet.http.HttpServletResponse` objects to the `me.desair.tus.server.TusFileUploadService.process()` method. Typical places were you can do this are inside Servlets, Filters or REST API Controllers (see [examples](#quick-start-and-examples)).

Optionally you can also pass a `String ownerKey` parameter. The `ownerKey` can be used to have a hard separation between uploads of different users, groups or tenants in a multi-tenant setup. Examples of `ownerKey` values are user ID's, group names, client ID's...

Expand All @@ -66,15 +68,15 @@ Once the upload has been completed by the user, the business logic layer of your
Using the `me.desair.tus.server.TusFileUploadService.getUploadInfo(String uploadURL)` method you can retrieve metadata about a specific upload process. This includes metadata provided by the client as well as metadata kept by the library like creation timestamp, creator ip-address list, upload length... The method `UploadInfo.getId()` will return the unique identifier of this upload encapsulated in an `UploadId` instance. The original (custom generated) identifier object of this upload can be retrieved using `UploadId.getOriginalObject()`. A URL safe string representation of the identifier is returned by `UploadId.toString()`. It is highly recommended to consult the [JavaDoc of both classes](https://tus.desair.me/).

### 4. Upload cleanup
After having processed the uploaded bytes on the server backend (e.g. copy them to their final persistent location), it's important to cleanup the (temporary) uploaded bytes. This can be done by calling the `me.desair.tus.server.TusFileUploadService.deleteUpload(String uploadURI)` method. This will remove the uploaded bytes and any associated upload information from the storage backend. Alternatively, a client can also remove an (in-progress) upload using the [termination extension](https://tus.io/protocols/resumable-upload.html#termination).
After having processed the uploaded bytes on the server backend (e.g. copy them to their final persistent location), it's important to cleanup the (temporary) uploaded bytes. This can be done by calling the `me.desair.tus.server.TusFileUploadService.deleteUpload(String uploadURI)` method. This will remove the uploaded bytes and any associated upload information from the storage backend. Alternatively, a client can also remove an (in-progress) upload using the [termination extension](https://tus.io/protocols/resumable-upload.html#termination).

Next to removing uploads after they have been completed and processed by the backend, it is also recommended to schedule a regular maintenance task to clean up any expired uploads or locks. Cleaning up expired uploads and locks can be achieved using the `me.desair.tus.server.TusFileUploadService.cleanup()` method.

## Compatible Client Implementations
This tus protocol implementation has been [tested](https://github.com/tomdesair/tus-java-server-spring-demo) with the [Uppy file upload client](https://uppy.io/). This repository also contains [many automated integration tests](https://github.com/tomdesair/tus-java-server/blob/master/src/test/java/me/desair/tus/server/ITTusFileUploadService.java) that validate the tus protocol server implementation using plain HTTP requests. So in theory this means we're compatible with any tus 1.0.0 compliant client.

## Versioning
This artifact is versioned as `A.B.C-X.Y` where `A.B.C` is the version of the implemented tus protocol (currently 1.0.0) and `X.Y` is the version of this library.
This artifact is versioned as `A.B.C-X.Y` where `A.B.C` is the version of the implemented tus protocol (currently 1.0.0) and `X.Y` is the version of this library.

## Contributing
This library comes without any warranty and is released under a [MIT license](https://github.com/tomdesair/tus-java-server/blob/master/LICENSE). If you encounter any bugs or if you have an idea for a useful improvement you are welcome to [open a new issue](https://github.com/tomdesair/tus-java-server/issues) or to [create a pull request](https://github.com/tomdesair/tus-java-server/pulls) with the proposed implementation. Please note that any contributed code needs to be accompanied by automated unit and/or integration tests and comply with the [defined code-style](https://github.com/tomdesair/tus-java-server/blob/master/checkstyle.xml).
37 changes: 28 additions & 9 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

<groupId>me.desair.tus</groupId>
<artifactId>tus-java-server</artifactId>
<version>1.0.0-2.1-SNAPSHOT</version>
<version>1.0.0-3.0-SNAPSHOT</version>
<packaging>jar</packaging>

<name>${project.groupId}:${project.artifactId}</name>
Expand All @@ -16,15 +16,15 @@

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.source>1.7</maven.compiler.source>
<maven.compiler.target>1.7</maven.compiler.target>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we go for the breaking change, then the compiler source and target should be 17?

</properties>

<dependencies>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<groupId>jakarta.servlet</groupId>
<artifactId>jakarta.servlet-api</artifactId>
<version>6.0.0</version>
<scope>provided</scope>
</dependency>
<dependency>
Expand Down Expand Up @@ -58,19 +58,27 @@
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.1</version>
<version>4.13.2</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-test</artifactId>
<version>3.2.18.RELEASE</version>
<version>6.0.7</version>
<scope>test</scope>
</dependency>
<dependency>
Copy link
Contributor Author

@ghoshrahul ghoshrahul May 9, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spring test no longer includes spring-web, hence this was externalized

<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>6.0.7</version>
<scope>compile</scope>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<version>2.23.4</version>
<version>4.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
Expand Down Expand Up @@ -210,6 +218,17 @@
</executions>
</plugin>

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.10.1</version>
<configuration>
<!-- <source>17</source>-->
<!-- <target>17</target>-->
<encoding>UTF-8</encoding>
</configuration>
</plugin>

</plugins>
</build>

Expand Down
2 changes: 1 addition & 1 deletion src/main/java/me/desair/tus/server/HttpMethod.java
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server;

import java.util.Set;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.Validate;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/me/desair/tus/server/RequestValidator.java
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.exception.TusException;
import me.desair.tus.server.upload.UploadStorageService;
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/me/desair/tus/server/TusExtension.java
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import java.io.IOException;
import java.util.Collection;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.exception.TusException;
import me.desair.tus.server.upload.UploadStorageService;
Expand Down
4 changes: 2 additions & 2 deletions src/main/java/me/desair/tus/server/TusFileUploadService.java
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.Set;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.checksum.ChecksumExtension;
import me.desair.tus.server.concatenation.ConcatenationExtension;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.checksum.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.concatenation.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.concatenation.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.concatenation.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpMethod;
import me.desair.tus.server.RequestValidator;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import java.io.IOException;
import java.util.Objects;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.core;

import java.util.Objects;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import java.io.IOException;
import java.util.Objects;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.core.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.core.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.core.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpMethod;
import me.desair.tus.server.RequestValidator;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.core.validation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpMethod;
import me.desair.tus.server.RequestValidator;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.core.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import java.io.IOException;
import java.util.Objects;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package me.desair.tus.server.creation;

import java.io.IOException;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
package me.desair.tus.server.creation;

import java.io.IOException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.creation.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpMethod;
import me.desair.tus.server.RequestValidator;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.creation.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.creation.validation;

import javax.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletRequest;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Objects;
import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

import me.desair.tus.server.HttpHeader;
import me.desair.tus.server.HttpMethod;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.exception;

import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

/**
* Exception thrown when the client sends a request for a checksum algorithm we do not support
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
package me.desair.tus.server.exception;

import javax.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponse;

public class InvalidContentLengthException extends TusException {
public InvalidContentLengthException(String message) {
Expand Down
Loading