DC SDK for Java

Overview

The samples are java executables that will:

  • Upload a file
  • Perform conversions or other PDF actions
  • Download the result

The SDK and samples require Java 8.

Configuration

The package contains a maven project which builds two jars:

  • The SDK as dcapi-java-sdk-0.5.0.jar
  • The sample programs as dcapi-java-sdk-samples-0.5.0.jar

To get started, navigate to SDK/java/ and build the project.

mvn clean install

Use the skipTest option to avoid unit tests for a faster build.

mvn install -DskipTests

The skeleton configuration to run the samples is defined in config/default.json . Users will need to update this file with their own registration details including a default-key.pem file.

The samples

exportpdf

Upload a PDF file and convert it to another file format. This sample also takes advantage of export's OCR capability while converting to docx format.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.ExportPDF -Dexec.args="config-file [pdf-file-to-convert]"

createpdf

Upload a file and convert it to PDF. This sample converts from an in-memory text representation or from a file provided on the command line. A 'do_ocr' option will perform OCR upon conversion.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.CreatePDF -Dexec.args="config-file [file-to-convert] [do_ocr]"

createpdf_from_html

Upload a ZIP file of HTML collateral and convert to PDF. This sample also demonstrates how to use the getSchema() API.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.CreatePDFFromHTML -Dexec.args="config-file [zip-file-to-convert]"

add_password

This sample uploads a PDF file and encrypts with password encryption.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.AddPassword -Dexec.args="config-file pdf-file password"

do_ocr

This sample uploads a PDF file and performs OCR on it.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.DoOCR -Dexec.args="config-file [pdf-file-to-ocr]"

organize_pages

This is the most complex sample. It accepts a list of files. It uploads each file and if not a PDF, will convert to PDF. Then for the set of uploaded/converted files will interleave their first 10 pages, rotating at various angles.

mvn -f samples/pom.xml exec:java -Dexec.mainClass=com.adobe.dcapi.samples.OrganizePages -Dexec.args="config-file [input-file [input-file...]]"

Running the samples

The default config file relative to samples/ is ../../config/default.json. Test files used as input to the samples can be found in ../../test-files.

When each sample has run to completion, it will open an HTML page with a log of all the http/API requests and responses. This log is useful both in understanding how DCAPI works, and for debugging issues if the sample fails.

Sample Details:

The overall sequence of requests in the sample:

  1. Retrieve an authentication token.
  2. Call /discovery to get API URI details.
  3. Retrieve options for this operation if applicable.
  4. Upload a file.
  5. Start a job. e.g. Export from PDF, Create PDF, Add Password, Organize Pages.
  6. Poll for job completion.
  7. When complete, request a URI for downloading the result.
  8. Download the result.

This is easily seen by looking at the sequence of calls in the call() method of samples/CreatePDF.java:

    // 1. Upload a txt file for conversion
    FormDataMultiPart multiPart = createTestUploadBody();
    String uploadedAssetUri = uploadFile(multiPart);

    // 2. Call the createpdf API
    JsonObject requestBody = Json.createObjectBuilder()
            .add("asset_uri", uploadedAssetUri)
            .add("name", "quotation.pdf")
            .build();

    Map headers = new HashMap<>();
    headers.put("x-request-id", UUID.randomUUID());

    CallOptions options = new CallOptions(
            CallOptions.accept, CallAccept.new_asset_job,
            CallOptions.content_type, CallContent.createpdf_parameters,
            CallOptions.content, requestBody,
            CallOptions.headers, headers);

    System.out.println("Call " + Operation.assets.createpdf + " ...");
    Response response = dcapi.call(Operation.assets.createpdf, options);

    // 3. Check the status of the createpdf operation until done
    String newPdfUri = checkJobStatus(response);

    // 4. Get download uri for the new pdf
    String downloadUri = getDownloadUri(newPdfUri);

    // 5. Download the newly created pdf file
    downloadFile(downloadUri);



The samples make use of the API class that factors out some common operations.

Every DCAPI application must begin by retrieving an authentication token. This is handled internally by an IdentityAccess handler using the related config/default.json or similar file. The IdentityDefaultAccess can be replaced if necessary in the config used to construct an API instance. The authentication token is needed for every subsequent API call.

The entry point to the API is /discovery. A GET on /discovery will return a list of all available resources and operations. This GET operation is performed automatically by the API() constructor. The results of /discovery are added as properties to the resulting api object.

API Functions/Members

public Response call(String operation, CallOptions options) throws IOException

API.call() accepts a collection of options to control the HTTP request. Most of the options are keys into the /discovery result to select operation details. Look at the code comments on API.call() in API.java for details. The return value is a javax.ws.rs.core.Response object.

public Response getSchema(String contentType)

API.getSchema() will retrieve the JSON schema specified in the contentType parameter. Pass in the schema-name index used in the "accept" or "content_type" objects for the specific resource entry in discovery, e.g. api.getSchema(“new_asset_job_v1.json”). The return value is a javax.ws.rs.core.Response object.

public void API.closeHttpLog() throws IOException

If logging is enabled, API.closeHttpLog() must be called at the end of a session in order to complete the logging session.

API.getFinalURI(String operation, CallOptions options)

API.getFinalURI prepares a final URI based on input parameters. Applications will normally use this method to generate URIs that can be used as a src attribute on HTML elements such as img or iframe. The return value is a String containing the final URI.