All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.itextpdf.xmp.XMPMeta Maven / Gradle / Ivy

//Copyright (c) 2006, Adobe Systems Incorporated
//All rights reserved.
//
//        Redistribution and use in source and binary forms, with or without
//        modification, are permitted provided that the following conditions are met:
//        1. Redistributions of source code must retain the above copyright
//        notice, this list of conditions and the following disclaimer.
//        2. Redistributions in binary form must reproduce the above copyright
//        notice, this list of conditions and the following disclaimer in the
//        documentation and/or other materials provided with the distribution.
//        3. All advertising materials mentioning features or use of this software
//        must display the following acknowledgement:
//        This product includes software developed by the Adobe Systems Incorporated.
//        4. Neither the name of the Adobe Systems Incorporated nor the
//        names of its contributors may be used to endorse or promote products
//        derived from this software without specific prior written permission.
//
//        THIS SOFTWARE IS PROVIDED BY ADOBE SYSTEMS INCORPORATED ''AS IS'' AND ANY
//        EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
//        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
//        DISCLAIMED. IN NO EVENT SHALL ADOBE SYSTEMS INCORPORATED BE LIABLE FOR ANY
//        DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
//        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
//        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
//        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
//        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
//        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
//        http://www.adobe.com/devnet/xmp/library/eula-xmp-library-java.html

package com.itextpdf.xmp;

import java.util.Calendar;

import com.itextpdf.xmp.options.IteratorOptions;
import com.itextpdf.xmp.options.ParseOptions;
import com.itextpdf.xmp.options.PropertyOptions;
import com.itextpdf.xmp.properties.XMPProperty;


/**
 * This class represents the set of XMP metadata as a DOM representation. It has methods to read and
 * modify all kinds of properties, create an iterator over all properties and serialize the metadata
 * to a String, byte-array or OutputStream.
 * 
 * @since 20.01.2006
 */
public interface XMPMeta extends Cloneable
{
	// ---------------------------------------------------------------------------------------------
	// Basic property manipulation functions

	/**
	 * The property value getter-methods all take a property specification: the first two parameters
	 * are always the top level namespace URI (the "schema" namespace) and the basic name
	 * of the property being referenced. See the introductory discussion of path expression usage
	 * for more information.
	 * 

* All of the functions return an object inherited from PropertyBase or * null if the property does not exists. The result object contains the value of * the property and option flags describing the property. Arrays and the non-leaf levels of * nodes do not have values. *

* See {@link PropertyOptions} for detailed information about the options. *

* This is the simplest property getter, mainly for top level simple properties or after using * the path composition functions in XMPPathFactory. * * @param schemaNS The namespace URI for the property. May be null or the empty * string if the first component of the propName path contains a namespace prefix. The * URI must be for a registered namespace. * @param propName The name of the property. May be a general path expression, must not be * null or the empty string. Using a namespace prefix on the first * component is optional. If present without a schemaNS value then the prefix specifies * the namespace. The prefix must be for a registered namespace. If both a schemaNS URI * and propName prefix are present, they must be corresponding parts of a registered * namespace. * @return Returns a XMPProperty containing the value and the options or * null if the property does not exist. * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPProperty getProperty(String schemaNS, String propName) throws XMPException; /** * Provides access to items within an array. The index is passed as an integer, you need not * worry about the path string syntax for array items, convert a loop index to a string, etc. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The * constant {@link XMPConst#ARRAY_LAST_ITEM} always refers to the last existing array * item. * @return Returns a XMPProperty containing the value and the options or * null if the property does not exist. * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPProperty getArrayItem(String schemaNS, String arrayName, int itemIndex) throws XMPException; /** * Returns the number of items in the array. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @return Returns the number of items in the array. * @throws XMPException Wraps all errors and exceptions that may occur. */ int countArrayItems(String schemaNS, String arrayName) throws XMPException; /** * Provides access to fields within a nested structure. The namespace for the field is passed as * a URI, you need not worry about the path string syntax. *

* The names of fields should be XML qualified names, that is within an XML namespace. The path * syntax for a qualified name uses the namespace prefix. This is unreliable since the prefix is * never guaranteed. The URI is the formal name, the prefix is just a local shorthand in a given * sequence of XML text. * * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. * @param structName The name of the struct. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the * schemaNS parameter. * @param fieldName The name of the field. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * structName parameter. * @return Returns a XMPProperty containing the value and the options or * null if the property does not exist. Arrays and non-leaf levels of * structs do not have values. * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPProperty getStructField( String schemaNS, String structName, String fieldNS, String fieldName) throws XMPException; /** * Provides access to a qualifier attached to a property. The namespace for the qualifier is * passed as a URI, you need not worry about the path string syntax. In many regards qualifiers * are like struct fields. See the introductory discussion of qualified properties for more * information. *

* The names of qualifiers should be XML qualified names, that is within an XML namespace. The * path syntax for a qualified name uses the namespace prefix. This is unreliable since the * prefix is never guaranteed. The URI is the formal name, the prefix is just a local shorthand * in a given sequence of XML text. *

* Note: Qualifiers are only supported for simple leaf properties at this time. * * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. * @param propName The name of the property to which the qualifier is attached. May be a general * path expression, must not be null or the empty string. Has the same * namespace prefix usage as in getProperty(). * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the * schemaNS parameter. * @param qualName The name of the qualifier. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * propName parameter. * @return Returns a XMPProperty containing the value and the options of the * qualifier or null if the property does not exist. The name of the * qualifier must be a single XML name, must not be null or the empty * string. Has the same namespace prefix usage as the propName parameter. *

* The value of the qualifier is only set if it has one (Arrays and non-leaf levels of * structs do not have values). * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPProperty getQualifier( String schemaNS, String propName, String qualNS, String qualName) throws XMPException; // --------------------------------------------------------------------------------------------- // Functions for setting property values /** * The property value setters all take a property specification, their * differences are in the form of this. The first two parameters are always the top level * namespace URI (the schema namespace) and the basic name of the property being * referenced. See the introductory discussion of path expression usage for more information. *

* All of the functions take a string value for the property and option flags describing the * property. The value must be Unicode in UTF-8 encoding. Arrays and non-leaf levels of structs * do not have values. Empty arrays and structs may be created using appropriate option flags. * All levels of structs that is assigned implicitly are created if necessary. appendArayItem * implicitly creates the named array if necessary. *

* See {@link PropertyOptions} for detailed information about the options. *

* This is the simplest property setter, mainly for top level simple properties or after using * the path composition functions in {@link XMPPathFactory}. * * @param schemaNS The namespace URI for the property. Has the same usage as in getProperty. * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the value for the property (only leaf properties have a value). * Arrays and non-leaf levels of structs do not have values. * Must be null if the value is not relevant.
* The value is automatically detected: Boolean, Integer, Long, Double, XMPDateTime and * byte[] are handled, on all other toString() is called. * * @param options Option flags describing the property. See the earlier description. * @throws XMPException Wraps all errors and exceptions that may occur. */ void setProperty( String schemaNS, String propName, Object propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setProperty(String, String, Object, PropertyOptions) * * @param schemaNS The namespace URI * @param propName The name of the property * @param propValue the value for the property * @throws XMPException Wraps all errors and exceptions */ void setProperty( String schemaNS, String propName, Object propValue) throws XMPException; /** * Replaces an item within an array. The index is passed as an integer, you need not worry about * the path string syntax for array items, convert a loop index to a string, etc. The array * passed must already exist. In normal usage the selected array item is modified. A new item is * automatically appended if the index is the array size plus 1. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty. * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. To address * the last existing item, use {@link XMPMeta#countArrayItems(String, String)} to find * out the length of the array. * @param itemValue the new value of the array item. Has the same usage as propValue in * setProperty(). * @param options the set options for the item. * @throws XMPException Wraps all errors and exceptions that may occur. */ void setArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setArrayItem(String, String, int, String, PropertyOptions) * * @param schemaNS The namespace URI * @param arrayName The name of the array * @param itemIndex The index to insert the new item * @param itemValue the new value of the array item * @throws XMPException Wraps all errors and exceptions */ void setArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue) throws XMPException; /** * Inserts an item into an array previous to the given index. The index is passed as an integer, * you need not worry about the path string syntax for array items, convert a loop index to a * string, etc. The array passed must already exist. In normal usage the selected array item is * modified. A new item is automatically appended if the index is the array size plus 1. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty. * @param itemIndex The index to insert the new item. Arrays in XMP are indexed from 1. Use * XMPConst.ARRAY_LAST_ITEM to append items. * @param itemValue the new value of the array item. Has the same usage as * propValue in setProperty(). * @param options the set options that decide about the kind of the node. * @throws XMPException Wraps all errors and exceptions that may occur. */ void insertArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#insertArrayItem(String, String, int, String, PropertyOptions) * * @param schemaNS The namespace URI for the array * @param arrayName The name of the array * @param itemIndex The index to insert the new item * @param itemValue the value of the array item * @throws XMPException Wraps all errors and exceptions */ void insertArrayItem( String schemaNS, String arrayName, int itemIndex, String itemValue) throws XMPException; /** * Simplifies the construction of an array by not requiring that you pre-create an empty array. * The array that is assigned is created automatically if it does not yet exist. Each call to * appendArrayItem() appends an item to the array. The corresponding parameters have the same * use as setArrayItem(). The arrayOptions parameter is used to specify what kind of array. If * the array exists, it must have the specified form. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be null or * the empty string. Has the same namespace prefix usage as propPath in getProperty. * @param arrayOptions Option flags describing the array form. The only valid options are *

    *
  • {@link PropertyOptions#ARRAY}, *
  • {@link PropertyOptions#ARRAY_ORDERED}, *
  • {@link PropertyOptions#ARRAY_ALTERNATE} or *
  • {@link PropertyOptions#ARRAY_ALT_TEXT}. *
* Note: the array options only need to be provided if the array is not * already existing, otherwise you can set them to null or use * {@link XMPMeta#appendArrayItem(String, String, String)}. * @param itemValue the value of the array item. Has the same usage as propValue in getProperty. * @param itemOptions Option flags describing the item to append ({@link PropertyOptions}) * @throws XMPException Wraps all errors and exceptions that may occur. */ void appendArrayItem( String schemaNS, String arrayName, PropertyOptions arrayOptions, String itemValue, PropertyOptions itemOptions) throws XMPException; /** * @see XMPMeta#appendArrayItem(String, String, PropertyOptions, String, PropertyOptions) * * @param schemaNS The namespace URI for the array * @param arrayName The name of the array * @param itemValue the value of the array item * @throws XMPException Wraps all errors and exceptions */ void appendArrayItem( String schemaNS, String arrayName, String itemValue) throws XMPException; /** * Provides access to fields within a nested structure. The namespace for the field is passed as * a URI, you need not worry about the path string syntax. The names of fields should be XML * qualified names, that is within an XML namespace. The path syntax for a qualified name uses * the namespace prefix, which is unreliable because the prefix is never guaranteed. The URI is * the formal name, the prefix is just a local shorthand in a given sequence of XML text. * * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. * @param structName The name of the struct. May be a general path expression, must not be null * or the empty string. Has the same namespace prefix usage as propName in getProperty. * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the * schemaNS parameter. * @param fieldName The name of the field. Must be a single XML name, must not be null or the * empty string. Has the same namespace prefix usage as the structName parameter. * @param fieldValue the value of thefield, if the field has a value. * Has the same usage as propValue in getProperty. * @param options Option flags describing the field. See the earlier description. * @throws XMPException Wraps all errors and exceptions that may occur. */ void setStructField( String schemaNS, String structName, String fieldNS, String fieldName, String fieldValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setStructField(String, String, String, String, String, PropertyOptions) * * @param schemaNS The namespace URI for the struct * @param structName The name of the struct * @param fieldNS The namespace URI for the field * @param fieldName The name of the field * @param fieldValue the value of the field * @throws XMPException Wraps all errors and exceptions */ void setStructField( String schemaNS, String structName, String fieldNS, String fieldName, String fieldValue) throws XMPException; /** * Provides access to a qualifier attached to a property. The namespace for the qualifier is * passed as a URI, you need not worry about the path string syntax. In many regards qualifiers * are like struct fields. See the introductory discussion of qualified properties for more * information. The names of qualifiers should be XML qualified names, that is within an XML * namespace. The path syntax for a qualified name uses the namespace prefix, which is * unreliable because the prefix is never guaranteed. The URI is the formal name, the prefix is * just a local shorthand in a given sequence of XML text. The property the qualifier * will be attached has to exist. * * @param schemaNS The namespace URI for the struct. Has the same usage as in getProperty. * @param propName The name of the property to which the qualifier is attached. Has the same * usage as in getProperty. * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the * schemaNS parameter. * @param qualName The name of the qualifier. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * propName parameter. * @param qualValue A pointer to the null terminated UTF-8 string that is the * value of the qualifier, if the qualifier has a value. Has the same usage as propValue * in getProperty. * @param options Option flags describing the qualifier. See the earlier description. * @throws XMPException Wraps all errors and exceptions that may occur. */ void setQualifier( String schemaNS, String propName, String qualNS, String qualName, String qualValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setQualifier(String, String, String, String, String, PropertyOptions) * * @param schemaNS The namespace URI for the struct * @param propName The name of the property to which the qualifier is attached * @param qualNS The namespace URI for the qualifier * @param qualName The name of the qualifier * @param qualValue the value of the qualifier * @throws XMPException Wraps all errors and exceptions */ void setQualifier( String schemaNS, String propName, String qualNS, String qualName, String qualValue) throws XMPException; // --------------------------------------------------------------------------------------------- // Functions for deleting and detecting properties. These should be obvious from the // descriptions of the getters and setters. /** * Deletes the given XMP subtree rooted at the given property. It is not an error if the * property does not exist. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. Has the same usage as in getProperty. */ void deleteProperty(String schemaNS, String propName); /** * Deletes the given XMP subtree rooted at the given array item. It is not an error if the array * item does not exist. * * @param schemaNS The namespace URI for the array. Has the same usage as in getProperty. * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The * constant XMPConst.ARRAY_LAST_ITEM always refers to the last * existing array item. */ void deleteArrayItem(String schemaNS, String arrayName, int itemIndex); /** * Deletes the given XMP subtree rooted at the given struct field. It is not an error if the * field does not exist. * * @param schemaNS The namespace URI for the struct. Has the same usage as in * getProperty(). * @param structName The name of the struct. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty. * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the * schemaNS parameter. * @param fieldName The name of the field. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * structName parameter. */ void deleteStructField(String schemaNS, String structName, String fieldNS, String fieldName); /** * Deletes the given XMP subtree rooted at the given qualifier. It is not an error if the * qualifier does not exist. * * @param schemaNS The namespace URI for the struct. Has the same usage as in * getProperty(). * @param propName The name of the property to which the qualifier is attached. Has the same * usage as in getProperty. * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the * schemaNS parameter. * @param qualName The name of the qualifier. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * propName parameter. */ void deleteQualifier(String schemaNS, String propName, String qualNS, String qualName); /** * Returns whether the property exists. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns true if the property exists. */ boolean doesPropertyExist(String schemaNS, String propName); /** * Tells if the array item exists. * * @param schemaNS The namespace URI for the array. Has the same usage as in * getProperty(). * @param arrayName The name of the array. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param itemIndex The index of the desired item. Arrays in XMP are indexed from 1. The * constant XMPConst.ARRAY_LAST_ITEM always refers to the last * existing array item. * @return Returns true if the array exists, false otherwise. */ boolean doesArrayItemExist(String schemaNS, String arrayName, int itemIndex); /** * DoesStructFieldExist tells if the struct field exists. * * @param schemaNS The namespace URI for the struct. Has the same usage as in * getProperty(). * @param structName The name of the struct. May be a general path expression, must not be * null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param fieldNS The namespace URI for the field. Has the same URI and prefix usage as the * schemaNS parameter. * @param fieldName The name of the field. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * structName parameter. * @return Returns true if the field exists. */ boolean doesStructFieldExist( String schemaNS, String structName, String fieldNS, String fieldName); /** * DoesQualifierExist tells if the qualifier exists. * * @param schemaNS The namespace URI for the struct. Has the same usage as in * getProperty(). * @param propName The name of the property to which the qualifier is attached. Has the same * usage as in getProperty(). * @param qualNS The namespace URI for the qualifier. Has the same URI and prefix usage as the * schemaNS parameter. * @param qualName The name of the qualifier. Must be a single XML name, must not be * null or the empty string. Has the same namespace prefix usage as the * propName parameter. * @return Returns true if the qualifier exists. */ boolean doesQualifierExist(String schemaNS, String propName, String qualNS, String qualName); // --------------------------------------------------------------------------------------------- // Specialized Get and Set functions /** * These functions provide convenient support for localized text properties, including a number * of special and obscure aspects. Localized text properties are stored in alt-text arrays. They * allow multiple concurrent localizations of a property value, for example a document title or * copyright in several languages. The most important aspect of these functions is that they * select an appropriate array item based on one or two RFC 3066 language tags. One of these * languages, the "specific" language, is preferred and selected if there is an exact match. For * many languages it is also possible to define a "generic" language that may be used if there * is no specific language match. The generic language must be a valid RFC 3066 primary subtag, * or the empty string. For example, a specific language of "en-US" should be used in the US, * and a specific language of "en-UK" should be used in England. It is also appropriate to use * "en" as the generic language in each case. If a US document goes to England, the "en-US" * title is selected by using the "en" generic language and the "en-UK" specific language. It is * considered poor practice, but allowed, to pass a specific language that is just an RFC 3066 * primary tag. For example "en" is not a good specific language, it should only be used as a * generic language. Passing "i" or "x" as the generic language is also considered poor practice * but allowed. Advice from the W3C about the use of RFC 3066 language tags can be found at: * http://www.w3.org/International/articles/language-tags/ *

* Note: RFC 3066 language tags must be treated in a case insensitive manner. The XMP * Toolkit does this by normalizing their capitalization: *

    *
  • The primary subtag is lower case, the suggested practice of ISO 639. *
  • All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166. *
  • All other subtags are lower case. The XMP specification defines an artificial language, *
  • "x-default", that is used to explicitly denote a default item in an alt-text array. *
* The XMP toolkit normalizes alt-text arrays such that the x-default item is the first item. * The SetLocalizedText function has several special features related to the x-default item, see * its description for details. The selection of the array item is the same for GetLocalizedText * and SetLocalizedText: *
    *
  • Look for an exact match with the specific language. *
  • If a generic language is given, look for a partial match. *
  • Look for an x-default item. *
  • Choose the first item. *
* A partial match with the generic language is where the start of the item's language matches * the generic string and the next character is '-'. An exact match is also recognized as a * degenerate case. It is fine to pass x-default as the specific language. In this case, * selection of an x-default item is an exact match by the first rule, not a selection by the * 3rd rule. The last 2 rules are fallbacks used when the specific and generic languages fail to * produce a match. getLocalizedText returns information about a selected item in * an alt-text array. The array item is selected according to the rules given above. * * Note: In a future version of this API a method * using Java java.lang.Locale will be added. * * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in * getProperty(). * @param altTextName The name of the alt-text array. May be a general path expression, must not * be null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param genericLang The name of the generic language as an RFC 3066 primary subtag. May be * null or the empty string if no generic language is wanted. * @param specificLang The name of the specific language as an RFC 3066 tag. Must not be * null or the empty string. * @return Returns an XMPProperty containing the value, the actual language and * the options if an appropriate alternate collection item exists, null * if the property. * does not exist. * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPProperty getLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang) throws XMPException; /** * Modifies the value of a selected item in an alt-text array. Creates an appropriate array item * if necessary, and handles special cases for the x-default item. If the selected item is from * a match with the specific language, the value of that item is modified. If the existing value * of that item matches the existing value of the x-default item, the x-default item is also * modified. If the array only has 1 existing item (which is not x-default), an x-default item * is added with the given value. If the selected item is from a match with the generic language * and there are no other generic matches, the value of that item is modified. If the existing * value of that item matches the existing value of the x-default item, the x-default item is * also modified. If the array only has 1 existing item (which is not x-default), an x-default * item is added with the given value. If the selected item is from a partial match with the * generic language and there are other partial matches, a new item is created for the specific * language. The x-default item is not modified. If the selected item is from the last 2 rules * then a new item is created for the specific language. If the array only had an x-default * item, the x-default item is also modified. If the array was empty, items are created for the * specific language and x-default. * * Note: In a future version of this API a method * using Java java.lang.Locale will be added. * * * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in * getProperty(). * @param altTextName The name of the alt-text array. May be a general path expression, must not * be null or the empty string. Has the same namespace prefix usage as * propName in getProperty(). * @param genericLang The name of the generic language as an RFC 3066 primary subtag. May be * null or the empty string if no generic language is wanted. * @param specificLang The name of the specific language as an RFC 3066 tag. Must not be * null or the empty string. * @param itemValue A pointer to the null terminated UTF-8 string that is the new * value for the appropriate array item. * @param options Option flags, none are defined at present. * @throws XMPException Wraps all errors and exceptions that may occur. */ void setLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang, String itemValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setLocalizedText(String, String, String, String, String, PropertyOptions) * * @param schemaNS The namespace URI for the alt-text array * @param altTextName The name of the alt-text array * @param genericLang The name of the generic language * @param specificLang The name of the specific language * @param itemValue the new value for the appropriate array item * @throws XMPException Wraps all errors and exceptions */ void setLocalizedText( String schemaNS, String altTextName, String genericLang, String specificLang, String itemValue) throws XMPException; // --------------------------------------------------------------------------------------------- // Functions accessing properties as binary values. /** * These are very similar to getProperty() and SetProperty() above, * but the value is returned or provided in a literal form instead of as a UTF-8 string. * The path composition functions in XMPPathFactory may be used to compose an path * expression for fields in nested structures, items in arrays, or qualifiers. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a Boolean value or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ Boolean getPropertyBoolean(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns an Integer value or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ Integer getPropertyInteger(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a Long value or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ Long getPropertyLong(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a Double value or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ Double getPropertyDouble(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a XMPDateTime-object or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ XMPDateTime getPropertyDate(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a Java Calendar-object or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ Calendar getPropertyCalendar(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a byte[]-array contained the decoded base64 value * or null if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ byte[] getPropertyBase64(String schemaNS, String propName) throws XMPException; /** * Convenience method to retrieve the literal value of a property. * Note: There is no setPropertyString(), * because setProperty() sets a string value. * * @param schemaNS The namespace URI for the property. Has the same usage as in * getProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @return Returns a String value or null * if the property does not exist. * @throws XMPException Wraps all exceptions that may occur, * especially conversion errors. */ String getPropertyString(String schemaNS, String propName) throws XMPException; /** * Convenience method to set a property to a literal boolean value. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the literal property value as boolean. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyBoolean( String schemaNS, String propName, boolean propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyBoolean(String, String, boolean, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the literal property value as boolean * @throws XMPException Wraps all exceptions */ void setPropertyBoolean( String schemaNS, String propName, boolean propValue) throws XMPException; /** * Convenience method to set a property to a literal int value. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the literal property value as int. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyInteger( String schemaNS, String propName, int propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyInteger(String, String, int, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the literal property value as int * @throws XMPException Wraps all exceptions */ void setPropertyInteger( String schemaNS, String propName, int propValue) throws XMPException; /** * Convenience method to set a property to a literal long value. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the literal property value as long. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyLong( String schemaNS, String propName, long propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyLong(String, String, long, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the literal property value as long * @throws XMPException Wraps all exceptions */ void setPropertyLong( String schemaNS, String propName, long propValue) throws XMPException; /** * Convenience method to set a property to a literal double value. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the literal property value as double. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyDouble( String schemaNS, String propName, double propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyDouble(String, String, double, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the literal property value as double * @throws XMPException Wraps all exceptions */ void setPropertyDouble( String schemaNS, String propName, double propValue) throws XMPException; /** * Convenience method to set a property with an XMPDateTime-object, * which is serialized to an ISO8601 date. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the property value as XMPDateTime. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyDate( String schemaNS, String propName, XMPDateTime propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyDate(String, String, XMPDateTime, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the property value as XMPDateTime * @throws XMPException Wraps all exceptions */ void setPropertyDate( String schemaNS, String propName, XMPDateTime propValue) throws XMPException; /** * Convenience method to set a property with a Java Calendar-object, * which is serialized to an ISO8601 date. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the property value as Java Calendar. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyCalendar( String schemaNS, String propName, Calendar propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyCalendar(String, String, Calendar, PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the property value as Calendar * @throws XMPException Wraps all exceptions */ void setPropertyCalendar( String schemaNS, String propName, Calendar propValue) throws XMPException; /** * Convenience method to set a property from a binary byte[]-array, * which is serialized as base64-string. * * @param schemaNS The namespace URI for the property. Has the same usage as in * setProperty(). * @param propName The name of the property. * Has the same usage as in getProperty(). * @param propValue the literal property value as byte array. * @param options options of the property to set (optional). * @throws XMPException Wraps all exceptions that may occur. */ void setPropertyBase64( String schemaNS, String propName, byte[] propValue, PropertyOptions options) throws XMPException; /** * @see XMPMeta#setPropertyBase64(String, String, byte[], PropertyOptions) * * @param schemaNS The namespace URI for the property * @param propName The name of the property * @param propValue the literal property value as byte array * @throws XMPException Wraps all exceptions */ void setPropertyBase64( String schemaNS, String propName, byte[] propValue) throws XMPException; /** * Constructs an iterator for the properties within this XMP object. * * @return Returns an XMPIterator. * @see XMPMeta#iterator(String, String, IteratorOptions) * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPIterator iterator() throws XMPException; /** * Constructs an iterator for the properties within this XMP object using some options. * * @param options Option flags to control the iteration. * @return Returns an XMPIterator. * @see XMPMeta#iterator(String, String, IteratorOptions) * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPIterator iterator(IteratorOptions options) throws XMPException; /** * Construct an iterator for the properties within an XMP object. According to the parameters it iterates the entire data tree, * properties within a specific schema, or a subtree rooted at a specific node. * * @param schemaNS Optional schema namespace URI to restrict the iteration. Omitted (visit all * schema) by passing null or empty String. * @param propName Optional property name to restrict the iteration. May be an arbitrary path * expression. Omitted (visit all properties) by passing null or empty * String. If no schema URI is given, it is ignored. * @param options Option flags to control the iteration. See {@link IteratorOptions} for * details. * @return Returns an XMPIterator for this XMPMeta-object * considering the given options. * @throws XMPException Wraps all errors and exceptions that may occur. */ XMPIterator iterator( String schemaNS, String propName, IteratorOptions options) throws XMPException; /** * This correlates to the about-attribute, * returns the empty String if no name is set. * * @return Returns the name of the XMP object. */ String getObjectName(); /** * @param name Sets the name of the XMP object. */ void setObjectName(String name); /** * @return Returns the unparsed content of the <?xpacket> processing instruction. * This contains normally the attribute-like elements 'begin="<BOM>" * id="W5M0MpCehiHzreSzNTczkc9d"' and possibly the deprecated elements 'bytes="1234"' or * 'encoding="XXX"'. If the parsed packet has not been wrapped into an xpacket, * null is returned. */ String getPacketHeader(); /** * Clones the complete metadata tree. * * @return Returns a deep copy of this instance. */ Object clone(); /** * Sorts the complete datamodel according to the following rules: *
    *
  • Schema nodes are sorted by prefix. *
  • Properties at top level and within structs are sorted by full name, that is * prefix + local name. *
  • Array items are not sorted, even if they have no certain order such as bags. *
  • Qualifier are sorted, with the exception of "xml:lang" and/or "rdf:type" * that stay at the top of the list in that order. *
*/ void sort(); /** * Perform the normalization as a separate parsing step. * Normally it is done during parsing, unless the parsing option * {@link ParseOptions#OMIT_NORMALIZATION} is set to true. * Note: It does no harm to call this method to an already normalized xmp object. * It was a PDF/A requirement to get hand on the unnormalized XMPMeta object. * * @param options optional parsing options. * @throws XMPException Wraps all errors and exceptions that may occur. */ void normalize(ParseOptions options) throws XMPException; /** * Renders this node and the tree unter this node in a human readable form. * @return Returns a multiline string containing the dump. */ String dumpObject(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy