com.sleepycat.dbxml
Class XmlDocument

java.lang.Object
  com.sleepycat.dbxml.XmlDocument

public class XmlDocument
extends Object

The unit of storage within an XmlContainer. A document consists of content, a name, and a set of metadata attributes.

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 Summary

XmlDocument(XmlDocument o)
Copy constructor.

Method Summary

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.
InputStream	getContentAsInputStream() Returns the document's content as an InputStream.
String	getContentAsString() Returns the document's content as a string.
XmlInputStream	getContentAsXmlInputStream() Returns the document's content as an XmlInputStream.
byte[]	getMetaData(String uri, String name) Returns the value of the specified binary metadata.
boolean	getMetaData(String uri, String name, XmlValue value) Returns the value of the specified metadata.
XmlMetaDataIterator	getMetaDataIterator() Returns an XmlMetaDataIterator.
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(String uri, 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(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(String uri, String name, byte[] value) Sets the value of the specified binary document metadata.
void	setMetaData(String uri, String name, XmlValue value) Sets the value of the specified document metadata.
void	setName(String name) Set the name of the document.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlDocument

public XmlDocument(XmlDocument o)
            throws XmlException

Copy constructor.

Throws:

XmlException

Method Detail

delete

public void delete()

Deprecated. as of release 2.4. Does not need to be called as of 2.4.

setName

public void setName(String name)
             throws XmlException

Set the name of the document. Note that when the document is put in a container, either the name that you specify must be unique, or you must use XmlDocumentConfig.setGenerateName(boolean), or an exception is thrown.

Throws:

XmlException

getName

public String getName()
               throws XmlException

Get the name of the document.

Throws:

XmlException

equals

public boolean equals(XmlDocument other)
               throws XmlException

Compares two XmlDocuments.

Parameters:

other - The other XmlDocument being compared.

Returns:

true if the XmlDocuments represent the same record in an XmlContainer, or returns true if they are constructed documents that share the same metadata and content. Returns false otherwise.

Throws:

XmlException

setContent

public void setContent(String content)
                throws XmlException

Sets the document's content to the provided string. 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). Use this method only for UTF-8 encoded XML, otherwise set the content as a byte[], XmlEventReader, or XmlInputStream.

Parameters:

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).

Throws:

XmlException

setContent

public void setContent(byte[] content)
                throws XmlException

Sets the document's content to the provided byte array. 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).

Parameters:

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).

Throws:

XmlException

getContentAsEventReader

public XmlEventReader getContentAsEventReader()
                                       throws XmlException

Returns the document's content as an XmlEventReader. The returned value is owned by the caller, and may hold database resources. Resources must be released by using XmlEventReader.close().

Throws:

XmlException

getContentAsInputStream

public InputStream getContentAsInputStream()
                                    throws XmlException

Returns the document's content as an InputStream.

Throws:

XmlException

getContentAsString

public String getContentAsString()
                          throws XmlException

Returns the document's content as a string. This function will only display UFT-8 encoded XML correctly. Use getContentAsEventReader(), getContent(), or getContentAsXmlInputStream() to get XML in other encodings.

Throws:

XmlException

getContentAsXmlInputStream

public XmlInputStream getContentAsXmlInputStream()
                                          throws XmlException

Returns the document's content as an XmlInputStream. The returned value is owned by the caller, and must be explicited deleted using XmlInputStream.delete().

Throws:

XmlException

getContentAsEventWriter

public void getContentAsEventWriter(XmlEventWriter writer)
                             throws XmlException

Writes the document's content as events to the specified XmlEventWriter, then calls XmlEventWriter.close() to release resources.

Parameters:

writer - The XmlEventWriter object to use as a sink for the content events.

Throws:

XmlException

getContent

public byte[] getContent()
                  throws XmlException

Returns the document's content as a byte array.

Throws:

XmlException

setContentAsEventReader

public void setContentAsEventReader(XmlEventReader reader)
                             throws XmlException

Sets the document's content to the provided 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).

Parameters:

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.

Throws:

XmlException

setContentAsXmlInputStream

public void setContentAsXmlInputStream(XmlInputStream adopted)
                                throws XmlException

Sets the document's content to the provided content. 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).

Parameters:

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.

Throws:

XmlException

fetchAllData

public void fetchAllData()
                  throws XmlException

This method causes all document data and metadata to be retrieved. Otherwise, if a document was retrieved lazily, then document content and metadata is only retrieved from the container on an as-needed basis. Note that documents in node storage containers are implicitly lazy.

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.

Throws:

XmlException

setMetaData

public void setMetaData(String uri,
                        String name,
                        XmlValue value)
                 throws XmlException

Sets the value of the specified document metadata. Document metadata comprises a name-value pair, which is stored with the document, but not as part of the document content.

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

Parameters:

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.

Throws:

XmlException

setMetaData

public void setMetaData(String uri,
                        String name,
                        byte[] value)
                 throws XmlException

Sets the value of the specified binary document metadata. Document metadata is a name-value pair, which is stored with the document, but not as part of the document content.

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

Parameters:

uri - The namespace within which the name resides. The empty string refers to the default namespace.

name - The name of the metadata

value - The metadata value.

Throws:

XmlException

getMetaData

public boolean getMetaData(String uri,
                           String name,
                           XmlValue value)
                    throws XmlException

Returns the value of the specified metadata.

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.

Parameters:

uri - The namespace within which the name resides. The empty string refers to the default namespace.

name - The name of the metadata

value - The XmlValue object into which the metadata value is to be placed.

Throws:

XmlException

getMetaData

public byte[] getMetaData(String uri,
                          String name)
                   throws XmlException

Returns the value of the specified binary metadata.

If found, this method returns the metadata for the XmlDocument that matches the given URI and name; otherwise, it returns null.

Parameters:

uri - The namespace within which the name resides. The empty string refers to the default namespace.

name - The name of the metadata

Throws:

XmlException

removeMetaData

public void removeMetaData(String uri,
                           String name)
                    throws XmlException

Removes the identified metadata from the document.

Parameters:

uri - The namespace within which the name resides. The empty string refers to the default namespace.

name - The name of the metadata

Throws:

XmlException

getMetaDataIterator

public XmlMetaDataIterator getMetaDataIterator()
                                        throws XmlException

Returns an XmlMetaDataIterator. Using this iterator, you can examine the individual metadata items set for the document by looping over them using XmlMetaDataIterator.next().

Throws:

XmlException

getResults

public XmlResults getResults()

Returns the XmlResults that is associated with this XmlDocument, or null if there is none. This function exists to make it easier to call XmlResults.delete() when the document is no longer needed.