XMPUtils
Date: 2012-05-15

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.adobe.xmp
Class XMPUtils

    java.lang.Object
      com.adobe.xmp.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
`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 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 java.lang.String` | `encodeBase64(byte[] buffer)` Convert from a byte array to a base64 encoded string.
`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:
    - `XMPConst.TRUESTR` and `XMPConst.FALSESTR`
    - "t" and "f"
    - "on" and "off"
    - "yes" and "no"
    - "value <> 0" and "value == 0"
  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006-2007 Adobe Systems Inc. All Rights Reserved.