| Package | com.adobe.idp |
| Class | public class Document |
| Inheritance | Document  Object
|
Document class passes data of arbitrary size between different LiveCycle services and components via remote RMI calls. The Document can also be used to store the data in process maps. These are the main features of the Document class:
Document content can be supplied or retrieved using various types: java.io.InputStream, com.adobe.service.DataBuffer, a file, or any in-memory object that provides special read or write routines. The content can also be supplied with a byte array. Document is a Java serializable type, so it can be passed over an RMI call (as opposed to java.io.InputStream). The receiving side can be collocated (same host, same class loader), local (same host, different class loader or an application server instance), or remote (different host). Passing of the 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). Document, the data is either stored in memory as part of the Document object, or saved on the disk as a file. Document collocate and share the same transaction, the in-memory object is passed directly with no extra serialization. Document content are removed automatically upon the Document disposal. The Document instance can be configured to be automatically disposed of by a timeout expiration, or by binding the Document lifetime to the current J2EE transaction. Below are some examples how to use the Document class.
java.io.InputStream is = new java.io.StringBufferInputStream("..."));
Document input = new Document(is);
input.passivate(); // save all data supplied by the input stream
someLiveCycleService.loadInputData(input);
someLiveCycleService.someBusinessMethod();
Document output = someLiveCycleService.saveOutputData();
java.io.InputStream resultStream = output.getInputStream();
... input.passivate call is optional. It simply guarantees that the input stream was fully read and detached from the Document instance. Without this call, reading the input stream is delayed until the data is requested, which in this case happens somewhere inside the someLiveCycleService.loadInputData call. Document APIs: Document input = new Document(new java.io.File("..."), true); // intending to own this file
// ensure that the input document is disposed of upon the transaction end
input.setTransactionBound(true);
input.passivate(); // save all data supplied by the file and take over the file
someLiveCycleService.loadInputData(data);
someLiveCycleService.someBusinessMethod();
Document middle = someLiveCycleService.saveOutputData();
// ensure that the middle document is available for a long enough period of time
middle.setDisposalTimeout(middle.getDisposalTimeout() + 60); // add extra 60 seconds
anotherLiveCycleService.loadInputData(data);
anotherLiveCycleService.loadInputData2(middle);
anotherLiveCycleService.anotherBusinessMethod();
Document output = anotherLiveCycleService.saveOutputData();
com.adobe.service.DataBuffer dataBuffer = output.getDataBuffer();
... As an indication of an error condition, any method of the Document class may throw a DocumentError exception. The DocumentError class is a runtime exception (it inherits from java.lang.RuntimeException). Runtime exceptions are also known as unchecked exceptions, as they don't need to be defined in the signature of the method throwing it. The unchecked exceptions (as opposed to checked exceptions which inherit from java.lang.Exception) simplify the user's code by trading off some type safety.
The following Document parameters are exposed through an external configuration:
| Name | Type | Default | Description |
|---|---|---|---|
localDocumentStorageSweepInterval | positive integer | 15 | The amount of time in seconds between attempts to delete any files that are no longer needed and that were used to pass the document data between LiveCycle components running on the same machine. |
globalDocumentStorageSweepInterval | positive integer | 30 | The amount of time in seconds between attempts to delete any files that are no longer needed that were used to pass the document data between LiveCycle components running on different machines. Specify this property only when deploying LiveCycle products in a clustered environment. |
globalDocumentStorageRootDir | string path | none | A path to an NFS shared directory used to store long-lived documents (the documents that are involved in a workflow process) and to share them among all cluster nodes. Specify this property only when deploying LiveCycle products in a clustered environment. |
globalDocumentStorageForceNFS | true/false | false | A switch controlling whether to use the NFS protocol to pass documents between different LiveCycle components. The NFS protocol must be used when deploying LiveCycle products in a clustered environment on Microsoft Windows. Note that additional NFS software should be installed on your Windows machine before enabling this option. This option does not affect UNIX deployments. |
defaultDocumentMaxInlineSize | positive integer | 65536 | The maximum number of bytes that are kept in memory when passing documents between different LiveCycle components. The documents that exceed this maximum are swapped out to the disk drive. Use this property for performance tuning. |
defaultDocumentDisposalTimeout | positive integer | 600 | The maximum amount of time in seconds during which a document, which is passed between different LiveCycle components, is considered alive. After this time has passed, any files used to store this document are subject to removal. Use this property to control the use of disk space. |
When using the Document class in the J2EE environment, the configuration parameters above are specified using Adobe Configuration Manager. When using the Document class in a standalone Java client, specify these parameters as Java system properties with a com.adobe.idp prefix (for example, com.adobe.idp.globalDocumentStorageRootDir).
| Method | Defined by | ||
|---|---|---|---|
|
Document(byte[] data)
Creates a new
Document out of the content specified by the byte array. | Document | ||
|
Document(InputStream is)
Creates a new
Document with the content provided by the java.io.InputStream object. | Document | ||
|
Document(URL url)
Creates a new
Document out of the content accessible via the URL. | Document | ||
|
Document(File file, boolean own)
Creates a new
Document out of the content stored in the file. | Document | ||
|
Document(DocumentWriter writer, Object obj)
Do not use.
| Document | ||
|
Creates a copy of the
Document supplied as input. | Document | ||
|
void copyToFile(File file)
Copies the document content to a file specified by a caller.
| Document | ||
|
void dispose()
Disposes of any local temporary storage resources (for example, file, database data, and so on) occupied by the document content.
| Document | ||
|
void doneReading()
Closes any resources opened by the
Document object while reading the content with any of the Document object's read() methods. | Document | ||
|
Serializable getAttribute(String name)
Returns the value of an attribute with a given name.
| Document | ||
|
String getContentType()
Returns the current MIME type of the
Document content. | Document | ||
|
DataBuffer getDataBuffer()
Do not use.
| Document | ||
|
[static] Returns the default disposal timeout value.
| Document | ||
|
int getDefaultMaxInlineSize()
[static] Returns the default maximum size of the document content that can be embedded within the
Document object. | Document | ||
|
int getDisposalTimeout()
Returns the timeout value if it was set using the #setDisposalTimeout(int) method.
| Document | ||
|
File getFile()
Returns the document content in a file.
| Document | ||
|
InputStream getInputStream()
Returns the document content in a
java.io.InputStream object. | Document | ||
|
int getMaxInlineSize()
Returns the maximum size of the document content that can be embedded within the
Document instance. | Document | ||
|
Object getObject(DocumentReader reader)
Do not use.
| Document | ||
|
boolean isPassivationLazy()
[static] Returns
true if lazy passivation is on. | Document | ||
|
boolean isTransactionBound()
Returns
true or false depending on whether the Document lifetime is transaction-bound. | Document | ||
|
long length()
Returns the
Document content's length. | Document | ||
|
Set listAttributes()
Lists the names of all attributes associated with this
Document instance. | Document | ||
|
void passivate()
Saves the document content into some persistent form (file, database BLOB, and so on).
| Document | ||
|
void passivateGlobally()
Passivates the
Document content (similar to the #passivate() method) in the global storage. | Document | ||
|
int read(long pos)
Reads a byte of the
Document object's content at the given position. | Document | ||
|
int read(long pos, byte[] b, int off, int len)
Reads up to
len bytes of the Document object's content into an array of bytes. | Document | ||
|
void removeAttribute(String name)
Removes an attribute with the given name.
| Document | ||
|
void setAttribute(String name, Serializable value)
Sets the value of an attribute with a given name.
| Document | ||
|
void setContentType(String type)
Overwrites the current MIME type of the
Document content. | Document | ||
|
void setDefaultDisposalTimeout(int seconds)
[static] Sets the default disposal timeout value, which is used if the timeout is not set using the #setDisposalTimeout(int) method.
| Document | ||
|
void setDefaultMaxInlineSize(int bytes)
[static] Sets the default maximum size of the document content that can be embedded within the
Document instance. | Document | ||
|
void setDisposalTimeout(int seconds)
Sets the amount of time (in seconds) before the
Document object is disposed of automatically. | Document | ||
|
void setInitialContext(InitialContext ic)
[static] Use this method to set the
InitialContext needed by the Document object in order to look up an internal server EJB, which is used to upload the Document object's content to the LiveCycle server. | Document | ||
|
void setMaxInlineSize(int bytes)
Sets the maximum size of the document content that can be embedded within the
Document instance. | Document | ||
|
void setPassivationLazy(boolean enable)
[static] Use this method to override the default passivation behavior.
| Document | ||
|
void setTransactionBound(boolean value)
Used to specify whether the
Document is transaction-bound. | Document | ||
|
String toString()
Returns a text representation of the
Document internal state. | Document | ||
| Document | () |
public Document(byte[] data)Creates a new Document out of the content specified by the byte array.
In this case, the new Document simply keeps a reference to the input array. So, the input source should remain available until the Document content is passivated (saved to permanent storage). The passivation happens either explicitly when passivate() is called, or implicitly when one tries to read the Document object's content (for example, when getInputStream(), getFile(), or another access method is called). Implicit passivation can be triggered either locally (when the access method is called on the same Document instance that was created with this constructor), or remotely (when the access method is called on another Document instance that is a copy of the source Document instance done via a serialization or deserialization or passed via a remote RMI call).
data — The byte array providing the input content. |
| Document | () |
public Document(InputStream is)Creates a new Document with the content provided by the java.io.InputStream object.
In this case, the new Document simply keeps a reference to the input stream. So, the input source should remain available until the Document content is passivated (saved to permanent storage). The passivation happens either explicitly when passivate() is called, or implicitly when one tries to read the Document object's content (for example, when getInputStream(), getFile(), or another access method is called). Implicit passivation can be triggered either locally (when the access method is called on the same Document instance that was created with this constructor), or remotely (when the access method is called on another Document instance that is a copy of the source Document instance done via a serialization or deserialization or passed via a remote RMI call).
is — The java.io.InputStream object providing the input content. |
| Document | () |
public Document(URL url)Creates a new Document out of the content accessible via the URL.
In this case, the new Document simply keeps a reference to the input URL. So, the input source should remain available until the Document content is passivated (saved to permanent storage). The passivation happens either explicitly when passivate() is called, or implicitly when one tries to read the Document object's content (for example, when getInputStream(), getFile(), or another access method is called). Implicit passivation can be triggered either locally (when the access method is called on the same Document instance that was created with this constructor), or remotely (when the access method is called on another Document instance that is a copy of the source Document instance done via a serialization or deserialization or passed via a remote RMI call).
url — The URL to the input content. |
| Document | () |
public Document(File file, boolean own)Creates a new Document out of the content stored in the file.
In this case, the new Document simply keeps a reference to the input file. So, the input source should remain available until the Document content is passivated (saved to permanent storage). The passivation happens either explicitly when passivate() is called, or implicitly when one tries to read the Document object's content (for example, when getInputStream(), getFile(), or another access method is called). Implicit passivation can be triggered either locally (when the access method is called on the same Document instance that was created with this constructor), or remotely (when the access method is called on another Document instance that is a copy of the source Document instance done via a serialization or deserialization or passed via a remote RMI call).
Setting the own flag to true means that the file will be deleted automatically when the Document instance is passivated. This can help to optimize IO, since the file can be moved rather than copied (which happens when the own flag is false) into the managed area on the disk.
file — The file providing the input content. |
|
own — The boolean flag controlling whether the new Document should take over the file when the Document is passivated. |
| Document | () |
public Document(DocumentWriter writer, Object obj)
Do not use.
Parameterswriter |
|
obj |
| Document | () |
public Document(Document doc)Creates a copy of the Document supplied as input.
doc — The source Document instance. |
| copyToFile | () |
public void copyToFile(File file)Copies the document content to a file specified by a caller. If the specified file already exists, it will be overwritten.
Note that after this method returns, it becomes the caller's responsibility to remove the file.
Parameters
file — The file to which to copy the document content. If the file exists, this method will overwrite it. If the file does not exist, this method will create one. |
| dispose | () |
public void dispose()Disposes of any local temporary storage resources (for example, file, database data, and so on) occupied by the document content. Once disposed, the Document instance becomes invalid, meaning that it becomes impossible to use the Document for any purpose.
In a few cases the Document can also be disposed of automatically. This occurs when the disposal timeout ends, which is set using the setDisposalTimeout(int) method, or when the current transaction ends and the Document is set as transaction-bound using the setTransactionBound(boolean) method.
See also
| doneReading | () |
public void doneReading()Closes any resources opened by the Document object while reading the content with any of the Document object's read() methods.
This method is also called by the dispose() method.
See also
| getAttribute | () |
public Serializable getAttribute(String name)Returns the value of an attribute with a given name.
An attribute is an arbitrary (preferably small) serializable object passed along with the Document instance. Every attribute should have a unique name. The predefined attributes are:
| Attribute | Description |
|---|---|
file | The original file name (as a string), if the Document was created with the Document(java.io.File, boolean) constructor. |
| url | The original URL (as a string), if the Document was created with the Document(java.net.URL) constructor. |
Parameters
name — The attribute name. |
| The attribute value. |
See also
| getContentType | () |
public String getContentType()Returns the current MIME type of the Document content.
The content type is a MIME string identifying the Document content (for example, "application/octet-stream", "text/plain", and so on). The content type is set either explicitly using the setContentType() method, or implicitly when the Document(java.net.URL), Document(java.io.File, boolean), or Document(java.io.InputStream) constructor is called. To determine the content type, the first and second constructors use a file/URL extension to map it to the MIME content type using a default javax.activation.FileTypeMap instance. The third constructor requests the content type from DataBuffer using the DataBuffer.getContentType() method.
If the Document is created using the Document(java.net.URL) constructor, and the URL does not have a file component in it (for example, http://www.adobe.com), then this method cannot determine the correct content type and most likely returns "application/octet-stream" as a result. This is done to avoid opening a java.net.URLConnection to this URL prematurely. If such behavior is not acceptable, consider setting the content type on the new Document instance explicitly, using the setContentType() method.
The current MIME content type. It can return null if the content type is unknown. |
See also
| getDataBuffer | () |
public DataBuffer getDataBuffer()
Do not use.
Returns| getDefaultDisposalTimeout | () |
public static int getDefaultDisposalTimeout()Returns the default disposal timeout value. If the default disposal timeout is not set, this method uses a value of a configurable defaultDocumentDisposalTimeout property. The default timeout is 600 seconds.
| The default disposal timeout in seconds. |
See also
| getDefaultMaxInlineSize | () |
public static int getDefaultMaxInlineSize()Returns the default maximum size of the document content that can be embedded within the Document object.
If the default inline size is not set using the setDefaultMaxInlineSize(int) method, this method uses a value of a configurable defaultDocumentMaxInlineSize property. The default value is 64 Kbytes.
| The default maximum inline size in bytes. |
See also
| getDisposalTimeout | () |
public int getDisposalTimeout()Returns the timeout value if it was set using the setDisposalTimeout(int) method. Otherwise, it returns the default timeout value (see the static getDefaultDisposalTimeout() method).
Returns| The current disposal timeout. |
See also
| getFile | () |
public File getFile()
Returns the document content in a file.
The only option available to the caller of this method is to open the returned file for reading. The caller should not try any other options (for example, writing to a file, renaming, removing, and so on) as this file is created and managed by the Document object.
If this method is called within the standalone client environment, the resulting file is created in the local temporary directory and is not managed. However, the file is marked with the java.io.File.deleteOnExit() method.
The java.io.File object containing the document content. |
| getInputStream | () |
public InputStream getInputStream()Returns the document content in a java.io.InputStream object.
The java.io.InputStream object containing the document content. |
| getMaxInlineSize | () |
public int getMaxInlineSize()Returns the maximum size of the document content that can be embedded within the Document instance. If this value is not set with the setMaxInlineSize(int) method, the default value is controlled by the setDefaultMaxInlineSize(int) method.
| The maximum inline size in bytes. |
See also
| getObject | () |
public Object getObject(DocumentReader reader)
Do not use.
Parameters
reader |
| isPassivationLazy | () |
public static boolean isPassivationLazy()Returns true if lazy passivation is on. If this is the case, the Document content is not passivated until the receiving side requests the content (unless it is passivated explicitly via the passivate() call). If it is off, the Document is passivated during its serialization (for example, when making an RMI/EJB call with a Document object as an input parameter).
Lazy passivation is a default behavior within the J2EE environment. For standalone J2SE applications, lazy passivation is off by default. This is because the lazy passivation might require a remote callback from the side receiving the Document object to the side supplying one. Such a callback might be problematic for standalone J2SE applications (for example, because the supplier side is behind a network firewall, or because the secure connection is a must but the supplier side does not support the SSL protocol in the callback direction).
true if the lazy passivation is on; false otherwise. |
See also
| isTransactionBound | () |
public boolean isTransactionBound()Returns true or false depending on whether the Document lifetime is transaction-bound.
The boolean value indicating if the Document is transaction-bound. |
See also
| length | () |
public long length()Returns the Document content's length. This method passivates the Document content internally using the passivate() method to cover the cases when the length is not known a priori (for example, when the Document is created with data whose length is unknown until the content is fully read, such as java.io.InpuStream or java.net.URL).
The Document content's length. |
See also
| listAttributes | () |
public Set listAttributes()Lists the names of all attributes associated with this Document instance.
| The set of all attribute names. |
See also
| passivate | () |
public void passivate()Saves the document content into some persistent form (file, database BLOB, and so on). After this method is called, the Document no longer keeps a reference to the object that provided the input for the document content (for example, the byte array, the java.io.InputStream, or the file provided by the corresponding Document constructor calls).
| passivateGlobally | () |
public void passivateGlobally()Passivates the Document content (similar to the passivate() method) in the global storage.
| read | () |
public int read(long pos)Reads a byte of the Document object's content at the given position.
Parameters
pos — The position from which to read the byte. |
The value of the byte, which can be in the range of 0 to 255, or -1 if the end of the data has been reached. |
| read | () |
public int read(long pos, byte[] b, int off, int len)Reads up to len bytes of the Document object's content into an array of bytes. While this method attempts to read as many as len bytes, a smaller number (0 to len bytes) may be read.
The very first call of this method passivates the Document. If the content is not stored in memory as part of the Document object, the very first call of this method also opens an internal resource, such as java.io.RandomAccessFile, to read the data. Thus, to help prevent resource leakage, it is important to call doneReading() when finished reading.
Parameters
pos — The position from which to read the bytes. |
|
b — The buffer into which the data is read. |
|
off — The starting index in the buffer (b) to which the data is written. |
|
len — The maximum number of bytes to read. |
The total number of bytes read into the buffer, or -1 if the end of the data has been reached. |
| removeAttribute | () |
public void removeAttribute(String name)Removes an attribute with the given name.
Parameters
name — The attribute name. |
See also
| setAttribute | () |
public void setAttribute(String name, Serializable value)Sets the value of an attribute with a given name.
Parameters
name — The attribute name. |
|
value — The attribute value. |
See also
| setContentType | () |
public void setContentType(String type)Overwrites the current MIME type of the Document content.
The content type is a MIME string identifying the Document content (for example, "application/octet-stream", "text/plain", and so on).
Parameters
type — The new content type. |
See also
| setDefaultDisposalTimeout | () |
public static void setDefaultDisposalTimeout(int seconds)Sets the default disposal timeout value, which is used if the timeout is not set using the setDisposalTimeout(int) method.
Parameters
seconds — The new default disposal timeout. |
| setDefaultMaxInlineSize | () |
public static void setDefaultMaxInlineSize(int bytes)Sets the default maximum size of the document content that can be embedded within the Document instance.
Parameters
bytes — The default maximum inline size in bytes. |
See also
| setDisposalTimeout | () |
public void setDisposalTimeout(int seconds)Sets the amount of time (in seconds) before the Document object is disposed of automatically. Use this method to guarantee disposal of any local temporary storage resources (for example, file, database data, and so on) occupied by the document content after a particular time elapsed. After the Document is disposed of, its content will no longer be available.
The recommended usage is document.setDisposalTimeout(document.getDisposalTimeout() + extraTime). Thus, changing the default disposal timeout at start-up can still affect the local disposal timeout.
The Document can also be disposed of either explicitly, when the dispose() method is called, or implicitly, when the current transaction ends and the Document is set as transaction-bound using the setTransactionBound(boolean) method.
If this method is never called, the Document is assigned a default disposal timeout (see the static getDefaultDisposalTimeout() method).
Parameters
seconds — The new disposal timeout in seconds. |
See also
| setInitialContext | () |
public static void setInitialContext(InitialContext ic)Use this method to set the InitialContext needed by the Document object in order to look up an internal server EJB, which is used to upload the Document object's content to the LiveCycle server. This method should be called by standalone client applications at initialization time. If this method is not called, the Document object will use an InitialContext object created with an empty constructor.
Parameters
ic |
| setMaxInlineSize | () |
public void setMaxInlineSize(int bytes)Sets the maximum size of the document content that can be embedded within the Document instance. If this value is not set, the default value controlled by the setDefaultMaxInlineSize(int) method is used.
Parameters
bytes — The maximum inline size in bytes. |
See also
| setPassivationLazy | () |
public static void setPassivationLazy(boolean enable)Use this method to override the default passivation behavior.
Parameters
enable — Set to true to enable lazy passivation. |
See also
| setTransactionBound | () |
public void setTransactionBound(boolean value)Used to specify whether the Document is transaction-bound.
If this method is called with value set to true, the Document instance is automatically disposed of upon the end of the transaction associated with the current thread (the Document becomes transaction-bound). By default, the Document is not transaction-bound.
When calling this method with the value set to true, make sure that the calling thread is associated with a J2EE transaction context. Otherwise, a DocumentError exception will be thrown.
The Document can also be disposed of in a few other ways. It can be disposed of explicitly, via the dispose() method call, or automatically: when the disposal timeout expires, or when the transaction ends (whichever happens earlier).
Parameters
value — The boolean value specifying whether the Document is transaction-bound. |
See also
| toString | () |
public String toString()Returns a text representation of the Document internal state. Use this method for debugging only.
A java.lang.String with the Document internal state in XML format. |
Send me an e-mail when comments are added to this page | Comment Report
Current page: http://livedocs.adobe.com/livecycle/es/sdkHelp/programmer/javadoc/com/adobe/idp/Document.html