Package com.adobe.xfa

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

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

      • 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:
        setPermsLock(boolean), checkPerms(), 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:
        setPermsLock(boolean), checkPerms(), checkAncestorPerms()

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

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

      • getXFAParent

        public Element getXFAParent()
        Gets this node's XFA parent.
        Returns:
        the XFA parent.
        See Also:
        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.

      • getPrivateName

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

      • getProperty

        public java.lang.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 java.lang.Object getProperty​(java.lang.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.

      • getSibling

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

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

      • getSOMExpression

        public final java.lang.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 java.lang.String getSomName()

      • getUniqueSOMName

        public final java.lang.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​(java.lang.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,
                        java.lang.String arg1,
                        java.lang.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​(java.lang.String sLHS,
                                    java.lang.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​(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:
        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.

      • resolveNode

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

      • resolveNodes

        public NodeList resolveNodes​(java.lang.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:
        Obj.sendMessenge(ExFull, int)

      • serialize

        public abstract void serialize​(java.io.OutputStream outFile,
                               DOMSaveOptions options,
                               int level,
                               Node prevSibling)
                        throws java.io.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:
        java.io.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​(java.lang.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​(java.lang.String aNewName)
        used when resolving protos

      • unLock

        public final void unLock()

      • validateSchema

        public boolean validateSchema​(int nTargetVersion,
                              int nTargetAvailability,
                              boolean bRecursive,
                              java.util.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:
        Obj.validateUsage(int, int, boolean)

      • 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:
        Obj.validateUsageFailedIsFatal(int, int)

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

      • getPropName

        public static java.lang.String getPropName​(Element oNode,
                                           int eTag)
        Helper routine for compareVersions()

      • getPIName

        public java.lang.String getPIName​(Element oNode,
                                  java.lang.String sPI)
        Helper routine for compareVersions()

      • getNodeAsXML

        public static java.lang.String getNodeAsXML​(Node oNode)
        Helper routine for compareVersions()

      • getPIAsXML

        public static java.lang.String getPIAsXML​(java.lang.String sPI)
        Helper routine for compareVersions()

      • logValueChangeHelper

        public void logValueChangeHelper​(Node oContainer,
                                 java.lang.String sNewValue,
                                 Node.ChangeLogger oChangeLogger,
                                 java.lang.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 -