Home » openjdk-7 » javax » naming » [javadoc | source]

    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 <tt>Name</tt> 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 <tt>Name</tt>; 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 <tt>Name</tt> 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        */
   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 <tt>Object.equals()</tt>, 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 <tt>Name</tt> of a
   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.
  173        * A name <tt>n</tt> is a prefix if it is equal to
  174        * <tt>getPrefix(n.size())</tt>.
  175        *
  176        * @param n
  177        *          the name to check
  178        * @return  true if <tt>n</tt> is a prefix of this name, false otherwise
  179        */
  180       public boolean startsWith(Name n);
  181   
  182       /**
  183        * Determines whether this name ends with a specified suffix.
  184        * A name <tt>n</tt> is a suffix if it is equal to
  185        * <tt>getSuffix(size()-n.size())</tt>.
  186        *
  187        * @param n
  188        *          the name to check
  189        * @return  true if <tt>n</tt> is a suffix of this name, false otherwise
  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        *
  200        * @throws  InvalidNameException if <tt>suffix</tt> is not a valid name,
  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
  222        * @throws  InvalidNameException if <tt>n</tt> is not a valid name,
  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        *
  235        * @throws  InvalidNameException if adding <tt>comp</tt> would violate
  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
  255        * @throws  InvalidNameException if adding <tt>comp</tt> would violate
  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   }

Home » openjdk-7 » javax » naming » [javadoc | source]