xmpmeta.java

flash xmp sdk,flash官方SDK

	/**
	 * 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/
	 * <p>
	 * <em>Note:</em> RFC 3066 language tags must be treated in a case insensitive manner. The XMP
	 * Toolkit does this by normalizing their capitalization:
	 * <ul>
	 * <li> The primary subtag is lower case, the suggested practice of ISO 639.
	 * <li> All 2 letter secondary subtags are upper case, the suggested practice of ISO 3166.
	 * <li> All other subtags are lower case. The XMP specification defines an artificial language,
	 * <li>"x-default", that is used to explicitly denote a default item in an alt-text array.
	 * </ul>
	 * 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:
	 * <ul>
	 * <li> Look for an exact match with the specific language.
	 * <li> If a generic language is given, look for a partial match.
	 * <li> Look for an x-default item.
	 * <li> Choose the first item.
	 * </ul>
	 * 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. <code>getLocalizedText</code> returns information about a selected item in
	 * an alt-text array. The array item is selected according to the rules given above.
	 * 
	 * <em>Note:</em> In a future version of this API a method 
	 * 		using Java <code>java.lang.Locale</code> will be added.
	 * 
	 * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in
	 *        <code>getProperty()</code>.
	 * @param altTextName The name of the alt-text 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 genericLang The name of the generic language as an RFC 3066 primary subtag. May be
	 *        <code>null</code> 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
	 *        <code>null</code> or the empty string.
	 * @return Returns an <code>XMPProperty</code> containing the value, the actual language and 
	 * 		   the options if an appropriate alternate collection item exists, <code>null</code> 
	 * 		  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.
	 * 
	 * <em>Note:</em> In a future version of this API a method 
	 * 		using Java <code>java.lang.Locale</code> will be added.
	 * 
	 * 
	 * @param schemaNS The namespace URI for the alt-text array. Has the same usage as in
	 *        <code>getProperty()</code>.
	 * @param altTextName The name of the alt-text 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 genericLang The name of the generic language as an RFC 3066 primary subtag. May be
	 *        <code>null</code> 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
	 *        <code>null</code> or the empty string.
	 * @param itemValue A pointer to the <code>null</code> 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 <code>getProperty()</code> and <code>SetProperty()</code> above, 
	 * but the value is returned or provided in a literal form instead of as a UTF-8 string. 
	 * The path composition functions in <code>XMPPathFactory</code> 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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a <code>Boolean</code> value or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns an <code>Integer</code> value or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a <code>Long</code> value or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a <code>Double</code> value or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a <code>XMPDateTime</code>-object or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a Java <code>Calendar</code>-object or <code>null</code> 
	 * 		   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
	 *         <code>getProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @return Returns a <code>byte[]</code>-array contained the decoded base64 value 
	 * 		   or <code>null</code> 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.
	 * <em>Note:</em> There is no <code>setPropertyString()</code>, 
	 * because <code>setProperty()</code> sets a string value.
	 * 
	 * @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 a <code>String</code> value or <code>null</code> 
	 * 		   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 <code>boolean</code> value.
	 * 
	 * @param  schemaNS The namespace URI for the property. Has the same usage as in
	 *         <code>setProperty()</code>.
	 * @param  propName The name of the property.
	 * 		   Has the same usage as in <code>getProperty()</code>.
	 * @param  propValue the literal property value as <code>boolean</code>.
	 * @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 <code>boolean</code>
	 * @throws XMPException Wraps all exceptions