1. /*

  2.  * @(#)NVList.java	1.27 03/12/19

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package org.omg.CORBA;

  9. 

  10. /**

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

  12.  * <P>

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

  14.  * <UL>

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

  16.  * in the Dynamic Invocation Interface and

  17.  * the Dynamic Skeleton Interface

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

  19.  * </UL>

  20.  * <P>

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

  22.  * <UL>

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

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

  25.  * <LI>an argument mode flag

  26.  * </UL>

  27.  * <P>

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

  29.  * may be created using one of the following

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

  31.  * <OL>

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

  33.  * <PRE>

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

  35.  * </PRE>

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

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

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

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

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

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

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

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

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

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

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

  47.  * its original length.

  48.  * <P>

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

  50.  * <PRE>

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

  52.  * </PRE>

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

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

  55.  * arguments to the method described in the given

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

  57.  * </OL>

  58.  * <P>

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

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

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

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

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

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

  65.  * at a given index.

  66.  *

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

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

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

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

  71.  *

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

  73.  * @since       JDK1.2

  74.  */

  75. 

  76. public abstract class NVList {

  77. 

  78.     /**

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

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

  81.      *

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

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

  84.      */

  85. 

  86.     public abstract int count();

  87. 

  88.     /**

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

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

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

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

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

  94.      *

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

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

  97.      */

  98. 

  99.     public abstract NamedValue add(int flags);

  100. 

  101.     /**

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

  103.      * given name and flag,

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

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

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

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

  108.      *

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

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

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

  112.      */

  113. 

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

  115. 

  116.     /**

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

  118.      * given name, value, and flag,

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

  120.      *

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

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

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

  124.      * @param flags	  one of the following argument passing modes:

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

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

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

  128.      */

  129. 

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

  131. 

  132.     /**

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

  134.      *

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

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

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

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

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

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

  141.      */

  142. 

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

  144. 

  145.     /**

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

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

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

  149.      *

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

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

  152.      *                    of the list minus one, inclusive.

  153.      *                    The first item is at index zero.

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

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

  156.      *                the list

  157.      */

  158. 

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

  160. 

  161. }