001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr;
005:
006: /**
007: * Each repository has a single, persistent namespace registry represented by
008: * the <code>NamespaceRegistry</code> object, accessed via Workspace.getNamespaceRegistry().
009: * The namespace registry contains the default prefixes of the registered
010: * namespaces. The namespace registry may contain namespaces that are not used
011: * in repository content, and there may be repository content with namespaces
012: * that are not included n the registry.
013: *
014: * @see Workspace#getNamespaceRegistry
015: */
016: public interface NamespaceRegistry {
017:
018: /**
019: * Sets a one-to-one mapping between <code>prefix</code> and <code>uri</code>
020: * in the global namespace registry of this repository.
021: * <p/>
022: * Assigning a new prefix to a URI that already exists in the namespace
023: * registry erases the old prefix. In general this can almost always be done,
024: * though an implementation is free to prevent particular remappings by
025: * throwing a <code>NamespaceException</code>.
026: * <p/>
027: * On the other hand, taking a prefix that is already assigned to a URI and
028: * re-assigning it to a new URI in effect unregisters that URI. Therefore,
029: * the same restrictions apply to this operation as to
030: * <code>NamespaceRegistry.unregisterNamespace</code>:
031: * <ul>
032: * <li>
033: * Attempting to re-assign a built-in prefix (<code>jcr</code>,
034: * <code>nt</code>, <code>mix</code>, <code>sv</code>, <code>xml</code>, or
035: * the empty prefix) to a new URI will throw a
036: * <code>NamespaceException</code>.
037: * </li>
038: * <li>
039: * Attempting to register a namespace with a prefix that begins with the
040: * characters "<code>xml</code>" (in any combination of case) will throw a
041: * <code>NamespaceException</code>.
042: * </li>
043: * <li>
044: * An implementation may prevent the re-assignment of any other namespace prefixes for
045: * implementation-specific reasons by throwing a <code>NamespaceException</code>.
046: * </li>
047: * </ul>
048: * In a level 1 implementation, this method always throws an
049: * <code>UnsupportedRepositoryOperationException</code>.
050: * <p/>
051: * If the session associated with the <code>Workspace</code> object through which this registry was acquired does not have sufficient permissions to register the
052: * namespace an <code>AccessDeniedException</code> is thrown.
053: * <p/>
054: * A <code>RepositoryException</code> is thrown if another error occurs.
055: *
056: * @param prefix The prefix to be mapped.
057: * @param uri The URI to be mapped.
058: * @throws NamespaceException if an illegal attempt is made to register a mapping.
059: * @throws UnsupportedRepositoryOperationException in a level 1 implementation
060: * @throws AccessDeniedException if the session associated with the <code>Workspace</code> object through which this registry was acquired does not have sufficient permissions to register the namespace.
061: * @throws RepositoryException if another error occurs.
062: */
063: public void registerNamespace(String prefix, String uri)
064: throws NamespaceException,
065: UnsupportedRepositoryOperationException,
066: AccessDeniedException, RepositoryException;
067:
068: /**
069: * Removes a namespace mapping from the registry. The following restriction apply:
070: * <ul>
071: * <li>
072: * Attempting to unregister a built-in namespace (<code>jcr</code>, <code>nt</code>,
073: * <code>mix</code>, <code>sv</code>, <code>xml</code> or the empty namespace) will
074: * throw a <code>NamespaceException</code>.
075: * </li>
076: * <li>
077: * An attempt to unregister a namespace that is not currently registered will throw a
078: * <code>NamespaceException</code>.
079: * </li>
080: * <li>
081: * An implementation may prevent the unregistering of any other namespace for
082: * implementation-specific reasons by throwing a <code>NamespaceException</code>.
083: * </li>
084: * </ul>
085: * In a level 1 implementation, this method always throws an
086: * <code>UnsupportedRepositoryOperationException</code>.
087: * <p/>
088: * If the session associated with the <code>Workspace</code> object through which this registry was acquired
089: * does not have sufficient permissions to unregister the
090: * namespace an <code>AccessDeniedException</code> is thrown.
091: * <p/>
092: * A <code>RepositoryException</code> is thrown if another error occurs.
093: *
094: * @param prefix The prefix of the mapping to be removed.
095: * @throws NamespaceException if an illegal attempt is made to remove a mapping.
096: * @throws UnsupportedRepositoryOperationException in a level 1 implementation
097: * @throws AccessDeniedException if the session associated with the <code>Workspace</code> object through which this registry was acquired does not have sufficient permissions
098: * to unregister the namespace.
099: * @throws RepositoryException if another error occurs.
100: */
101: public void unregisterNamespace(String prefix)
102: throws NamespaceException,
103: UnsupportedRepositoryOperationException,
104: AccessDeniedException, RepositoryException;
105:
106: /**
107: * Returns an array holding all currently registered prefixes.
108: * @return a string array
109: * @throws RepositoryException if an error occurs.
110: */
111: public String[] getPrefixes() throws RepositoryException;
112:
113: /**
114: * Returns an array holding all currently registered URIs.
115: * @return a string array
116: * @throws RepositoryException if an error occurs.
117: */
118: public String[] getURIs() throws RepositoryException;
119:
120: /**
121: * Returns the URI to which the given <code>prefix</code> is mapped.
122: * @param prefix a string
123: * @return a string
124: * @throws NamespaceException if a mapping with the specified <code>prefix</code> does not exist.
125: * @throws RepositoryException is another error occurs
126: */
127: public String getURI(String prefix) throws NamespaceException,
128: RepositoryException;
129:
130: /**
131: * Returns the prefix which is mapped to the given <code>uri</code>.
132: *
133: * @param uri a string
134: * @return a string
135: * @throws NamespaceException if a mapping with the specified <code>uri</code> does not exist.
136: * @throws RepositoryException is another error occurs
137: */
138: public String getPrefix(String uri) throws NamespaceException,
139: RepositoryException;
140: }
|