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