1. /*

  2.  * @(#)NVList.java	1.22 00/02/02

  3.  *

  4.  * Copyright 1996-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 org.omg.CORBA;

  12. 

  13. /**

  14.  * A modifiable list containing <code>NamedValue</code> objects.

  15.  * <P>

  16.  * The class <code>NVList</code> is used as follows:

  17.  * <UL>

  18.  * <LI>to describe arguments for a <code>Request</code> object

  19.  * in the Dynamic Invocation Interface and

  20.  * the Dynamic Skeleton Interface

  21.  * <LI>to describe context values in a <code>Context</code> object

  22.  * </UL>

  23.  * <P>

  24.  * Each <code>NamedValue</code> object consists of the following:

  25.  * <UL>

  26.  * <LI>a name, which is a <code>String</code> object

  27.  * <LI>a value, as an <code>Any</code> object

  28.  * <LI>an argument mode flag

  29.  * </UL>

  30.  * <P>

  31.  * An <code>NVList</code> object

  32.  * may be created using one of the following

  33.  * <code>ORB</code> methods:

  34.  * <OL>

  35.  * <LI><code>org.omg.CORBA.ORB.create_list</code>

  36.  * <PRE>

  37.  *    org.omg.CORBA.NVList nv = orb.create_list(3);

  38.  * </PRE>

  39.  * The variable <code>nv</code> represents a newly-created

  40.  * <code>NVList</code> object.  The argument is a memory-management

  41.  * hint to the orb and does not imply the actual length of the list.

  42.  * If, for example, you want to use an <code>NVList</code> object

  43.  * in a request, and the method being invoked takes three parameters,

  44.  * you might optimize by supplying 3 to the method

  45.  * <code>create_list</code>.  Note that the new <code>NVList</code>

  46.  * will not necessarily have a length of 3; it

  47.  * could have a length of 2 or 4, for instance.

  48.  * Note also that you can add any number of

  49.  * <code>NamedValue</code> objects to this list regardless of

  50.  * its original length.

  51.  * <P>

  52.  * <LI><code>org.omg.CORBA.ORB.create_operation_list</code>

  53.  * <PRE>

  54.  *    org.omg.CORBA.NVList nv = orb.create_operation_list(myOperationDef);

  55.  * </PRE>

  56.  * The variable <code>nv</code> represents a newly-created

  57.  * <code>NVList</code> object that contains descriptions of the

  58.  * arguments to the method described in the given

  59.  * <code>OperationDef</code> object.

  60.  * </OL>

  61.  * <P>

  62.  * The methods in the class <code>NVList</code> all deal with

  63.  * the <code>NamedValue</code> objects in the list.

  64.  * There are three methods for adding a <code>NamedValue</code> object,

  65.  * a method for getting the count of <code>NamedValue</code> objects in

  66.  * the list, a method for retrieving a <code>NamedValue</code> object

  67.  * at a given index, and a method for removing a <code>NamedValue</code> object

  68.  * at a given index.

  69.  *

  70.  * @see org.omg.CORBA.Request

  71.  * @see org.omg.CORBA.ServerRequest

  72.  * @see org.omg.CORBA.NamedValue

  73.  * @see org.omg.CORBA.Context

  74.  *

  75.  * @version 1.14 ,09/09/97

  76.  * @since       JDK1.2

  77.  */

  78. 

  79. public abstract class NVList {

  80. 

  81.     /**

  82.      * Returns the number of <code>NamedValue</code> objects that have

  83.      * been added to this <code>NVList</code> object.

  84.      *

  85.      * @return			an <code>int</code> indicating the number of

  86.      * <code>NamedValue</code> objects in this <code>NVList</code>.

  87.      */

  88. 

  89.     public abstract int count();

  90. 

  91.     /**

  92.      * Creates a new <code>NamedValue</code> object initialized with the given flag

  93.      * and adds it to the end of this <code>NVList</code> object.

  94.      * The flag can be any one of the argument passing modes:

  95.      * <code>ARG_IN.value</code>, <code>ARG_OUT.value</code>, or

  96.      * <code>ARG_INOUT.value</code>.

  97.      *

  98.      * @param flags		one of the argument mode flags

  99.      * @return			the newly-created <code>NamedValue</code> object

  100.      */

  101. 

  102.     public abstract NamedValue add(int flags);

  103. 

  104.     /**

  105.      * Creates a new <code>NamedValue</code> object initialized with the

  106.      * given name and flag,

  107.      * and adds it to the end of this <code>NVList</code> object.

  108.      * The flag can be any one of the argument passing modes:

  109.      * <code>ARG_IN.value</code>, <code>ARG_OUT.value</code>, or

  110.      * <code>ARG_INOUT.value</code>.

  111.      *

  112.      * @param item_name	the name for the new <code>NamedValue</code> object

  113.      * @param flags		one of the argument mode flags

  114.      * @return			the newly-created <code>NamedValue</code> object

  115.      */

  116. 

  117.     public abstract NamedValue add_item(String item_name, int flags);

  118. 

  119.     /**

  120.      * Creates a new <code>NamedValue</code> object initialized with the

  121.      * given name, value, and flag,

  122.      * and adds it to the end of this <code>NVList</code> object.

  123.      * The flag can be any one of the argument passing modes:

  124.      * <code>ARG_IN.value</code>, <code>ARG_OUT.value</code>, or

  125.      * <code>ARG_INOUT.value</code>.

  126.      *

  127.      * @param item_name	the name for the new <code>NamedValue</code> object

  128.      * @param value		an <code>Any</code> object containing the  value

  129.      *                    for the new <code>NamedValue</code> object

  130.      * @param flags		one of the argument mode flags

  131.      * @return			the newly-created <code>NamedValue</code> object

  132.      */

  133. 

  134.     public abstract NamedValue add_value(String item_name, Any val, int flags);

  135. 

  136.     /**

  137.      * Retrieves the <code>NamedValue</code> object at the given index.

  138.      *

  139.      * @param index		the index of the desired <code>NamedValue</code> object,

  140.      *                    which must be between zero and the length of the list

  141.      *                    minus one, inclusive.  The first item is at index zero.

  142.      * @return			the <code>NamedValue</code> object at the given index

  143.      * @exception org.omg.CORBA.Bounds  if the index is greater than

  144.      *				or equal to number of <code>NamedValue</code> objects

  145.      */

  146. 

  147.     public abstract NamedValue item(int index) throws org.omg.CORBA.Bounds;

  148. 

  149.     /**

  150.      * Removes the <code>NamedValue</code> object at the given index.

  151.      * Note that the indices of all <code>NamedValue</code> objects following

  152.      * the one removed are shifted down by one.

  153.      *

  154.      * @param index		the index of the <code>NamedValue</code> object to be

  155.      *                    removed, which must be between zero and the length

  156.      *                    of the list minus one, inclusive.

  157.      *                    The first item is at index zero.

  158.      * @exception org.omg.CORBA.Bounds  if the index is greater than

  159.      *				or equal to number of <code>NamedValue</code> objects in

  160.      *                the list

  161.      */

  162. 

  163.     public abstract void remove(int index) throws org.omg.CORBA.Bounds;

  164. 

  165. }