org.jaxup.xupdate
Class XUpdate

java.lang.Object
  |
  +--org.jaxup.xupdate.XUpdate

public class XUpdate
extends 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.


Field Summary
static String NS_XUPDATE
          Namespace for xupdate command elements.
 
Constructor Summary
XUpdate(org.jaxup.Updater docUpdater)
          Creates an xupdate engine.
XUpdate(org.jaxup.Updater docUpdater, Navigator xuNavigator)
          Creates an xupdate engine.
 
Method Summary
protected  void addFragmentToTarget(int type, List fragment, Object targetNode, int childIndex)
           
protected  void conditional(Object doc, Object instrNode)
          Handles an xupdate 'if' instruction.
protected  void creation(Object doc, Object instrNode, int type)
          Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction.
protected  Object evaluateAttribute(Object doc, Object instrNode, Object selectContext)
          Evaluates an attribute creation instruction in a template.
protected  Object evaluateComment(Object doc, Object instrNode)
          Evaluates a comment creation instruction in a template.
protected  Object evaluateElement(Object doc, Object instrNode, Object selectContext)
           
protected  Object evaluateProcessingInstruction(Object doc, Object instrNode)
          Evaluates a processing-instruction creation instruction in a template.
protected  Object evaluateText(Object doc, Object instrNode)
          Evaluates a text creation instruction in a template.
protected  List evaluateValueOf(Object doc, Object instrNode, 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(Object doc, Object instructionsContainer)
          Handles an xupdate 'modifications' or 'if' instruction container.
protected static Object getAttributeNode(Navigator nav, Object element, String name)
          Returns attribute without namespace with the specified NCName in specified element, or null if there is no such attribute.
protected  String getNodeListStringValue(List nodeList)
           
protected  List instantiateTemplate(Object doc, Object templateHolder, Object selectContext)
           
protected  XPath parseXPath(String xpath, Object xuElement)
          Parses an xpath expression in the context of an element with regard to namespace bindings.
protected  void remove(Object doc, Object removeNode)
          Handles an xupdate 'remove' instruction.
protected  void removeChildren(Object element)
          Removes the children of given element, if it has any children.
 void runUpdate(Object sourceDoc, Object xupdateContainer)
          Runs a series of xupdate instructions to manipulate a given source document.
 void runUpdateDocument(Object sourceDoc, Object xupdateDocument)
          Runs a series of xupdate instructions to manipulate a given source document.
protected  void singleNodeCreation(Object doc, Object instrNode, Object targetNode, int type)
          Handles an xupdate 'append', 'update', 'insert-before' and 'insert-after' instruction for a single node.
protected static String[] splitQName(String qname)
          Splits a Qname into a prefix and a localname, and returns these as an array of two strings.
protected  void variable(Object doc, 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 String NS_XUPDATE
Namespace for xupdate command elements.

See Also:
Constant Field Values
Constructor Detail

XUpdate

public XUpdate(org.jaxup.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.


XUpdate

public XUpdate(org.jaxup.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(Object sourceDoc,
                      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.
JaxenException
org.saxpath.SAXPathException
UpdateException

runUpdateDocument

public void runUpdateDocument(Object sourceDoc,
                              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.
JaxenException
org.saxpath.SAXPathException
UpdateException

executeUpdateInstructions

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

JaxenException
org.saxpath.SAXPathException
UpdateException

getAttributeNode

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

JaxenException

parseXPath

protected XPath parseXPath(String xpath,
                           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.
JaxenException
org.saxpath.SAXPathException

splitQName

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

JaxenException

variable

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

conditional

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

JaxenException
org.saxpath.SAXPathException
UpdateException

remove

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

JaxenException
UpdateException
org.saxpath.SAXPathException

evaluateElement

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

getNodeListStringValue

protected String getNodeListStringValue(List nodeList)

evaluateAttribute

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

JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateProcessingInstruction

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

JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateComment

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

JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateText

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

JaxenException
org.saxpath.SAXPathException
UpdateException

evaluateValueOf

protected List evaluateValueOf(Object doc,
                               Object instrNode,
                               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.
JaxenException
org.saxpath.SAXPathException
UpdateException

creation

protected void creation(Object doc,
                        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
JaxenException
org.saxpath.SAXPathException
UpdateException

singleNodeCreation

protected void singleNodeCreation(Object doc,
                                  Object instrNode,
                                  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
JaxenException
org.saxpath.SAXPathException
UpdateException

addFragmentToTarget

protected void addFragmentToTarget(int type,
                                   List fragment,
                                   Object targetNode,
                                   int childIndex)
                            throws UpdateException,
                                   JaxenException
UpdateException
JaxenException

removeChildren

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

JaxenException
UpdateException

instantiateTemplate

protected List instantiateTemplate(Object doc,
                                   Object templateHolder,
                                   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.
JaxenException
org.saxpath.SAXPathException
UpdateException