Package com.adobe.aemfd.docmanager

Class Document

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, Adaptable
    public class Document
extends SlingAdaptable
implements java.io.Closeable, 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 Description
      Document()
      Creates a Document
      Document​(byte[] data)
      Creates a Document from a byte-array.
      Document​(java.io.File file)
      Creates a Document from a file.
      Document​(java.io.File file, boolean ownFile)
      Creates a Document from a file.
      Document​(java.io.InputStream is)
      Creates a Document from an input-stream.
      Document​(java.lang.String jcrPath)
      Creates a Document from the path of a JCR node.
      Document​(java.lang.String jcrPath, ResourceResolver resolver)
      Creates a Document from the path of a JCR node.
      Document​(java.lang.String jcrPath, ResourceResolver resolver, boolean manageResolver)
      Creates a Document from the path of a JCR node.
      Document​(java.net.URL url)
      Creates a Document from a URL.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <AdapterType>
      AdapterType      		 adaptTo​(java.lang.Class<AdapterType> type)
      Adapts the Document to various other types of objects.
      void close()
      Disposes of the Document.
      void copyToFile​(java.io.File file)
      Copies the contents of the Document to the given File.
      void dispose()
      Disposes of the Document, and cleans up any managed resources.
      java.lang.Object getAttribute​(java.lang.String name)
      Returns the Document attribute with the given name.
      java.lang.String getContentType()
      Returns the type of the Document contents.
      Document getDelegate()
      Returns the document delegate created by the DocumentFactory instance.
      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)).
      java.io.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​(java.lang.String name)
      Removes the Document attribute with the given name.
      void setAttribute​(java.lang.String name, java.lang.Object val)
      Sets a Document attribute.
      void setContentType​(java.lang.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.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Document

        public Document()
        Creates a Document

      • 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​(java.net.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​(java.io.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​(java.io.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​(java.io.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​(java.lang.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​(java.lang.String jcrPath,
                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​(java.lang.String jcrPath,
                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 java.io.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:
        java.io.IOException

      • getInlineData

        public byte[] getInlineData()
                     throws java.io.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:
        java.io.IOException - If an error occurs loading the Document contents.

      • getInputStream

        public java.io.InputStream getInputStream()
                                   throws java.io.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:
        java.io.IOException - If an error occurs while creating a stream over the Document contents.

      • getDelegate

        public Document getDelegate()
        Returns the document delegate created by the DocumentFactory instance.
        Returns:
        Document delegate.

      • length

        public long length()
            throws java.io.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:
        java.io.IOException - If an error occurs determining the content-length.

      • getContentType

        public java.lang.String getContentType()
                                throws java.io.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:
        java.io.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:
        java.lang.IllegalStateException - If the Document is already in a passivated state when this method is called.

      • getAttribute

        public java.lang.Object getAttribute​(java.lang.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​(java.lang.String name,
                         java.lang.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​(java.lang.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​(java.lang.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​(java.io.File file)
                throws java.io.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:
        java.io.IOException - If an error occurs while copying the Document contents.

      • adaptTo

        public <AdapterType> AdapterType adaptTo​(java.lang.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
        Specified by:
        adaptTo in interface Adaptable
        Overrides:
        adaptTo in class SlingAdaptable
        Type Parameters:
        AdapterType -
        Parameters:
        type -
        Returns:

      • close

        public void close()
           throws java.io.IOException
        Disposes of the Document. See dispose().
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - If an error occurs during disposal.