001    /*
002     * JBoss, Home of Professional Open Source.
003     * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004     * as indicated by the @author tags. See the copyright.txt file in the
005     * distribution for a full listing of individual contributors. 
006     *
007     * This is free software; you can redistribute it and/or modify it
008     * under the terms of the GNU Lesser General Public License as
009     * published by the Free Software Foundation; either version 2.1 of
010     * the License, or (at your option) any later version.
011     *
012     * This software is distributed in the hope that it will be useful,
013     * but WITHOUT ANY WARRANTY; without even the implied warranty of
014     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015     * Lesser General Public License for more details.
016     *
017     * You should have received a copy of the GNU Lesser General Public
018     * License along with this software; if not, write to the Free
019     * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020     * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021     */
022    package org.jboss.dna.graph.properties;
023    
024    import java.io.Serializable;
025    import net.jcip.annotations.Immutable;
026    import org.jboss.dna.common.text.TextEncoder;
027    import org.jboss.dna.graph.properties.Path.Segment;
028    
029    /**
030     * A qualified name consisting of a namespace and a local name.
031     * 
032     * @author Randall Hauch
033     */
034    @Immutable
035    public interface Name extends Comparable<Name>, Serializable {
036    
037        /**
038         * Get the local name part of this qualified name.
039         * 
040         * @return the local name; never null
041         */
042        String getLocalName();
043    
044        /**
045         * Get the URI for the namespace used in this qualified name.
046         * 
047         * @return the URI; never null but possibly empty
048         */
049        String getNamespaceUri();
050    
051        /**
052         * Get the string form of the name. The {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters in the local
053         * name and namespace.
054         * 
055         * @return the encoded string
056         * @see #getString(TextEncoder)
057         */
058        public String getString();
059    
060        /**
061         * Get the encoded string form of the name, using the supplied encoder to encode characters in the local name and namespace.
062         * 
063         * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
064         * @return the encoded string
065         * @see #getString()
066         */
067        public String getString( TextEncoder encoder );
068    
069        /**
070         * Get the string form of the name, using the supplied namespace registry to convert the {@link #getNamespaceUri() namespace
071         * URI} to a prefix. The {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters in each of the path
072         * segments.
073         * 
074         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
075         *        {@link Name#getNamespaceUri() namespace URI}
076         * @return the encoded string
077         * @throws IllegalArgumentException if the namespace registry is null
078         * @see #getString(NamespaceRegistry,TextEncoder)
079         */
080        public String getString( NamespaceRegistry namespaceRegistry );
081    
082        /**
083         * Get the encoded string form of the name, using the supplied namespace registry to convert the {@link #getNamespaceUri()
084         * namespace URI} to a prefix.
085         * 
086         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
087         *        {@link Name#getNamespaceUri() namespace URI}
088         * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
089         * @return the encoded string
090         * @throws IllegalArgumentException if the namespace registry is null
091         * @see #getString(NamespaceRegistry)
092         */
093        public String getString( NamespaceRegistry namespaceRegistry,
094                                 TextEncoder encoder );
095    
096        /**
097         * Get the encoded string form of the name, using the supplied namespace registry to convert the names' namespace URIs to
098         * prefixes and the supplied encoder to encode characters in each of the path segments, and using the second delimiter to
099         * encode (or convert) the delimiter used between the namespace prefix and the local part.
100         * 
101         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the
102         *        {@link Name#getNamespaceUri() namespace URIs} in the segment {@link Segment#getName() names}
103         * @param encoder the encoder to use for encoding the {@link Name#getLocalName() local part} and
104         *        {@link Name#getNamespaceUri() namespace prefix}, or null if the {@link Path#DEFAULT_ENCODER default encoder} should
105         *        be used
106         * @param delimiterEncoder the encoder to use for encoding the delimiter between the {@link Name#getLocalName() local part}
107         *        and {@link Name#getNamespaceUri() namespace prefix}, or null if the standard delimiter should be used
108         * @return the encoded string
109         * @see #getString(NamespaceRegistry)
110         * @see #getString(NamespaceRegistry, TextEncoder)
111         */
112        public String getString( NamespaceRegistry namespaceRegistry,
113                                 TextEncoder encoder,
114                                 TextEncoder delimiterEncoder );
115    }