public class XmlDocument
extends java.lang.Object
The document content is a byte stream. It must be well formed XML, but need not be valid.
The document name is a unique identifier for the document. The name is
specified when the document is first placed in the container. It can
either be explicitly specified by the user, or it can be auto-generated
by Berkeley DB XML. See XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
for details.
The user can retrieve the document by name using
XmlContainer.getDocument(java.lang.String)
. In addition, the document name can
be referenced in an XQuery expression using the doc() navigation
function. For example, suppose your document's name is 'doc1.xml' and
the container that it exists in is 'container1.bdbxml'. In this case,
you can explicitly request the document by it's name using:
doc('dbxml:/container1.bdbxml/doc1.xml')
The user can create an empty XmlDocument object using
XmlManager.createDocument()
. This object can then be assigned
a name, content, and metadata.
The metadata attributes provide a means of associating information with a document, without having to store it within the document itself. Example metadata attributes might be: document owner, creation time, receipt time, originating source, final destination, and next processing phase. They are analogous to the attributes of a file in a file system. Each metadata attribute consists of a name-value pair. The document's name is an implicit metadata attribute.
You can access the metadata for a given document by using either
getMetaData(java.lang.String, java.lang.String, com.sleepycat.dbxml.XmlValue)
or by iterating over the document's metadata. Use
getMetaDataIterator()
to retrieve an
XmlMetaDataIterator
object.
You can instantiate an empty XmlDocument object using
XmlManager.createDocument()
.
A copy constructor is provided for this class. The class is implemented using a handle-body idiom. When a handle is copied both handles maintain a reference to the same body.
This object is not thread-safe, and can only be safely used by one thread at a time in an application.
Constructor and Description |
---|
XmlDocument(XmlDocument o)
Copy constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
delete()
Deprecated.
as of release 2.4.
Does not need to be called as of 2.4.
|
boolean |
equals(XmlDocument other)
Compares two XmlDocuments.
|
void |
fetchAllData()
This method causes all document data and metadata to be retrieved.
|
byte[] |
getContent()
Returns the document's content as a byte array.
|
XmlEventReader |
getContentAsEventReader()
Returns the document's content as an
XmlEventReader . |
void |
getContentAsEventWriter(XmlEventWriter writer)
Writes the document's content as events to the specified
XmlEventWriter , then calls XmlEventWriter.close() to
release resources. |
java.io.InputStream |
getContentAsInputStream()
Returns the document's content as an
InputStream . |
java.lang.String |
getContentAsString()
Returns the document's content as a string.
|
XmlInputStream |
getContentAsXmlInputStream()
Returns the document's content as an
XmlInputStream . |
byte[] |
getMetaData(java.lang.String uri,
java.lang.String name)
Returns the value of the specified binary metadata.
|
boolean |
getMetaData(java.lang.String uri,
java.lang.String name,
XmlValue value)
Returns the value of the specified metadata.
|
XmlMetaDataIterator |
getMetaDataIterator()
Returns an
XmlMetaDataIterator . |
java.lang.String |
getName()
Get the name of the document.
|
XmlResults |
getResults()
Returns the XmlResults that is associated with this XmlDocument, or null if there is none.
|
void |
removeMetaData(java.lang.String uri,
java.lang.String name)
Removes the identified metadata from the document.
|
void |
setContent(byte[] content)
Sets the document's content to the provided byte array.
|
void |
setContent(java.lang.String content)
Sets the document's content to the provided string.
|
void |
setContentAsEventReader(XmlEventReader reader)
Sets the document's content to the provided
XmlEventReader . |
void |
setContentAsXmlInputStream(XmlInputStream adopted)
Sets the document's content to the provided content.
|
void |
setMetaData(java.lang.String uri,
java.lang.String name,
byte[] value)
Sets the value of the specified binary document metadata.
|
void |
setMetaData(java.lang.String uri,
java.lang.String name,
XmlValue value)
Sets the value of the specified document metadata.
|
void |
setName(java.lang.String name)
Set the name of the document.
|
public XmlDocument(XmlDocument o) throws XmlException
XmlException
public void delete()
public void setName(java.lang.String name) throws XmlException
XmlDocumentConfig.setGenerateName(boolean)
, or an exception is thrown.XmlException
public java.lang.String getName() throws XmlException
XmlException
public boolean equals(XmlDocument other) throws XmlException
other
- The other XmlDocument being compared.XmlContainer
, or returns true if they are constructed
documents that share the same metadata and content. Returns false
otherwise.XmlException
public void setContent(java.lang.String content) throws XmlException
XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
. If you are updating an already
existing document, you can update the document in the container using
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
. Use this method only for UTF-8 encoded XML, otherwise set the content as a byte[], XmlEventReader, or XmlInputStream.content
- The string containing the new document
contents. Note that the document contents must be well-formed XML.
However, in the event of incorrect content, an exception is not thrown
until an attempt is made to place the contents into a container using
either XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
or
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
.XmlException
public void setContent(byte[] content) throws XmlException
XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
. If you are updating an already
existing document, you can update the document in the container using
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
.content
- The raw bytes containing the new document
contents. Note that the document contents must be well-formed XML.
However, in the event of incorrect content, an exception is not thrown
until an attempt is made to place the contents into a container using
either XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
or
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
.XmlException
public XmlEventReader getContentAsEventReader() throws XmlException
XmlEventReader
. The
returned value is owned by the caller, and may hold database resources.
Resources must be released by using XmlEventReader.close()
.XmlException
public java.io.InputStream getContentAsInputStream() throws XmlException
InputStream
.XmlException
public java.lang.String getContentAsString() throws XmlException
getContentAsEventReader()
, getContent()
, or getContentAsXmlInputStream()
to get XML in other encodings.XmlException
public XmlInputStream getContentAsXmlInputStream() throws XmlException
XmlInputStream
. The
returned value is owned by the caller, and must be explicited deleted
using XmlInputStream.delete()
.XmlException
public void getContentAsEventWriter(XmlEventWriter writer) throws XmlException
XmlEventWriter
, then calls XmlEventWriter.close()
to
release resources.writer
- The XmlEventWriter
object to use as a sink for the
content events.XmlException
public byte[] getContent() throws XmlException
XmlException
public void setContentAsEventReader(XmlEventReader reader) throws XmlException
XmlEventReader
.
The XmlEventReader is donated to the document object, and must not
be used further by the caller.
If this document
is a new document (that is, its name is currently not in use by another
document in the container), you can add it to a container using
XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
. If you are updating an already
existing document, you can update the document in the container using
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
.reader
- The XmlEventReader
object to use as new content for this
document. It is donated to the document object, and must not
be used further by the caller.XmlException
public void setContentAsXmlInputStream(XmlInputStream adopted) throws XmlException
XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
. If you are updating an already
existing document, you can update the document in the container using
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
.adopted
- The input stream that points to the well-formed XML to be used as this document's content. Note that the document contents must be well-formed XML. However, in the
event of incorrect content, an exception is not thrown until an attempt
is made to place the contents into a container using either
XmlContainer.putDocument(com.sleepycat.dbxml.XmlDocument)
or
XmlContainer.updateDocument(com.sleepycat.dbxml.XmlDocument)
. After this call, the adopted
stream is owned by the document, which will delete the object.XmlException
public void fetchAllData() throws XmlException
Note that if the document was not retrieved lazily, then use of this method has no significant performance impact. However, if the document was retrieved lazily, then repeatedly calling this method on any given document may hurt your application's performance. This is because each time this method is called, Berkeley DB XML must walk the entire document tree in order to ensure that it has retrieved the entire document.
XmlException
public void setMetaData(java.lang.String uri, java.lang.String name, XmlValue value) throws XmlException
A metadata name consists of a namespace URI and a name. The namespace URI is optional but it should be used to avoid naming collisions.
Document metadata can be queried using a query expression that
uses the special dbxml:metadata()
function within a predicate.
If a given metadata item is indexed, it is possible to use
XmlContainer.lookupIndex(com.sleepycat.dbxml.XmlQueryContext, java.lang.String, java.lang.String, java.lang.String, com.sleepycat.dbxml.XmlValue)
to perform fast lookup.
Binary metadata cannot be accessed from within a query
uri
- The namespace within which the name resides. The empty string refers to the default namespace.name
- The name of the metadata item.value
- The typed metadata value.XmlException
public void setMetaData(java.lang.String uri, java.lang.String name, byte[] value) throws XmlException
A Metadata name consists of a namespace URI and a name. The namespace URI is optional but it should be used to avoid naming collisions.
Document metadata can be queried using a query expression that
uses the special dbxml:metadata()
function within a predicate.
If a given metadata item is indexed, it is possible to use
XmlContainer.lookupIndex(com.sleepycat.dbxml.XmlQueryContext, java.lang.String, java.lang.String, java.lang.String, com.sleepycat.dbxml.XmlValue)
to perform fast lookup.
Binary metadata cannot be accessed from within a query
uri
- The namespace within which the name resides. The empty string refers to the default namespace.name
- The name of the metadatavalue
- The metadata value.XmlException
public boolean getMetaData(java.lang.String uri, java.lang.String name, XmlValue value) throws XmlException
This method returns true if metadata is found for the XmlDocument that matches the given URI and name, and can be represented as an XmlValue; otherwise, it returns false.
uri
- The namespace within which the name resides. The empty string refers to
the default namespace.name
- The name of the metadatavalue
- The XmlValue
object into which the metadata value is to be placed.XmlException
public byte[] getMetaData(java.lang.String uri, java.lang.String name) throws XmlException
If found, this method returns the metadata for the XmlDocument that matches the given URI and name; otherwise, it returns null.
uri
- The namespace within which the name resides. The empty string refers to
the default namespace.name
- The name of the metadataXmlException
public void removeMetaData(java.lang.String uri, java.lang.String name) throws XmlException
uri
- The namespace within which the name resides. The empty string
refers to the default namespace.name
- The name of the metadataXmlException
public XmlMetaDataIterator getMetaDataIterator() throws XmlException
XmlMetaDataIterator
. Using this iterator, you can
examine the individual metadata items set for the document by looping
over them using XmlMetaDataIterator.next()
.XmlException
public XmlResults getResults()
XmlResults.delete()
when the document is no longer needed.Copyright (c) 2004,2014 Oracle. All rights reserved.