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 }