| /* |
| * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package javax.naming; |
| |
| import java.util.Enumeration; |
| |
| /** |
| * The {@code Name} interface represents a generic name -- an ordered |
| * sequence of components. It can be a composite name (names that |
| * span multiple namespaces), or a compound name (names that are |
| * used within individual hierarchical naming systems). |
| * |
| * <p> There can be different implementations of {@code Name}; for example, |
| * composite names, URLs, or namespace-specific compound names. |
| * |
| * <p> The components of a name are numbered. The indexes of a name |
| * with N components range from 0 up to, but not including, N. This |
| * range may be written as [0,N). |
| * The most significant component is at index 0. |
| * An empty name has no components. |
| * |
| * <p> None of the methods in this interface accept null as a valid |
| * value for a parameter that is a name or a name component. |
| * Likewise, methods that return a name or name component never return null. |
| * |
| * <p> An instance of a {@code Name} may not be synchronized against |
| * concurrent multithreaded access if that access is not read-only. |
| * |
| * @author Rosanna Lee |
| * @author Scott Seligman |
| * @author R. Vasudevan |
| * @since 1.3 |
| */ |
| |
| public interface Name |
| extends Cloneable, java.io.Serializable, Comparable<Object> |
| { |
| |
| /** |
| * The class fingerprint that is set to indicate |
| * serialization compatibility with a previous |
| * version of the class. |
| */ |
| static final long serialVersionUID = -3617482732056931635L; |
| |
| /** |
| * Generates a new copy of this name. |
| * Subsequent changes to the components of this name will not |
| * affect the new copy, and vice versa. |
| * |
| * @return a copy of this name |
| * |
| * @see Object#clone() |
| */ |
| public Object clone(); |
| |
| /** |
| * Compares this name with another name for order. |
| * Returns a negative integer, zero, or a positive integer as this |
| * name is less than, equal to, or greater than the given name. |
| * |
| * <p> As with {@code Object.equals()}, the notion of ordering for names |
| * depends on the class that implements this interface. |
| * For example, the ordering may be |
| * based on lexicographical ordering of the name components. |
| * Specific attributes of the name, such as how it treats case, |
| * may affect the ordering. In general, two names of different |
| * classes may not be compared. |
| * |
| * @param obj the non-null object to compare against. |
| * @return a negative integer, zero, or a positive integer as this name |
| * is less than, equal to, or greater than the given name |
| * @throws ClassCastException if obj is not a {@code Name} of a |
| * type that may be compared with this name |
| * |
| * @see Comparable#compareTo(Object) |
| */ |
| public int compareTo(Object obj); |
| |
| /** |
| * Returns the number of components in this name. |
| * |
| * @return the number of components in this name |
| */ |
| public int size(); |
| |
| /** |
| * Determines whether this name is empty. |
| * An empty name is one with zero components. |
| * |
| * @return true if this name is empty, false otherwise |
| */ |
| public boolean isEmpty(); |
| |
| /** |
| * Retrieves the components of this name as an enumeration |
| * of strings. The effect on the enumeration of updates to |
| * this name is undefined. If the name has zero components, |
| * an empty (non-null) enumeration is returned. |
| * |
| * @return an enumeration of the components of this name, each a string |
| */ |
| public Enumeration<String> getAll(); |
| |
| /** |
| * Retrieves a component of this name. |
| * |
| * @param posn |
| * the 0-based index of the component to retrieve. |
| * Must be in the range [0,size()). |
| * @return the component at index posn |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| */ |
| public String get(int posn); |
| |
| /** |
| * Creates a name whose components consist of a prefix of the |
| * components of this name. Subsequent changes to |
| * this name will not affect the name that is returned and vice versa. |
| * |
| * @param posn |
| * the 0-based index of the component at which to stop. |
| * Must be in the range [0,size()]. |
| * @return a name consisting of the components at indexes in |
| * the range [0,posn). |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| */ |
| public Name getPrefix(int posn); |
| |
| /** |
| * Creates a name whose components consist of a suffix of the |
| * components in this name. Subsequent changes to |
| * this name do not affect the name that is returned and vice versa. |
| * |
| * @param posn |
| * the 0-based index of the component at which to start. |
| * Must be in the range [0,size()]. |
| * @return a name consisting of the components at indexes in |
| * the range [posn,size()). If posn is equal to |
| * size(), an empty name is returned. |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| */ |
| public Name getSuffix(int posn); |
| |
| /** |
| * Determines whether this name starts with a specified prefix. |
| * A name {@code n} is a prefix if it is equal to |
| * {@code getPrefix(n.size())}. |
| * |
| * @param n |
| * the name to check |
| * @return true if {@code n} is a prefix of this name, false otherwise |
| */ |
| public boolean startsWith(Name n); |
| |
| /** |
| * Determines whether this name ends with a specified suffix. |
| * A name {@code n} is a suffix if it is equal to |
| * {@code getSuffix(size()-n.size())}. |
| * |
| * @param n |
| * the name to check |
| * @return true if {@code n} is a suffix of this name, false otherwise |
| */ |
| public boolean endsWith(Name n); |
| |
| /** |
| * Adds the components of a name -- in order -- to the end of this name. |
| * |
| * @param suffix |
| * the components to add |
| * @return the updated name (not a new one) |
| * |
| * @throws InvalidNameException if {@code suffix} is not a valid name, |
| * or if the addition of the components would violate the syntax |
| * rules of this name |
| */ |
| public Name addAll(Name suffix) throws InvalidNameException; |
| |
| /** |
| * Adds the components of a name -- in order -- at a specified position |
| * within this name. |
| * Components of this name at or after the index of the first new |
| * component are shifted up (away from 0) to accommodate the new |
| * components. |
| * |
| * @param n |
| * the components to add |
| * @param posn |
| * the index in this name at which to add the new |
| * components. Must be in the range [0,size()]. |
| * @return the updated name (not a new one) |
| * |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| * @throws InvalidNameException if {@code n} is not a valid name, |
| * or if the addition of the components would violate the syntax |
| * rules of this name |
| */ |
| public Name addAll(int posn, Name n) throws InvalidNameException; |
| |
| /** |
| * Adds a single component to the end of this name. |
| * |
| * @param comp |
| * the component to add |
| * @return the updated name (not a new one) |
| * |
| * @throws InvalidNameException if adding {@code comp} would violate |
| * the syntax rules of this name |
| */ |
| public Name add(String comp) throws InvalidNameException; |
| |
| /** |
| * Adds a single component at a specified position within this name. |
| * Components of this name at or after the index of the new component |
| * are shifted up by one (away from index 0) to accommodate the new |
| * component. |
| * |
| * @param comp |
| * the component to add |
| * @param posn |
| * the index at which to add the new component. |
| * Must be in the range [0,size()]. |
| * @return the updated name (not a new one) |
| * |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| * @throws InvalidNameException if adding {@code comp} would violate |
| * the syntax rules of this name |
| */ |
| public Name add(int posn, String comp) throws InvalidNameException; |
| |
| /** |
| * Removes a component from this name. |
| * The component of this name at the specified position is removed. |
| * Components with indexes greater than this position |
| * are shifted down (toward index 0) by one. |
| * |
| * @param posn |
| * the index of the component to remove. |
| * Must be in the range [0,size()). |
| * @return the component removed (a String) |
| * |
| * @throws ArrayIndexOutOfBoundsException |
| * if posn is outside the specified range |
| * @throws InvalidNameException if deleting the component |
| * would violate the syntax rules of the name |
| */ |
| public Object remove(int posn) throws InvalidNameException; |
| } |