1. /*

  2.  * @(#)Name.java	1.5 00/02/02

  3.  *

  4.  * Copyright 1999, 2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package javax.naming;

  12. 

  13. import java.util.Enumeration;

  14. 

  15. /**

  16.  * The <tt>Name</tt> interface represents a generic name -- an ordered

  17.  * sequence of components.  It can be a composite name (names that

  18.  * span multiple namespaces), or a compound name (names that are

  19.  * used within individual hierarchical naming systems).

  20.  *

  21.  * <p> There can be different implementations of <tt>Name</tt> for example,

  22.  * composite names, URLs, or namespace-specific compound names.

  23.  *

  24.  * <p> The components of a name are numbered.  The indexes of a name

  25.  * with N components range from 0 up to, but not including, N.  This

  26.  * range may be written as [0,N).

  27.  * The most significant component is at index 0.

  28.  * An empty name has no components.

  29.  *

  30.  * <p> None of the methods in this interface accept null as a valid

  31.  * value for a parameter that is a name or a name component.

  32.  * Likewise, methods that return a name or name component never return null.

  33.  *

  34.  * <p> An instance of a <tt>Name</tt> may not be synchronized against

  35.  * concurrent multithreaded access if that access is not read-only.

  36.  *

  37.  * @author Rosanna Lee

  38.  * @author Scott Seligman

  39.  * @author R. Vasudevan

  40.  * @version 1.5 00/02/02

  41.  * @since 1.3

  42.  */

  43. 

  44. public interface Name extends Cloneable, java.io.Serializable {

  45. 

  46.     /**

  47.      * Generates a new copy of this name.

  48.      * Subsequent changes to the components of this name will not

  49.      * affect the new copy, and vice versa.

  50.      *

  51.      * @return	a copy of this name

  52.      *

  53.      * @see Object#clone()

  54.      */

  55.     public Object clone();

  56. 

  57.     /**

  58.      * Compares this name with another name for order.

  59.      * Returns a negative integer, zero, or a positive integer as this

  60.      * name is less than, equal to, or greater than the given name.

  61.      *

  62.      * <p> As with <tt>Object.equals()</tt>, the notion of ordering for names 

  63.      * depends on the class that implements this interface.

  64.      * For example, the ordering may be

  65.      * based on lexicographical ordering of the name components.

  66.      * Specific attributes of the name, such as how it treats case,

  67.      * may affect the ordering.  In general, two names of different

  68.      * classes may not be compared.

  69.      *

  70.      * @param   obj the non-null object to compare against.

  71.      * @return  a negative integer, zero, or a positive integer as this name

  72.      *		is less than, equal to, or greater than the given name

  73.      * @throws	ClassCastException if obj is not a <tt>Name</tt> of a

  74.      *		type that may be compared with this name

  75.      *

  76.      * @see Comparable#compareTo(Object)

  77.      */

  78.     public int compareTo(Object obj);

  79. 

  80.     /**

  81.      * Returns the number of components in this name.

  82.      *

  83.      * @return	the number of components in this name

  84.      */

  85.     public int size();

  86. 

  87.     /**

  88.      * Determines whether this name is empty.

  89.      * An empty name is one with zero components.

  90.      *

  91.      * @return	true if this name is empty, false otherwise

  92.      */

  93.     public boolean isEmpty();

  94. 

  95.     /**

  96.      * Retrieves the components of this name as an enumeration

  97.      * of strings.  The effect on the enumeration of updates to

  98.      * this name is undefined.  If the name has zero components,

  99.      * an empty (non-null) enumeration is returned.

  100.      *

  101.      * @return	an enumeration of the components of this name, each a string

  102.      */

  103.     public Enumeration getAll();

  104. 

  105.     /**

  106.      * Retrieves a component of this name.

  107.      *

  108.      * @param posn

  109.      *		the 0-based index of the component to retrieve.

  110.      *		Must be in the range [0,size()).

  111.      * @return	the component at index posn

  112.      * @throws	ArrayIndexOutOfBoundsException

  113.      *		if posn is outside the specified range

  114.      */

  115.     public String get(int posn);

  116. 

  117.     /**

  118.      * Creates a name whose components consist of a prefix of the

  119.      * components of this name.  Subsequent changes to

  120.      * this name will not affect the name that is returned and vice versa.

  121.      *

  122.      * @param posn

  123.      *		the 0-based index of the component at which to stop.

  124.      *		Must be in the range [0,size()].

  125.      * @return	a name consisting of the components at indexes in

  126.      *		the range [0,posn).

  127.      * @throws	ArrayIndexOutOfBoundsException

  128.      *		if posn is outside the specified range

  129.      */

  130.     public Name getPrefix(int posn);

  131. 

  132.     /**

  133.      * Creates a name whose components consist of a suffix of the

  134.      * components in this name.  Subsequent changes to

  135.      * this name do not affect the name that is returned and vice versa.

  136.      *

  137.      * @param posn

  138.      *		the 0-based index of the component at which to start.

  139.      *		Must be in the range [0,size()].

  140.      * @return	a name consisting of the components at indexes in

  141.      *		the range [posn,size()).  If posn is equal to 

  142.      *		size(), an empty name is returned.

  143.      * @throws	ArrayIndexOutOfBoundsException

  144.      *		if posn is outside the specified range

  145.      */

  146.     public Name getSuffix(int posn);

  147. 

  148.     /**

  149.      * Determines whether this name starts with a specified prefix.

  150.      * A name <tt>n</tt> is a prefix if it is equal to

  151.      * <tt>getPrefix(n.size())</tt>.

  152.      *

  153.      * @param n

  154.      *		the name to check

  155.      * @return	true if <tt>n</tt> is a prefix of this name, false otherwise

  156.      */

  157.     public boolean startsWith(Name n);

  158. 

  159.     /**

  160.      * Determines whether this name ends with a specified suffix.

  161.      * A name <tt>n</tt> is a suffix if it is equal to

  162.      * <tt>getSuffix(size()-n.size())</tt>.

  163.      *

  164.      * @param n

  165.      *		the name to check

  166.      * @return	true if <tt>n</tt> is a suffix of this name, false otherwise

  167.      */

  168.     public boolean endsWith(Name n);

  169. 

  170.     /**

  171.      * Adds the components of a name -- in order -- to the end of this name.

  172.      *

  173.      * @param suffix

  174.      *		the components to add

  175.      * @return	the updated name (not a new one)

  176.      *

  177.      * @throws	InvalidNameException if <tt>suffix</tt> is not a valid name,

  178.      *		or if the addition of the components would violate the syntax

  179.      *		rules of this name

  180.      */

  181.     public Name addAll(Name suffix) throws InvalidNameException;

  182. 

  183.     /**

  184.      * Adds the components of a name -- in order -- at a specified position

  185.      * within this name.

  186.      * Components of this name at or after the index of the first new

  187.      * component are shifted up (away from 0) to accommodate the new

  188.      * components.

  189.      *

  190.      * @param n

  191.      *		the components to add

  192.      * @param posn

  193.      *		the index in this name at which to add the new

  194.      *		components.  Must be in the range [0,size()].

  195.      * @return	the updated name (not a new one)

  196.      *

  197.      * @throws	ArrayIndexOutOfBoundsException

  198.      *		if posn is outside the specified range

  199.      * @throws	InvalidNameException if <tt>n</tt> is not a valid name,

  200.      *		or if the addition of the components would violate the syntax

  201.      *		rules of this name

  202.      */

  203.     public Name addAll(int posn, Name n) throws InvalidNameException;

  204. 

  205.     /**

  206.      * Adds a single component to the end of this name.

  207.      *

  208.      * @param comp

  209.      *		the component to add

  210.      * @return	the updated name (not a new one)

  211.      *

  212.      * @throws	InvalidNameException if adding <tt>comp</tt> would violate

  213.      *		the syntax rules of this name

  214.      */

  215.     public Name add(String comp) throws InvalidNameException;

  216. 

  217.     /**

  218.      * Adds a single component at a specified position within this name.

  219.      * Components of this name at or after the index of the new component

  220.      * are shifted up by one (away from index 0) to accommodate the new

  221.      * component.

  222.      *

  223.      * @param comp

  224.      *		the component to add

  225.      * @param posn

  226.      *		the index at which to add the new component.

  227.      *		Must be in the range [0,size()].

  228.      * @return	the updated name (not a new one)

  229.      *

  230.      * @throws	ArrayIndexOutOfBoundsException

  231.      *		if posn is outside the specified range

  232.      * @throws	InvalidNameException if adding <tt>comp</tt> would violate

  233.      *		the syntax rules of this name

  234.      */

  235.     public Name add(int posn, String comp) throws InvalidNameException;

  236. 

  237.     /**

  238.      * Removes a component from this name.

  239.      * The component of this name at the specified position is removed.

  240.      * Components with indexes greater than this position

  241.      * are shifted down (toward index 0) by one.

  242.      *

  243.      * @param posn

  244.      *		the index of the component to remove.

  245.      *		Must be in the range [0,size()).

  246.      * @return	the component removed (a String)

  247.      *

  248.      * @throws	ArrayIndexOutOfBoundsException

  249.      *		if posn is outside the specified range

  250.      * @throws	InvalidNameException if deleting the component

  251.      *		would violate the syntax rules of the name

  252.      */

  253.     public Object remove(int posn) throws InvalidNameException;

  254. }