Created

4 August 2008

You can create a Java servlet that invokes an Adobe LiveCycle ES long-lived or short-lived process. An advantage of using a Java servlet is that you can write the return value of the process to a client web browser. That is, a Java servlet can be used as the link between a LiveCycle ES process that returns a form and a client web browser.

Assume, for example, that a LiveCycle ES process returns an interactive form (after the process performs other business tasks, such as retrieving customer data from an enterprise database and populating some of the form fields with data). Using a Java servlet, you can write the form to a client web browser so that a customer can enter data into the form. After populating the form with data, the web user clicks a submit button located on the form to send information back to the Java servlet, where the data can be retrieved and processed. For example, the data can be sent to another LiveCycle ES process (see Figure 1).

This document describes how to create a Java servlet that invokes a LiveCycle ES short-lived process named GetMortgageForm. For more information about invoking processes, see the "Invoking LiveCycle ES Processes" section in Programming with LiveCycle ES.

GetMortgageForm process

The following illustration shows the GetMortgageForm process (see Figure 2).

Note: This document does not describe how to create a process by using Adobe LiveCycle Workbench ES. (For information, see Workbench ES Help.)

The following table describes the steps in this diagram.

Operation

Description

1

The user submits a custom identifier value and the operation to perform. In this situation, assume that the user is applying for a mortgage. The input parameters for this process are a string value that specifies the form name (named formName) and another string value that represents the custom identifier value (named custId).

Note: In the Java application logic located in the Java servlet, the formName and custId process variables are referenced.

2

The process uses the customer identifier value to perform a relational database look-up for additional customer information by using the JdbcService service's Execute SQL Statement operation. The custom identifier value acts as the primary key value.

3

Merges customer data into an XML data source that is used to prepopulate the form. (See "Prepopulating Dynamic Forms" in Programming with LiveCycle ES.)

4

The mortgage form is rendered with customer data located in some of the fields, such as the address field. This action is based on the Forms service's renderPDFForm operation.

The Java servlet receives the form (return value for the process) and writes the form to a client web browser. The name of the output parameter is RenderedForm. This parameter is a process variable and its data type is FormsResult.

Note: In the Java application logic located in the Java servlet that invokes this process, the RenderedForm process variable is referenced.

This interactive loan form is rendered by the GetMortgageForm process (see Figure 3).

Note: This document describes how to use the Invocation API to invoke a LiveCycle ES process. It is recommended that you are familiar with the Invocation API before you follow along with this document. (See "Invoking LiveCycle ES Processes" in Programming with LiveCycle ES.)

Summary of steps

To create a Java servlet that invokes a LiveCycle ES process, perform the following steps:

  1. Create a new web project.
  2. Create Java application logic that represents the Java servlet.
  3. Create the web page for the web application.
  4. Package the web application to a WAR file.
  5. Deploy the WAR file to the J2EE application server.
  6. Test your web application.

Note: Some of these steps depend on the J2EE application on which LiveCycle ES is deployed. For example, the method you use to deploy a WAR file depends on the J2EE application server that you are using. This document assumes that LiveCycle ES is deployed on JBoss®.

Creating a web project

The first step to create a Java servlet that can invoke a LiveCycle ES process is to create a new web project. The Java IDE that this document is based on is Eclipse 3.3. Using the Eclipse IDE, create a web project and add the required JAR files to your project. Finally, add an HTML page named index.html and a Java servlet to your project.

The following list specifies the JAR files that you must add to your web project:

  • adobe-forms-client.jar
  • adobe-livecycle-client.jar
  • adobe-usermanager-client.jar
  • adobe-utilities.jar

For the location of these JAR files, see "Including LiveCycle ES Java library files" in Programming with LiveCycle ES.

Note: The adobe-forms-client.jar file is required because the process returns a FormsResult object, which is defined in this JAR file.

To create a web project:

  1. Start Eclipse and click File > New Project.
  2. In the New Project dialog box, select Web > Dynamic Web Project.
  3. Type InvokeMortgageProcess for the name of your project and then click Finish.

To add required JAR files to your project:

  1. From the Project Explorer window, right-click the InvokeMortgageProcess project and select Properties.
  2. Click Java build path and then click the Libraries tab.
  3. Click the Add External JARs button and browse to the JAR files to include.

To add a Java servlet to your project:

  1. From the Project Explorer window, right-click the Invoke Mortgage Process project and select New > Other.
  2. Expand the Web folder, select Servlet, and then click Next.
  3. In the Create Servlet dialog box, type GetForm for the name of the servlet and then click Finish.

To add an HTML page to your project:

  1. From the Project Explorer window, right-click the Invoke Mortgage Process project and select New > Other.
  2. Expand the Web folder, select HTML, and click Next.
  3. In the New HTML dialog box, type index.html for the file name and then click Finish.

Creating Java application logic for the servlet

You create Java application logic that invokes the GetMortgageForm process from within the Java servlet. To invoke a LiveCycle ES process, such as the GetMortgageForm process, use the Invocation API. The following code shows the syntax of the GetForm Java Servlet:

public class GetForm extends HttpServlet implements Servlet { public void doGet(HttpServletRequest req, HttpServletResponse resp throws ServletException, IOException { doPost(req,resp); } public void doPost(HttpServletRequest req, HttpServletResponse resp throws ServletException, IOException { //Add Invocation API code here to invoke the LiveCycle ES Process }

Normally, you would not place client code within a Java servlet's doGet or doPost methods. A better programming practice is to place this code within a separate class, instantiate the class from within the doPost method (or doGet method), and call the appropriate methods. However, for code brevity, the code examples in this section are kept to a minimum and code examples are placed in the doPost method.

When invoking a LiveCycle ES process, you must prepare input values that are required by the process. This step is specific to the process. That is, if the process requires four input values, you must prepare four input values to pass to the process. The GetMortgageForm process requires two input parameters.

When using the Java Invocation API to invoke a process, pass required input values by using a java.util.HashMap object. For each parameter to pass, invoke the java.util.HashMap object's put method and specify the name-value pair that is required by the process. You must specify the exact name of the parameter that belongs to the process and a corresponding value. For example, if the name of the input parameter is custId and requires string value, you can create a String variable to pass to the process.

To invoke a LiveCycle ES process by using the Invocation API, perform the following tasks:

  • Within the Java servlet's doPost method, create a ServiceClientFactory object that contains connection properties. (See "Setting connection properties" in Programming with LiveCycle ES.)
  • Create a ServiceClient object by using its constructor and passing the ServiceClientFactory object. A ServiceClient object lets you invoke a service operation. It handles tasks such as locating, dispatching, and routing invocation requests
  • Create a java.util.HashMap object by using its constructor.
  • Invoke the java.util.HashMap object's put method for each input parameter to pass to the long-lived process. The GetMortgageForm process requires two string input values: a custom identifier value and the form name.
  • Create an InvocationRequest object by invoking the ServiceClientFactory object's createInvocationRequest method and passing the following values:
    • A string value that specifies the name of the process to invoke. In this situation, specify GetMortgageForm.
    • A string value that represents the name of the process operation. Typically, the name of a process operation is invoke.
    • The java.util.HashMap object that contains the parameter values that the service operation requires.
    • A Boolean value that specifies true, which creates a synchronous request (used to invoke a short-lived operation).

Note: The difference between invoking a long-lived process and a short-lived process is that a short-lived process can be invoked by passing the value true and the fourth parameter of the createInvocationRequest method. Passing the value true creates a synchronous request.

  • Send the invocation request to LiveCycle ES by invoking the ServiceClient object's invoke method and passing the InvocationRequest object. The invoke method returns an InvocationReponse object.
  • Retrieve the return value of the process by invoking the InvocationReponse object's getOutputParameter method and passing a string value that specifies the name of the output parameter. The name of the output parameter for the GetMortgageForm process is RenderedForm. This is a process variable and its data type is FormsResult. Cast the getOutputParameter method's return value to FormResult.
  • Create a com.adobe.idp.Document object by invoking the FormsResult object ‘s getOutputContent method. The FormResult object contains the interactive form returned by the process.
  • Get the content type of the com.adobe.idp.Document object by invoking its getContentType method.
  • Set the javax.servlet.http.HttpServletResponse object's content type by invoking its setContentType method and passing the content type of the com.adobe.idp.Document object.
  • Create a javax.servlet.ServletOutputStream object that is used to write the form data stream to the client web browser by invoking the javax.servlet.http.HttpServletResponse object's getOutputStream method.
  • Create a java.io.InputStream object by invoking the com.adobe.idp.Document object's getInputStream method.
  • Create a byte array and allocate the size of the InputStream object. Invoke the InputStream object's available method to obtain the size of the InputStream object.
  • Populate the byte array with the form data stream by invoking the InputStream object's read method and passing the byte array as an argument.
  • Invoke the javax.servlet.ServletOutputStream object's write method to send the form data stream to the client web browser. Pass the byte array to the write method.

The following code example represents the Java servlet that invokes the GetMortgageForm short-lived process.

/* * This Java Servlet uses the following JAR files * 1. adobe-forms-client.jar * 2. adobe-livecycle-client.jar * 3. adobe-usermanager-client.jar * 4. adobe-utilities.jar * * These JAR files are located in the following path: * <install directory>/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.IOException; import java.io.InputStream; import java.util.HashMap; import java.util.Map; import java.util.Properties; import javax.servlet.ServletException; import javax.servlet.ServletOutputStream; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.adobe.idp.Document; import com.adobe.idp.dsc.clientsdk.ServiceClientFactory; import com.adobe.idp.dsc.clientsdk.ServiceClient; import com.adobe.idp.dsc.clientsdk.ServiceClientFactoryProperties; import com.adobe.idp.dsc.InvocationRequest; import com.adobe.idp.dsc.InvocationResponse; import com.adobe.livecycle.formsservice.client.FormsResult; /** * This Java servlet invokes the LiveCycle ES GetMortgageForm short-lived process */ public class GetForm extends javax.servlet.http.HttpServlet implements javax.servlet.Servlet { static final long serialVersionUID = 1L; public GetForm() { super(); } protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request,response); } protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { try{ String custId = null; String formName = null; //Get the values submitted from the web page custId = request.getParameter("custID"); formName = request.getParameter("formName"); //Set connection properties required to invoke LiveCycle ES Properties connectionProps = new Properties(); connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://localhost: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 object ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps); //Create a ServiceClient object ServiceClient myServiceClient = myFactory.getServiceClient(); //Create a Map object to store the parameter value Map params = new HashMap(); //Populate the Map object with a parameter value //required to invoke the GetMortgageForm process params.put("formName", formName); params.put("custId", custId); //Create an InvocationRequest object InvocationRequest esRequest = myFactory.createInvocationRequest( "GetMortgageForm", //Specify the LiveCycle ES process name "invoke", //Specify the operation name params, //Specify input values true); //Create a synchronous request //Send the invocation request to the process and //get back an invocation response object InvocationResponse esResponse = myServiceClient.invoke(esRequest); FormsResult formOut = (FormsResult)esResponse.getOutputParameter("RenderedForm"); //Create a Document object that stores form data Document myData = formOut.getOutputContent(); //Get the content type of the response and //set the HttpServletResponse object's content type String contentType = myData.getContentType(); response.setContentType(contentType); //Create a ServletOutputStream object ServletOutputStream oOutput = response.getOutputStream(); //Create an InputStream object InputStream inputStream = myData.getInputStream(); //Get the size of the InputStream object int size = inputStream.available(); //Create and populate a byte array byte[] data = new byte[size]; inputStream.read(data); //Write the data stream to the web browser oOutput.write(data); }catch (Exception e) { e.printStackTrace(); } } }

Creating the web page

The index.html web page provides an entry point to the Java servlet and invokes the GetMortgage process. This web page is a basic HTML form that contains two text boxes and a submit button. The names of the text boxes are custID and formName. When the user clicks the submit button, form data is posted to the GetForm Java servlet.

The following illustration shows the contents of the HTML page (see Figure 4).

The Java servlet captures the data that is posted from the HTML page by using the following Java code:

//Get the values submitted from the web page String custId = request.getParameter("custID"); String formName = request.getParameter("formName");

The following HTML code is located in the index.html file that was created during setup of the development environment.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Web Application</title> </head> <body> <form name="form1" action="/InvokeMortgageProcess/GetForm" method="post"> <br> <label>Customer Id <input type="text" name="custID" id="custID" /></label> <br> <label>Form Name <select name="formName" id="formName"> <option>Mortgage Form</option> <option>Car Loan</option> <option>Personnal Loan</option> </select> </label> <br> <label>submit <input type="submit" name="submit" id="submit" value="submit" /> </label> </form> </body> </html>

Packaging the web application

To deploy the Java servlet that invokes the GetMortgageForm process, package your web application to a WAR file. Ensure that external JAR files that the component's business logic depends on, such as adobe-livecycle-client.jar and adobe-forms-client.jar, are also included in the WAR file.

The following illustration shows the Eclipse project's content, which is packaged to a WAR file (see Figure 5).

To package a web application to a WAR file:

  1. From the Project Explorer window, right-click the InvokeMortgageProcess project and select Export > WAR file.
  2. In the Web module text box, type InvokeMortgageProcess for the name of the Java project.
  3. In the Destination text box, type InvokeMortgageProcess for the file name, specify the location for your WAR file, and then click Finish.

Deploying the WAR file to the J2EE application server

You can deploy the WAR file to the J2EE application server on which LiveCycle ES is deployed. After the WAR file is deployed, you can access the HTML web page that invokes the GetMortgageForm process by using a web browser.

To package a web application to a WAR file:

  • Copy the WAR file from the export path to [LiveCycle Install]\Adobe\LiveCycle8.2\jboss\server\all\deploy.

Testing your web application

After you deploy the web application, you can test it by using a web browser. Assuming that you are using the same computer that is hosting LiveCycle ES, you can specify the following URL:

http://localhost:8080/InvokeMortgageProcess/index.html

Enter a customer identifier value and a form name, and then click the submit button. If problems occur, see the J2EE application server's log file.

Attributions

For more information about creating applications that invoke LiveCycle ES, see Programming with LiveCycle ES.