com.adobe.xfa
Class Node

java.lang.Object
  com.adobe.xfa.Obj
      com.adobe.xfa.Node

Direct Known Subclasses:

Chars, Comment, Element, ProcessingInstruction

public abstract class Node
extends Obj

A base class to represent all the types of nodes in a DOM.

The class provides methods to traverse XML DOMs and XFA DOMs. XFA DOMs differ from XML DOMs in that they are composed exclusively of nodes that belong to an XFA schema.

Nested Class Summary

static interface

Node.ChangeLogger This interface defines the logging operations available when differences (changes) are encountered while comparing DOMs using Node.compareVersions(Node, Node.ChangeLogger, Object).

Field Summary

static int	CREATE_ALWAYS_NEW An allowable enumeration eMode value to the assignNode() method.
static int	CREATE_IF_NOT_EXIST An allowable enumeration eMode value to the assignNode() method.
static int	CREATE_MUST_NOT_EXIST An allowable enumeration eMode value to the assignNode() method.
static int	CREATE_REPLACE An allowable enumeration eMode value to the assignNode() method.

Method Summary

Node	assignNode(java.lang.String sSOMExpression, java.lang.String sValue, int eMode) Assigns the value given to the node located by the given SOM (Scripting Object Model) expression and interpreted relative to this node's context.
boolean	checkAncestorPerms() Determines whether this node and all of its ancestors are unlocked for scripting execution.
boolean	checkDescendentPerms() Checks that this node and all of its descendents are unlocked for scripting execution.
boolean	checkPerms() Determines whether this node is unlocked for scripting execution.
void	cleanDirtyFlags()
boolean	compareVersions(Node oRollbackNode, Node.ChangeLogger oChangeLogger, java.lang.Object oUserData) Determines if this node (and all it's descendants) differs from the given roll-back node.
java.lang.String	getData() Gets this node's data.
protected ScriptDynamicPropObj	getDynamicScriptProp(java.lang.String sPropertyName, boolean bPropertyOverride, boolean bPeek, int nXFAVersion, int nAvailability)
Node	getFirstXFAChild() Gets this node's first XFA child.
Node	getFirstXMLChild() Gets this node's first XML child.
Node	getLastXMLChild() Gets this node's last XML child.
Model	getModel() Gets this node's model.
abstract java.lang.String	getName() Gets this node's name.
Node	getNextXFASibling() Gets this node's next XFA sibling.
Node	getNextXMLSibling() Gets this node's next XML sibling.
Document	getOwnerDocument() Gets this node's owner document.
Node	getPreviousXMLSibling() Gets this node's previous XML sibling.
java.lang.String	getSOMExpression() Gets this element's absolute SOM expression.
int	getXFAChildCount() Gets this node's number of XFA children.
Element	getXFAParent() Gets this node's XFA parent.
int	getXMLChildCount() Gets this node's XML child count.
Element	getXMLParent() Gets this node's XML parent.
void	hasChanged(boolean bIsDirty) Sets this changed state of this node and its descendants to the given state.
void	remove() Removes this node from its parent child list.
Node	resolveNode(java.lang.String somExpr) Evaluates the Scripting Object Model expression, using this node as the current context.
Node	resolveNode(java.lang.String somExpr, boolean bPeek, boolean bLastOccurence, boolean bNoProperties) Evaluates the Scripting Object Model expression, using this node as the current context.
NodeList	resolveNodes(java.lang.String somExpr, boolean bPeek, boolean bLastOccurence, boolean bNoProperties) Evaluates the Scripting Object Model expression, using this node as the current context.
protected void	setNextXMLSibling(Node node) Sets this node's next XML sibling.
void	setPermsLock(boolean bPermsLock) Sets the permissions state of this node.
protected void	setXMLParent(Element parent) Sets this node's XML parent.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CREATE_REPLACE

public static final int CREATE_REPLACE

An allowable enumeration eMode value to the assignNode() method.

See Also:

Constant Field Values

CREATE_MUST_NOT_EXIST

public static final int CREATE_MUST_NOT_EXIST

An allowable enumeration eMode value to the assignNode() method.

See Also:

Constant Field Values

CREATE_IF_NOT_EXIST

public static final int CREATE_IF_NOT_EXIST

An allowable enumeration eMode value to the assignNode() method.

See Also:

Constant Field Values

CREATE_ALWAYS_NEW

public static final int CREATE_ALWAYS_NEW

An allowable enumeration eMode value to the assignNode() method.

See Also:

Constant Field Values

Method Detail

assignNode

public Node assignNode(java.lang.String sSOMExpression,
                       java.lang.String sValue,
                       int eMode)

Assigns the value given to the node located by the given SOM (Scripting Object Model) expression and interpreted relative to this node's context.

If the node doesn't exist, it can be created depending of the value of the given eMode. The eMode values are:

CREATE_REPLACE

If the node exists, the value is updated, if the node doesn't exist, it will be created.

CREATE_MUST_NOT_EXIST

If the node exists, an error will be thrown, if the node doesn't exist, it will be created.

CREATE_IF_NOT_EXIST

If the node exists, no action is taken, if the node doesn't exist, it will be created.

CREATE_ALWAYS_NEW

A new node is always created.

Parameters:

sSOMExpression - a SOM expression evaluating to a node.

sValue - the value to be assigned.

eMode - specifies whether the node should be created or not.

Returns:

null.

checkPerms

public boolean checkPerms()

Determines whether this node is unlocked for scripting execution.

Returns:

true if this node is unlocked for scripting execution.

See Also:

Node.setPermsLock(boolean), Node.checkAncestorPerms(), Node.checkDescendentPerms()

checkAncestorPerms

public boolean checkAncestorPerms()

Determines whether this node and all of its ancestors are unlocked for scripting execution.

Returns:

true if this node and all of its ancestors are unlocked for scripting execution.

See Also:

Node.setPermsLock(boolean), Node.checkPerms(), Node.checkDescendentPerms()

checkDescendentPerms

public boolean checkDescendentPerms()

Checks that this node and all of its descendents are unlocked for scripting execution.

Returns:

true if this node and all of its descendents are unlocked for scripting execution.

See Also:

Node.setPermsLock(boolean), Node.checkPerms(), Node.checkAncestorPerms()

getXMLChildCount

public final int getXMLChildCount()

Gets this node's XML child count.

Returns:

the number of XML child nodes.

getData

public java.lang.String getData()

Gets this node's data.

Returns:

the data appropriate for the various node types.

getDynamicScriptProp

protected ScriptDynamicPropObj getDynamicScriptProp(java.lang.String sPropertyName,
                                                    boolean bPropertyOverride,
                                                    boolean bPeek,
                                                    int nXFAVersion,
                                                    int nAvailability)

getFirstXMLChild

public Node getFirstXMLChild()

Gets this node's first XML child.

Returns:

null - nodes do not have children.

getFirstXFAChild

public Node getFirstXFAChild()

Gets this node's first XFA child.

Returns:

null - nodes do not have children.

getLastXMLChild

public Node getLastXMLChild()

Gets this node's last XML child. Note that this is a fairly expensive operation -- involves iterating to find the last child.

Returns:

the last child, or null if none.

getModel

public Model getModel()

Gets this node's model.

Returns:

the model.

getName

public abstract java.lang.String getName()

Gets this node's name. The name of a node is the value of its name attribute, or the element tagname if there is no name attribute.

Returns:

the name of the node.

getNextXMLSibling

public final Node getNextXMLSibling()

Gets this node's next XML sibling.

Returns:

the next XML sibling, or null if none.

getNextXFASibling

public Node getNextXFASibling()

Gets this node's next XFA sibling.

Returns:

the next XFA sibling, or null if none.

getOwnerDocument

public final Document getOwnerDocument()

Gets this node's owner document.

Returns:

the owner document, or null if this node is a document or does not have a parent.

getXMLParent

public Element getXMLParent()

Gets this node's XML parent.

Returns:

the XML parent.

See Also:

Node.getXFAParent()

getXFAParent

public Element getXFAParent()

Gets this node's XFA parent.

Returns:

the XFA parent.

See Also:

Node.getXMLParent()

getPreviousXMLSibling

public Node getPreviousXMLSibling()

Gets this node's previous XML sibling. Note that this may be a fairly expensive operation, as it involves iterating through the parent's children looking for this node.

Returns:

the previous sibling, or null, if none.

getSOMExpression

public final java.lang.String getSOMExpression()

Gets this element's absolute SOM expression.

Returns:

the SOM expression reflecting this element's absolute location within the document hierarchy.

getXFAChildCount

public final int getXFAChildCount()

Gets this node's number of XFA children.

Returns:

the number of XFA child nodes.

hasChanged

public final void hasChanged(boolean bIsDirty)

Sets this changed state of this node and its descendants to the given state.

Parameters:

bIsDirty - the dirty state.

cleanDirtyFlags

public final void cleanDirtyFlags()

remove

public void remove()

Removes this node from its parent child list.

resolveNode

public final Node resolveNode(java.lang.String somExpr)

Evaluates the Scripting Object Model expression, using this node as the current context.

For example, resolveNode("data.name[1]") returns the requested node if it exists; otherwise it returns null.

The method call resolveNode(somExpr) is equivalent to the call:

resolveNode(somExpr, false, false, false)

Parameters:

somExpr - a SOM expression.

Returns:

the node corresponding to the SOM expression if it exists, and null otherwise.

Throws:

ExFull - of type SOMTypeException, if more than one node was found.

See Also:

Node.resolveNode(String, boolean, boolean, boolean)

resolveNode

public final Node resolveNode(java.lang.String somExpr,
                              boolean bPeek,
                              boolean bLastOccurence,
                              boolean bNoProperties)

Evaluates the Scripting Object Model expression, using this node as the current context.

To peek at the node, set the peek argument to true. If the node is present, it is returned; otherwise null is returned. When set to true, default properties aren't created, and proto references are not expanded.

Parameters:

somExpr - a SOM expression.

bPeek - whether to beek at the node, or not.

bLastOccurence - whether to get the last occurence of the node whenever [*] is used in the somExpr argument, or not.

bNoProperties - whether to return no properties in the result, or not.

Returns:

the node corresponding to the SOM expression if it exists, and null otherwise.

Throws:

ExFull - of type SOMTypeException, if more than one node was found.

resolveNodes

public NodeList resolveNodes(java.lang.String somExpr,
                             boolean bPeek,
                             boolean bLastOccurence,
                             boolean bNoProperties)

Evaluates the Scripting Object Model expression, using this node as the current context.

For example, resolveNodes("data.name[*]") returns a node list corresponding to the SOM expression, which may be an empty.

Parameters:

somExpr - a SOM expression.

bPeek - if true, don't create default properties in the result.

bLastOccurence - if true, only get the last occurence whenever [*] is used in the SOM expression.

bNoProperties - if true, don't return properties in the result.

Returns:

a node list corresponding to the SOM expression if nodes are found, an empty NodeList (not null) otherwise.

setNextXMLSibling

protected final void setNextXMLSibling(Node node)

Sets this node's next XML sibling.

Parameters:

node - the sibling.

setXMLParent

protected final void setXMLParent(Element parent)

Sets this node's XML parent.

Parameters:

parent - the parent.

setPermsLock

public void setPermsLock(boolean bPermsLock)

Sets the permissions state of this node. Locking a node will cause some attempts to invoke methods or set properties to throw an exception.

Parameters:

bPermsLock - the permissions state to set this node to: true will lock the node; false will unlock the node.

compareVersions

public boolean compareVersions(Node oRollbackNode,
                               Node.ChangeLogger oChangeLogger,
                               java.lang.Object oUserData)

Determines if this node (and all it's descendants) differs from the given roll-back node. Callers wishing to know what differs can supply a change logger which will get a notification call for each change found: any out-of-order nodes will get reported as changed.

Parameters:

oRollbackNode - the roll-back node.

oChangeLogger - an optional (may be null) instance of a change logger. The change logger's methods will be called for each change found.

oUserData - an optional (may be null) user-supplied object managed by the change logger.

Returns:

true if this node matches the roll-back node, and false otherwise.