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 10 package com.adobe.xmp; 11 12 import java.util.Map; 13 14 import 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 */ 44 public 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 }
