1 /* 2 * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.naming; 27 28 import java.util.Enumeration; 29 30 /** 31 * The {@code Name} interface represents a generic name -- an ordered 32 * sequence of components. It can be a composite name (names that 33 * span multiple namespaces), or a compound name (names that are 34 * used within individual hierarchical naming systems). 35 * 36 * <p> There can be different implementations of {@code Name}; for example, 37 * composite names, URLs, or namespace-specific compound names. 38 * 39 * <p> The components of a name are numbered. The indexes of a name 40 * with N components range from 0 up to, but not including, N. This 41 * range may be written as [0,N). 42 * The most significant component is at index 0. 43 * An empty name has no components. 44 * 45 * <p> None of the methods in this interface accept null as a valid 46 * value for a parameter that is a name or a name component. 47 * Likewise, methods that return a name or name component never return null. 48 * 49 * <p> An instance of a {@code Name} may not be synchronized against 50 * concurrent multithreaded access if that access is not read-only. 51 * 52 * @author Rosanna Lee 53 * @author Scott Seligman 54 * @author R. Vasudevan 55 * @since 1.3 56 */ 57 58 public interface Name 59 extends Cloneable, java.io.Serializable, Comparable<Object> 60 { 61 62 /** 63 * The class fingerprint that is set to indicate 64 * serialization compatibility with a previous 65 * version of the class. 66 */ 67 static final long serialVersionUID = -3617482732056931635L; 68 69 /** 70 * Generates a new copy of this name. 71 * Subsequent changes to the components of this name will not 72 * affect the new copy, and vice versa. 73 * 74 * @return a copy of this name 75 * 76 * @see Object#clone() 77 */ clone()78 public Object clone(); 79 80 /** 81 * Compares this name with another name for order. 82 * Returns a negative integer, zero, or a positive integer as this 83 * name is less than, equal to, or greater than the given name. 84 * 85 * <p> As with {@code Object.equals()}, the notion of ordering for names 86 * depends on the class that implements this interface. 87 * For example, the ordering may be 88 * based on lexicographical ordering of the name components. 89 * Specific attributes of the name, such as how it treats case, 90 * may affect the ordering. In general, two names of different 91 * classes may not be compared. 92 * 93 * @param obj the non-null object to compare against. 94 * @return a negative integer, zero, or a positive integer as this name 95 * is less than, equal to, or greater than the given name 96 * @throws ClassCastException if obj is not a {@code Name} of a 97 * type that may be compared with this name 98 * 99 * @see Comparable#compareTo(Object) 100 */ compareTo(Object obj)101 public int compareTo(Object obj); 102 103 /** 104 * Returns the number of components in this name. 105 * 106 * @return the number of components in this name 107 */ size()108 public int size(); 109 110 /** 111 * Determines whether this name is empty. 112 * An empty name is one with zero components. 113 * 114 * @return true if this name is empty, false otherwise 115 */ isEmpty()116 public boolean isEmpty(); 117 118 /** 119 * Retrieves the components of this name as an enumeration 120 * of strings. The effect on the enumeration of updates to 121 * this name is undefined. If the name has zero components, 122 * an empty (non-null) enumeration is returned. 123 * 124 * @return an enumeration of the components of this name, each a string 125 */ getAll()126 public Enumeration<String> getAll(); 127 128 /** 129 * Retrieves a component of this name. 130 * 131 * @param posn 132 * the 0-based index of the component to retrieve. 133 * Must be in the range [0,size()). 134 * @return the component at index posn 135 * @throws ArrayIndexOutOfBoundsException 136 * if posn is outside the specified range 137 */ get(int posn)138 public String get(int posn); 139 140 /** 141 * Creates a name whose components consist of a prefix of the 142 * components of this name. Subsequent changes to 143 * this name will not affect the name that is returned and vice versa. 144 * 145 * @param posn 146 * the 0-based index of the component at which to stop. 147 * Must be in the range [0,size()]. 148 * @return a name consisting of the components at indexes in 149 * the range [0,posn). 150 * @throws ArrayIndexOutOfBoundsException 151 * if posn is outside the specified range 152 */ getPrefix(int posn)153 public Name getPrefix(int posn); 154 155 /** 156 * Creates a name whose components consist of a suffix of the 157 * components in this name. Subsequent changes to 158 * this name do not affect the name that is returned and vice versa. 159 * 160 * @param posn 161 * the 0-based index of the component at which to start. 162 * Must be in the range [0,size()]. 163 * @return a name consisting of the components at indexes in 164 * the range [posn,size()). If posn is equal to 165 * size(), an empty name is returned. 166 * @throws ArrayIndexOutOfBoundsException 167 * if posn is outside the specified range 168 */ getSuffix(int posn)169 public Name getSuffix(int posn); 170 171 /** 172 * Determines whether this name starts with a specified prefix. 173 * A name {@code n} is a prefix if it is equal to 174 * {@code getPrefix(n.size())}. 175 * 176 * @param n 177 * the name to check 178 * @return true if {@code n} is a prefix of this name, false otherwise 179 */ startsWith(Name n)180 public boolean startsWith(Name n); 181 182 /** 183 * Determines whether this name ends with a specified suffix. 184 * A name {@code n} is a suffix if it is equal to 185 * {@code getSuffix(size()-n.size())}. 186 * 187 * @param n 188 * the name to check 189 * @return true if {@code n} is a suffix of this name, false otherwise 190 */ endsWith(Name n)191 public boolean endsWith(Name n); 192 193 /** 194 * Adds the components of a name -- in order -- to the end of this name. 195 * 196 * @param suffix 197 * the components to add 198 * @return the updated name (not a new one) 199 * 200 * @throws InvalidNameException if {@code suffix} is not a valid name, 201 * or if the addition of the components would violate the syntax 202 * rules of this name 203 */ addAll(Name suffix)204 public Name addAll(Name suffix) throws InvalidNameException; 205 206 /** 207 * Adds the components of a name -- in order -- at a specified position 208 * within this name. 209 * Components of this name at or after the index of the first new 210 * component are shifted up (away from 0) to accommodate the new 211 * components. 212 * 213 * @param n 214 * the components to add 215 * @param posn 216 * the index in this name at which to add the new 217 * components. Must be in the range [0,size()]. 218 * @return the updated name (not a new one) 219 * 220 * @throws ArrayIndexOutOfBoundsException 221 * if posn is outside the specified range 222 * @throws InvalidNameException if {@code n} is not a valid name, 223 * or if the addition of the components would violate the syntax 224 * rules of this name 225 */ addAll(int posn, Name n)226 public Name addAll(int posn, Name n) throws InvalidNameException; 227 228 /** 229 * Adds a single component to the end of this name. 230 * 231 * @param comp 232 * the component to add 233 * @return the updated name (not a new one) 234 * 235 * @throws InvalidNameException if adding {@code comp} would violate 236 * the syntax rules of this name 237 */ add(String comp)238 public Name add(String comp) throws InvalidNameException; 239 240 /** 241 * Adds a single component at a specified position within this name. 242 * Components of this name at or after the index of the new component 243 * are shifted up by one (away from index 0) to accommodate the new 244 * component. 245 * 246 * @param comp 247 * the component to add 248 * @param posn 249 * the index at which to add the new component. 250 * Must be in the range [0,size()]. 251 * @return the updated name (not a new one) 252 * 253 * @throws ArrayIndexOutOfBoundsException 254 * if posn is outside the specified range 255 * @throws InvalidNameException if adding {@code comp} would violate 256 * the syntax rules of this name 257 */ add(int posn, String comp)258 public Name add(int posn, String comp) throws InvalidNameException; 259 260 /** 261 * Removes a component from this name. 262 * The component of this name at the specified position is removed. 263 * Components with indexes greater than this position 264 * are shifted down (toward index 0) by one. 265 * 266 * @param posn 267 * the index of the component to remove. 268 * Must be in the range [0,size()). 269 * @return the component removed (a String) 270 * 271 * @throws ArrayIndexOutOfBoundsException 272 * if posn is outside the specified range 273 * @throws InvalidNameException if deleting the component 274 * would violate the syntax rules of the name 275 */ remove(int posn)276 public Object remove(int posn) throws InvalidNameException; 277 } 278