xmpmeta.java

flash xmp sdk,flash官方SDK

// =================================================================================================
// ADOBE SYSTEMS INCORPORATED
// Copyright 2006-2007 Adobe Systems Incorporated
// All Rights Reserved
//
// NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
// of the Adobe license agreement accompanying it.
// =================================================================================================

package com.adobe.xmp;

import java.util.Calendar;

import com.adobe.xmp.options.IteratorOptions;
import com.adobe.xmp.options.PropertyOptions;
import com.adobe.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 <code>OutputStream</code>.
 * 
 * @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 &quot;schema&quot; namespace) and the basic name
	 * of the property being referenced. See the introductory discussion of path expression usage
	 * for more information.
	 * <p>
	 * All of the functions return an object inherited from <code>PropertyBase</code> or
	 * <code>null</code> 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.
	 * <p>
	 * See {@link PropertyOptions} for detailed information about the options.
	 * <p>
	 * 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 <code>null</code> 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
	 *        <code>null</code> 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 <code>XMPProperty</code> containing the value and the options or
	 *         <code>null</code> 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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as
	 *        propName in <code>getProperty()</code>.
	 * @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 <code>XMPProperty</code> containing the value and the options or
	 *         <code>null</code> 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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as
	 *        propName in <code>getProperty()</code>.
	 * @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.
	 * <p>
	 * 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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as
	 *        propName in <code>getProperty()</code>.
	 * @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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as the
	 *        structName parameter.
	 * @return Returns a <code>XMPProperty</code> containing the value and the options or
	 *         <code>null</code> 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.
	 * <p>
	 * 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.
	 * <p>
	 * <em>Note:</em> 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 <code>null</code> or the empty string. Has the same
	 *        namespace prefix usage as in <code>getProperty()</code>.
	 * @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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as the
	 *        propName parameter.
	 * @return Returns a <code>XMPProperty</code> containing the value and the options of the
	 *         qualifier or <code>null</code> if the property does not exist. The name of the
	 *         qualifier must be a single XML name, must not be <code>null</code> or the empty
	 *         string. Has the same namespace prefix usage as the propName parameter.
	 *         <p>
	 *         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 <code>setters</code> 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 <code>schema</code> namespace) and the basic name of the property being
	 * referenced. See the introductory discussion of path expression usage for more information.
	 * <p>
	 * 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.
	 * <p>
	 * See {@link PropertyOptions} for detailed information about the options.
	 * <p>
	 * 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 <code>getProperty()</code>.
	 * @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 <code>null</code> if the value is not relevant.<br/>
	 *        The value is automatically detected: Boolean, Integer, Long, Double, XMPDateTime and
	 *        byte[] are handled, on all other <code>toString()</code> 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
	 *        <code>null</code> 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
	 *        <code>setProperty()</code>.
	 * @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
	 *        <code>null</code> 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
	 * 		  <code>XMPConst.ARRAY_LAST_ITEM</code> to append items.
	 * @param itemValue the new value of the array item. Has the same usage as
	 *        propValue in <code>setProperty()</code>.
	 * @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