Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.dbxml
Class XmlDocument

    java.lang.Object
      com.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.

Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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