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 XmlModify

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

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.