1 /* 2 * ModeShape (http://www.modeshape.org) 3 * See the COPYRIGHT.txt file distributed with this work for information 4 * regarding copyright ownership. Some portions may be licensed 5 * to Red Hat, Inc. under one or more contributor license agreements. 6 * See the AUTHORS.txt file in the distribution for a full listing of 7 * individual contributors. 8 * 9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape 10 * is licensed to you under the terms of the GNU Lesser General Public License as 11 * published by the Free Software Foundation; either version 2.1 of 12 * the License, or (at your option) any later version. 13 * 14 * ModeShape is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with this software; if not, write to the Free 21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org. 23 */ 24 package org.modeshape.graph.property; 25 26 import java.util.Set; 27 import net.jcip.annotations.Immutable; 28 import net.jcip.annotations.ThreadSafe; 29 30 /** 31 * Registry of namespaces, which are used to provide isolated and independent domains for {@link Name names}. 32 */ 33 @ThreadSafe 34 public interface NamespaceRegistry { 35 36 /** 37 * Return the namespace URI that is currently mapped to the empty prefix, or null if there is no current default namespace. 38 * 39 * @return the namespace URI that represents the default namespace, or null if there is no default namespace 40 */ 41 String getDefaultNamespaceUri(); 42 43 /** 44 * Get the namespace URI for the supplied prefix. 45 * 46 * @param prefix the namespace prefix 47 * @return the namespace URI for the supplied prefix, or null if there is no namespace currently registered to use that prefix 48 * @throws IllegalArgumentException if the prefix is null 49 */ 50 String getNamespaceForPrefix( String prefix ); 51 52 /** 53 * Return the prefix used for the supplied namespace URI. 54 * 55 * @param namespaceUri the namespace URI 56 * @param generateIfMissing true if the namespace URI has not already been registered and the method should auto-register the 57 * namespace with a generated prefix, or false if the method should never auto-register the namespace 58 * @return the prefix currently being used for the namespace, or <code>null</code> if the namespace has not been registered 59 * and <code>generateIfMissing</code> is <code>false</code> 60 * @throws IllegalArgumentException if the namespace URI is null 61 * @see #isRegisteredNamespaceUri(String) 62 */ 63 String getPrefixForNamespaceUri( String namespaceUri, 64 boolean generateIfMissing ); 65 66 /** 67 * Return whether there is a registered prefix for the supplied namespace URI. 68 * 69 * @param namespaceUri the namespace URI 70 * @return true if the supplied namespace has been registered with a prefix, or false otherwise 71 * @throws IllegalArgumentException if the namespace URI is null 72 */ 73 boolean isRegisteredNamespaceUri( String namespaceUri ); 74 75 /** 76 * Register a new namespace using the supplied prefix, returning the namespace URI previously registered under that prefix. 77 * 78 * @param prefix the prefix for the namespace, or null if a namesapce prefix should be generated automatically 79 * @param namespaceUri the namespace URI 80 * @return the namespace URI that was previously registered with the supplied prefix, or null if the prefix was not previously 81 * bound to a namespace URI 82 * @throws IllegalArgumentException if the namespace URI is null 83 */ 84 String register( String prefix, 85 String namespaceUri ); 86 87 /** 88 * Unregister the namespace with the supplied URI. 89 * 90 * @param namespaceUri the namespace URI 91 * @return true if the namespace was removed, or false if the namespace was not registered 92 * @throws IllegalArgumentException if the namespace URI is null 93 * @throws NamespaceException if there is a problem unregistering the namespace 94 */ 95 boolean unregister( String namespaceUri ); 96 97 /** 98 * Obtain the set of namespaces that are registered. 99 * 100 * @return the set of 101 */ 102 Set<String> getRegisteredNamespaceUris(); 103 104 /** 105 * Obtain a snapshot of all of the {@link Namespace namespaces} registered at the time this method is called. The resulting 106 * set is immutable, and will <i>not</i> reflect changes made to the registry. 107 * 108 * @return an immutable set of {@link Namespace} objects reflecting a snapshot of the registry; never null 109 */ 110 Set<Namespace> getNamespaces(); 111 112 /** 113 * Representation of a single namespace at a single point in time. This object does not change to reflect changes made to the 114 * {@link NamespaceRegistry registry}. 115 * 116 * @see NamespaceRegistry#getNamespaces() 117 * @author Randall Hauch 118 */ 119 @Immutable 120 interface Namespace extends Comparable<Namespace> { 121 /** 122 * Get the prefix for the namespace 123 * 124 * @return the prefix; never null but possibly the empty string 125 */ 126 String getPrefix(); 127 128 /** 129 * Get the URI for the namespace 130 * 131 * @return the namespace URI; never null but possibly the empty string 132 */ 133 String getNamespaceUri(); 134 } 135 136 }