Java API Client

Java integration handles uploads and file operations by wrapping Uploadcare Upload API and REST API. This comprehensive API client lets you use most of the Uploadcare features from within your Java app.

GitHub →

Features

Uploading (Upload API):

  • Upload files from local storage and URLs (up to 5 TB)
  • Multipart uploading for large files
  • Uploading network to speed uploading jobs (like CDN)

File management (REST API):

  • Get file info and perform various operations (store/delete/copy) with them
  • Work with groups of files
  • Get info about account project
  • Manage webhooks
  • Paginated resources are fetched as List<T>
  • CDN path builder

Image processing (URL API):

  • Compression
  • Geometry
  • Colors
  • Definition
  • Image and text overlays
  • Rotations
  • Recognition
  • File info
  • Proxy (fetch)

Security features:

  • Secure authentication
  • Secure uploads (signed uploads)

Requirements

Go to your Uploadcare Dashboard and create a new project for your Java app. It’ll have API keys to complete Java API client integration.

Setup

The latest stable library version is available at Maven Central.

Include the following code into your build by adding the following dependencies into pom.xml for your project.

1<dependency>
2  <groupId>com.uploadcare</groupId>
3  <artifactId>uploadcare</artifactId>
4  <version>3.5.1</version>
5</dependency>

To build with Gradle add to Gradle build file:

1compile 'com.uploadcare:uploadcare:3.3.1'

Usage example

Create Client and basic API usage

Use your Public and Secret API Keys from the Java project’s dashboard.

Create a new API Client:

1Client client = new Client("YOUR_PUBLIC_KEY", "YOUR_SECRET_KEY");
2Project project = client.getProject();
3Project.Collaborator owner = project.getOwner();
4
5List<URI> published = new ArrayList<URI>();
6Iterable<File> files = client.getFiles().asIterable();
7for (File file : files) {
8    if (file.isMadePublic()) {
9        published.add(file.getOriginalFileUrl());
10    }
11}

Building CDN URLs

Uploadcare CDN can process images by adding directives like this:

1https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/resize/640x640/image.jpg

Here’s a Java example to automate CDN URL creation:

1File file = client.getFile("85b5644f-e692-4855-9db0-8c5a83096e25");
2CdnPathBuilder builder = file.cdnPath()
3        .resizeWidth(200)
4        .cropCenter(200, 200)
5        .grayscale();
6URI url = Urls.cdn(builder);

Upload files with FileUploader and UrlUploader

Check out two options to upload files with the Java Uploadcare library Uploader interface.

Upload with UrlUploader:

1@Test
2void uploadFileWithUrlUploader_uploadedAndRequestedFilesShouldMatch() throws UploadFailureException {
3  Uploader uploader = new UrlUploader(client, URL);
4  File uploadedFile = uploader.upload();
5  String uploadedFileId = uploadedFile.getFileId();
6
7  File requestedByIdFile = client.getFile(uploadedFileId);
8
9  then(requestedByIdFile.hasOriginalFileUrl()).isTrue();
10  then(requestedByIdFile.getOriginalFileUrl().getRawPath()).contains(uploadedFileId);
11  then(requestedByIdFile.getOriginalFilename()).isEqualToIgnoringCase(SHUTTERSTOCK_FILE_NAME);
12  then(requestedByIdFile.getMimeType()).isEqualTo("image/jpeg");
13  then(requestedByIdFile.isRemoved()).isFalse();
14  then(requestedByIdFile.isStored()).isTrue();
15  then(requestedByIdFile.getUploadDate()).isInSameHourAs(new Date());
16}

Upload with FileUploader by providing java.io.File:

1@Test
2void uploadFileWithFileUploader_uploadedAndRequestedFilesShouldMatch() throws UploadFailureException {
3  java.io.File localFile = new java.io.File(Optional.ofNullable(getClass().getClassLoader()
4      .getResource(LOCAL_FILE_NAME)).map(java.net.URL::getFile)
5      .orElseThrow(RuntimeException::new));
6  Uploader uploader = new FileUploader(client, localFile);
7  File uploadedFile = uploader.upload();
8  String uploadedFileId = uploadedFile.getFileId();
9
10  File requestedByIdFile = client.getFile(uploadedFileId);
11
12  then(requestedByIdFile.hasOriginalFileUrl()).isTrue();
13  then(requestedByIdFile.getOriginalFileUrl().getRawPath()).contains(uploadedFileId);
14  then(requestedByIdFile.getOriginalFilename()).isEqualToIgnoringCase(LOCAL_FILE_NAME);
15  then(requestedByIdFile.isRemoved()).isFalse();
16  then(requestedByIdFile.isStored()).isTrue();
17  then(requestedByIdFile.getUploadDate()).isInSameHourAs(new Date());
18}

Note: the com.uploadcare.api.File#getOriginalFileUrl method returns a combination of UUID and an original file name without whitespaces.

Manage project data and files

With Client, you get a few utility methods to retrieve and handle the project-specific data, like fetching a file by a file id or listing all uploaded files for the project. Note, ids are Uploadcare UUIDs associated with files whenever they get uploaded.

Here’s a short example of navigating your files and retrieving 10 file names uploaded to your project after today’s midnight and matching some arbitrary pattern:

1// Print 10 file names uploaded after today's midnight and matching regexp
2client.getFiles().asList()
3        .stream()
4        .map(f -> new Pair<>(f.getOriginalFilename(), f.getUploadDate()))
5        .filter(p -> p.getValue().after(Date.from(todayMidnight))
6                && p.getKey().matches(FILENAME_STARTING_WITH_LETTERS_AND_HAVING_EXTENSION))
7        .limit(10)
8        .forEach(System.out::println);

Automatic File Storing

When Automatic File Storing in storage settings is on (default), all newly uploaded files will be stored permanently. If it’s switched off, all incoming files will be deleted in 24 hours to prevent your storage cluttering.

With Automatic File Storing. turned off, you can still store files selectively via API. In Java, these per-file controls are provided by both com.uploadcare.api.Client#saveFile taking a UUID as a parameter and com.uploadcare.api.File#save.

Transfer files to Amazon S3

You can connect an Amazon S3 Bucket to your Uploadcare account as custom storage for specific cases. See custom storage docs on how to configure it.

With the Java library, you can move files to custom storage with the com.uploadcare.api.Client#copyFile java method. You can do the same via remote_copy REST API.

More examples

Refer the GitHub and check out more java examples.

Full documentation

Read the full documentation on GitHub.