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.io.Serializable;
027 import net.jcip.annotations.Immutable;
028 import org.jboss.dna.common.text.TextEncoder;
029 import org.jboss.dna.graph.property.Path.Segment;
030
031 /**
032 * A qualified name consisting of a namespace and a local name.
033 *
034 * @author Randall Hauch
035 */
036 @Immutable
037 public interface Name extends Comparable<Name>, Serializable {
038
039 /**
040 * Get the local name part of this qualified name.
041 *
042 * @return the local name; never null
043 */
044 String getLocalName();
045
046 /**
047 * Get the URI for the namespace used in this qualified name.
048 *
049 * @return the URI; never null but possibly empty
050 */
051 String getNamespaceUri();
052
053 /**
054 * Get the string form of the name. The {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters in the local
055 * name and namespace.
056 *
057 * @return the encoded string
058 * @see #getString(TextEncoder)
059 */
060 public String getString();
061
062 /**
063 * Get the encoded string form of the name, using the supplied encoder to encode characters in the local name and namespace.
064 *
065 * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
066 * @return the encoded string
067 * @see #getString()
068 */
069 public String getString( TextEncoder encoder );
070
071 /**
072 * Get the string form of the name, using the supplied namespace registry to convert the {@link #getNamespaceUri() namespace
073 * URI} to a prefix. The {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters in each of the path
074 * segments.
075 *
076 * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
077 * {@link Name#getNamespaceUri() namespace URI}
078 * @return the encoded string
079 * @throws IllegalArgumentException if the namespace registry is null
080 * @see #getString(NamespaceRegistry,TextEncoder)
081 */
082 public String getString( NamespaceRegistry namespaceRegistry );
083
084 /**
085 * Get the encoded string form of the name, using the supplied namespace registry to convert the {@link #getNamespaceUri()
086 * namespace URI} to a prefix.
087 *
088 * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
089 * {@link Name#getNamespaceUri() namespace URI}
090 * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
091 * @return the encoded string
092 * @throws IllegalArgumentException if the namespace registry is null
093 * @see #getString(NamespaceRegistry)
094 */
095 public String getString( NamespaceRegistry namespaceRegistry,
096 TextEncoder encoder );
097
098 /**
099 * Get the encoded string form of the name, using the supplied namespace registry to convert the names' namespace URIs to
100 * prefixes and the supplied encoder to encode characters in each of the path segments, and using the second delimiter to
101 * encode (or convert) the delimiter used between the namespace prefix and the local part.
102 *
103 * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
104 * {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
105 * @param encoder the encoder to use for encoding the {@link Name#getLocalName() local part} and
106 * {@link Name#getNamespaceUri() namespace prefix}, or null if the {@link Path#DEFAULT_ENCODER default encoder} should
107 * be used
108 * @param delimiterEncoder the encoder to use for encoding the delimiter between the {@link Name#getLocalName() local part}
109 * and {@link Name#getNamespaceUri() namespace prefix}, or null if the standard delimiter should be used
110 * @return the encoded string
111 * @see #getString(NamespaceRegistry)
112 * @see #getString(NamespaceRegistry, TextEncoder)
113 */
114 public String getString( NamespaceRegistry namespaceRegistry,
115 TextEncoder encoder,
116 TextEncoder delimiterEncoder );
117 }