Package com.adobe.xfa

Class Node

java.lang.Object
com.adobe.xfa.Obj
com.adobe.xfa.Node
All Implemented Interfaces:
Peer
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.

  • Field Details

  • Method Details

    • assignNode

      public Node assignNode(String sSOMExpression, 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:

    • 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:

    • 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:

    • clone

      public abstract Node clone(Element parent)

    • getAll

      public NodeList getAll(boolean bByName)
      Return the collection of like-named, in-scope, nodes.
      Returns:
      the collection.

    • getXMLChildCount

      public final int getXMLChildCount()
      Gets this node's XML child count.
      Returns:
      the number of XML child nodes.

    • getData

      public String getData()
      Gets this node's data.
      Returns:
      the data appropriate for the various node types.

    • getFirstXMLChild

      public Node getFirstXMLChild()
      Gets this node's first XML child.
      Returns:
      null - nodes do not have children.

    • getFirstXMLChildElement

      public final Element getFirstXMLChildElement()
      Return the first child that is an element. Scans through children sequentially for the first one that is an element. This is useful when processing non-XFA content.
      Returns:
      First element child of the node; null if the node has no element children or the derived class is incapable of having children.

    • getFirstXFAChild

      public Node getFirstXFAChild()
      Gets this node's first XFA child.
      Returns:
      null - nodes do not have children.

    • getIndex

      public int getIndex(boolean bByName)

    • 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.

    • getLocked

      public final boolean getLocked()
      Gets the locked state of this node.
      Returns:
      true if the node is locked and false otherwise.

    • getModel

      public Model getModel()
      Gets this node's model.
      Returns:
      the model.

    • getName

      public abstract 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.

    • getNextXMLSiblingElement

      public final Element getNextXMLSiblingElement()
      Return the next sibling that is an element. This method skips through intervening non-element nodes until it finds one that is an element.
      Returns:
      Next element subling; null if there is no such sibling.

    • getNextXFASibling

      public Node getNextXFASibling()
      Gets this node's next XFA sibling.
      Returns:
      the next XFA sibling, or null if none.

    • getNodes

      public NodeList getNodes()
      Gets this node's list of all child nodes.
      Returns:
      the list of child nodes.

    • 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:

    • getXFAParent

      public Element getXFAParent()
      Gets this node's XFA parent.
      Returns:
      the XFA parent.
      See Also:

    • 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.

    • getPrivateName

      public String getPrivateName()
      used for determining uniqueness when resolving protos

    • getProperty

      public Object getProperty(int ePropertyTag, int nOccurrence)
      Get a property for this node.
      Parameters:
      ePropertyTag - The XFA tag (name) of the property to check for.
      nOccurrence - if this property can occur a fix number of times (usually [0..n]), then specify which occurrence to get. Defaults to 0.
      Returns:
      The requested property. If the property has not been specified, this will contain a default value. There is a special case for the handling of pcdata. Technically, pcdata is a child node relationship, but it is retrieved via an attribute - XFAString. The property name in this case is XFA::textNodeTag(). The return value will never be a null object. The XFAProperty will refer to either an Node or an Attribute.

    • getProperty

      public Object getProperty(String propertyName, int nOccurrence)
      string version of getProperty. ***Less efficient than the int version The parameter propertyName should correspond to the name of either a child element that occurs 0..1 times OR is the name of an attribute. The parameter propertyName must be a valid property for this particular class.

    • getScriptTable

      public ScriptTable getScriptTable()
      Overrides:
      getScriptTable in class Obj

    • getSibling

      public Node getSibling(int index, boolean bByName, boolean bExceptionIfNotFound)

    • getSOMExpression

      public final String getSOMExpression()
      Gets this element's absolute SOM expression.
      Returns:
      the SOM expression reflecting this element's absolute location within the document hierarchy.

    • getSOMExpression

      public final String getSOMExpression(Node oRelativeTo, boolean bSkipZeroIndex)
      Gets this element's relative SOM expression.
      Parameters:
      oRelativeTo - if non-null, the SOM expression will be relative to this node. In order for this to be useful, the given node must be in the parent hierarchy of this element.
      Returns:
      the SOM expression reflecting this element's relative location within the document hierarchy.

    • getSomName

      public String getSomName()

    • getUniqueSOMName

      public final String getUniqueSOMName(Element contextNode)

    • getWillDirty

      public boolean getWillDirty()

    • 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()

    • isContainer

      public boolean isContainer()
      Check to see if this is a container object. A container is defined as something that is not a leaf node not properties ( [0..1] occurrences ). It does NOT indicate whether this node derives from XFAContainer
      Returns:
      true if this node is a container, false otherwise

    • isDefault

      public boolean isDefault(boolean bCheckProto)

    • isDirty

      public final boolean isDirty()
      Determine if this node is dirty.
      Returns:
      the dirty state.

    • setDirty

      public final void setDirty()
      Set the dirty state of this node.

    • setDocument

      public final void setDocument(Document document)

    • isLeaf

      public abstract boolean isLeaf()
      Is this node is a leaf.
      Returns:
      true if this node is a leaf and false otherwise.

    • isMapped

      public boolean isMapped()
      Get the mapped state for the current node.

    • isPermsLockSet

      public boolean isPermsLockSet()
      Gets the permissions state of this node.
      Returns:
      true if the node is locked.

    • isPropertySpecified

      public boolean isPropertySpecified(int ePropertyTag, boolean bCheckProtos, int nOccurrence)
      Check if a specific property has been defined for this node.
      Parameters:
      ePropertyTag - The XFA tag (name) of the property to check for.
      bCheckProtos - if true, check if this property is specified via prototype inheritance. Defaults to true.
      nOccurrence - if this property can occur a fix number of times (usually [0..n]), then specify which occurrence to check for. Defaults to 0.
      Returns:
      True if the property has been specified.

      The property name should correspond to the name of either a child element that occurs 0..1 times OR is the name of an attribute. The parameter propertyName must be a valid property for this particular class.

    • isSpecified

      public boolean isSpecified(int ePropertyTag, boolean bCheckProtos, int nOccurrence)
      Check if a property, child, or oneOfChild has been defined for this node
      Parameters:
      ePropertyTag - The XFA tag (name) of the property/child/oneOfChild to check for.
      bCheckProtos - if true, check if this property is specified via prototype inheritance. Defaults to true.
      nOccurrence - if this property can occur a fix number of times (usually [0..n]), then specify which occurrence to check for. Defaults to 0.
      Returns:
      True if the property has been specified.

    • isTransient

      public boolean isTransient()
      Determine if this node is transient or not. Transient nodes are not saved when the DOM is written out.
      Returns:
      boolean transient status.

    • isTransient

      public void isTransient(boolean bTransient, boolean bSetChildren)
      Set the transient state of this node. Transient nodes are not saved when the DOM is written out.
      Parameters:
      bTransient - the new transient state.

    • isTransparent

      public boolean isTransparent()

    • locateChildByClass

      public Node locateChildByClass(int eChildTag, int nIndex)

    • locateChildByName

      public final Node locateChildByName(String aChildName, int nIndex)
      Note. This method needs to use the "XML" API calls as it is invoked by HrefStore.filterPackets() to read config values.

    • makeDefault

      public void makeDefault()
      Mark this element as a default property

    • makeNonDefault

      public void makeNonDefault(boolean bRecursive)
      Mark this element to indicate it is not a default property

    • notifyPeers

      public void notifyPeers(int eventType, String arg1, Object arg2)
      Description copied from interface: Peer
      Sends notification to the peer nodes that this object has changed.
      Specified by:
      notifyPeers in interface Peer
      Overrides:
      notifyPeers in class Obj
      Parameters:
      eventType - the event type as enumerated in this class
      arg1 - additional event information
      arg2 - additional event information

    • performSOMAssignment

      public boolean performSOMAssignment(String sLHS, String sRHS, Obj[] oObjectParameters)

    • peekOneOfChild

      public Node peekOneOfChild(boolean bReturnDefault)
      READ ONLY VERSION of getOneOfChild In the case where an element may contain a "OneOf" child, this method will retrieve the child element that has the XFA::oneOfChild relationship to its parent.

      When one only one child node out of a set of nodes can exist for a particular node, then that set of nodes is called a oneOf children.

      Note! Proto references are not expanded, SHOULD NOT modify the resulting node.

      Parameters:
      bReturnDefault - true if you want the defualt node to be returned if the "OneOf" child doesn't exist, if false null will be returned
      Returns:
      the "OneOf" child for this node. If this child has not been specified, this method will return null.

    • postSave

      public abstract void postSave()

    • preSave

      public abstract void preSave(boolean bSaveXMLScript)

    • remove

      public void remove()
      Removes this node from its parent child list.

    • resolveNode

      public final Node resolveNode(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:

    • resolveNode

      public final Node resolveNode(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.

    • resolveNode

      public final Node resolveNode(String somExpr, boolean bPeek, boolean bLastOccurence, boolean bNoProperties, DependencyTracker dependencyTracker, BooleanHolder isAssociation)
      Evaluates the Scripting Object Model expression, using this node as the current context.

    • resolveNodes

      public NodeList resolveNodes(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.

    • resolveNodes

      public NodeList resolveNodes(String somExpr, boolean bPeek, boolean bLastOccurence, boolean bNoProperties, DependencyTracker dependencyTracker, BooleanHolder isAssociation)
      Evaluates the Scripting Object Model expression, using this node as the current context.

    • sendMessenge

      public void sendMessenge(ExFull error, int eSeverity)
      Description copied from class: Obj
      Send message to host so it can be logged
      Overrides:
      sendMessenge in class Obj
      Parameters:
      error - contains message Id and text
      eSeverity - the message severity
      See Also:

    • serialize

      public abstract void serialize(OutputStream outFile, DOMSaveOptions options, int level, Node prevSibling) throws IOException
      The helper function used by saveXML()
      Parameters:
      outFile - Streamfile to write to
      options - save options
      level - the indent level
      prevSibling - our previous sibling -- needed for some markup options.
      Throws:
      IOException

    • setLocked

      public final void setLocked(boolean bLockState)
      Set the locked state of this node to be locked

    • setMapped

      public void setMapped(boolean bIsMapped)
      Set the mapped state for the current node.
      Parameters:
      bIsMapped -

    • setName

      public void setName(String aName)

    • 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.

    • setWillDirty

      public void setWillDirty(boolean bWillDirty)

    • setPrivateName

      public void setPrivateName(String aNewName)
      used when resolving protos

    • unLock

      public final void unLock()

    • validateSchema

      public boolean validateSchema(int nTargetVersion, int nTargetAvailability, boolean bRecursive, List<NodeValidationInfo> pValidationInfo)
      Validate this node against the schema.
      Parameters:
      nTargetVersion - the target XFA version
      nTargetAvailability - a collection of bits defining what subsets of the schema are supported
      pValidationInfo - list of invalid children, attributes and attribute values based on the target version and availability. If this node is not valid child of its parent this node will be the first entry of pInfo.
      Returns:
      TRUE if this node, the child or all attributes are valid, otherwise FALSE

    • validateUsage

      public boolean validateUsage(int nXFAVersion, int nAvailability, boolean bUpdateVersion)
      Description copied from class: Obj
      Validate if the given Version and Availability flags are valid for the current document
      Overrides:
      validateUsage in class Obj
      Parameters:
      nXFAVersion - The target XFA Version
      nAvailability - The target Availability flags, this indicates for what clients the script is available
      bUpdateVersion - indicates if the model version can be updated by the calling code
      Returns:
      if true, Version and Availability flags are valid
      See Also:

    • validateUsageFailedIsFatal

      public boolean validateUsageFailedIsFatal(int nXFAVersion, int nAvailability)
      Description copied from class: Obj
      Determines if disallowing a version should be considered a fatal error.

      This method is called after calling Obj.validateUsage(int, int, boolean) when that method returns false.

      Overrides:
      validateUsageFailedIsFatal in class Obj
      Parameters:
      nXFAVersion - The target XFA Version
      nAvailability - The target Availability flags, this indicates for what clients the script is available
      Returns:
      true if disallowing nVersion should be considered a fatal error
      See Also:

    • compareVersions

      public boolean compareVersions(Node oRollbackNode, Node.ChangeLogger oChangeLogger, 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.

    • getPropName

      public static String getPropName(Element oNode, int eTag)
      Helper routine for compareVersions()

    • getPIName

      public String getPIName(Element oNode, String sPI)
      Helper routine for compareVersions()

    • getNodeAsXML

      public static String getNodeAsXML(Node oNode)
      Helper routine for compareVersions()

    • getPIAsXML

      public static String getPIAsXML(String sPI)
      Helper routine for compareVersions()

    • logValueChangeHelper

      public void logValueChangeHelper(Node oContainer, String sNewValue, Node.ChangeLogger oChangeLogger, Object oUserData)
      Helper routine for compareVersions()

    • getXfaPeer

      public Element getXfaPeer()
      Gets the XFA DOM Node that is the peer to this XML DOM Node.

    • setXfaPeer

      public void setXfaPeer(Element xfaPeer)
      Parameters:
      xfaPeer -