DC SDK for Java
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.
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
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]"
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]"
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]"
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"
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]"
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.
The overall sequence of requests in the sample:
- Retrieve an authentication token.
- Call /discovery to get API URI details.
- Retrieve options for this operation if applicable.
- Upload a file.
- Start a job. e.g. Export from PDF, Create PDF, Add Password, Organize Pages.
- Poll for job completion.
- When complete, request a URI for downloading the result.
- 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.
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.