Using the Java invocation API to display an ES2 Guide

When you wish to display a Guide as part of your own web application you need to somehow send this request to LiveCycle.  Prior to LiveCycle ES2 the Forms API could be used to render forms in a variety of formats including form guides.  Since Guides in ES2 are derived from a model and not an XDP the Forms API cannot be used.  Instead, an ES2 Guide can be displayed by calling an appropriate process that has been deployed to the LiveCycle server.  As with all LiveCycle processes there are a number of ways thay can be invoked.  A common way to invoke a process that returns a Guide is to use the supplied REST URL.  Another method however that may be preferred is to programmatically invoke the process using the invocation API.  The remainder of the explanation will look at this option.

Generate Guide System Process

Luckily an application called Guides (system) gets deployed by default when LiveCycle is installed.  Included with this application is a process called Generate Guide.  This is the process we will use display our Guide.

This process has the following inputs:

• data *
• guidePath *
• inputKeyPrefix
• inputMap
• targetUrl *
• variation

This solution will only use the inputs marked with an *.

The process returns the Guide bytes which can then be displayed in a browser.

The Render Guide Servlet

Now a servlet needs to be written that will use the invocation API to access the process defined above a return the Guide to the browser.

Determine Server details

//Get server info
String serverscheme = request.scheme;
String serverPort = Integer.toString(request.getServerPort());
String contextPath = request.getContextPath();

try
{
   InetAddress addr = InetAddress.getLocalHost();
   serverName = addr.getHostName();
   if (!serverName.equals(request.getServerName()))
   {
      serverName = request.getServerName();
   }
}
catch (Exception e)
{  
   serverName = "localhost";
}

String appRoot = serverScheme + "://" + serverName + ":" +
serverPort + contextPath;

Get an instance of the Service Client

//Set connection properties required to invoke LiveCycle ES2 
Properties connectionProps = new Properties();   
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT,
"jnp://" + serverName + ":1099");
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
   
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE,
"JBoss");
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME,"administrator");
  
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD,
"password");
 
// Create a ServiceClientFactory instance
ServiceClientFactory factory =
ServiceClientFactory.createInstance(connectionProps);

//Create a ServiceClient object
ServiceClient myServiceClient = factory.getServiceClient();

Create a map for input values

The targetURL should point to a servlet that will handle the submitted XML data.  In most cases this data will probably just be passed back to a different LiveCycle process using the same invocation API.  The guidePath parameter is the path to your Guide within your server's application structure.

Map params = new HashMap();
params.put("targetUrl", 
appRoot + "/SubmitToProcess");    
params.put("guidePath", 
"/Applications/MySampleApp/1.0/Guides/MySampleGuide.guide");
params.put("data", null);

Invoke the Process

//Create an InvocationRequest object
InvocationRequest irequest =  factory.createInvocationRequest(     
 
 
 
 "Guides (system)/Processes/Generate Guide",
//Specify the process name
   "invoke", //Specify the operation name
   params, //Specify input values
   true); //Create a synchronous request

//Send the invocation request to the short-lived process and get
back a response
InvocationResponse iresponse = myServiceClient.invoke(irequest);

Get the Guide from the response

Map outputMap = iresponse.getOutputParameters();
Document myGuide = (Document)outputMap.get("htmlWrapper");

Write Guide to the browser

ServletOutputStream oOutput = response.getOutputStream();
InputStream inputStream =   myGuide.getInputStream();
byte[] data = new byte[4096];
int bytesRead = 0;
while ((bytesRead = inputStream.read(data)) > 0)
{   
   oOutput.write(data, 0, bytesRead);
}

Classpath

The following JAR files will need to included in your classpath.

1. adobe-convertpdf-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 ES2 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

For more help on setting up your Java project and using the Java invocation API please go to http://www.adobe.com/go/learn_lc_programming_9.

For more help on creating Guide please go to http://www.adobe.com/go/learn_lc_workbench_9.