#include <DbXml.hpp>

class DbXml::XmlModify {
public:
	XmlModify(const std::string &xpath, ModificationType operation, 
		  XmlObject type, const std::string &name, 
		  const std::string &content, int location = -1,
		  XmlQueryContext *context = 0);
	XmlModify(XmlQueryExpression &expression, ModificationType operation, 
		  XmlObject type, const std::string &name, 
		  const std::string &content, int location = -1);
	~XmlModify();
	...
};

Description: XmlModify

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.

Parameters

xpath

The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.

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.

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 the following values:

XmlModify::InsertAfter

Insert new XML content as a sibling node after the target node.

XmlModify::InsertBefore

Insert new XML content as a sibling node before the target node.

XmlModify::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.

XmlModify::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.

XmlModify::Remove

Remove the target node. This operation ignores the arguments specifying type, name, and content.

XmlModify::Rename

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

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 the following values:

XmlModify::Element

New content is an element. The name argument must be valid; content is used if present.

XmlModify::Attribute

New content is an attribute. The name and content arguments must be valid.

XmlModify::Text

New content is text. The content argument is used if present. Name is ignored.

XmlModify::ProcessingInstruction

New content is a processing instruction. The name and content arguments must be valid.

XmlModify::Comment

New content is a comment. The content argument is used as comment text. Name is ignored.

XmlModify::None

This enumeration is offered as a convenience to be used when the type argument is not used.

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.

Errors

The XmlModify method may fail and throw XmlException, encapsulating one of the following non-zero errors:

INVALID_VALUE

The XmlQueryExpression used in construction was not created using an XmlQueryContext which has a ReturnType of XmlQueryContext::ResultDocumentsAndValues.

Class