Berkeley DbXML
version 1.2.1

com.sleepycat.dbxml
Class XmlDocument

java.lang.Object
  extended bycom.sleepycat.dbxml.XmlDocument

public class XmlDocument
extends Object

An XmlDocument is the unit of storage within an XmlContainer. A document consists of content, a name, an ID, 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 user-provided identifier for the document. The user can retrieve the document by name through the container query interface. The document name can be referenced in an XPath expression as "dbxml:name". For example, the XPath expression:

/*[@dbxml:name='abc123']

would retrieve the document with the name "abc123".

The Berkeley DB XML system assigns each document a unique ID when it is inserted into a container. The document ID uniquely identifies the document within a container, and can be used to retrieve the document from its container.

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 copy constructor and assignment operator are 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.


Constructor Summary
XmlDocument()
           
 
Method Summary
 void delete()
           
 byte[] getContent()
          The XmlDocument.getContent method returns a pointer to the document content.
 String getContentAsString()
          The getContentAsString() method copies the content of the document into a string .
 int getID()
          The XmlDocument.getID method returns the XmlDocument ID.
 boolean getMetaData(String uri, String name, XmlValue value)
          The XmlDocument.getMetaData method returns the value of the specified metadata attribute.
 String getName()
          The XmlDocument.getName method returns the XmlDocument name.
 void modifyDocument(XmlModify modify)
          The XmlDocument.modifyDocument method modifies the XmlDocument contents based on the information contained in the XmlModify object.
 XmlResults queryWithXPath(String query, XmlQueryContext context)
          The XmlDocument.queryWithXPath method executes an XPath expression against the XmlDocument, and returns the results.
 XmlResults queryWithXPath(XmlQueryExpression query)
          The XmlDocument.queryWithXPath method executes an XPath expression against the XmlDocument, and returns the results.
 void setContent(byte[] content)
          The XmlDocument.setContent method sets the XmlDocument content.
 void setContent(String content)
          The XmlDocument.setContent method sets the XmlDocument content.
 void setMetaData(String uri, String prefix, String name, XmlValue value)
          The XmlDocument.setMetaData method sets the value of the specified metadata attribute.
 void setName(String name)
          The XmlDocument.setName method sets 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()
            throws XmlException
Throws:
XmlException
Method Detail

delete

public void delete()

getID

public int getID()
The XmlDocument.getID method returns the XmlDocument ID. The document ID is zero if the document has not yet been assigned any content or the document has not yet been added to an XmlContainer.

Returns:
Returns the XmlDocument ID.

Throws:
XmlException

setName

public void setName(String name)
             throws XmlException
The XmlDocument.setName method sets the name of the document.

Parameters:
name - A string containing the name to be assigned to the XmlDocument.
Throws:
XmlException

getName

public String getName()
               throws XmlException
The XmlDocument.getName method returns the XmlDocument name.

Returns:
Returns the name of the XmlDocument.
Throws:
XmlException

setContent

public void setContent(byte[] content)
                throws XmlException
The XmlDocument.setContent method sets the XmlDocument content. The content is copied from the content parameter into the XmlDocument.

Parameters:
content - A byte array containing the document content.
Throws:
XmlException

getContent

public byte[] getContent()
The XmlDocument.getContent method returns a pointer to the document content. The returned value is owned by the XmlDocument, and is destroyed when the document is destroyed.

Returns:
Returns a pointer to the XmlDocument content as raw bytes.

Throws:
XmlException

setContent

public void setContent(String content)
                throws XmlException
The XmlDocument.setContent method sets the XmlDocument content. The content is copied from the content parameter into the XmlDocument.

Parameters:
content - A string containing the document content.
Throws:
XmlException

modifyDocument

public void modifyDocument(XmlModify modify)
                    throws XmlException
The XmlDocument.modifyDocument method modifies the XmlDocument contents based on the information contained in the XmlModify object. In order to determine how many modification operations were performed, the XmlModify.getNumModifications method should be used.

Parameters:
modify - The XmlModify object describing how to change the document. It encapsulates the XPath query, which specifies the target nodes in the document, as well as the modification operation to perform, with associated arguments.
Throws:
XmlException - The XmlDocument.modifyDocument method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The modification operation specified could not be performed on the node(s) specified by the XPath query.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.

  • getContentAsString

    public String getContentAsString()
                              throws XmlException
    The getContentAsString() method copies the content of the document into a string . The getContent() method can be used to avoid the copy.

    Returns:
    Returns the XmlDocument content as a string.

    Throws:
    XmlException

    setMetaData

    public void setMetaData(String uri,
                            String prefix,
                            String name,
                            XmlValue value)
                     throws XmlException
    The XmlDocument.setMetaData method sets the value of the specified metadata attribute. A metadata attribute is a name-value pair, which is stored with the document, but not as part of the document content.

    A metadata attribute name consists of three parts; a namespace URI, a namespace prefix, and a local name. The namespace URI and prefix are optional, but should be used to avoid naming collisions.

    Typed values are passed to the API as an instance of XmlValue, and may be of type Number, String, or Boolean. The system reflects each typed metadata attribute into the document by adding a namespace declaration attribute and metadata attribute to the document root element. The following example associates a metadata attribute with a document:

    XmlDocument document; document.setContent("<x/>"); document.setMetaData("http://acme.com/", "acme", "received", new XmlValue("1-Jan-2002"));

    The system reflects the metadata attribute into the document as follows:

    <x xmlns:acme= 'http://acme.com/' acme:received= '1-Jan-2002'/>

    The metadata attribute can be queried using the XPath expression:

    /*[@acme:received= '1-Jan-2002'].

    Parameters:
    uri - The namespace within which the name resides. The empty string refers to the default namespace.
    prefix - The prefix for the namespace.
    name - The name of the metadata attribute.
    value - A Number, String, or Boolean value.
    Throws:
    XmlException

    getMetaData

    public boolean getMetaData(String uri,
                               String name,
                               XmlValue value)
                        throws XmlException
    The XmlDocument.getMetaData method returns the value of the specified metadata attribute.

    Parameters:
    uri - The namespace within which the name resides. The empty string refers to the default namespace.
    name - The name of the metadata attribute.
    value - A Number, String, or Boolean value.
    Returns:
    The method returns true if a value for the named metadata attribute is found within the document.

    Throws:
    XmlException

    queryWithXPath

    public XmlResults queryWithXPath(String query,
                                     XmlQueryContext context)
                              throws XmlException
    The XmlDocument.queryWithXPath method executes an XPath expression against the XmlDocument, and returns the results.

    The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, and specifies that the method should return the set of values selected by the XPath expression.

    Parameters:
    query - The XPath expression provided as a string, conforming to the syntax defined in the W3C XPath 1.0 specification.
    context - The context within which the query is to be performed. The context contains the variable bindings, the namespace prefix to URI mapping, and the query processing flags.
    Returns:
    The result of the query.
    Throws:
    XmlException - The XmlDocument.queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The DOM parser was unable to parse an XML document.
  • The XPath expression referred to an undefined variable.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.

  • queryWithXPath

    public XmlResults queryWithXPath(XmlQueryExpression query)
                              throws XmlException
    The XmlDocument.queryWithXPath method executes an XPath expression against the XmlDocument, and returns the results.

    Parameters:
    query - The XPath expression as an XmlQueryExpression.
    Returns:
    The result of the query.

    Throws:
    XmlException - The XmlDocument.queryWithXPath method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The DOM parser was unable to parse an XML document.
  • The XPath expression referred to an undefined variable.
  • The XPath evaluator was unable to execute the XPath expression.
  • The XPath parser could not parse the XPath expression.

  • Berkeley DbXML
    version 1.2.1

    Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.