com.adobe.xmp

Interface XMPSchemaRegistry

public interface XMPSchemaRegistry

The schema registry keeps track of all namespaces and aliases used in the XMP metadata. At initialisation time, the default namespaces and default aliases are automatically registered. Namespaces must be registered before used in namespace URI parameters or path expressions. Within the XMP Toolkit the registered namespace URIs and prefixes must be unique. Additional namespaces encountered when parsing RDF are automatically registered. The namespace URI should always end in an XML name separator such as '/' or '#'. This is because some forms of RDF shorthand catenate a namespace URI with an element name to form a new URI.

Aliases in XMP serve the same purpose as Windows file shortcuts, Macintosh file aliases, or UNIX file symbolic links. The aliases are simply multiple names for the same property. One distinction of XMP aliases is that they are ordered, there is an alias name pointing to an actual name. The primary significance of the actual name is that it is the preferred name for output, generally the most widely recognized name.

The names that can be aliased in XMP are restricted. The alias must be a top level property name, not a field within a structure or an element within an array. The actual may be a top level property name, the first element within a top level array, or the default element in an alt-text array. This does not mean the alias can only be a simple property. It is OK to alias a top level structure or array to an identical top level structure or array, or to the first item of an array of structures.

Since:

27.01.2006

Method Summary

Modifier and Type	Method and Description
void	deleteAlias(java.lang.String aliasNS, java.lang.String aliasProp) Delete an alias.
void	deleteNamespace(java.lang.String namespaceURI) Deletes a namespace from the registry.
XMPAliasInfo	findAlias(java.lang.String qname) Searches for registered aliases.
XMPAliasInfo[]	findAliases(java.lang.String aliasNS) Collects all aliases that are contained in the provided namespace.
java.util.Map	getAliases()
java.lang.String	getNamespacePrefix(java.lang.String namespaceURI) Obtain the prefix for a registered namespace URI.
java.util.Map	getNamespaces()
java.lang.String	getNamespaceURI(java.lang.String namespacePrefix) Obtain the URI for a registered namespace prefix.
java.util.Map	getPrefixes()
void	registerAlias(java.lang.String aliasNS, java.lang.String aliasProp, java.lang.String actualNS, java.lang.String actualProp, AliasOptions aliasForm) Associates an alias name with an actual name.
java.lang.String	registerNamespace(java.lang.String namespaceURI, java.lang.String suggestedPrefix) Register a namespace URI with a suggested prefix.
XMPAliasInfo	resolveAlias(java.lang.String aliasNS, java.lang.String aliasProp) Determines if a name is an alias, and what it is aliased to.

Method Detail

registerNamespace

java.lang.String registerNamespace(java.lang.String namespaceURI,
                                   java.lang.String suggestedPrefix)
                            throws XMPException

Register a namespace URI with a suggested prefix. It is not an error if the URI is already registered, no matter what the prefix is. If the URI is not registered but the suggested prefix is in use, a unique prefix is created from the suggested one. The actual registeed prefix is always returned. The function result tells if the registered prefix is the suggested one.

Note: No checking is presently done on either the URI or the prefix.

Parameters:

namespaceURI - The URI for the namespace. Must be a valid XML URI.

suggestedPrefix - The suggested prefix to be used if the URI is not yet registered. Must be a valid XML name.

Returns:

Returns the registered prefix for this URI, is equal to the suggestedPrefix if the namespace hasn't been registered before, otherwise the existing prefix.

Throws:

XMPException - If the parameters are not accordingly set

getNamespacePrefix

java.lang.String getNamespacePrefix(java.lang.String namespaceURI)

Obtain the prefix for a registered namespace URI.

It is not an error if the namespace URI is not registered. The output namespacePrefix string is not modified if the namespace URI is not registered.

Parameters:

namespaceURI - The URI for the namespace. Must not be null or the empty string.

Returns:

Returns true if the namespace URI is registered.

getNamespaceURI

java.lang.String getNamespaceURI(java.lang.String namespacePrefix)

Obtain the URI for a registered namespace prefix.

It is not an error if the namespace prefix is not registered. The output namespaceURI string is not modified if the namespace prefix is not registered.

Parameters:

namespacePrefix - The prefix for the namespace. Must not be null or the empty string.

Returns:

Returns the URI registered for this prefix.

getNamespaces

java.util.Map getNamespaces()

Returns:

Returns the registered prefix/namespace-pairs as map, where the keys are the namespaces and the values are the prefixes.

getPrefixes

java.util.Map getPrefixes()

Returns:

Returns the registered namespace/prefix-pairs as map, where the keys are the prefixes and the values are the namespaces.

deleteNamespace

void deleteNamespace(java.lang.String namespaceURI)

Deletes a namespace from the registry.

Does nothing if the URI is not registered, or if the namespaceURI parameter is null or the empty string.

Note: Not yet implemented.

Parameters:

namespaceURI - The URI for the namespace.

registerAlias

void registerAlias(java.lang.String aliasNS,
                   java.lang.String aliasProp,
                   java.lang.String actualNS,
                   java.lang.String actualProp,
                   AliasOptions aliasForm)
            throws XMPException

Associates an alias name with an actual name.

Define a alias mapping from one namespace/property to another. Both property names must be simple names. An alias can be a direct mapping, where the alias and actual have the same data type. It is also possible to map a simple alias to an item in an array. This can either be to the first item in the array, or to the 'x-default' item in an alt-text array. Multiple alias names may map to the same actual, as long as the forms match. It is a no-op to reregister an alias in an identical fashion.

Parameters:

aliasNS - The namespace URI for the alias. Must not be null or the empty string.

aliasProp - The name of the alias. Must be a simple name, not null or the empty string and not a general path expression.

actualNS - The namespace URI for the actual. Must not be null or the empty string.

actualProp - The name of the actual. Must be a simple name, not null or the empty string and not a general path expression.

aliasForm - Provides options for aliases for simple aliases to array items. This is needed to know what kind of array to create if set for the first time via the simple alias. Pass XMP_NoOptions, the default value, for all direct aliases regardless of whether the actual data type is an array or not (see AliasOptions).

Throws:

XMPException - for inconsistant aliases.

resolveAlias

XMPAliasInfo resolveAlias(java.lang.String aliasNS,
                          java.lang.String aliasProp)

Determines if a name is an alias, and what it is aliased to.

Parameters:

aliasNS - The namespace URI of the alias. Must not be null or the empty string.

aliasProp - The name of the alias. May be an arbitrary path expression path, must not be null or the empty string.

Returns:

Returns the XMPAliasInfo for the given alias namespace and property or null if there is no such alias.

findAliases

XMPAliasInfo[] findAliases(java.lang.String aliasNS)

Collects all aliases that are contained in the provided namespace. If nothing is found, an empty array is returned.

Parameters:

aliasNS - a schema namespace URI

Returns:

Returns all alias infos from aliases that are contained in the provided namespace.

findAlias

XMPAliasInfo findAlias(java.lang.String qname)

Searches for registered aliases.

Parameters:

qname - an XML conform qname

Returns:

Returns if an alias definition for the given qname to another schema and property is registered.

deleteAlias

void deleteAlias(java.lang.String aliasNS,
                 java.lang.String aliasProp)

Delete an alias.

This only deletes the registration of the alias, it does not delete the actual property. It does delete any view of the property through the alias name. It is OK to attempt to delete an alias that does not exist, that is if the alias name is not registered as an alias.

Parameters:

aliasNS - The namespace URI for the alias. Must not be null or the empty string.

aliasProp - The name of the alias. Must be a simple name, not null or the empty string and not a general path expression.

getAliases

java.util.Map getAliases()

Returns:

Returns the registered aliases as map, where the key is the "qname" (prefix and name) and the value an XMPAliasInfo-object.