public class Document extends org.apache.sling.api.adapter.SlingAdaptable implements Closeable, org.apache.sling.api.adapter.Adaptable
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).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 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.
|
Modifier and Type | Method and Description |
---|---|
<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.
|
public Document(byte[] data)
data
- The byte-array serving as the content-source for the Document.public Document(URL url)
url
- The URL serving as the content-source for the Document.public Document(File file)
new Document(file, false)
.
See Document(java.io.File, boolean)
for more details.file
- The file serving as the content-source for the Document.public Document(File file, boolean ownFile)
file
- The file serving as the content-source for the Document.ownFile
- Whether the file is henceforth to be managed by the Document.public Document(InputStream is)
is
- The input-stream serving as the content-source for the Document.public Document(String jcrPath)
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.jcrPath
- The path of the JCR-node serving as the content-source for the Document.public Document(String jcrPath, org.apache.sling.api.resource.ResourceResolver resolver)
new Document(jcrPath, resolver, false)
.
See Document(String, org.apache.sling.api.resource.ResourceResolver, boolean)
for more details.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.public Document(String jcrPath, org.apache.sling.api.resource.ResourceResolver resolver, boolean manageResolver)
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.public void passivate() throws IOException
setMaxInlineSize(int)
), orgetInputStream()
. 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.getInputStream()
, length()
, getInlineData()
, etc.).IOException
public byte[] getInlineData() throws IOException
setMaxInlineSize(int)
). If the
contents are not small enough, then null
is returned.null
.IOException
- If an error occurs loading the Document contents.public InputStream getInputStream() throws IOException
IOException
- If an error occurs while creating a stream over the Document contents.public long length() throws IOException
IOException
- If an error occurs determining the content-length.public String getContentType() throws IOException
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.null
is returned if the application has not explicitly set
a content-type and a default content-type could also not be deduced.IOException
- If an error occurs while attempting to deduce the default content-type.public void dispose()
IllegalStateException
being thrown.public int getMaxInlineSize()
public void setMaxInlineSize(int maxInlineSize)
IllegalStateException
is thrown if setMaxInlineSize() is called post-passivation.maxInlineSize
- The value of the max-inline-size property to be used during passivation.IllegalStateException
- If the Document is already in a passivated state when this method is called.public Object getAttribute(String name)
name
- The name of the Document attribute whose value is required.null
if the Document does not
have an attribute with this name.public void setAttribute(String name, Object val)
name
- The name of attribute being set.val
- The value of the attribute being set.public void removeAttribute(String name)
name
- The name of the attibute to be removed.public void setContentType(String contentType)
contentType
- The Document content-type.public void copyToFile(File file) throws IOException
file
- The file to which the Document contents are to be copied.IOException
- If an error occurs while copying the Document contents.public <AdapterType> AdapterType adaptTo(Class<AdapterType> type)
InputStream
: An adaptation of the Document's content-stream as returned by getInputStream()
Map
: An adaptation of the Document's attributesValueMap
: An adaptation of the Document's attributesadaptTo
in class org.apache.sling.api.adapter.SlingAdaptable
AdapterType
- type
- public void close() throws IOException
dispose()
.IOException
- If an error occurs during disposal.Copyright © 1982–2022 Adobe Systems Inc.. All rights reserved.