Invoking the LiveCycle ES 8.2.1 Distiller API from Java

Scott MacDonald and I created a tutorial to help LiveCycle ES developers better understand the process around using the Quick Start guides available from the LiveCycle area of the Adobe Developer Connection. In this tutorial, you will learn how to download and configure the code samples, configure the right JAR files, set user permissions, and invoke a LiveCycle ES SOAP endpoint to convert a PostScript file into a PDF file.

Before you start:

You will need to ensure you have the following on your local drive. I used a MacBook Pro laptop to conduct this lab.

• Java JDK 1.5 – ensure your environment variables are set as per the instructions from the LiveCycle ES documentation
• Eclipse 3.4 (Ganymede)
• The LiveCycle ES Client SDK JAR files. You will need the following JAR files to make this lab work:

/*
* This Java Quick Start uses the EJB mode and contains the following JAR files
* in the class path:
* 1. adobe-encryption-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:
* {install directory}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-libs/common
*
* The adobe-utilities.jar file is located in the following path:
* {install directory}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-libs/jboss
*
* The jbossall-client.jar file is located in the following path:
* {install directory}/Adobe/LiveCycle9.0/jboss/client
*/

 


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}/Adobe/LiveCycle9.0/LiveCycle_ES_SDK/client-
*  libs/thirdparty
*/

 


For information about the SOAP and EJB mode, see "Setting connection properties" in Programming with LiveCycle ES.

For complete details about the location of the LiveCycle ES JAR files, see "Including LiveCycle ES library files" in Programming with LiveCycle ES.

1. Open up Eclipse and set up a new Java project by choosing File > New > Project.

2. Select Java Project.



3. Type a name for the project and click Finish.



4. When the new project opens in your workspace navigator, right-click (Windows) or Control-click (Mac) on the src folder under the project.

5. Choose New > Package.



6. 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.

7. Right-click on the package name you just created (under your project) and choose New > Class to create a new class file.



8. In the New Java Class dialog box, type the name for your class (I used “CreatePDF”) and click Finish.




9. You should see some skeleton code under your new project. Highlight all code below the package name and delete it.

10. 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:
 * /Adobe/LiveCycle8/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();
  }
 }
}

 


11. 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 gotchas you need to know about 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 8.0, for example, might not always work with an 8.2.1 instance.

Second, the JARs are in various locations and not always easy to grab. (See above for the exact locations.)

We put our jars into a parallel directory that we created under our Eclipse workspace called “JavaOne2009_libs”. This allows us to easily use these JAR files for multiple projects.



12. 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.



13. 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 the image below we have highlighted some extra jars because we plan to add more class files to this project later.)



14. Once your JAR files are added, your build path should look similar to this:



15. Click OK, check any warnings in Eclipse, and correct as needed.

16. Now locate the lines of code that set the connection properties. They are at around line 14 and 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}");

 

17. You will have to change three values. The first is the server IP address and port. If the server is on the same machine, http://localhost:8080 should suffice. Change it as required to match your server's location.

18. Next, you will be required to supply a username and password of a user with the right privileges. We 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.

To run the code in this tutorial, however, you will need to update the roles assigned to kvarsen. To do this, you must have administrator access to the LiveCycle Server you wish to connect to. Log in to the adminui at http://{your_server_ip}:{http_port}/adminui. For example, ours was http://duanesworldtv.org:8080/adminui. Once inside, navigate to Home > Settings > User Management > Users and Groups.



19. 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.



20. Click the Role Assignments tab.




21. 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 the screenshot below the user is already assigned the PDFG User role; your setup will likely not show this yet.)



22. To find the appropriate roles, click Find Roles, which will bring up a list.




23. Locate and select the PDFG User role, and then click OK. You can then log out of the adminui console.




24. 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 we 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";

 


25. Replace this path with a path to a valid Postscript file.

26. You also need to specify the path used to save the file when it comes back from LiveCycle ES. This is around line 72 and 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"));

 


27. 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.

Congratulations – you have just invoked your first remote SOAP endpoint using LiveCycle ES!