Passing data to LiveCycle services using the Java API

LiveCycle 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 LiveCycle services is com.adobe.idp.Document.

LiveCycle 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();

// Ethnio survey code removed