Invoking AEM Forms using the Java API invoking-aem-forms-using-the-javaapi

Samples and examples in this document are only for AEM Forms on JEE environment.

AEM Forms can be invoked by using the AEM Forms Java API. When using the AEM Forms Java API, you can use either the Invocation API or Java client libraries. Java client libraries are available for services such as the Rights Management service. These strongly typed APIs let you develop Java applications that invoke AEM Forms.

The Invocation API are classes that are in the com.adobe.idp.dsc package. Using these classes, you can send an invocation request directly to a service and handle an invocation response that is returned. Use the Invocation API to invoke short-lived or long-lived processes that were created by using Workbench.

The recommended way to programmatically invoke a service is to use a Java client library that corresponds to the service as opposed to the Invocation API. For example, to invoke the Encryption service, use the Encryption service client library. To perform an Encryption service operation, invoke a method that belongs to the Encryption service client object. You can encrypt a PDF document with a password by invoking the EncryptionServiceClient object’s encryptPDFUsingPassword method.

The Java API supports the following features:

Including AEM Forms Java library files

Invoking Human-Centric Long-Lived Processes

Invoking AEM Forms using Web Services

Setting connection properties

Passing data to AEM Forms services using the Java API

Invoking a service using a Java client library

Invoking a short-lived process using the Invocation API

Creating a Java web application that invokes a human-centric long-lived process

Including AEM Forms Java library files including-aem-forms-java-library-files

To programmatically invoke a AEM Forms service by using the Java API, include required library files (JAR files) in your Java project’s classpath. The JAR files that you include in your client application’s classpath depend on several factors:

Service-specific JAR files service-specific-jar-files

The following table lists the JAR files that are required to invoke AEM Forms services.

Connection mode and J2EE application JAR files connection-mode-and-j2ee-application-jar-files

The following table lists the JAR files that are dependant upon the connection mode and the J2EE application server on which AEM Forms is deployed.

Invoking scenarios invoking-scenarios

The following table specifies invoking scenarios and lists the required JAR files to successfully invoke AEM Forms.

Upgrading JAR files upgrading-jar-files

If you are upgrading from LiveCycle to AEM Forms, it is recommeded that you include the AEM Forms JAR files in your Java project’s class path. For example, if you are using services such as the Rights Management service, you will encounter a compatibility issue if you do not include AEM Forms JAR files in your class path.

Assuming that you are upgrading to AEM Forms. To use a Java application that invokes the Rights Management service, include the AEM Forms versions of the following JAR files:

See also

Invoking AEM Forms using the Java API

Setting connection properties

Passing data to AEM Forms services using the Java API

Invoking a service using a Java client library

Setting connection properties setting-connection-properties

You set connection properties to invoke AEM Forms when using the Java API. When setting connection properties, specify whether to invoke services remotely or locally, and also specify the connection mode and authentication values. Authentication values are required if service security is enabled. However, if service security is disabled, it is not necessary to specify authentication values.

The connection mode can either be SOAP or EJB mode. The EJB mode uses the RMI/IIOP protocol, and the performance of the EJB mode is better than the performance of the SOAP mode. The SOAP mode is used to eliminate a J2EE application server dependency or when a firewall is located between AEM Forms and the client application. The SOAP mode uses the https protocol as the underlying transport and can communicate across firewall boundaries. If neither a J2EE application server dependency or a firewall is an issue, it is recommended that you use the EJB mode.

To successfully invoke a AEM Forms service, set the following connection properties:

To set connection properties, perform the following tasks:

Setting the EJB connection mode for JBoss

The following Java code example sets connection properties to invoke AEM Forms deployed on JBoss and using the EJB connection mode.

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "https://<hostname>:8080");
 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");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DOCUMENT_HTTP_ENDPOINT,"https://<hostname>:8080");

Setting the EJB connection mode for WebLogic

The following Java code example sets connection properties to invoke AEM Forms deployed on WebLogic and using the EJB connection mode.

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "t3://localhost:7001");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebLogic");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting the EJB connection mode for WebSphere

The following Java code example sets connection properties to invoke AEM Forms deployed on WebSphere and using the EJB connection mode.

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "iiop://localhost:2809");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "WebSphere");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting the SOAP connection mode

The following Java code example sets connection properties in SOAP mode to invoke AEM Forms deployed on JBoss.

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");

Setting connection properties when service security is disabled

The following Java code example sets connection properties required to invoke AEM Forms deployed on JBoss Application Server and when service security is disabled.

 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");

Setting the SOAP connection mode with custom request timeout limit

 Properties ConnectionProps = new Properties();
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://localhost:8080");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL,ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, "JBoss");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
 ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");
ConnectionProps.setProperty(ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT, "1800000"); // Request timeout limit 30 Minutes

Using a Context object to invoke AEM Forms

You can use a com.adobe.idp.Context object to invoke a AEM Forms service with an authenticated user (the com.adobe.idp.Context object represents an authenticated user). When using a com.adobe.idp.Context object, you do not need to set the DSC_CREDENTIAL_USERNAME or DSC_CREDENTIAL_PASSWORD properties. You can obtain a com.adobe.idp.Context object when authenicating users by using the AuthenticationManagerServiceClient object’s authenticate method.

The authenticate method returns an AuthResult object that contains the results of the authentication. You can create a com.adobe.idp.Context object by invoking its constructor. Then invoke the com.adobe.idp.Context object’s initPrincipal method and pass the AuthResult object, as shown in the following code:

 Context myCtx = new Context();
 myCtx.initPrincipal(authResult);

Instead of setting the DSC_CREDENTIAL_USERNAME or DSC_CREDENTIAL_PASSWORD properties, you can invoke the ServiceClientFactory object’s setContext method and pass the com.adobe.idp.Context object. When using an AEM forms user to invoke a service, ensure that they have the role named Services User that is required to invoke a AEM Forms service.

The following code example shows how to use a com.adobe.idp.Context object within connection settings that are used to create an EncryptionServiceClient object.

 //Authenticate a user and use the Context object within connection settings
 // Authenticate the user
 String username = "wblue";
 String password = "password";
 AuthResult authResult = authClient.authenticate(username, password.getBytes());

 //Set a Content object that represents the authenticated user
 //Use the Context object to invoke the Encryption service
 Context myCtx = new Context();
 myCtx.initPrincipal(authResult);

 //Set connection settings
 Properties connectionProps = new Properties();
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT, "jnp://<server>:1099");
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_EJB_PROTOCOL);
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE);
 connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DOCUMENT_HTTP_ENDPOINT,"jnp://<server>:1099");


 //Create a ServiceClientFactory object
 ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps);
 myFactory.setContext(myCtx);

 //Create an EncryptionServiceClient object
 EncryptionServiceClient encryptClient  = new EncryptionServiceClient(myFactory);

Invoking scenarios invoking_scenarios-1

The following invoking scenarios are discussed in this section:

Client application invoking a stand-alone AEM Forms instance client-application-invoking-a-stand-alone-aem-forms-instance

The following diagram shows a client application running in its own JVM and invoking a stand-alone AEM Forms instance.

In this scenario, a client application is running in its own JVM and invokes AEM Forms services.

Client application invoking clustered AEM Forms instances client-application-invoking-clustered-aem-forms-instances

The following diagram shows a client application running in its own JVM and invoking AEM Forms instances in a cluster.

This scenario is similar to a client application invoking a stand-alone AEM Forms instance. However, the provider URL is different. If a client application wants to connect to a specific J2EE application server, the application must change the URL to reference the specific J2EE application server.

Referencing a specific J2EE application server is not recommended because the connection between the client application and AEM Forms is terminated if the application server stops. It is recommended that the provider URL reference a cell-level JNDI manager, instead of a specific J2EE application server.

Client applications that use the SOAP connection mode can use the HTTP load balancer port for the cluster. Client applications that use the EJB connection mode can connect to the EJB port of a specific J2EE application server. This action handles the Load Balancing between cluster nodes.

WebSphere

The following example shows the contents of a jndi.properties file that is used to connect to AEM Forms that is deployed on WebSphere.

 java.naming.factory.initial=com.ibm.websphere.naming.
 WsnInitialContextFactory
 java.naming.provider.url=corbaloc::appserver1:9810,:appserver2:9810

WebLogic

The following example shows the contents of a jndi.properties file that is used to connect to AEM Forms that is deployed on WebLogic.

 java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory
 java.naming.provider.url=t3://appserver1:8001, appserver2:8001

JBoss

The following example shows the contents of a jndi.properties file that is used to connect to AEM Forms that is deployed on JBoss.

 java.naming.factory.initial= org.jnp.interfaces.NamingContextFactory
 java.naming.provider.url= jnp://appserver1:1099, appserver2:1099,
 appserver3:1099

See also

Including AEM Forms Java library files

Passing data to AEM Forms services using the Java API

Invoking a service using a Java client library

Passing data to AEM Forms services using the Java API passing-data-to-aem-forms-services-using-the-java-api

AEM Forms service operations typically consume or produce PDF documents. When you invoke a service, sometimes it is necessary to pass a PDF document (or other document types such as XML data) to the service. Likewise sometimes it is necessary to handle a PDF document that is returned from the service. The Java class that enables you to pass data to and from AEM Forms services is com.adobe.idp.Document.

AEM Forms services do not accept a PDF document as other data types, such as a java.io.InputStream object or a byte array. A com.adobe.idp.Document object can also be used to pass other types of data, such as XML data, to services.

A com.adobe.idp.Document object is a Java serializable type, so it can be passed over an RMI call. The receiving side can be collocated (same host, same class loader), local (same host, different class loader), or remote (different host). Passing of document content is optimized for each case. For example, if the sender and receiver are located on the same host, the content is passed over a local file system. (In some cases, documents can be passed in memory.)

Depending on the com.adobe.idp.Document object size, the data is carried within the com.adobe.idp.Document object or stored on the server’s file system. Any temporary storage resources occupied by the com.adobe.idp.Document object are removed automatically upon the com.adobe.idp.Document disposal. (See Disposing Document objects.)

Sometimes it is necessary to know the content type of a com.adobe.idp.Document object before you can pass it to a service. For example, if an operation requires a specific content type, such as application/pdf, it is recommended that you determine the content type. (See Determining the content type of a document.)

The com.adobe.idp.Document object attempts to determine the content type using the supplied data. If the content type cannot be retrieved from the data supplied (for example, when the data was supplied as a byte array), set the content type. To set the content type, invoke the com.adobe.idp.Document object’s setContentType method. (See Determining the content type of a document)

If collateral files reside on the same file system, creating a com.adobe.idp.Document object is faster. If collateral files reside on remote file systems, a copy operation must be done, which affects performance.

An application can contain both com.adobe.idp.Document and org.w3c.dom.Document data types. However, ensure that you fully qualify the org.w3c.dom.Document data type. For information about converting a org.w3c.dom.Document object to a com.adobe.idp.Document object, see Quick Start (EJB mode): Prepopulating Forms with Flowable Layouts using the Java API.

        // Set up the chunk size to prevent a potential memory leak
        int buffSize = 2048;

        // Determine the total number of bytes to read
        int docLength = (int) inDoc.length();
        byte [] byteDoc = new byte[docLength];

        // Set up the reading position
        int pos = 0;

        // Loop through the document information, 2048 bytes at a time
        while (docLength > 0) {
      // Read the next chunk of information
            int toRead = Math.min(buffSize, docLength);
            int bytesRead = inDoc.read(pos, byteDoc, pos, toRead);

            // Handle the exception in case data retrieval failed
            if (bytesRead == -1) {

                inDoc.doneReading();
                inDoc.dispose();
                throw new RuntimeException("Data retrieval failed!");

            }

             // Update the reading position and number of bytes remaining
             pos += bytesRead;
             docLength -= bytesRead;

        }

        // The document information has been successfully read
        inDoc.doneReading();
        inDoc.dispose();

See also

Invoking AEM Forms using the Java API

Setting connection properties

Creating documents creating-documents

Create a com.adobe.idp.Document object before you invoke a service operation that requires a PDF document (or other document types) as an input value. The com.adobe.idp.Document class provides constructors that enable you to create a document from the following content types:

Creating a document based on a byte array creating-a-document-based-on-a-byte-array

The following code example creates a com.adobe.idp.Document object that is based on a byte array.

Creating a Document object that is based on a byte array

 Document myPDFDocument = new Document(myByteArray);

Creating a document based on another document creating-a-document-based-on-another-document

The following code example creates a com.adobe.idp.Document object that is based on another com.adobe.idp.Document object.

Creating a Document object that is based on another document

 //Create a Document object based on a byte array
 InputStream is = new FileInputStream("C:\\Map.pdf");
 int len = is.available();
 byte [] myByteArray = new byte[len];
 int i = 0;
 while (i < len) {
       i += is.read(myByteArray, i, len);
 }
 Document myPDFDocument = new Document(myByteArray);

 //Create another Document object
 Document anotherDocument = new Document(myPDFDocument);

Creating a document based on a file creating-a-document-based-on-a-file

The following code example creates a com.adobe.idp.Document object that is based on a PDF file named map.pdf. This file is in the root of the C hard drive. This constructor attempts to set the MIME content type of the com.adobe.idp.Document object using the filename extension.

The com.adobe.idp.Document constructor that accepts a java.io.File object also accepts a Boolean parameter. By setting this parameter to true, the com.adobe.idp.Document object deletes the file. This action means that you do not have to remove the file after passing it to the com.adobe.idp.Document constructor.

Setting this parameter to false means that you retain ownership of this file. Setting this parameter to true is more efficient. The reason is because the com.adobe.idp.Document object can move the file directly to the local managed area instead of copying it (which is slower).

Creating a Document object that is based on a PDF file

 //Create a Document object based on the map.pdf source file
 File mySourceMap = new File("C:\\map.pdf");
 Document myPDFDocument = new Document(mySourceMap,true);

Creating a document based on an InputStream object creating-a-document-based-on-an-inputstream-object

The following Java code example creates a com.adobe.idp.Document object that is based on a java.io.InputStream object.

Creating a document based on an InputStream object

 //Create a Document object based on an InputStream object
 InputStream is = new FileInputStream("C:\\Map.pdf");
 Document myPDFDocument = new Document(is);

Creating a document based on content accessible from a URL creating-a-document-based-on-content-accessible-from-an-url

The following Java code example creates a com.adobe.idp.Document object that is based on a PDF file named map.pdf. This file is located within a web application named WebApp that is running on localhost. This constructor attempts to set the com.adobe.idp.Document object’s MIME content type using the content type returned with the URL protocol.

The URL supplied to the com.adobe.idp.Document object is always read at the side where the original com.adobe.idp.Document object is created, as shown in this example:

     Document doc = new Document(new java.net.URL("file:c:/temp/input.pdf"));

The c:/temp/input.pdf file must be located on the client computer (not on the server computer). The client computer is where the URL is read and where the com.adobe.idp.Document object was created.

Creating a document based on content accessible from a URL

 //Create a Document object based on a java.net.URL object
 URL myURL = new URL("http", "localhost", 8080,"/WebApp/map.pdf");

 //Create another Document object
 Document myPDFDocument = new Document(myURL);

See also

Invoking AEM Forms using the Java API

Setting connection properties

Handling returned documents handling-returned-documents

Service operations that return a PDF document (or other data types such as XML data) as an output value return a com.adobe.idp.Document object. After you receive a com.adobe.idp.Document object, you can convert it to the following formats:

The following line of code converts a com.adobe.idp.Document object to a java.io.InputStream object. Assume that myPDFDocument represents a com.adobe.idp.Document object:

     java.io.InputStream resultStream = myDocument.getInputStream();

Likewise, you can copy the contents of a com.adobe.idp.Document to a local file by performing the following tasks:

The following code example copies the contents of a com.adobe.idp.Document object to a file named AnotherMap.pdf.

Copying the contents of a document object to a file

 File outFile = new File("C:\\AnotherMap.pdf");
 myDocument.copyToFile (outFile);

See also

Invoking AEM Forms using the Java API

Setting connection properties

Determining the content type of a document determining-the-content-type-of-a-document

Determine the MIME type of a com.adobe.idp.Document object by invoking the com.adobe.idp.Document object’s getContentType method. This method returns a string value that specifies the content type of the com.adobe.idp.Document object. The following table describes the different content types that AEM Forms returns.

The following code example determines the content type of a com.adobe.idp.Document object.

Determining the content type of a Document object

 //Determine the content type of the Document object
 String ct = myDocument.getContentType();
 System.out.println("The content type of the Document object is " +ct);

See also

Invoking AEM Forms using the Java API

Setting connection properties

Disposing Document objects disposing-document-objects

When you no longer require a Document object, it is recommended that you dispose of it by invoking its dispose method. Each Document object consumes a file descriptor and as much as 75 MB of RAM space on your application’s host platform. If a Document object is not disposed, then the Java Garage collection process disposes it. However, by disposing of it sooner by using the dispose method, you can free the memory occupied by the Document object.

See also

Invoking AEM Forms using the Java API

Including AEM Forms Java library files

Invoking a service using a Java client library

Invoking a service using a Java client library invoking-a-service-using-a-java-client-library

AEM Forms service operations can be invoked by using a service’s strongly typed API, which is known as a Java client library. A Java client library is a set of concrete classes that provide access to services deployed in the service container. You instantiate a Java object that represents the service to invoke instead of creating an InvocationRequest object by using the Invocation API. The Invocation API is used to invoke processes, such as long-lived processes, created in Workbench. (See Invoking Human-Centric Long-Lived Processes.)

To perform a service operation, invoke a method that belongs to the Java object. A Java client library contains methods that typically map one-to-one with service operations. When using a Java client library, set required connection properties. (See Setting connection properties.)

After you set connection properties, create a ServiceClientFactory object that is used to instantiate a Java object that lets you invoke a service. Each service that has a Java client library has a corresponding client object. For example, to invoke the Repository service, create a ResourceRepositoryClient object by using its constructor and passing the ServiceClientFactory object. The ServiceClientFactory object is responsible for maintaining connection settings that are required to invoke AEM Forms services.

Although obtaining a ServiceClientFactory is typically fast, some overhead is involved when the factory is first used. This object is optimized for reuse and therefore, when possible, use the same ServiceClientFactory object when you are creating multiple Java client objects. That is, do not create a separate ServiceClientFactory object for each client library object that you create.

There is a User Manager setting that controls the lifetime of the SAML assertion that is inside the com.adobe.idp.Context object that affects the ServiceClientFactory object. This setting controls all authentication context lifetimes throughout AEM Forms, including all invocations performed by using the Java API. By default, the time period in which a ServiceCleintFactory object can be used is two hours.

You can invoke the Repository service by using a Java client library and by performing the following steps:

See also

Quick Start (EJB mode): Writing a resource using the Java API

Invoking AEM Forms using the Java API

Including AEM Forms Java library files

Invoking a short-lived process using the Invocation API invoking-a-short-lived-process-using-the-invocation-api

You can invoke a short-lived process using the Java Invocation API. When you invoke a short-lived process using the Invocation API, you pass required parameter values by using a java.util.HashMap object. For each parameter to pass to a service, invoke the java.util.HashMap object’s put method and specify the name-value pair that is required by the service to perform the specified operation. Specify the exact name of the parameters that belong to the short-lived process.

The discussion here is about using Invocation API to invoke the following AEM Forms short-lived process named MyApplication/EncryptDocument.

When this process is invoked, it performs the following actions:

Invoke the MyApplication/EncryptDocument short-lived process using the Java invocation API invoke-the-myapplication-encryptdocument-short-lived-process-using-the-java-invocation-api

Invoke the MyApplication/EncryptDocument short-lived process using the Java invocation API:

See also

Quick Start: Invoking a short-lived process using the Invocation API

Invoking Human-Centric Long-Lived Processes

Including AEM Forms Java library files