Package com.adobe.internal.xmp

Class XMPUtils

  • public class XMPUtils
extends java.lang.Object
    Utility methods for XMP. I included only those that are different from the Java default conversion utilities.
    Since:
    21.02.2006

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void appendProperties​(XMPMeta source, XMPMeta dest, boolean doAllProperties, boolean replaceOldValues)
      Alias without the new option deleteEmptyValues.
      static void appendProperties​(XMPMeta source, XMPMeta dest, boolean doAllProperties, boolean replaceOldValues, boolean deleteEmptyValues)
      Append properties from one XMP object to another.
      static void applyTemplate​(XMPMeta workingXMP, XMPMeta templateXMP, TemplateOptions options)
      modifies a working XMP object according to a template object.
      static java.lang.String catenateArrayItems​(XMPMeta xmp, java.lang.String schemaNS, java.lang.String arrayName, java.lang.String separator, java.lang.String quotes, boolean allowCommas)
      Create a single edit string from an array of strings.
      static java.lang.String convertFromBoolean​(boolean value)
      Convert from boolean to string.
      static java.lang.String convertFromDate​(XMPDateTime value)
      Convert from XMPDateTime to string.
      static java.lang.String convertFromDouble​(double value)
      Convert from long to string.
      static java.lang.String convertFromInteger​(int value)
      Convert from int to string.
      static java.lang.String convertFromLong​(long value)
      Convert from long to string.
      static boolean convertToBoolean​(java.lang.String value)
      Convert from string to Boolean.
      static XMPDateTime convertToDate​(java.lang.String rawValue)
      Converts a string value to an XMPDateTime.
      static double convertToDouble​(java.lang.String rawValue)
      Converts a string value to a double.
      static int convertToInteger​(java.lang.String rawValue)
      Converts a string value to an int.
      static long convertToLong​(java.lang.String rawValue)
      Converts a string value to a long.
      static byte[] decodeBase64​(java.lang.String base64String)
      Decode from Base64 encoded string to raw data.
      static void duplicateSubtree​(XMPMeta source, XMPMeta dest, java.lang.String sourceNS, java.lang.String sourceRoot, java.lang.String destNS, java.lang.String destRoot, PropertyOptions options)
      Replicate a subtree from one XMP object into another, possibly at a different location.
      static java.lang.String encodeBase64​(byte[] buffer)
      Convert from a byte array to a base64 encoded string.
      static void mergeFromJPEG​(XMPMeta fullXMP, XMPMeta extendedXMP)
      merges standard and extended XMP retrieved from a JPEG file.
      static void packageForJPEG​(XMPMeta origXMP, java.lang.StringBuilder stdStr, java.lang.StringBuilder extStr, java.lang.StringBuilder digestStr)
      creates XMP serializations appropriate for a JPEG file.
      static void removeProperties​(XMPMeta xmp, java.lang.String schemaNS, java.lang.String propName, boolean doAllProperties, boolean includeAliases)
      Remove multiple properties from an XMP object.
      static void separateArrayItems​(XMPMeta xmp, java.lang.String schemaNS, java.lang.String arrayName, java.lang.String catedStr, PropertyOptions arrayOptions, boolean preserveCommas)
      Separate a single edit string into an array of strings.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • catenateArrayItems

        public static java.lang.String catenateArrayItems​(XMPMeta xmp,
                                                  java.lang.String schemaNS,
                                                  java.lang.String arrayName,
                                                  java.lang.String separator,
                                                  java.lang.String quotes,
                                                  boolean allowCommas)
                                           throws XMPException
        Create a single edit string from an array of strings.
        Parameters:
        xmp - The XMP object containing the array to be catenated.
        schemaNS - The schema namespace URI for the array. Must not be null or the empty string.
        arrayName - The name of the array. May be a general path expression, must not be null or the empty string. Each item in the array must be a simple string value.
        separator - The string to be used to separate the items in the catenated string. Defaults to "; ", ASCII semicolon and space (U+003B, U+0020).
        quotes - The characters to be used as quotes around array items that contain a separator. Defaults to '"'
        allowCommas - Option flag to control the catenation.
        Returns:
        Returns the string containing the catenated array items.
        Throws:
        XMPException - Forwards the Exceptions from the metadata processing

      • separateArrayItems

        public static void separateArrayItems​(XMPMeta xmp,
                                      java.lang.String schemaNS,
                                      java.lang.String arrayName,
                                      java.lang.String catedStr,
                                      PropertyOptions arrayOptions,
                                      boolean preserveCommas)
                               throws XMPException
        Separate a single edit string into an array of strings.
        Parameters:
        xmp - The XMP object containing the array to be updated.
        schemaNS - The schema namespace URI for the array. Must not be null or the empty string.
        arrayName - The name of the array. May be a general path expression, must not be null or the empty string. Each item in the array must be a simple string value.
        catedStr - The string to be separated into the array items.
        arrayOptions - Option flags to control the separation.
        preserveCommas - Flag if commas shall be preserved
        Throws:
        XMPException - Forwards the Exceptions from the metadata processing

      • removeProperties

        public static void removeProperties​(XMPMeta xmp,
                                    java.lang.String schemaNS,
                                    java.lang.String propName,
                                    boolean doAllProperties,
                                    boolean includeAliases)
                             throws XMPException
        Remove multiple properties from an XMP object. RemoveProperties was created to support the File Info dialog's Delete button, and has been been generalized somewhat from those specific needs. It operates in one of three main modes depending on the schemaNS and propName parameters:
        • Non-empty schemaNS and propName - The named property is removed if it is an external property, or if the flag doAllProperties option is true. It does not matter whether the named property is an actual property or an alias.
        • Non-empty schemaNS and empty propName - The all external properties in the named schema are removed. Internal properties are also removed if the flag doAllProperties option is set. In addition, aliases from the named schema will be removed if the flag includeAliases option is set.
        • Empty schemaNS and empty propName - All external properties in all schema are removed. Internal properties are also removed if the flag doAllProperties option is passed. Aliases are implicitly handled because the associated actuals are internal if the alias is.
        It is an error to pass an empty schemaNS and non-empty propName.
        Parameters:
        xmp - The XMP object containing the properties to be removed.
        schemaNS - Optional schema namespace URI for the properties to be removed.
        propName - Optional path expression for the property to be removed.
        doAllProperties - Option flag to control the deletion: do internal properties in addition to external properties.
        includeAliases - Option flag to control the deletion: Include aliases in the "named schema" case above. Note: Currently not supported.
        Throws:
        XMPException - Forwards the Exceptions from the metadata processing

      • appendProperties

        public static void appendProperties​(XMPMeta source,
                                    XMPMeta dest,
                                    boolean doAllProperties,
                                    boolean replaceOldValues)
                             throws XMPException
        Alias without the new option deleteEmptyValues.
        Parameters:
        source - The source XMP object.
        dest - The destination XMP object.
        doAllProperties - Do internal properties in addition to external properties.
        replaceOldValues - Replace the values of existing properties.
        Throws:
        XMPException - Forwards the Exceptions from the metadata processing

      • appendProperties

        public static void appendProperties​(XMPMeta source,
                                    XMPMeta dest,
                                    boolean doAllProperties,
                                    boolean replaceOldValues,
                                    boolean deleteEmptyValues)
                             throws XMPException

        Append properties from one XMP object to another.

        XMPUtils#appendProperties was created to support the File Info dialog's Append button, and has been been generalized somewhat from those specific needs. It appends information from one XMP object (source) to another (dest). The default operation is to append only external properties that do not already exist in the destination. The flag doAllProperties can be used to operate on all properties, external and internal. The flag replaceOldValues option can be used to replace the values of existing properties. The notion of external versus internal applies only to top level properties. The keep-or-replace-old notion applies within structs and arrays as described below.

        • If replaceOldValues is true then the processing is restricted to the top level properties. The processed properties from the source (according to doAllProperties) are propagated to the destination, replacing any existing values.Properties in the destination that are not in the source are left alone.
        • If replaceOldValues is not passed then the processing is more complicated. Top level properties are added to the destination if they do not already exist. If they do exist but differ in form (simple/struct/array) then the destination is left alone. If the forms match, simple properties are left unchanged while structs and arrays are merged.
        • If deleteEmptyValues is passed then an empty value in the source XMP causes the corresponding destination XMP property to be deleted. The default is to treat empty values the same as non-empty values. An empty value is any of a simple empty string, an array with no items, or a struct with no fields. Qualifiers are ignored.

        The detailed behavior is defined by the following pseudo-code: 

            appendProperties ( sourceXMP, destXMP, doAllProperties,
                        replaceOldValues, deleteEmptyValues ):
       for all source schema (top level namespaces):
          for all top level properties in sourceSchema:
             if doAllProperties or prop is external:
                appendSubtree ( sourceNode, destSchema, replaceOldValues, deleteEmptyValues )

    appendSubtree ( sourceNode, destParent, replaceOldValues, deleteEmptyValues ):
        if deleteEmptyValues and source value is empty:
            delete the corresponding child from destParent
        else if sourceNode not in destParent (by name):
           copy sourceNode's subtree to destParent
        else if replaceOld:
            delete subtree from destParent
            copy sourceNode's subtree to destParent
        else:
            // Already exists in dest and not replacing, merge structs and arrays
            if sourceNode and destNode forms differ:
                return, leave the destNode alone
            else if form is a struct:
                for each field in sourceNode:
                    AppendSubtree ( sourceNode.field, destNode, replaceOldValues )
            else if form is an alt-text array:
                copy new items by "xml:lang" value into the destination
            else if form is an array:
                copy new items by value into the destination, ignoring order and duplicates

        Note: appendProperties can be expensive if replaceOldValues is not passed and the XMP contains large arrays. The array item checking described above is n-squared. Each source item is checked to see if it already exists in the destination, without regard to order or duplicates.

        Simple items are compared by value and "xml:lang" qualifier, other qualifiers are ignored. Structs are recursively compared by field names, without regard to field order. Arrays are compared by recursively comparing all items.

        Parameters:
        source - The source XMP object.
        dest - The destination XMP object.
        doAllProperties - Do internal properties in addition to external properties.
        replaceOldValues - Replace the values of existing properties.
        deleteEmptyValues - Delete destination values if source property is empty.
        Throws:
        XMPException - Forwards the Exceptions from the metadata processing

      • convertToBoolean

        public static boolean convertToBoolean​(java.lang.String value)
                                throws XMPException
        Convert from string to Boolean.
        Parameters:
        value - The string representation of the Boolean.
        Returns:
        The appropriate boolean value for the string. The checked values for true and false are:
        Throws:
        XMPException - If an empty string is passed.

      • convertFromBoolean

        public static java.lang.String convertFromBoolean​(boolean value)
        Convert from boolean to string.
        Parameters:
        value - a boolean value
        Returns:
        The XMP string representation of the boolean. The values used are given by the constnts XMPConst.TRUESTR and XMPConst.FALSESTR.

      • convertToInteger

        public static int convertToInteger​(java.lang.String rawValue)
                            throws XMPException
        Converts a string value to an int.
        Parameters:
        rawValue - the string value
        Returns:
        Returns an int.
        Throws:
        XMPException - If the rawValue is null or empty or the conversion fails.

      • convertFromInteger

        public static java.lang.String convertFromInteger​(int value)
        Convert from int to string.
        Parameters:
        value - an int value
        Returns:
        The string representation of the int.

      • convertToLong

        public static long convertToLong​(java.lang.String rawValue)
                          throws XMPException
        Converts a string value to a long.
        Parameters:
        rawValue - the string value
        Returns:
        Returns a long.
        Throws:
        XMPException - If the rawValue is null or empty or the conversion fails.

      • convertFromLong

        public static java.lang.String convertFromLong​(long value)
        Convert from long to string.
        Parameters:
        value - a long value
        Returns:
        The string representation of the long.

      • convertToDouble

        public static double convertToDouble​(java.lang.String rawValue)
                              throws XMPException
        Converts a string value to a double.
        Parameters:
        rawValue - the string value
        Returns:
        Returns a double.
        Throws:
        XMPException - If the rawValue is null or empty or the conversion fails.

      • convertFromDouble

        public static java.lang.String convertFromDouble​(double value)
        Convert from long to string.
        Parameters:
        value - a long value
        Returns:
        The string representation of the long.

      • convertToDate

        public static XMPDateTime convertToDate​(java.lang.String rawValue)
                                 throws XMPException
        Converts a string value to an XMPDateTime.
        Parameters:
        rawValue - the string value
        Returns:
        Returns an XMPDateTime-object.
        Throws:
        XMPException - If the rawValue is null or empty or the conversion fails.

      • convertFromDate

        public static java.lang.String convertFromDate​(XMPDateTime value)
        Convert from XMPDateTime to string.
        Parameters:
        value - an XMPDateTime
        Returns:
        The string representation of the long.

      • encodeBase64

        public static java.lang.String encodeBase64​(byte[] buffer)
        Convert from a byte array to a base64 encoded string.
        Parameters:
        buffer - the byte array to be converted
        Returns:
        Returns the base64 string.

      • decodeBase64

        public static byte[] decodeBase64​(java.lang.String base64String)
                           throws XMPException
        Decode from Base64 encoded string to raw data.
        Parameters:
        base64String - a base64 encoded string
        Returns:
        Returns a byte array containg the decoded string.
        Throws:
        XMPException - Thrown if the given string is not property base64 encoded

      • packageForJPEG

        public static void packageForJPEG​(XMPMeta origXMP,
                                  java.lang.StringBuilder stdStr,
                                  java.lang.StringBuilder extStr,
                                  java.lang.StringBuilder digestStr)
                           throws java.security.NoSuchAlgorithmException,
                                  XMPException
        creates XMP serializations appropriate for a JPEG file. The standard XMP in a JPEG file is limited to 64K bytes. This function serializes the XMP metadata in an XMP object into a string of RDF . If the data does not fit into the 64K byte limit, it creates a second packet string with the extended data.
        Parameters:
        origXMP - The XMP object containing the metadata.
        stdStr - A string builder object in which to return the full standard XMP packet.
        extStr - A string builder object in which to return the serialized extended XMP, empty if not needed.
        digestStr - A string builder object in which to return an MD5 digest of the serialized extended XMP, empty if not needed.
        Throws:
        java.security.NoSuchAlgorithmException - if fail to find algorithm for MD5
        XMPException - in case of internal error occurs.

      • mergeFromJPEG

        public static void mergeFromJPEG​(XMPMeta fullXMP,
                                 XMPMeta extendedXMP)
                          throws XMPException
        merges standard and extended XMP retrieved from a JPEG file. When an extended partition stores properties that do not fit into the JPEG file limitation of 64K bytes, this function integrates those properties back into the same XMP object with those from the standard XMP packet.
        Parameters:
        fullXMP - An XMP object which the caller has initialized from the standard XMP packet in a JPEG file. The extended XMP is added to this object.
        extendedXMP - An XMP object which the caller has initialized from the extended XMP packet in a JPEG file.
        Throws:
        XMPException - in case of internal error occurs.

      • applyTemplate

        public static void applyTemplate​(XMPMeta workingXMP,
                                 XMPMeta templateXMP,
                                 TemplateOptions options)
                          throws XMPException
        modifies a working XMP object according to a template object.

        The XMP template can be used to add, replace or delete properties from the working XMP object. The actions that you specify determine how the template is applied. Each action can be applied individually or combined; if you do not specify any actions, the properties and values in the working XMP object do not change.

        These actions are available:

        • Clear CLEAR_UNNAMED_PROPERTIES : Deletes top-level properties. Any top-level property that is present in the template (even with empty value) is retained. All other top-level properties in the working object are deleted
        • Add ADD_NEW_PROPERTIES : Adds new properties to the working object if the template properties have values. See additional detail below.
        • Replace REPLACE_EXISTING_PROPERTIES : Replaces the values of existing top-level properties in the working XMP if the value forms match those in the template. Properties with empty values in the template are ignored. If combined with Clear or Add actions, those take precedence; values are cleared or added, rather than replaced.
        • Replace/Delete empty REPLACE_WITH_DELETE_EMPTY : Replaces values in the same way as the simple Replace action, and also deletes properties if the value in the template is empty. If combined with Clear or Add actions, those take precedence; values are cleared or added, rather than replaced.
        • Include internal INCLUDE_INTERNAL_PROPERTIES : Performs specified action on internal properties as well as external properties. By default, internal properties are ignored for all actions.

        The Add behavior depends on the type of property:

        • If a top-level property is not in the working XMP, and has a value in the template, the property and value are added. Empty properties are not added.
        • If a property is in both the working XMP and template, the value forms must match, otherwise the template is ignored for that property.
        • If a struct is present in both the working XMP and template, the individual fields of the template struct are added as appropriate; that is, the logic is recursively applied to the fields. Struct values are equivalent if they have the same fields with equivalent values.
        • If an array is present in both the working XMP and template, items from the template are added if the value forms match. Array values match if they have sets of equivalent items, regardless of order.
        • Alt-text arrays use the \c xml:lang qualifier as a key, adding languages that are missing.

        Array item checking is n-squared; this can be time-intensive if the Replace option is not specified. Each source item is checked to see if it already exists in the destination, without regard to order or duplicates. Simple items are compared by value and xml:lang qualifier; other qualifiers are ignored. Structs are recursively compared by field names, without regard to field order. Arrays are compared by recursively comparing all items.

        Parameters:
        workingXMP - The destination XMP object.
        templateXMP - The template to apply to the destination XMP object.
        options - Option flags to control the copying. If none are specified, the properties and values in the working XMP do not change. A logical OR of these bit-flag constants:
        • CLEAR_UNNAMED_PROPERTIES Delete anything that is not in the template
        • ADD_NEW_PROPERTIES Add properties; see detailed description.
        • REPLACE_EXISTING_PROPERTIES Replace the values of existing properties.
        • REPLACE_WITH_DELETE_EMPTY Replace the values of existing properties and delete properties if the new value is empty.
        • INCLUDE_INTERNAL_PROPERTIES Operate on internal properties as well as external properties.
        Throws:
        XMPException - in case of internal error occurs.

      • duplicateSubtree

        public static void duplicateSubtree​(XMPMeta source,
                                    XMPMeta dest,
                                    java.lang.String sourceNS,
                                    java.lang.String sourceRoot,
                                    java.lang.String destNS,
                                    java.lang.String destRoot,
                                    PropertyOptions options)
                             throws XMPException
        Replicate a subtree from one XMP object into another, possibly at a different location.
        Parameters:
        source - The source XMP object.
        dest - The destination XMP object.
        sourceNS - The schema namespace URI for the source subtree.
        sourceRoot - The root location for the source subtree. May be a general path expression, must not be null or the empty string.
        destNS - The schema namespace URI for the destination. Defaults to the source namespace.
        destRoot - The root location for the destination. May be a general path expression. Defaults to the source location.
        options - Option flags to control the separation. (For now, this argument is ignored. 0 should be passed.
        Throws:
        XMPException - throws an XMPException