org.jaxup.xupdate
Class XUpdate

java.lang.Object
  extended by org.jaxup.xupdate.XUpdate

public class XUpdate
extends java.lang.Object

XUpdate engine. This class can, using the instructions in an XUpdate instruction document, change another XML document in-place. For small changes to large XML files, this may be preferable over a full XSLT translation. It is especially efficient if the XML document is either kept in memory for a long time, or is stored in a persistent database.

Author:
Erwin Bolwidt

Field Summary
static java.lang.String NS_XUPDATE
          Namespace for xupdate command elements.
 
Constructor Summary
XUpdate(Updater docUpdater)
          Creates an xupdate engine.
XUpdate(Updater docUpdater, Navigator xuNavigator)
          Creates an xupdate engine.
 
Method Summary
protected  void addFragmentToTarget(int type, java.util.List fragment, java.lang.Object targetNode, int childIndex)
           
protected  void conditional(java.lang.Object doc, java.lang.Object instrNode)
          Handles an xupdate 'if' instruction.
protected  void creation(java.lang.Object doc, java.lang.Object instrNode, int type)
          Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction.
protected  java.lang.Object evaluateAttribute(java.lang.Object doc, java.lang.Object instrNode, java.lang.Object selectContext)
          Evaluates an attribute creation instruction in a template.
protected  java.lang.Object evaluateComment(java.lang.Object doc, java.lang.Object instrNode)
          Evaluates a comment creation instruction in a template.
protected  java.lang.Object evaluateElement(java.lang.Object doc, java.lang.Object instrNode, java.lang.Object selectContext)
           
protected  java.lang.Object evaluateProcessingInstruction(java.lang.Object doc, java.lang.Object instrNode)
          Evaluates a processing-instruction creation instruction in a template.
protected  java.lang.Object evaluateText(java.lang.Object doc, java.lang.Object instrNode)
          Evaluates a text creation instruction in a template.
protected  java.util.List evaluateValueOf(java.lang.Object doc, java.lang.Object instrNode, java.lang.Object selectContext)
          Evaluates a value-of instruction in a template, which will instantiate a copy of the result of an xpath expression, possibly containing xpath variables.
protected  void executeUpdateInstructions(java.lang.Object doc, java.lang.Object instructionsContainer)
          Handles an xupdate 'modifications' or 'if' instruction container.
protected static java.lang.Object getAttributeNode(Navigator nav, java.lang.Object element, java.lang.String name)
          Returns attribute without namespace with the specified NCName in specified element, or null if there is no such attribute.
protected  java.lang.String getNodeListStringValue(java.util.List nodeList)
           
protected  java.util.List instantiateTemplate(java.lang.Object doc, java.lang.Object templateHolder, java.lang.Object selectContext)
           
protected  XPath parseXPath(java.lang.String xpath, java.lang.Object xuElement)
          Parses an xpath expression in the context of an element with regard to namespace bindings.
protected  void remove(java.lang.Object doc, java.lang.Object removeNode)
          Handles an xupdate 'remove' instruction.
protected  void removeChildren(java.lang.Object element)
          Removes the children of given element, if it has any children.
 void runUpdate(java.lang.Object sourceDoc, java.lang.Object xupdateContainer)
          Runs a series of xupdate instructions to manipulate a given source document.
 void runUpdateDocument(java.lang.Object sourceDoc, java.lang.Object xupdateDocument)
          Runs a series of xupdate instructions to manipulate a given source document.
protected  void singleNodeCreation(java.lang.Object doc, java.lang.Object instrNode, java.lang.Object targetNode, int type)
          Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction for a single node.
protected static java.lang.String[] splitQName(java.lang.String qname)
          Splits a Qname into a prefix and a localname, and returns these as an array of two strings.
protected  void variable(java.lang.Object doc, java.lang.Object instrNode)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NS_XUPDATE

public static final java.lang.String NS_XUPDATE
Namespace for xupdate command elements.

See Also:
Constant Field Values
Constructor Detail

XUpdate

public XUpdate(Updater docUpdater)
Creates an xupdate engine. The source documents that are updated, and the xml documents containing the xupdate instructions, are both stored in the same data model, e.g. DOM, JDOM, DOM4J, EXML.

Parameters:
updater - An implementation of the Updater interface to update source and rad xupdate instruction documents.

XUpdate

public XUpdate(Updater docUpdater,
               Navigator xuNavigator)
Creates an xupdate engine. The source documents that are updated and the xml documents containing the xupdate instructions may be stored in different data models, i.e. the source document in W3C DOM and the xupdate instructions in JDOM.

Parameters:
docUpdater - An implementation of the Updater interface to update source documents.
xuNavigator - An implementation of the Navigator interface to read xupdate instruction documents.
Method Detail

runUpdate

public void runUpdate(java.lang.Object sourceDoc,
                      java.lang.Object xupdateContainer)
               throws JaxenException,
                      org.saxpath.SAXPathException,
                      UpdateException
Runs a series of xupdate instructions to manipulate a given source document.

Parameters:
sourceDoc - The source document that is going to be changed.
xupdateContainer - An element node that contains xupdate instructions as its children. Ordinarily, this would be the document element of an xupdate XML document.
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

runUpdateDocument

public void runUpdateDocument(java.lang.Object sourceDoc,
                              java.lang.Object xupdateDocument)
                       throws JaxenException,
                              org.saxpath.SAXPathException,
                              UpdateException
Runs a series of xupdate instructions to manipulate a given source document.

Parameters:
sourceDoc - The source document that is going to be changed.
xupdateContainer - An element node that contains xupdate instructions as its children. Ordinarily, this would be the document element of an xupdate XML document.
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

executeUpdateInstructions

protected void executeUpdateInstructions(java.lang.Object doc,
                                         java.lang.Object instructionsContainer)
                                  throws JaxenException,
                                         org.saxpath.SAXPathException,
                                         UpdateException
Handles an xupdate 'modifications' or 'if' instruction container.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

getAttributeNode

protected static java.lang.Object getAttributeNode(Navigator nav,
                                                   java.lang.Object element,
                                                   java.lang.String name)
                                            throws JaxenException
Returns attribute without namespace with the specified NCName in specified element, or null if there is no such attribute.

Throws:
JaxenException

parseXPath

protected XPath parseXPath(java.lang.String xpath,
                           java.lang.Object xuElement)
                    throws JaxenException,
                           org.saxpath.SAXPathException
Parses an xpath expression in the context of an element with regard to namespace bindings.

Parameters:
xpath - The xpath expression.
xuElement - The element in the xupdate document from which the namespace bindings should be used in the xpath expression.
Returns:
The parsed xpath expression, bound to the variable context of this xupdate engine, and with its namespaces bound like the given element.
Throws:
JaxenException
org.saxpath.SAXPathException

splitQName

protected static java.lang.String[] splitQName(java.lang.String qname)
                                        throws JaxenException
Splits a Qname into a prefix and a localname, and returns these as an array of two strings.

Throws:
JaxenException

variable

protected void variable(java.lang.Object doc,
                        java.lang.Object instrNode)
                 throws JaxenException,
                        org.saxpath.SAXPathException,
                        UpdateException
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

conditional

protected void conditional(java.lang.Object doc,
                           java.lang.Object instrNode)
                    throws JaxenException,
                           org.saxpath.SAXPathException,
                           UpdateException
Handles an xupdate 'if' instruction.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

remove

protected void remove(java.lang.Object doc,
                      java.lang.Object removeNode)
               throws JaxenException,
                      UpdateException,
                      org.saxpath.SAXPathException
Handles an xupdate 'remove' instruction.

Throws:
JaxenException
UpdateException
org.saxpath.SAXPathException

evaluateElement

protected java.lang.Object evaluateElement(java.lang.Object doc,
                                           java.lang.Object instrNode,
                                           java.lang.Object selectContext)
                                    throws JaxenException,
                                           org.saxpath.SAXPathException,
                                           UpdateException
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

getNodeListStringValue

protected java.lang.String getNodeListStringValue(java.util.List nodeList)

evaluateAttribute

protected java.lang.Object evaluateAttribute(java.lang.Object doc,
                                             java.lang.Object instrNode,
                                             java.lang.Object selectContext)
                                      throws JaxenException,
                                             org.saxpath.SAXPathException,
                                             UpdateException
Evaluates an attribute creation instruction in a template.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateProcessingInstruction

protected java.lang.Object evaluateProcessingInstruction(java.lang.Object doc,
                                                         java.lang.Object instrNode)
                                                  throws JaxenException,
                                                         org.saxpath.SAXPathException,
                                                         UpdateException
Evaluates a processing-instruction creation instruction in a template.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateComment

protected java.lang.Object evaluateComment(java.lang.Object doc,
                                           java.lang.Object instrNode)
                                    throws JaxenException,
                                           org.saxpath.SAXPathException,
                                           UpdateException
Evaluates a comment creation instruction in a template.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateText

protected java.lang.Object evaluateText(java.lang.Object doc,
                                        java.lang.Object instrNode)
                                 throws JaxenException,
                                        org.saxpath.SAXPathException,
                                        UpdateException
Evaluates a text creation instruction in a template.

Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateValueOf

protected java.util.List evaluateValueOf(java.lang.Object doc,
                                         java.lang.Object instrNode,
                                         java.lang.Object selectContext)
                                  throws JaxenException,
                                         org.saxpath.SAXPathException,
                                         UpdateException
Evaluates a value-of instruction in a template, which will instantiate a copy of the result of an xpath expression, possibly containing xpath variables.

Parameters:
selectContext - If this value-of is evaluated in the context of another select, such as the select attribute from an append, update, etc. instruction, then this parameter contains this node. If no context is known, it is null.
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

creation

protected void creation(java.lang.Object doc,
                        java.lang.Object instrNode,
                        int type)
                 throws JaxenException,
                        org.saxpath.SAXPathException,
                        UpdateException
Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction.

Parameters:
type - OP_APPEND, OP_UPDATE, OP_INSERT_BEFORE, OP_INSERT_AFTER
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

singleNodeCreation

protected void singleNodeCreation(java.lang.Object doc,
                                  java.lang.Object instrNode,
                                  java.lang.Object targetNode,
                                  int type)
                           throws JaxenException,
                                  org.saxpath.SAXPathException,
                                  UpdateException
Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction for a single node.

Parameters:
type - OP_APPEND, OP_UPDATE, OP_INSERT_BEFORE, OP_INSERT_AFTER
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException

addFragmentToTarget

protected void addFragmentToTarget(int type,
                                   java.util.List fragment,
                                   java.lang.Object targetNode,
                                   int childIndex)
                            throws UpdateException,
                                   JaxenException
Throws:
UpdateException
JaxenException

removeChildren

protected void removeChildren(java.lang.Object element)
                       throws JaxenException,
                              UpdateException
Removes the children of given element, if it has any children.

Throws:
JaxenException
UpdateException

instantiateTemplate

protected java.util.List instantiateTemplate(java.lang.Object doc,
                                             java.lang.Object templateHolder,
                                             java.lang.Object selectContext)
                                      throws JaxenException,
                                             org.saxpath.SAXPathException,
                                             UpdateException
Parameters:
selectContext - If this value-of is evaluated in the context of another select, such as the select attribute from an append, update, etc. instruction, then this parameter contains this node. If no context is known, it is null.
Throws:
JaxenException
org.saxpath.SAXPathException
UpdateException