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 net.jcip.annotations.Immutable;
027    import org.jboss.dna.common.text.TextEncoder;
028    import org.jboss.dna.graph.property.Path.Segment;
029    
030    /**
031     * An interface defining methods to obtain a "readable" string representation.
032     */
033    @Immutable
034    public interface Readable {
035    
036        /**
037         * Get the string form of the object. A {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters.
038         * 
039         * @return the encoded string
040         * @see #getString(TextEncoder)
041         */
042        public String getString();
043    
044        /**
045         * Get the encoded string form of the object, using the supplied encoder to encode characters.
046         * 
047         * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
048         * @return the encoded string
049         * @see #getString()
050         */
051        public String getString( TextEncoder encoder );
052    
053        /**
054         * Get the string form of the object, using the supplied namespace registry to convert any namespace URIs to prefixes. A
055         * {@link Path#DEFAULT_ENCODER default encoder} is used to encode characters.
056         * 
057         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for any namespace URIs
058         * @return the encoded string
059         * @throws IllegalArgumentException if the namespace registry is null
060         * @see #getString(NamespaceRegistry,TextEncoder)
061         */
062        public String getString( NamespaceRegistry namespaceRegistry );
063    
064        /**
065         * Get the encoded string form of the object, using the supplied namespace registry to convert the any namespace URIs to
066         * prefixes.
067         * 
068         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the namespace URIs
069         * @param encoder the encoder to use, or null if the {@link Path#DEFAULT_ENCODER default encoder} should be used
070         * @return the encoded string
071         * @throws IllegalArgumentException if the namespace registry is null
072         * @see #getString(NamespaceRegistry)
073         */
074        public String getString( NamespaceRegistry namespaceRegistry,
075                                 TextEncoder encoder );
076    
077        /**
078         * Get the encoded string form of the object, using the supplied namespace registry to convert the names' namespace URIs to
079         * prefixes and the supplied encoder to encode characters, and using the second delimiter to encode (or convert) the delimiter
080         * used between the namespace prefix and the local part of any names.
081         * 
082         * @param namespaceRegistry the namespace registry that should be used to obtain the prefix for the namespace URIs in the
083         *        segment {@link Segment#getName() names}
084         * @param encoder the encoder to use for encoding the local part and namespace prefix of any names, or null if the
085         *        {@link Path#DEFAULT_ENCODER default encoder} should be used
086         * @param delimiterEncoder the encoder to use for encoding the delimiter between the local part and namespace prefix of any
087         *        names, or null if the standard delimiter should be used
088         * @return the encoded string
089         * @see #getString(NamespaceRegistry)
090         * @see #getString(NamespaceRegistry, TextEncoder)
091         */
092        public String getString( NamespaceRegistry namespaceRegistry,
093                                 TextEncoder encoder,
094                                 TextEncoder delimiterEncoder );
095    }