J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 1 | /* |
Kelly O'Hair | fe008ae | 2010-05-25 15:58:33 -0700 | [diff] [blame] | 2 | * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 |
Kelly O'Hair | fe008ae | 2010-05-25 15:58:33 -0700 | [diff] [blame] | 7 | * published by the Free Software Foundation. Oracle designates this |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 8 | * particular file as subject to the "Classpath" exception as provided |
Kelly O'Hair | fe008ae | 2010-05-25 15:58:33 -0700 | [diff] [blame] | 9 | * by Oracle in the LICENSE file that accompanied this code. |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 | * |
Kelly O'Hair | fe008ae | 2010-05-25 15:58:33 -0700 | [diff] [blame] | 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. |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 24 | */ |
| 25 | |
| 26 | package javax.naming; |
| 27 | |
| 28 | import java.util.Enumeration; |
| 29 | |
| 30 | /** |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 31 | * The {@code Name} interface represents a generic name -- an ordered |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 | * |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 36 | * <p> There can be different implementations of {@code Name}; for example, |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 | * |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 49 | * <p> An instance of a {@code Name} may not be synchronized against |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 | */ |
| 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 | * |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 85 | * <p> As with {@code Object.equals()}, the notion of ordering for names |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 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 |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 96 | * @throws ClassCastException if obj is not a {@code Name} of a |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 97 | * type that may be compared with this name |
| 98 | * |
| 99 | * @see Comparable#compareTo(Object) |
| 100 | */ |
| 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 | */ |
| 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 | */ |
| 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 | */ |
| 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 | */ |
| 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 | */ |
| 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 | */ |
| 169 | public Name getSuffix(int posn); |
| 170 | |
| 171 | /** |
| 172 | * Determines whether this name starts with a specified prefix. |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 173 | * A name {@code n} is a prefix if it is equal to |
| 174 | * {@code getPrefix(n.size())}. |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 175 | * |
| 176 | * @param n |
| 177 | * the name to check |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 178 | * @return true if {@code n} is a prefix of this name, false otherwise |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 179 | */ |
| 180 | public boolean startsWith(Name n); |
| 181 | |
| 182 | /** |
| 183 | * Determines whether this name ends with a specified suffix. |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 184 | * A name {@code n} is a suffix if it is equal to |
| 185 | * {@code getSuffix(size()-n.size())}. |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 186 | * |
| 187 | * @param n |
| 188 | * the name to check |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 189 | * @return true if {@code n} is a suffix of this name, false otherwise |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 190 | */ |
| 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 | * |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 200 | * @throws InvalidNameException if {@code suffix} is not a valid name, |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 201 | * or if the addition of the components would violate the syntax |
| 202 | * rules of this name |
| 203 | */ |
| 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 |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 222 | * @throws InvalidNameException if {@code n} is not a valid name, |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 223 | * or if the addition of the components would violate the syntax |
| 224 | * rules of this name |
| 225 | */ |
| 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 | * |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 235 | * @throws InvalidNameException if adding {@code comp} would violate |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 236 | * the syntax rules of this name |
| 237 | */ |
| 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 |
Alexander Stepanov | ff767bf | 2015-08-05 13:40:18 +0300 | [diff] [blame] | 255 | * @throws InvalidNameException if adding {@code comp} would violate |
J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame] | 256 | * the syntax rules of this name |
| 257 | */ |
| 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 | */ |
| 276 | public Object remove(int posn) throws InvalidNameException; |
| 277 | } |