Class XMPNodeUtils

  • All Implemented Interfaces:
    XMPConst

    public class XMPNodeUtils
    extends java.lang.Object
    implements XMPConst
    Utilities for XMPNode.
    Since:
    Aug 28, 2006
    • Constructor Detail

      • XMPNodeUtils

        private XMPNodeUtils()
        Private Constructor
    • Method Detail

      • findSchemaNode

        static XMPNode findSchemaNode​(XMPNode tree,
                                      java.lang.String namespaceURI,
                                      boolean createNodes)
                               throws XMPException
        Find or create a schema node if createNodes is false and
        Parameters:
        tree - the root of the xmp tree.
        namespaceURI - a namespace
        createNodes - a flag indicating if the node shall be created if not found. Note: The namespace must be registered prior to this call.
        Returns:
        Returns the schema node if found, null otherwise. Note: If createNodes is true, it is always returned a valid node.
        Throws:
        XMPException - An exception is only thrown if an error occurred, not if a node was not found.
      • findSchemaNode

        static XMPNode findSchemaNode​(XMPNode tree,
                                      java.lang.String namespaceURI,
                                      java.lang.String suggestedPrefix,
                                      boolean createNodes)
                               throws XMPException
        Find or create a schema node if createNodes is true.
        Parameters:
        tree - the root of the xmp tree.
        namespaceURI - a namespace
        suggestedPrefix - If a prefix is suggested, the namespace is allowed to be registered.
        createNodes - a flag indicating if the node shall be created if not found. Note: The namespace must be registered prior to this call.
        Returns:
        Returns the schema node if found, null otherwise. Note: If createNodes is true, it is always returned a valid node.
        Throws:
        XMPException - An exception is only thrown if an error occurred, not if a node was not found.
      • findChildNode

        static XMPNode findChildNode​(XMPNode parent,
                                     java.lang.String childName,
                                     boolean createNodes)
                              throws XMPException
        Find or create a child node under a given parent node. If the parent node is no Returns the found or created child node.
        Parameters:
        parent - the parent node
        childName - the node name to find
        createNodes - flag, if new nodes shall be created.
        Returns:
        Returns the found or created node or null.
        Throws:
        XMPException - Thrown if
      • findNode

        static XMPNode findNode​(XMPNode xmpTree,
                                XMPPath xpath,
                                boolean createNodes,
                                PropertyOptions leafOptions)
                         throws XMPException
        Follow an expanded path expression to find or create a node.
        Parameters:
        xmpTree - the node to begin the search.
        xpath - the complete xpath
        createNodes - flag if nodes shall be created (when called by setProperty())
        leafOptions - the options for the created leaf nodes (only when createNodes == true).
        Returns:
        Returns the node if found or created or null.
        Throws:
        XMPException - An exception is only thrown if an error occurred, not if a node was not found.
      • deleteNode

        static void deleteNode​(XMPNode node)
        Deletes the the given node and its children from its parent. Takes care about adjusting the flags.
        Parameters:
        node - the top-most node to delete.
      • setNodeValue

        static void setNodeValue​(XMPNode node,
                                 java.lang.Object value)
        This is setting the value of a leaf node.
        Parameters:
        node - an XMPNode
        value - a value
      • verifySetOptions

        static PropertyOptions verifySetOptions​(PropertyOptions options,
                                                java.lang.Object itemValue)
                                         throws XMPException
        Verifies the PropertyOptions for consistancy and updates them as needed. If options are null they are created with default values.
        Parameters:
        options - the PropertyOptions
        itemValue - the node value to set
        Returns:
        Returns the updated options.
        Throws:
        XMPException - If the options are not consistant.
      • serializeNodeValue

        static java.lang.String serializeNodeValue​(java.lang.Object value)
        Converts the node value to String, apply special conversions for defined types in XMP.
        Parameters:
        value - the node value to set
        Returns:
        Returns the String representation of the node value.
      • followXPathStep

        private static XMPNode followXPathStep​(XMPNode parentNode,
                                               XMPPathSegment nextStep,
                                               boolean createNodes)
                                        throws XMPException
        After processing by ExpandXPath, a step can be of these forms:
        • qualName - A top level property or struct field.
        • [index] - An element of an array.
        • [last()] - The last element of an array.
        • [qualName="value"] - An element in an array of structs, chosen by a field value.
        • [?qualName="value"] - An element in an array, chosen by a qualifier value.
        • ?qualName - A general qualifier.
        Find the appropriate child node, resolving aliases, and optionally creating nodes.
        Parameters:
        parentNode - the node to start to start from
        nextStep - the xpath segment
        createNodes -
        Returns:
        returns the found or created XMPPath node
        Throws:
        XMPException
      • findQualifierNode

        private static XMPNode findQualifierNode​(XMPNode parent,
                                                 java.lang.String qualName,
                                                 boolean createNodes)
                                          throws XMPException
        Find or create a qualifier node under a given parent node. Returns a pointer to the qualifier node, and optionally an iterator for the node's position in the parent's vector of qualifiers. The iterator is unchanged if no qualifier node (null) is returned. Note: On entry, the qualName parameter must not have the leading '?' from the XMPPath step.
        Parameters:
        parent - the parent XMPNode
        qualName - the qualifier name
        createNodes - flag if nodes shall be created
        Returns:
        Returns the qualifier node if found or created, null otherwise.
        Throws:
        XMPException
      • findIndexedItem

        private static int findIndexedItem​(XMPNode arrayNode,
                                           java.lang.String segment,
                                           boolean createNodes)
                                    throws XMPException
        Parameters:
        arrayNode - an array node
        segment - the segment containing the array index
        createNodes - flag if new nodes are allowed to be created.
        Returns:
        Returns the index or index = -1 if not found
        Throws:
        XMPException - Throws Exceptions
      • lookupFieldSelector

        private static int lookupFieldSelector​(XMPNode arrayNode,
                                               java.lang.String fieldName,
                                               java.lang.String fieldValue)
                                        throws XMPException
        Searches for a field selector in a node: [fieldName="value] - an element in an array of structs, chosen by a field value. No implicit nodes are created by field selectors.
        Parameters:
        arrayNode -
        fieldName -
        fieldValue -
        Returns:
        Returns the index of the field if found, otherwise -1.
        Throws:
        XMPException
      • lookupQualSelector

        private static int lookupQualSelector​(XMPNode arrayNode,
                                              java.lang.String qualName,
                                              java.lang.String qualValue,
                                              int aliasForm)
                                       throws XMPException
        Searches for a qualifier selector in a node: [?qualName="value"] - an element in an array, chosen by a qualifier value. No implicit nodes are created for qualifier selectors, except for an alias to an x-default item.
        Parameters:
        arrayNode - an array node
        qualName - the qualifier name
        qualValue - the qualifier value
        aliasForm - in case the qual selector results from an alias, an x-default node is created if there has not been one.
        Returns:
        Returns the index of th
        Throws:
        XMPException
      • normalizeLangArray

        static void normalizeLangArray​(XMPNode arrayNode)
        Make sure the x-default item is first. Touch up "single value" arrays that have a default plus one real language. This case should have the same value for both items. Older Adobe apps were hardwired to only use the "x-default" item, so we copy that value to the other item.
        Parameters:
        arrayNode - an alt text array node
      • detectAltText

        static void detectAltText​(XMPNode arrayNode)
        See if an array is an alt-text array. If so, make sure the x-default item is first.
        Parameters:
        arrayNode - the array node to check if its an alt-text array
      • appendLangItem

        static void appendLangItem​(XMPNode arrayNode,
                                   java.lang.String itemLang,
                                   java.lang.String itemValue)
                            throws XMPException
        Appends a language item to an alt text array.
        Parameters:
        arrayNode - the language array
        itemLang - the language of the item
        itemValue - the content of the item
        Throws:
        XMPException - Thrown if a duplicate property is added
      • chooseLocalizedText

        static java.lang.Object[] chooseLocalizedText​(XMPNode arrayNode,
                                                      java.lang.String genericLang,
                                                      java.lang.String specificLang)
                                               throws XMPException
        1. Look for an exact match with the specific language.
        2. If a generic language is given, look for partial matches.
        3. Look for an "x-default"-item.
        4. Choose the first item.
        Parameters:
        arrayNode - the alt text array node
        genericLang - the generic language
        specificLang - the specific language
        Returns:
        Returns the kind of match as an Integer and the found node in an array.
        Throws:
        XMPException
      • lookupLanguageItem

        static int lookupLanguageItem​(XMPNode arrayNode,
                                      java.lang.String language)
                               throws XMPException
        Looks for the appropriate language item in a text alternative array.item
        Parameters:
        arrayNode - an array node
        language - the requested language
        Returns:
        Returns the index if the language has been found, -1 otherwise.
        Throws:
        XMPException