xmpmeta.java

flash xmp sdk,flash官方SDK

	 * @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
	 *        <ul>
	 *        <li> {@link PropertyOptions#ARRAY},
	 *        <li> {@link PropertyOptions#ARRAY_ORDERED},
	 *        <li> {@link PropertyOptions#ARRAY_ALTERNATE} or
	 *        <li> {@link PropertyOptions#ARRAY_ALT_TEXT}.
	 *        </ul>
	 *        <em>Note:</em> the array options only need to be provided if the array is not 
	 *        already existing, otherwise you can set them to <code>null</code> 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
	 *        <code>null</code> or the empty string. Has the same namespace prefix usage as the
	 *        propName parameter.
	 * @param qualValue A pointer to the <code>null</code> 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
	 *        <code>getProperty()</code>.
	 * @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
	 *        <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 <code>XMPConst.ARRAY_LAST_ITEM</code> 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
	 *        <code>getProperty()</code>.
	 * @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 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
	 *        <code>null</code> 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
	 *        <code>getProperty()</code>.
	 * @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
	 *        <code>null</code> 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
	 *        <code>getProperty()</code>.
	 * @param propName The name of the property. 
	 * 		  Has the same usage as in <code>getProperty()</code>.
	 * @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
	 *        <code>getProperty()</code>.
	 * @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 <code>XMPConst.ARRAY_LAST_ITEM</code> always refers to the last
	 *        existing array item.
	 * @return Returns <code>true</code> if the array exists, <code>false</code> 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
	 *        <code>getProperty()</code>.
	 * @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 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
	 *        <code>getProperty()</code>.
	 * @param propName The name of the property to which the qualifier is attached. Has the same
	 *        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 true if the qualifier exists.
	 */
	boolean doesQualifierExist(String schemaNS, String propName, String qualNS, String qualName);


	// ---------------------------------------------------------------------------------------------
	// Specialized Get and Set functions