You're viewing help content for version:
- 6.5
- 6.4
- 6.3
- Older Versions
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 located 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:
RMI transport protocol for remote invocation
VM transport for local invocation
SOAP for remote invocation
Different authentication, such as user name and password
Synchronous and asynchronous invocation requests
The Adobe Developer website contains the following articles that discuss invoking AEM Forms services using the Java API:
Including AEM Forms Java library files
Invoking Human-Centric Long-Lived Processes
Invoking AEM Forms using Web Services
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
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:
The AEM Forms service to invoke. A client application can invoke one or more services.
The mode in which you want to invoke a AEM Forms service. You can use the EJB or SOAP mode. (See Setting connection properties.)
The J2EE application server on which AEM Forms is deployed.
File |
Description |
Location |
|---|---|---|
adobe-livecycle-client.jar |
Must always be included in a Java client application’s class path. |
<install directory>/sdk/client-libs/common |
adobe-usermanager-client.jar |
Must always be included in a Java client application’s class path. |
<install directory>/sdk/client-libs/common |
adobe-utilities.jar |
Must always be included in a Java client application’s class path. |
<install directory>/sdk//client-libs/<app server> |
adobe-applicationmanager-client-sdk.jar |
Required to invoke the Application Manager service. |
<install directory>/sdk/client-libs/common |
adobe-assembler-client.jar |
Required to invoke the Assembler service. |
<install directory>/sdk/client-libs/common |
adobe-backup-restore-client-sdk.jar |
Required to invoke the Backup and Restore service API. |
<install directory>/sdk/client-libs/common |
adobe-barcodedforms-client.jar |
Required to invoke the barcoded forms service. |
<install directory>/sdk/client-libs/common |
adobe-convertpdf-client.jar |
Required to invoke the Convert PDF service. |
<install directory>/sdk/client-libs/common |
adobe-distiller-client.jar |
Required to invoke the Distiller service. |
<install directory>/sdk/client-libs/common |
adobe-docconverter-client.jar |
Required to invoke the DocConverter service. |
<install directory>/sdk/client-libs/common |
adobe-contentservices-client.jar |
Required to invoke the Document Management service. |
<install directory>/sdk/client-libs/common |
adobe-encryption-client.jar |
Required to invoke the Encryption service. |
<install directory>/sdk/client-libs/common |
adobe-forms-client.jar |
Required to invoke the Forms service. |
<install directory>/sdk/client-libs/common |
adobe-formdataintegration-client.jar |
Required to invoke the Form Data Integration service. |
<install directory>/sdk/client-libs/common |
adobe-generatepdf-client.jar |
Required to invoke the Generate PDF service. |
<install directory>/sdk/client-libs/common |
adobe-generate3dpdf-client.jar |
Required to invoke the Generate 3D PDF service. |
<install directory>/sdk/client-libs/common |
adobe-jobmanager-client-sdk.jar |
Required to invoke the Job Manager service. |
<install directory>/sdk/client-libs/common |
adobe-output-client.jar |
Required to invoke the Output service. |
<install directory>/sdk/client-libs/common |
adobe-pdfutility-client.jar |
Required to invoke the PDF Utilities or XMP Utilities service. |
<install directory>/sdk/client-libs/common |
adobe-reader-extensions-client.jar |
Required to invoke the Acrobat Reader DC extensions service. |
<install directory>/sdk/client-libs/common |
adobe-repository-client.jar commons-codec-1.3.jar |
Required to invoke the Repository service. |
<install directory>/sdk/client-libs/common <install directory>/sdk/client-libs\thirdparty |
|
Required to invoke the Rights Management service. If AEM Forms is deployed on JBoss, include all these files. |
<install directory>/sdk/client-libs/common JBoss-specific lib directory |
adobe-signatures-client.jar |
Required to invoke the Signature service. |
<install directory>/sdk/client-libs/common |
adobe-taskmanager-client-sdk.jar |
Required to invoke the Task Manager service. |
<install directory>/sdk/client-libs/common |
adobe-truststore-client.jar |
Required to invoke the Trust Store service. |
<install directory>/sdk/client-libs/common |
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.
File |
Description |
Location |
|---|---|---|
|
if AEM Forms is invoked using the SOAP mode, include these JAR files. |
<install directory>/sdk/client-libs/thirdparty |
jbossall-client.jar |
if AEM Forms is deployed on JBoss Application Server, include this JAR file. The size of jbossall-client.jar is significantly lesser in JBoss 5.1.0. This is because JBoss 4.2.1 jbossall-client.jar packages all the classes required to connect to JBoss 4.2.1 server. However, JBoss 5.1.0 jbossall-client.jar does not package any classes. This jar file contains a classpath reference to various client jar files used by the JBoss client applications. When writing AEM Forms API-based programs where AEM Forms is running on JBoss 5.2.1, you must place jbossall-client.jar and all the referenced jars in a single folder and then include jbossall-client.jar in the classpath. Required classes will not be found by the classloader if jbossall-client.jar and the referenced jars are not co-located. |
JBoss client lib directory If you deploy your client application on the same J2EE application server, you do not need to include this file. |
|
if AEM Forms is deployed on JBoss Application Server, include this JAR file. |
JBoss client lib directory If you deploy your client application on the same J2EE application server, you do not need to include this file. |
wlclient.jar |
if AEM Forms is deployed on BEA WebLogic Server®, then include this JAR file. |
WebLogic-specific lib directory If you deploy your client application on the same J2EE application server, you do not need to include this file. |
|
|
WebSphere-specific lib directory ([WAS_HOME]/runtimes) If you deploy your client application on the same J2EE application server, you do not have to include these files. |
The following table specifies invoking scenarios and lists the required JAR files to successfully invoke AEM Forms.
Services |
Invocation mode |
J2EE application server |
Required JAR files |
|---|---|---|---|
Forms service |
EJB |
JBoss |
|
Forms service Acrobat Reader DC extensions service Signature service |
EJB |
JBoss |
|
Forms service |
SOAP |
WebLogic |
|
Forms service Acrobat Reader DC extensions service Signature service |
SOAP |
WebLogic |
|
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:
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. (See Disabling Service Security.)
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:
DSC_DEFAULT_EJB_ENDPOINT: If you are using the EJB connection mode, this value represents the URL of the J2EE application server on which AEM Forms is deployed. To remotely invoke AEM Forms, specify the J2EE application server name on which AEM Forms is deployed. If your client application is located on the same J2EE application server, then you can specify localhost. Depending on which J2EE application server AEM Forms is deployed on, specify one of the following values:
JBoss: jnp://<ServerName>:1099 (default port)
WebSphere: iiop://<ServerName>:2809 (default port)
WebLogic: t3://<ServerName>:7001 (default port)
DSC_DEFAULT_SOAP_ENDPOINT: If you are using the SOAP connection mode, this value represents the endpoint to where an invocation request is sent. To remotely invoke AEM Forms, specify the J2EE application server name on which AEM Forms is deployed. If your client application is located on the same J2EE application server, you can specify localhost (for example, http://localhost:8080.)
The port value 8080 is applicable if the J2EE application is JBoss. If the J2EE application server is IBM® WebSphere®, use port 9080. Likewise, if the J2EE application server is WebLogic, use port 7001. (These values are default port values. If you change the port value, use the applicable port number.)
DSC_TRANSPORT_PROTOCOL: If you are using the EJB connection mode, specify ServiceClientFactoryProperties.DSC_EJB_PROTOCOL for this value. If you are using the SOAP connection mode, specify ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL.
DSC_SERVER_TYPE: Specifies the J2EE application server on which AEM Forms is deployed. Valid values are JBoss, WebSphere, WebLogic.
If you set this connection property to WebSphere, the java.naming.factory.initial value is set to com.ibm.ws.naming.util.WsnInitCtxFactory.
If you set this connection property to WebLogic, the java.naming.factory.initial value is set to weblogic.jndi.WLInitialContextFactory.
Likewise, if you set this connection property to JBoss, the java.naming.factory.initial value is set to org.jnp.interfaces.NamingContextFactory.
You can set the java.naming.factory.initial property to a value that meets your requirements if you do not want to use the default values.
Note: Instead of using a string to set the DSC_SERVER_TYPE connection property, you can use a static member of the ServiceClientFactoryProperties class. The following values can be used: ServiceClientFactoryProperties.DSC_WEBSPHERE_SERVER_TYPE, ServiceClientFactoryProperties.DSC_WEBLOGIC_SERVER_TYPE, or ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE.
DSC_CREDENTIAL_USERNAME: Specifies the AEM forms user name. For a user to sucessfully invoke a AEM Forms service, they need the Services User role. A user can also have another role that includes the Service Invoke permission. Otherwise, an exception is thrown when they attempt to invoke a service. If service security is disabled, it is not necessary to specify this connection property. (See Disabling Service Security.)
DSC_CREDENTIAL_PASSWORD: Specifies the corresponding password value. If service security is disabled, it is not necessary to specify this connection property.
DSC_REQUEST_TIMEOUT: The default request timeout limit for the SOAP request is 1200000 milliseconds (20 minutes). Sometime, a request can require longer time to complete the operation. For example, a SOAP request that retrieves a large set of records can require a longer timeout limit. You can use the ServiceClientFactoryProperties.DSC_REQUEST_TIMEOUT to increase the request call timeout limit for the SOAP requests.
note: Only SOAP-based invocations support the DSC_REQUEST_TIMEOUT property.
-
To set the DSC_DEFAULT_EJB_ENDPOINT connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
The ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT enumeration value
A string value that specifies the URL of the J2EE application server that hosts AEM Forms
Note:
If you are using the SOAP connection mode, specify the ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT enumeration value instead of the ServiceClientFactoryProperties.DSC_DEFAULT_EJB_ENDPOINT enumeration value.
-
To set the DSC_TRANSPORT_PROTOCOL connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
The ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL enumeration value
The ServiceClientFactoryProperties.DSC_EJB_PROTOCOL enumeration value
Note:
If you are using the SOAP connection mode, specify the ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL enumeration value instead of the ServiceClientFactoryProperties.DSC_EJB_PROTOCOL enumeration value.
-
To set the DSC_SERVER_TYPE connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
The ServiceClientFactoryProperties.DSC_SERVER_TYPE enumeration value
A string value that specifies the J2EE application server that hosts AEM Forms (for example, if AEM Forms is deployed on JBoss, specify JBoss).
To set the DSC_CREDENTIAL_USERNAME connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
The ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME enumeration value
A string value that specifies the user name required to invoke AEM Forms
To set the DSC_CREDENTIAL_PASSWORD connection property, invoke the java.util.Properties object’s setProperty method and pass the following values:
The ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD enumeration value
A string value that specifies the corresponding password value
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, "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");
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");
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");
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");
Note:
If you select the SOAP connection mode, ensure to include additional JAR files in your client application’s class path.
The following Java code example sets connection properties required to invoke AEM Forms deployed on JBoss Application Server and when service security is disabled. (See Disabling Service Security.)
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");
Note:
All Java Quick Starts associated with Programming with AEM Forms show both EJB and SOAP connection settings.
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
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 a 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://hiro-xp:1099"); connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_EJB_PROTOCOL); connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE); //Create a ServiceClientFactory object ServiceClientFactory myFactory = ServiceClientFactory.createInstance(connectionProps); myFactory.setContext(myCtx); //Create an EncryptionServiceClient object EncryptionServiceClient encryptClient = new EncryptionServiceClient(myFactory);
Note:
For complete details about authenticating a user, see Authenticating Users.
A client application running in its own Java virtual machine (JVM) invokes a stand-alone AEM Forms instance.
A client application running in its own JVM invokes clustered AEM Forms instances.
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.
Note:
This scenario is the invoking scenario on which all Quick Starts are based.
The following diagram shows a client application running in its own JVM and invoking AEM Forms instances located 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.
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
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
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
Note:
Consult your administrator to determine the J2EE application server name and port number.
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.
Note:
To prevent a memory leak in WebLogic while using a com.adobe.idp.Document object, read the document information in chunks of 2048 bytes or less. For example, the following code reads the document information in chunks of 2048 bytes:
// 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();
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:
A byte array
An existing com.adobe.idp.Document object
A java.io.File object
A java.io.InputStream object
A java.net.URL object
Document myPDFDocument = new Document(myByteArray);
The following code example creates a com.adobe.idp.Document object that is based on another com.adobe.idp.Document object.
//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);
The following code example creates a com.adobe.idp.Document object that is based on a PDF file named map.pdf. This file is located 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).
//Create a Document object based on the map.pdf source file
File mySourceMap = new File("C:\\map.pdf");
Document myPDFDocument = new Document(mySourceMap,true);
The following Java code example creates a com.adobe.idp.Document object that is based on a java.io.InputStream object.
//Create a Document object based on an InputStream object
InputStream is = new FileInputStream("C:\\Map.pdf");
Document myPDFDocument = new Document(is);
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.
//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);
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.
File outFile = new File("C:\\AnotherMap.pdf");
myDocument.copyToFile (outFile);
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.
MIME type |
Description |
|---|---|
application/pdf |
PDF document |
application/vnd.adobe.xdp+xml |
XML Data Packaging (XDP), which is used for exported XML Forms Architecture (XFA) forms |
text/xml |
Bookmarks, attachments, or other XML documents |
application/vnd.fdf |
Forms Data Format (FDF), which is used for exported Acrobat forms |
application/vnd.adobe.xfdf |
XML Forms Data Format (XFDF), which is used for exported Acrobat forms |
application/rdf+xml |
Rich data format and XML |
application/octet-stream |
Generic data format |
NULL |
Unspecified MIME type |
//Determine the content type of the Document object
String ct = myDocument.getContentType();
System.out.println("The content type of the Document object is " +ct);
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.
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.
Note:
To explain how to invoke a service by using the Java API, the Repository service’s writeResource operation is invoked. This operation places a new resource into the repository.
You can invoke the Repository service by using a Java client library and by performing the following steps:
-
Include client JAR files, such as the adobe-repository-client.jar, in your Java project’s class path. For information about the location of these files, see Including AEM Forms Java library files.
-
Create a com.adobe.idp.Document object by passing a java.io.FileInputStream object that stores the XDP file to add to the repository. (See Creating a document based on an InputStream object.)
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 in order to perform the specified operation. Specify the exact name of the parameters that belong to the short-lived process.
Note:
For information about invoking a long-lived process, see Invoking Human-Centric Long-Lived Processes.
The discussion here is about using Invocation API to invoke the following AEM Forms short-lived process named MyApplication/EncryptDocument.
Note:
This process is not based on an existing AEM Forms process. To follow along with the code example, create a process named MyApplication/EncryptDocument using Workbench. (See Using Workbench.)
-
Include client JAR files, such as the adobe-livecycle-client.jar, in your Java project’s class path. (See Including AEM Forms Java library files.)
-
Create a ServiceClientFactory object that contains connection properties. (See Setting connection properties.)
-
Invoke the java.util.HashMap object’s put method for each input parameter to pass to the long-lived process. Because the MyApplication/EncryptDocument short-lived process requires one input parameter of type Document, you only have to invoke the put method once, as shown in the following example.
//Create a Map object to store the parameter value for inDoc Map params = new HashMap(); InputStream inFile = new FileInputStream("C:\\Adobe\Loan.pdf"); Document inDoc = new Document(inFile); params.put("inDoc", inDoc); -
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 long-lived process to invoke. To invoke the MyApplication/EncryptDocument process, specify MyApplication/EncryptDocument.
A string value that represents the process operation name. Typically the name of a short-lived 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 (this value is applicable to invoke a short-lived process).
-
Send the invocation request to the service by invoking the ServiceClient object’s invoke method and passing the InvocationRequest object. The invoke method returns an InvocationReponse object.
Note:
A long-lived process can be invoked by passing the value false as the fourth parameter of the createInvocationRequest method. Passing the value false creates an asynchronous request.
-
Retrieve the process’s return value by invoking the InvocationReponse object’s getOutputParameter method and passing a string value that specifies the name of the output parameter. In this situation, specify outDoc (outDoc is the name of the output parameter for the MyApplication/EncryptDocument process). Cast the return value to Document, as shown in the following example.
InvocationResponse response = myServiceClient.invoke(request); Document encryptDoc = (Document) response.getOutputParameter("outDoc");
Twitter™ and Facebook posts are not covered under the terms of Creative Commons.