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    }