Invoking the LiveCycle ES Distiller API from Java
Modified
18 May 2009
Requirements
Prerequisite knowledge
Familiarity with creating Java applications in Eclipse.
User level
All
In this tutorial, you will learn how to invoke a LiveCycle ES SOAP endpoint to convert a PostScript file into a PDF file. Scott MacDonald and I created this tutorial to help LiveCycle ES developers better understand the steps needed to use Quick Start guides available from the LiveCycle ES area of the Adobe Developer Connection, including how to download and configure the code samples, configure the right JAR files, and set user permissions.
Installing the required JAR files
You will need the following LiveCycle ES client SDK JAR files for this tutorial:
- adobe-encryption-client.jar
- adobe-livecycle-client.jar
- adobe-usermanager-client.jar
These JAR files are located in the following path: {install directory}/LiveCycle<version>/LiveCycle_ES_SDK/client-libs/common
- adobe-utilities.jar
This file is located in the following path:
{install directory}/LiveCycle<version>/LiveCycle_ES_SDK/client-libs/jboss
- jbossall-client.jar
This file is located in the following path:
{install directory}/LiveCycle<version>/jboss/client
(Use a different JAR file if LiveCycle ES is not deployed on JBoss.)
You will also need the third-party JAR files to use the SOAP stack rather than EJB endpoints. If you want to invoke a remote LiveCycle ES instance and there is a firewall between the client application and LiveCycle ES, then it is recommended that you use the SOAP mode. When using the SOAP mode, you have to include additional JAR files located in the following path:
{install directory}/LiveCycle<version>/LiveCycle_ES_SDK/client-libs/thirdparty
For information about the SOAP and EJB modes, see Setting connection properties in Programming with LiveCycle ES.
Creating the application
Follow these steps to create the application.
- Start Eclipse and set up a new Java project by choosing File > New > Project.
- Select Java Project (see Figure 1).
- Type a name for the project and click Finish (see Figure 2).
- When the new project opens in your workspace navigator, right-click (Windows) or Control-click (Mac) on the src folder under the project.
- Choose New > Package (see Figure 3).
- Type a name for your package (I used "org.duanesworldtv.samples") and click Finish. This step is important because it keeps your class files distinct from other class files with the same names under your workspace by namespace-qualifying them.
- Right-click the package name you just created (under your project) and choose New > Class to create a new class file (see Figure 4).
- In the New Java Class dialog box, type the name for your class (I used "CreatePDF") and click Finish (see Figure 5).
- You should see some skeleton code under your new project. Highlight all code below the package name and delete it.
- Replace the deleted skeleton code with this source code:
package org.duanesworldtv.samples;
/*
* This Java Quick Start uses the following JAR files
* 1. adobe-distiller-client.jar
* 2. adobe-livecycle-client.jar
* 3. adobe-usermanager-client.jar
* 4. adobe-utilities.jar
* 5. jbossall-client.jar (use a different JAR file if LiveCycle ES is not deployed
* on JBoss)
*
* These JAR files are located in the following path:
* /LiveCycle<version>/LiveCycle_ES_SDK/client-libs
*
* For complete details about the location of these JAR files,
* see "Including LiveCycle ES library files" in Programming
* with LiveCycle ES
*/
import java.io.File;
import java.io.FileInputStream;
import java.util.Properties;
import com.adobe.livecycle.generatepdf.client.CreatePDFResult;
import com.adobe.idp.Document;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactory;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactoryProperties;
import com.adobe.livecycle.distiller.client.DistillerServiceClient;
public class CreatePDF {
public static void main(String[] args)
{
try
{
//Set connection properties required to invoke LiveCycle ES
Properties ConnectionProps = new Properties();
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://{your_server_IP}:{HTTP_PORT}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "{username_of_privileged_user}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "{password}");
// Create a ServiceClientFactory instance
ServiceClientFactory factory = ServiceClientFactory.createInstance(ConnectionProps);
DistillerServiceClient disClient = new DistillerServiceClient(factory );
// Get a PS file document to convert to a PDF document and populate a com.adobe.idp.Document object
String inputFileName = "/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/test.ps";
FileInputStream fileInputStream = new FileInputStream(inputFileName);
Document inDoc = new Document(fileInputStream);
//Set run-time options
String adobePDFSettings = "Standard";
String securitySettings = "No Security";
//Convert a PS file into a PDF file
CreatePDFResult result = new CreatePDFResult();
result = disClient.createPDF(
inDoc, inputFileName, adobePDFSettings,
securitySettings, null, null
);
//Get the newly created document
Document createdDocument = result.getCreatedDocument();
//Save the PDF file
createdDocument.copyToFile(new File("/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/DuanesWorldTest.pdf"));
}
catch (Exception e) {
e.printStackTrace();
}
}
}
Be sure to replace the package name with your own package name.
- When you paste this code into your project, you will notice several red Xs beside various lines. This is because you have not yet imported any of the LiveCycle ES JAR files.
There are a couple of things you need to be aware of with respect to these JARs.
First, the JARs must be from the same release of LiveCycle as the instance you are going to connect to. JARs from LiveCycle ES, version 8.0, for example, might not always work with a LiveCycle ES, version 8.2.1 instance.
Second, the JARs are not all found in the same location. (See Installing the required JAR files for details.)
I put the JAR files into a parallel directory that I created under my Eclipse workspace called "JavaOne2009_libs". This allows me to easily use these JAR files for multiple projects.
- To add the JARs to your project, highlight the project name in the navigator tab, then right-click and open the project Properties dialog box (see Figure 7).
- Select Java Build Path and then the Libraries tab. Click Add External Jars. Select all the JARs under the "thirdparty" folder (for SOAP only – these are not required for EJB endpoints invocation). You will also need to import the Adobe LiveCycle client JARs. (Note: In Figure 8, I have highlighted some extra JAR files because I plan to add more class files to this project later.)
- Once your JAR files are added, your build path should look similar to the one shown in Figure 9.
- Click OK, check any warnings in Eclipse, and correct as needed.
- Now locate the lines of code that set the connection properties. They look like this:
//Set connection properties required to invoke LiveCycle ES
Properties ConnectionProps = new Properties();
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://{your_server_ip}:{http_port}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "{username_of_privileged_user}");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "{password}");
- You will have to change three values. The first is the server IP address and port. If the server is on the same machine, then http://localhost:8080 should suffice. Change it as required to match your server's location.
- Next, you will be required to supply a username and password of a user with the right privileges. I used the username "kvarsen" because it is installed by default when you install the LiveCycle ES samples. The matching password for kvarsen is "password", all lowercase.
Setting user privileges
To run the code in this tutorial, you will need to update the roles assigned to kvarsen. To do this, you must have administrator access to the LiveCycle ES server you wish to connect to.
- Log in to the adminui at http://{your_server_ip}:{http_port}/adminui. For example, I used the following URL: http://duanesworldtv.org:8080/adminui. Once inside, navigate to Home > Settings > User Management > Users and Groups (see Figure 10).
- Type the user's name in the Find text box (for Kel Varsen, type varsen) and click Find. The user's name will come up in the list with a hyperlink. Click on the name to show what permissions the user has (see Figure 11).
- Click the Role Assignments tab (see Figure 12).
- This will bring up a screen that shows all the roles and permissions that this particular user has. For this tutorial, you want to ensure that Kel Varsen is privileged with the PDFG (PDF Generation) service. (In Figure 13 the user is already assigned the PDFG User role; your setup will likely not show this yet.)
- To find the appropriate roles, click Find Roles, which will bring up a list (see Figure 14).
- Locate and select the PDFG User role, and then click OK (see Figure 15). You can then log out of the adminui console.
Running the application
You are almost ready to run the code.
- Back in Eclipse, you will notice two lines of code that contain path references. One is a reference to a PostScript document. You need to change this to correspond to an absolute path to a PostScript document on your hard drive. The path I used is:
// Get a PS file document to convert to a PDF document and
populate a com.adobe.idp.Document object
String inputFileName =
"/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/test.ps";
- Replace this path with a path to a valid Postscript file.
- You also need to specify the path used to save the file when it comes back from LiveCycle ES. This looks something like the code below. Change the path to a location on your system for which you have access.
//Save the PDF file
createdDocument.copyToFile(new File("/Users/duane/Desktop/eclipse/workspace/JavaOne2009-docs/DuanesWorldTest.pdf"));
- Now run the application. You should see the console output working with no errors. Go to the location you referenced in the previous step and you should find a file there titled "DuanesWorldTest.pdf" or whatever you named your file.
Where to go from here
Now that you have a better idea of how to invoke a LiveCycle ES SOAP endpoint, you may want to try some of the other LiveCycle Remoting Quick Starts:
- Generating a PDF file from a Word file using LiveCycle Remoting
- Invoking a long-lived process using LiveCycle Remoting
- Add a form design (an XDP file) to the repository by using LiveCycle Remoting
You can also explore the LiveCycle ES DSK help documentation and APIs.
This work is licensed under a Creative Commons Attribution-Noncommercial 3.0 Unported License.
