java-sdk

A Java Integration for Transloadit's file uploading and encoding service

Intro

Transloadit is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, Transloadit is the Swiss Army Knife for your files.

This is a Java SDK to make it easy to talk to the Transloadit REST API.

Install

The JARs can be downloaded manually from Maven Central Search, or can be installed from the Maven repository.

Existing users should take note of the JCenter shutdown and update their build files to receive the most recent versions.

Gradle:

implementation 'com.transloadit.sdk:transloadit:2.1.0'

Maven:

<dependency>
  <groupId>com.transloadit.sdk</groupId>
  <artifactId>transloadit</artifactId>
  <version>2.1.0</version>
</dependency>

Usage

All interactions with the SDK begin with the com.transloadit.sdk.Transloadit class.

Authentication

The SDK supports two methods of authentication:

1. Using API Key and Secret

This is the traditional method where you provide both your API key and secret:

Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

2. Using External Signature Provider (Since v2.1.0)

For enhanced security in client applications, you can provide signatures from an external source (like your backend server) instead of including the secret in your application:

import com.transloadit.sdk.SignatureProvider;

// Implement a signature provider that fetches signatures from your backend
SignatureProvider signatureProvider = new SignatureProvider() {
    @Override
    public String generateSignature(String paramsJson) throws Exception {
        // Make a request to your backend to sign the parameters
        // This example uses a hypothetical HTTP client
        HttpResponse response = httpClient.post("https://your-backend.com/sign")
            .body(paramsJson)
            .execute();

        if (response.isSuccessful()) {
            return response.body().getString("signature");
        } else {
            throw new Exception("Failed to get signature from backend");
        }
    }
};

// Initialize Transloadit with the signature provider
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", signatureProvider);

This approach is particularly useful for:

• Mobile applications (Android, JavaFX) where you don't want to ship secrets
• Client-side applications that need to maintain security
• Scenarios where you want centralized control over request authorization

Create an Assembly

To create an assembly, you use the newAssembly method.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;

import java.io.File;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        // Using traditional authentication (for backend applications)
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        Assembly assembly = transloadit.newAssembly();

        Map<String, Object> stepOptions = new HashMap<>();
        stepOptions.put("width", 75);
        stepOptions.put("height", 75);
        assembly.addStep("resize", "/image/resize", stepOptions);

        assembly.addFile(new File("PATH/TO/FILE.jpg"));
        // you can skip this part if you don't want to wait till the
        // assembly is complete
        assembly.setShouldWaitForCompletion(true);
        try {
            AssemblyResponse response = assembly.save();

            System.out.println(response.getId());
            System.out.println(response.getUrl());
            System.out.println(response.json());

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Get an Assembly

The method, getAssembly, retrieves the JSON status of an assembly identified by the given assembly_Id.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            AssemblyResponse response = transloadit.getAssembly("ASSEMBLY_ID");

            System.out.println(response.getUrl());
            System.out.println(response.json());

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

You may also get an assembly by url with the getAssemblyByUrl method.

    AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");

Cancel an Assembly

To cancel an executing assembly, you use the cancelAssembly method, passing the Assembly ID as a parameter.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            AssemblyResponse response = transloadit.cancelAssembly("ASSEMBLY_ID");

            System.out.println(response.isCancelled()); // prints true
        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

List Assemblies

The method, listAssemblies, retrieves an array of assemblies according to the given options. Valid options can be page, pagesize, type, fromdate and todate. Please consult the Transloadit API docs for details.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;

import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            Map<String, Object> options = new HashMap<>();
            options.put("pagesize", 10);
            ListResponse response = transloadit.listAssemblies(options);

            System.out.println(response.size());  // number of assemblies on the list.
            System.out.println(response.getItems());  // returns an iterable json array

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Create a Template

To create a new template, you use the newTemplate method, passing the template name as a parameter.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        Template template = transloadit.newTemplate("MY_TEMPLATE_NAME");

        Map<String, Object> resizeOptions = new HashMap<>();
        resizeOptions.put("width", 75);
        resizeOptions.put("height", 75);

        Map<String, Object> optimizeOptions = new HashMap<>();
        optimizeOptions.put("use", ":original");

        template.addStep("resize", "/image/resize", resizeOptions);
        template.addStep("resize", "/image/optimize", optimizeOptions);

        try {
            Response response = template.save();

            System.out.println(response.json());
            System.out.println(response.json().getString("id")); // gets the Template ID.
        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Update a Template

To update a template, you use the updateTemplate method, passing the Template ID and options to update as a parameters.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.Steps;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        Steps steps = new Steps();

        Map<String, Object> stepOptions = new HashMap<>();
        stepOptions.put("width", 150);
        stepOptions.put("height", 150);
        steps.addStep("resize", "/image/resize", stepOptions);

        Map<String, Object> templateOptions = new HashMap<>();
        templateOptions.put("steps", steps.toMap());
        templateOptions.put("name", "MY_NEW_TEMPLATE_NAME");

        try {
            Response response = transloadit.updateTemplate("TEMPLATE_ID", templateOptions);

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Delete a Template

To delete a template, you use the deleteTemplate method, passing the Template ID as a parameter.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            Response response = transloadit.deleteTemplate("TEMPLATE_ID");

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

List Templates

To get a list of all templates under your account, you use the listTemplates method.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            ListResponse response = transloadit.listTemplates();

            System.out.println(response.size());  // number of assemblies on the list.
            System.out.println(response.getItems());  // returns an iterable json array

        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Get a template

To get a particular template, you use the getTemplate method, passing the Template ID as a parameter.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            AssemblyResponse response = transloadit.getTemplate("TEMPLATE_ID");
            System.out.println(response.json());
        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Get bill

To get your account billing details for a particular month, you use the getBill method, passing the month and year as parameters.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

public class Main {
    public static void main(String[] args) {
        Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

        try {
            ListResponse response = transloadit.getBill(3, 2017);

            System.out.println(response.json());
        } catch (RequestException | LocalOperationException e) {
            // handle exception here
        }
    }
}

Example

For fully working examples take a look at /examples.

Development

Use the provided Docker tooling to run the test suite without installing Java locally:

./scripts/test-in-docker.sh

The script builds a tiny eclipse-temurin:17-jdk based image, mounts the repository in the container, and caches Gradle downloads inside .gradle-docker/ so follow-up runs stay fast. Pass additional Gradle arguments after the script name if you need something other than test.

Documentation

See Javadoc for full API documentation.

License

The MIT License.

Verfication

Releases can be verified with our GPG Release Signing Key:

User ID: Transloadit Release Signing Key <[email protected]>

Fingerprint: 2F4F F0E1 8659 76C6 5B73 782B ECBD 0B65 8705 AE5A

Or download it from keys.openpgp.org