001 /*
002 * JBoss DNA (http://www.jboss.org/dna)
003 * See the COPYRIGHT.txt file distributed with this work for information
004 * regarding copyright ownership. Some portions may be licensed
005 * to Red Hat, Inc. under one or more contributor license agreements.
006 * See the AUTHORS.txt file in the distribution for a full listing of
007 * individual contributors.
008 *
009 * JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
010 * is licensed to you under the terms of the GNU Lesser General Public License as
011 * published by the Free Software Foundation; either version 2.1 of
012 * the License, or (at your option) any later version.
013 *
014 * JBoss DNA is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this software; if not, write to the Free
021 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
023 */
024 package org.jboss.dna.graph.property;
025
026 import java.util.Set;
027 import net.jcip.annotations.Immutable;
028 import net.jcip.annotations.ThreadSafe;
029
030 /**
031 * Registry of namespaces, which are used to provide isolated and independent domains for {@link Name names}.
032 *
033 * @author Randall Hauch
034 */
035 @ThreadSafe
036 public interface NamespaceRegistry {
037
038 /**
039 * Return the namespace URI that is currently mapped to the empty prefix, or null if there is no current default namespace.
040 *
041 * @return the namespace URI that represents the default namespace, or null if there is no default namespace
042 */
043 String getDefaultNamespaceUri();
044
045 /**
046 * Get the namespace URI for the supplied prefix.
047 *
048 * @param prefix the namespace prefix
049 * @return the namespace URI for the supplied prefix, or null if there is no namespace currently registered to use that prefix
050 * @throws IllegalArgumentException if the prefix is null
051 */
052 String getNamespaceForPrefix( String prefix );
053
054 /**
055 * Return the prefix used for the supplied namespace URI.
056 *
057 * @param namespaceUri the namespace URI
058 * @param generateIfMissing true if the namespace URI has not already been registered and the method should auto-register the
059 * namespace with a generated prefix, or false if the method should never auto-register the namespace
060 * @return the prefix currently being used for the namespace, or <code>null</code> if the namespace has not been registered
061 * and <code>generateIfMissing</code> is <code>false</code>
062 * @throws IllegalArgumentException if the namespace URI is null
063 * @see #isRegisteredNamespaceUri(String)
064 */
065 String getPrefixForNamespaceUri( String namespaceUri,
066 boolean generateIfMissing );
067
068 /**
069 * Return whether there is a registered prefix for the supplied namespace URI.
070 *
071 * @param namespaceUri the namespace URI
072 * @return true if the supplied namespace has been registered with a prefix, or false otherwise
073 * @throws IllegalArgumentException if the namespace URI is null
074 */
075 boolean isRegisteredNamespaceUri( String namespaceUri );
076
077 /**
078 * Register a new namespace using the supplied prefix, returning the namespace URI previously registered under that prefix.
079 *
080 * @param prefix the prefix for the namespace, or null if a namesapce prefix should be generated automatically
081 * @param namespaceUri the namespace URI
082 * @return the namespace URI that was previously registered with the supplied prefix, or null if the prefix was not previously
083 * bound to a namespace URI
084 * @throws IllegalArgumentException if the namespace URI is null
085 */
086 String register( String prefix,
087 String namespaceUri );
088
089 /**
090 * Unregister the namespace with the supplied URI.
091 *
092 * @param namespaceUri the namespace URI
093 * @return true if the namespace was removed, or false if the namespace was not registered
094 * @throws IllegalArgumentException if the namespace URI is null
095 * @throws NamespaceException if there is a problem unregistering the namespace
096 */
097 boolean unregister( String namespaceUri );
098
099 /**
100 * Obtain the set of namespaces that are registered.
101 *
102 * @return the set of
103 */
104 Set<String> getRegisteredNamespaceUris();
105
106 /**
107 * Obtain a snapshot of all of the {@link Namespace namespaces} registered at the time this method is called. The resulting
108 * set is immutable, and will <i>not</i> reflect changes made to the registry.
109 *
110 * @return an immutable set of {@link Namespace} objects reflecting a snapshot of the registry; never null
111 */
112 Set<Namespace> getNamespaces();
113
114 /**
115 * Representation of a single namespace at a single point in time. This object does not change to reflect changes made to the
116 * {@link NamespaceRegistry registry}.
117 *
118 * @see NamespaceRegistry#getNamespaces()
119 * @author Randall Hauch
120 */
121 @Immutable
122 interface Namespace extends Comparable<Namespace> {
123 /**
124 * Get the prefix for the namespace
125 *
126 * @return the prefix; never null but possibly the empty string
127 */
128 String getPrefix();
129
130 /**
131 * Get the URI for the namespace
132 *
133 * @return the namespace URI; never null but possibly the empty string
134 */
135 String getNamespaceUri();
136 }
137
138 }