1// =================================================================================================
2// ADOBE SYSTEMS INCORPORATED
3// Copyright 2006 Adobe Systems Incorporated
4// All Rights Reserved
5//
6// NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
7// of the Adobe license agreement accompanying it.
8// =================================================================================================
9
10package com.adobe.xmp;
11
12import java.util.Map;
13
14import com.adobe.xmp.properties.XMPAliasInfo;
15
16/**
17 * The schema registry keeps track of all namespaces and aliases used in the XMP
18 * metadata. At initialisation time, the default namespaces and default aliases
19 * are automatically registered. <b>Namespaces</b> must be registered before
20 * used in namespace URI parameters or path expressions. Within the XMP Toolkit
21 * the registered namespace URIs and prefixes must be unique. Additional
22 * namespaces encountered when parsing RDF are automatically registered. The
23 * namespace URI should always end in an XML name separator such as '/' or '#'.
24 * This is because some forms of RDF shorthand catenate a namespace URI with an
25 * element name to form a new URI.
26 * <p>
27 * <b>Aliases</b> in XMP serve the same purpose as Windows file shortcuts,
28 * Macintosh file aliases, or UNIX file symbolic links. The aliases are simply
29 * multiple names for the same property. One distinction of XMP aliases is that
30 * they are ordered, there is an alias name pointing to an actual name. The
31 * primary significance of the actual name is that it is the preferred name for
32 * output, generally the most widely recognized name.
33 * <p>
34 * The names that can be aliased in XMP are restricted. The alias must be a top
35 * level property name, not a field within a structure or an element within an
36 * array. The actual may be a top level property name, the first element within
37 * a top level array, or the default element in an alt-text array. This does not
38 * mean the alias can only be a simple property. It is OK to alias a top level
39 * structure or array to an identical top level structure or array, or to the
40 * first item of an array of structures.
41 *
42 * @since 27.01.2006
43 */
44public interface XMPSchemaRegistry
45{
46	// ---------------------------------------------------------------------------------------------
47	// Namespace Functions
48
49	/**
50	 * Register a namespace URI with a suggested prefix. It is not an error if
51	 * the URI is already registered, no matter what the prefix is. If the URI
52	 * is not registered but the suggested prefix is in use, a unique prefix is
53	 * created from the suggested one. The actual registeed prefix is always
54	 * returned. The function result tells if the registered prefix is the
55	 * suggested one.
56	 * <p>
57	 * Note: No checking is presently done on either the URI or the prefix.
58	 *
59	 * @param namespaceURI
60	 *            The URI for the namespace. Must be a valid XML URI.
61	 * @param suggestedPrefix
62	 *            The suggested prefix to be used if the URI is not yet
63	 *            registered. Must be a valid XML name.
64	 * @return Returns the registered prefix for this URI, is equal to the
65	 *         suggestedPrefix if the namespace hasn't been registered before,
66	 *         otherwise the existing prefix.
67	 * @throws XMPException If the parameters are not accordingly set
68	 */
69	String registerNamespace(String namespaceURI, String suggestedPrefix) throws XMPException;
70
71
72	/**
73	 * Obtain the prefix for a registered namespace URI.
74	 * <p>
75	 * It is not an error if the namespace URI is not registered. The output
76	 * namespacePrefix string is not modified if the namespace URI is not
77	 * registered.
78	 *
79	 * @param namespaceURI
80	 *            The URI for the namespace. Must not be null or the empty
81	 *            string.
82	 * @return Returns true if the namespace URI is registered.
83	 */
84	String getNamespacePrefix(String namespaceURI);
85
86
87	/**
88	 * Obtain the URI for a registered namespace prefix.
89	 * <p>
90	 * It is not an error if the namespace prefix is not registered. The output
91	 * namespaceURI string is not modified if the namespace prefix is not
92	 * registered.
93	 *
94	 * @param namespacePrefix
95	 *            The prefix for the namespace. Must not be null or the empty
96	 *            string.
97	 * @return Returns the URI registered for this prefix.
98	 */
99	String getNamespaceURI(String namespacePrefix);
100
101
102	/**
103	 * @return Returns the registered prefix/namespace-pairs as map, where the keys are the
104	 *         namespaces and the values are the prefixes.
105	 */
106	Map getNamespaces();
107
108
109	/**
110	 * @return Returns the registered namespace/prefix-pairs as map, where the keys are the
111	 *         prefixes and the values are the namespaces.
112	 */
113	Map getPrefixes();
114
115
116	/**
117	 * Deletes a namespace from the registry.
118	 * <p>
119	 * Does nothing if the URI is not registered, or if the namespaceURI
120	 * parameter is null or the empty string.
121	 * <p>
122	 * Note: Not yet implemented.
123	 *
124	 * @param namespaceURI
125	 *            The URI for the namespace.
126	 */
127	void deleteNamespace(String namespaceURI);
128
129
130
131
132
133	// ---------------------------------------------------------------------------------------------
134	// Alias Functions
135
136
137	/**
138	 * Determines if a name is an alias, and what it is aliased to.
139	 *
140	 * @param aliasNS
141	 *            The namespace URI of the alias. Must not be <code>null</code> or the empty
142	 *            string.
143	 * @param aliasProp
144	 *            The name of the alias. May be an arbitrary path expression
145	 *            path, must not be <code>null</code> or the empty string.
146	 * @return Returns the <code>XMPAliasInfo</code> for the given alias namespace and property or
147	 * 		<code>null</code> if there is no such alias.
148	 */
149	XMPAliasInfo resolveAlias(String aliasNS, String aliasProp);
150
151
152	/**
153	 * Collects all aliases that are contained in the provided namespace.
154	 * If nothing is found, an empty array is returned.
155	 *
156	 * @param aliasNS a schema namespace URI
157	 * @return Returns all alias infos from aliases that are contained in the provided namespace.
158	 */
159	XMPAliasInfo[] findAliases(String aliasNS);
160
161
162	/**
163	 * Searches for registered aliases.
164	 *
165	 * @param qname
166	 *            an XML conform qname
167	 * @return Returns if an alias definition for the given qname to another
168	 *         schema and property is registered.
169	 */
170	XMPAliasInfo findAlias(String qname);
171
172
173	/**
174	 * @return Returns the registered aliases as map, where the key is the "qname" (prefix and name)
175	 * and the value an <code>XMPAliasInfo</code>-object.
176	 */
177	Map getAliases();
178
179
180}