Berkeley DbXML
version 1.2.1

com.sleepycat.dbxml
Class XmlModify

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

public class XmlModify
extends Object

The XmlModify class encapsulates the context within which a set of documents specified by an XPath query can be modified in place. The modification is performed using an XmlModify object, and either XmlDocument.modifyDocument or XmlContainer.modifyDocument. There are two parts to the object -- the query and the operation. The query identifies target nodes against which the operation is run. The operation specifies what modifications to perform. An operation may use some, or none of the remaining parameters, depending on its requirements. After a modification operation is performed, it is possible to determine the number of individual operations by calling XmlModify.getNumModifications. The value should be approximately the number of node hits in the specified query.

There is an additional method available, XmlModify.setNewEncoding, that allows the user to specify a new character encoding for the modified documents. If not used, the content will be as indicated in the document's XML declaration, or defaulted to UTF-8.

An XmlModify object can be used for multiple calls, but cannot be modified between calls. If a different modification is required, a new object must be constructed.


Field Summary
static int Append
          Add new XML content as a child node of the target.
static int Attribute
          New content is an attribute.
static int Comment
          New content is a comment.
static int Element
          New content is an element.
static int InsertAfter
          Insert new XML content as a sibling node after the target node.
static int InsertBefore
          Insert new XML content as a sibling node before the target node.
static int None
          This enumeration is offered as a convenience to be used when the type argument is not used.
static int ProcessingInstruction
          New content is a processing instruction.
static int Remove
          Remove the target node.
static int Rename
          Rename the target node.
static int Text
          New content is text.
static int Update
          Modifies text content of the target node.
 
Constructor Summary
XmlModify(String xpath, int operation, int type, String name, String content, int location, XmlQueryContext context)
           
XmlModify(XmlQueryExpression expression, int operation, int type, String name, String content, int location)
           
 
Method Summary
 void delete()
           
 int getNumModifications()
          The XmlModify.getNumModifications method returns the number of modification operations performed by a call to either XmlContainer.modifyDocument or XmlDocument.modifyDocument.
 void setNewEncoding(String newEncoding)
          The XmlModify.setNewEncoding method sets a new character encoding to be used for documents modified by calls to XmlContainer.modifyDocument or XmlDocument.modifyDocument.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

InsertAfter

public static final int InsertAfter
Insert new XML content as a sibling node after the target node.


InsertBefore

public static final int InsertBefore
Insert new XML content as a sibling node before the target node.


Append

public static final int Append
Add new XML content as a child node of the target. This operation uses the location argument to determine where the child is inserted.


Update

public static final int Update
Modifies text content of the target node. If the target has existing text, it will be replaced by the specified content. If the target has no existing text, the new text is added. If there is no content specified, this operation results in simple removal of existing text content.


Remove

public static final int Remove
Remove the target node. This operation ignores the arguments specifying type, name, and content.


Rename

public static final int Rename
Rename the target node. The node target must have a name. This operation ignores the arguments specifying type and content.


Element

public static final int Element
New content is an element. The name argument must be valid; content is used if present.


Attribute

public static final int Attribute
New content is an attribute. The name and content arguments must be valid.


Text

public static final int Text
New content is text. The content argument is used if present. Name is ignored.


ProcessingInstruction

public static final int ProcessingInstruction
New content is a processing instruction. The name and content arguments must be valid.


Comment

public static final int Comment
New content is a comment. The content argument is used as comment text. Name is ignored.


None

public static final int None
This enumeration is offered as a convenience to be used when the type argument is not used.

Constructor Detail

XmlModify

public XmlModify(String xpath,
                 int operation,
                 int type,
                 String name,
                 String content,
                 int location,
                 XmlQueryContext context)
          throws XmlException
Parameters:
xpath - The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.
context - The optional 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.
operation - Specifies the modification operation to be performed, and must be set to one of: XmlModify.InsertBefore, XmlModify.InsertAfter, XmlModify.Append, XmlModify.Update, XmlModify.Remove, XmlModify.Rename.
type - Specifies the type of the XML content to be used for operations that result in new content. Some operations do not require a type argument, in which case it is ignored. This argument must be set to one of: XmlModify.Element, XmlModify.Attribute, XmlModify.Text, XmlModify.Comment, XmlModify.ProcessingInstruction, XmlModify.None.
name - The name for new XML content when the operation requires a name. The name must be encoded as UTF-8, or an empty string. Operations that do not require a name ignore this argument.
content - The XML content for operations that require content. Content must be encoded as UTF-8, or an empty string. Operations that do not require content ignore this argument.
location - Integer location indicating where a new child node will be placed for the append operation. It is not used for other operations. If it is -1 (the default), the new child is appended as the last child of the target node; otherwise, it is used as an index for the new location. The index is zero-based, so a location of 0 means the new node will be the first child, and a location of 1 means it will be inserted as the second child of the target, assuming there is an existing child.
Throws:
XmlException - The XmlModify method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • One or more parameters was not a valid argument.

  • XmlModify

    public XmlModify(XmlQueryExpression expression,
                     int operation,
                     int type,
                     String name,
                     String content,
                     int location)
              throws XmlException
    Parameters:
    expression - This constructor accepts a pre-parsed query expression instead of the xpath query string and optional context. The expression is created by a call to the XmlContainer.parseXPathExpression method. If this constructor is used, it is necessary that the XmlQueryExpression be created using an XmlQueryContext that has its return type set to XmlQueryContext.ResultDocumentsAndValues. If not, an exception will be thrown.
    operation - Specifies the modification operation to be performed, and must be set to one of: XmlModify.InsertBefore, XmlModify.InsertAfter, XmlModify.Append, XmlModify.Update, XmlModify.Remove, XmlModify.Rename.
    type - Specifies the type of the XML content to be used for operations that result in new content. Some operations do not require a type argument, in which case it is ignored. This argument must be set to one of: XmlModify.Element, XmlModify.Attribute, XmlModify.Text, XmlModify.Comment, XmlModify.ProcessingInstruction, XmlModify.None.
    name - The name for new XML content when the operation requires a name. The name must be encoded as UTF-8, or an empty string. Operations that do not require a name ignore this argument.
    content - The XML content for operations that require content. Content must be encoded as UTF-8, or an empty string. Operations that do not require content ignore this argument.
    location - Integer location indicating where a new child node will be placed for the append operation. It is not used for other operations. If it is -1 (the default), the new child is appended as the last child of the target node; otherwise, it is used as an index for the new location. The index is zero-based, so a location of 0 means the new node will be the first child, and a location of 1 means it will be inserted as the second child of the target, assuming there is an existing child.
    Throws:
    XmlException - The XmlModify method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The XmlQueryExpression used in construction was not created using an XmlQueryContext which has a ReturnType of Db.XmlQueryContext::ResultDocumentsAndValues.
  • Method Detail

    delete

    public void delete()

    setNewEncoding

    public void setNewEncoding(String newEncoding)
                        throws XmlException
    The XmlModify.setNewEncoding method sets a new character encoding to be used for documents modified by calls to XmlContainer.modifyDocument or XmlDocument.modifyDocument. It operates on the XmlModify object used for these calls. The encoding must be a valid encoding for an XML document, such as "UTF-8" or "ISO-8859-1". Errors or invalid encodings may not be detected until the modification operation is performed.

    Parameters:
    newEncoding - Specifies the encoding to use. This string must be encoded as UTF-8.
    Throws:
    XmlException

    getNumModifications

    public int getNumModifications()
                            throws XmlException
    The XmlModify.getNumModifications method returns the number of modification operations performed by a call to either XmlContainer.modifyDocument or XmlDocument.modifyDocument. In general, it will be equal to the number of nodes referenced by the query. The stored value is implicitly reset to 0 when a new call is made using the same XmlModify object.

    Returns:
    Returns the number of modification operations performed.

    Throws:
    XmlException

    Berkeley DbXML
    version 1.2.1

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