com.adobe.aemfd.docmanager

Class Document

java.lang.Object

org.apache.sling.api.adapter.SlingAdaptable

com.adobe.aemfd.docmanager.Document

All Implemented Interfaces:

Closeable, AutoCloseable, org.apache.sling.api.adapter.Adaptable

public class Document
extends org.apache.sling.api.adapter.SlingAdaptable
implements Closeable, org.apache.sling.api.adapter.Adaptable

The Document class is an abstraction over various sources of content (URLs, JCR nodes, etc.) which serves the content-stream and also provides other meta-information (length, content-type, etc.) about the content.
A Document object exists in three major phases:

• Initialized: This is the initial state of the object after it has been created by one of the various Document constructors.
• Passivated: Passivation is a lazy activity which occurs the first time the application which created the Document tries to delve into the content-source with which the Document was initialized (e.g. when it tries to create and read a stream off the content-source by calling getInputStream()). Passivation involves either loading the contents into memory if they're small enough (as dictated by the Document's max-inline-size property, see setMaxInlineSize(int)), or saving the contents to a location from where fresh streams can be created on-demand (if the original content-source is not itself suitable for the purpose, e.g. a one-time-use InputStream).
• Disposed: A Document reaches this state when the application which created it no longer needs it and calls dispose() or close() on it. The Document is unusable once it reaches this state. It is very important that applications properly dispose of Documents once they are no longer needed, so that any resources managed by Documents (e.g. temporary files created as part of passivation) get cleaned up properly.

Constructor Summary

Constructors

Constructor and Description
Document(byte[] data) Creates a Document from a byte-array.
Document(File file) Creates a Document from a file.
Document(File file, boolean ownFile) Creates a Document from a file.
Document(InputStream is) Creates a Document from an input-stream.
Document(String jcrPath) Creates a Document from the path of a JCR node.
Document(String jcrPath, org.apache.sling.api.resource.ResourceResolver resolver) Creates a Document from the path of a JCR node.
Document(String jcrPath, org.apache.sling.api.resource.ResourceResolver resolver, boolean manageResolver) Creates a Document from the path of a JCR node.
Document(URL url) Creates a Document from a URL.

Method Summary

Modifier and Type	Method and Description
<AdapterType> AdapterType	adaptTo(Class<AdapterType> type) Adapts the Document to various other types of objects.
void	close() Disposes of the Document.
void	copyToFile(File file) Copies the contents of the Document to the given File.
void	dispose() Disposes of the Document, and cleans up any managed resources.
Object	getAttribute(String name) Returns the Document attribute with the given name.
String	getContentType() Returns the type of the Document contents.
byte[]	getInlineData() Returns the Document contents as a byte-array, only if the contents are small enough to fit in memory as decided by the max-inline-size property (see setMaxInlineSize(int)).
InputStream	getInputStream() Returns an input-stream over the Document contents.
int	getMaxInlineSize() Returns the value of the max-inline-size property which decides whether the Document contents can be loaded into memory during passivation.
long	length() Returns the length of the Document contents.
void	passivate() Triggers passivation on the Document, as a result of which one of the following happens to the contents of the content-source from which the Document was initialized: The contents are loaded into memory if they are small enough, as dictated by the max-inline-size property (see setMaxInlineSize(int)), or The contents are potentially saved to a location from which fresh content-streams can be created every time the application calls getInputStream().
void	removeAttribute(String name) Removes the Document attribute with the given name.
void	setAttribute(String name, Object val) Sets a Document attribute.
void	setContentType(String contentType) Sets the Document content-type.
void	setMaxInlineSize(int maxInlineSize) Sets the value of the max-inline-size property to be used during passivation for deciding whether the Document contents can be loaded into memory.

Constructor Detail

Document

public Document(byte[] data)

Creates a Document from a byte-array.

Parameters:

data - The byte-array serving as the content-source for the Document.

Document

public Document(URL url)

Creates a Document from a URL. The Document attempts to deduce its default content-type from a connection to the URL, if available in the connection headers.

Parameters:

url - The URL serving as the content-source for the Document.

Document

public Document(File file)

Creates a Document from a file. Equivalent to new Document(file, false). See Document(java.io.File, boolean) for more details.

Parameters:

file - The file serving as the content-source for the Document.

Document

public Document(File file,
                boolean ownFile)

Creates a Document from a file. The Document attempts to deduce its default content-type from the file's extension. The Document also starts "managing" the file if the ownFile parameter is true, which means that the file is automatically deleted when the Document no longer needs it. This could happen after passivation itself, if the file is small enough to fit in memory, or at the very end of the Document's life-cycle when it is disposed.

Parameters:

file - The file serving as the content-source for the Document.

ownFile - Whether the file is henceforth to be managed by the Document.

Document

public Document(InputStream is)

Creates a Document from an input-stream. Note that the Document at no point in its life-cycle ever closes the input-stream itself, in keeping with the practice of not managing resources passed in externally unless explicitly instructed to do so. Hence, it is the responsibility of the application creating the Document to also close the input-stream properly when the time comes. However, the application should close the stream only after the Document is done with it, i.e. only after the Document has been passivated or disposed.

Parameters:

is - The input-stream serving as the content-source for the Document.

Document

public Document(String jcrPath)

Creates a Document from the path of a JCR node. The Document uses a thread-based resource-resolver (see ResourceResolverHelper) for resolving the given path, so it is the application's responsibility to ensure that a resolver is set properly in the thread-context while invoking operations which need to interact with the JCR repository (e.g. getInputStream(), length(), etc.). Failure to do so will lead to an IllegalStateException being thrown when these operations are attempted.
The Document attempts to deduce its default content-type from the meta-information provided by the JCR repository for the given node. The given JCR node path is treated as follows:

• If the path references a DAM asset, it is first translated to the path of that asset's original rendition, and the translated path is used as the source for the Document object.
• For nodes which are not DAM assets, the given path is used as-is.

Parameters:

jcrPath - The path of the JCR-node serving as the content-source for the Document.

Document

public Document(String jcrPath,
                org.apache.sling.api.resource.ResourceResolver resolver)

Creates a Document from the path of a JCR node. Equivalent to new Document(jcrPath, resolver, false). See Document(String, org.apache.sling.api.resource.ResourceResolver, boolean) for more details.

Parameters:

jcrPath - The path of the JCR-node serving as the content-source for the Document.

resolver - The resource-resolver to be used for resolving the given path.

Document

public Document(String jcrPath,
                org.apache.sling.api.resource.ResourceResolver resolver,
                boolean manageResolver)

Creates a Document from the path of a JCR node. The Document uses the provided resource-resolver for resolving the given path. The Document also starts "managing" the resolver if the manageResolver parameter is true, which means that the resolver is automatically closed when the Document no longer needs it. This could happen after passivation itself, if the JCR node contents are small enough to fit in memory, or at the very end of the Document's life-cycle when it is disposed.
The Document attempts to deduce its default content-type from the meta-information provided by the JCR repository for the given node. The given JCR node path is treated as follows:

• If the path references a DAM asset, it is first translated to the path of that asset's original rendition, and the translated path is used as the source for the Document object.
• For nodes which are not DAM assets, the given path is used as-is.

Parameters:

jcrPath - The path of the JCR-node serving as the content-source for the Document.

resolver - The resource-resolver to be used for resolving the given path.

manageResolver - Whether the resource-resolver is henceforth to be managed by the Document.

Method Detail

passivate

public void passivate()
               throws IOException

Triggers passivation on the Document, as a result of which one of the following happens to the contents of the content-source from which the Document was initialized:

• The contents are loaded into memory if they are small enough, as dictated by the max-inline-size property (see setMaxInlineSize(int)), or
• The contents are potentially saved to a location from which fresh content-streams can be created every time the application calls getInputStream(). This happens only if the original content-source is not of a type from which fresh content-streams can be reliably created on demand (e.g. an InputStream serving as the content-source is often a one-time-use source and hence its contents need to be saved to a more reusable location). Sources such as URLs, JCR nodes, etc. do not suffer from this one-time-use constraint and hence the content-copying operation does not need to be performed for such sources.

Note that passivation is a one-time activity and happens only the first time passivate() is invoked. Subsequent invocations of passivate() have no effect.
Also note that passivation is triggered automatically the first time the application invokes any other Document operation which involves interacting with the content-source with which the Document was initialized (e.g. getInputStream(), length(), getInlineData(), etc.).

Throws:

IOException

getInlineData

public byte[] getInlineData()
                     throws IOException

Returns the Document contents as a byte-array, only if the contents are small enough to fit in memory as decided by the max-inline-size property (see setMaxInlineSize(int)). If the contents are not small enough, then null is returned.

Returns:

The Document contents as a byte-array if small enough, else null.

Throws:

IOException - If an error occurs loading the Document contents.

getInputStream

public InputStream getInputStream()
                           throws IOException

Returns an input-stream over the Document contents. Note that a fresh stream is created every time getInputStream() is invoked, and it is the responsibility of the application to properly close all streams opened this way, and that too before the associated Document is disposed.

Returns:

A fresh input-stream over the Document contents.

Throws:

IOException - If an error occurs while creating a stream over the Document contents.

length

public long length()
            throws IOException

Returns the length of the Document contents. Note that this method always returns a proper non-negative value representing the actual length of the contents, and never a negative value (e.g. -1) representing an unknown length.

Returns:

The length of the Document contents

Throws:

IOException - If an error occurs determining the content-length.

getContentType

public String getContentType()
                      throws IOException

Returns the type of the Document contents. If the application has explicitly set a content-type via setContentType(String), then that is returned, else if the Document could deduce a default content-type based on the content-source it was initialized with, then that is returned, else null is returned.

Returns:

The Document's content-type. null is returned if the application has not explicitly set a content-type and a default content-type could also not be deduced.

Throws:

IOException - If an error occurs while attempting to deduce the default content-type.

dispose

public void dispose()

Disposes of the Document, and cleans up any managed resources. These resources could be those passed to the Document at initialization time (e.g. files/JCR resource-resolvers having the management flag set) or those created by the Document itself as part of its life-cycle (e.g. temporary files as part of passivation). It is of the utmost importance that Documents be disposed once they are done with, so that this clean-up can occur.
Once a Document has been disposed, it becomes unusable and any attempt to invoke an operation on a disposed Document results in an IllegalStateException being thrown.
Calling dispose() on an already disposed document has no effect.

getMaxInlineSize

public int getMaxInlineSize()

Returns the value of the max-inline-size property which decides whether the Document contents can be loaded into memory during passivation. The default value is 64k bytes.

Returns:

The value of the max-inline-size property.

setMaxInlineSize

public void setMaxInlineSize(int maxInlineSize)

Sets the value of the max-inline-size property to be used during passivation for deciding whether the Document contents can be loaded into memory. If setMaxInlineSize() is not called prior to passivation, a default value of 64k is used. This operation is not permitted once passivation has occurred and an IllegalStateException is thrown if setMaxInlineSize() is called post-passivation.

Parameters:

maxInlineSize - The value of the max-inline-size property to be used during passivation.

Throws:

IllegalStateException - If the Document is already in a passivated state when this method is called.

getAttribute

public Object getAttribute(String name)

Returns the Document attribute with the given name.

Parameters:

name - The name of the Document attribute whose value is required.

Returns:

The Document attribute with the given name, null if the Document does not have an attribute with this name.

setAttribute

public void setAttribute(String name,
                         Object val)

Sets a Document attribute.

Parameters:

name - The name of attribute being set.

val - The value of the attribute being set.

removeAttribute

public void removeAttribute(String name)

Removes the Document attribute with the given name. Has no effect if the Document has no attribute with this name.

Parameters:

name - The name of the attibute to be removed.

setContentType

public void setContentType(String contentType)

Sets the Document content-type. This overrides any default content-type deduced by the Document from the content-source with which it was initialized.

Parameters:

contentType - The Document content-type.

copyToFile

public void copyToFile(File file)
                throws IOException

Copies the contents of the Document to the given File.

Parameters:

file - The file to which the Document contents are to be copied.

Throws:

IOException - If an error occurs while copying the Document contents.

adaptTo

public <AdapterType> AdapterType adaptTo(Class<AdapterType> type)

Adapts the Document to various other types of objects. The following types are supported:

• InputStream: An adaptation of the Document's content-stream as returned by getInputStream()
• Map: An adaptation of the Document's attributes
• ValueMap: An adaptation of the Document's attributes

Overrides:

adaptTo in class org.apache.sling.api.adapter.SlingAdaptable

Type Parameters:

AdapterType -

Parameters:

type -

Returns:

close

public void close()
           throws IOException

Disposes of the Document. See dispose().

Throws:

IOException - If an error occurs during disposal.