iText 5 itextpdf.jar Source Code
itextpdf.jar is a component in iText 5 Java library to provide core functionalities.
iText Java library allows you to generate and manage PDF documents.
The Source Code files are provided at iText GitHub site.
You can compile it to generate your JAR file, using pom.xml as the build configuration file.
The source code of itextpdf-5.5.14.jar is provided below:
✍: FYIcenter.com
⏎ com/itextpdf/xmp/XMPMeta.java
//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 <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 "schema" 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
* @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
/**
* 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
*/
void setPropertyBoolean(
String schemaNS,
String propName,
boolean propValue) throws XMPException;
/**
* Convenience method to set a property to a literal <code>int</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>int</code>.
* @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 <code>int</code>
* @throws XMPException Wraps all exceptions
*/
void setPropertyInteger(
String schemaNS,
String propName,
int propValue) throws XMPException;
/**
* Convenience method to set a property to a literal <code>long</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>long</code>.
* @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 <code>long</code>
* @throws XMPException Wraps all exceptions
*/
void setPropertyLong(
String schemaNS,
String propName,
long propValue) throws XMPException;
/**
* Convenience method to set a property to a literal <code>double</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>double</code>.
* @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 <code>double</code>
* @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
* <code>setProperty()</code>.
* @param propName The name of the property.
* Has the same usage as in <code>getProperty()</code>.
* @param propValue the property value as <code>XMPDateTime</code>.
* @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 <code>XMPDateTime</code>
* @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
* <code>setProperty()</code>.
* @param propName The name of the property.
* Has the same usage as in <code>getProperty()</code>.
* @param propValue the property value as Java <code>Calendar</code>.
* @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 <code>Calendar</code>
* @throws XMPException Wraps all exceptions
*/
void setPropertyCalendar(
String schemaNS,
String propName,
Calendar propValue) throws XMPException;
/**
* Convenience method to set a property from a binary <code>byte[]</code>-array,
* which is serialized as base64-string.
*
* @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 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 <code>XMPIterator</code>.
* @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 <code>XMPIterator</code>.
* @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 <code>null</code> or empty String.
* @param propName Optional property name to restrict the iteration. May be an arbitrary path
* expression. Omitted (visit all properties) by passing <code>null</code> 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 <code>XMPIterator</code> for this <code>XMPMeta</code>-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,
* <code>null</code> 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:
* <ul>
* <li>Schema nodes are sorted by prefix.
* <li>Properties at top level and within structs are sorted by full name, that is
* prefix + local name.
* <li>Array items are not sorted, even if they have no certain order such as bags.
* <li>Qualifier are sorted, with the exception of "xml:lang" and/or "rdf:type"
* that stay at the top of the list in that order.
* </ul>
*/
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 <code>true</code>.
* <em>Note:</em> 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 <code>XMPMeta</code> 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();
}⏎ com/itextpdf/xmp/XMPMeta.java
Or download all of them as a single archive file:
File name: itextpdf-5.5.14-fyi.zip File size: 2163839 bytes Release date: 2009-10-09 Download
⇒ iText-2.1.6.jar - iText, a JAVA-PDF library
⇐ iText layout.jar Source Code
2021-07-03, 113113👍, 0💬
