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 }