1. /*

  2.  * @(#)Request.java	1.21 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.  * An object containing the information necessary for

  15.  * invoking a method.  This class is

  16.  * the cornerstone of the ORB Dynamic

  17.  * Invocation Interface (DII), which allows dynamic creation and

  18.  * invocation of requests.

  19.  * A server cannot tell the difference between a client

  20.  * invocation using a client stub and a request using the DII.

  21.  * <P>

  22.  * A <code>Request</code> object consists of:

  23.  * <UL>

  24.  * <LI>the name of the operation to be invoked

  25.  * <LI>an <code>NVList</code> containing arguments for the operation.<BR>

  26.  * Each item in the list is a <code>NamedValue</code> object, which has three

  27.  * parts:

  28.  *  <OL>

  29.  *    <LI>the name of the argument

  30.  *    <LI>the value of the argument (as an <code>Any</code> object)

  31.  *    <LI>the argument mode flag indicating whether the argument is

  32.  *        for input, output, or both

  33.  *  </OL>

  34.  * </UL>

  35.  * <P>

  36.  * <code>Request</code> objects may also contain additional information,

  37.  * depending on how an operation was defined in the original IDL

  38.  * interface definition.  For example, where appropriate, they may contain

  39.  * a <code>NamedValue</code> object to hold the return value or exception,

  40.  * a context, a list of possible exceptions, and a list of

  41.  * context strings that need to be resolved.

  42.  * <P>

  43.  * New <code>Request</code> objects are created using one of the

  44.  * <code>create_request</code> methods in the <code>Object</code> class.

  45.  * In other words, a <code>create_request</code> method is performed on the

  46.  * object which is to be invoked.

  47.  *

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

  49.  *

  50.  * @version 1.13 09/09/97

  51.  */

  52. 

  53. public abstract class Request {

  54. 

  55.     /**

  56.      * Retrieves the the target object reference.

  57.      *

  58.      * @return			the object reference that points to the

  59.      *                    object implementation for the method

  60.      *                    to be invoked

  61.      */

  62. 

  63.     public abstract org.omg.CORBA.Object target();

  64. 

  65.     /**

  66.      * Retrieves the name of the method to be invoked.

  67.      *

  68.      * @return			the name of the method to be invoked

  69.      */

  70. 

  71.     public abstract String operation();

  72. 

  73.     /**

  74.      * Retrieves the <code>NVList</code> object containing the arguments

  75.      * to the method being invoked.  The elements in the list are

  76.      * <code>NamedValue</code> objects, with each one describing an argument

  77.      * to the method.

  78.      *

  79.      * @return	the <code>NVList</code> object containing the arguments

  80.      *			for the method

  81.      *

  82.      */

  83. 

  84.     public abstract NVList arguments();

  85. 

  86.     /**

  87.      * Retrieves the <code>NamedValue</code> object containing the return

  88.      * value for the method.

  89.      *

  90.      * @return		the <code>NamedValue</code> object containing the result

  91.      *				of the method

  92.      */

  93. 

  94.     public abstract NamedValue result();

  95. 

  96.     /**

  97.      * Retrieves the <code>Environment</code> object for this request.

  98.      * It contains the exception that the method being invoked has

  99.      * thrown (after the invocation returns).

  100.      *

  101.      *

  102.      * @return	the <code>Environment</code> object for this request

  103.      */

  104. 

  105.     public abstract Environment env();

  106. 

  107.     /**

  108.      * Retrieves the <code>ExceptionList</code> object for this request.

  109.      * This list contains <code>TypeCode</code> objects describing the

  110.      * exceptions that may be thrown by the method being invoked.

  111.      *

  112.      * @return	the <code>ExceptionList</code> object describing the exceptions

  113.      *            that may be thrown by the method being invoked

  114.      */

  115. 

  116.     public abstract ExceptionList exceptions();

  117. 

  118.     /**

  119.      * Retrieves the <code>ContextList</code> object for this request.

  120.      * This list contains context <code>String</code>s that need to

  121.      * be resolved and sent with the invocation.

  122.      *

  123.      *

  124.      * @return			the list of context strings whose values

  125.      *				need to be resolved and sent with the

  126.      *				invocation.

  127.      */

  128. 

  129.     public abstract ContextList contexts();

  130. 

  131.     /**

  132.      * Retrieves the <code>Context</code> object for this request.

  133.      * This is a list of properties giving information about the

  134.      * client, the environment, or the circumstances of this request.

  135.      *

  136.      * @return		the <code>Context</code> object that is to be used

  137.      *				to resolve any context strings whose

  138.      *				values need to be sent with the invocation

  139.      */

  140. 

  141.     public abstract Context ctx();

  142. 

  143.     /**

  144.      * Sets this request's <code>Context</code> object to the one given.

  145.      *

  146.      * @param c		the new <code>Context</code> object to be used for

  147.      *				resolving context strings

  148.      */

  149. 

  150.     public abstract void ctx(Context c);

  151. 

  152. 

  153.     /**

  154.      * Creates an input argument and adds it to this <code>Request</code>

  155.      * object.

  156.      *

  157.      * @return		an <code>Any</code> object that contains the

  158.      *                value and typecode for the input argument added

  159.      */

  160. 

  161.     public abstract Any add_in_arg();

  162. 

  163.     /**

  164.      * Creates an input argument with the given name and adds it to

  165.      * this <code>Request</code> object.

  166.      *

  167.      * @param name		the name of the argument being added

  168.      * @return		an <code>Any</code> object that contains the

  169.      *                value and typecode for the input argument added

  170.      */

  171. 

  172.     public abstract Any add_named_in_arg(String name);

  173. 

  174.     /**

  175.      * Adds an input/output argument to this <code>Request</code> object.

  176.      *

  177.      * @return		an <code>Any</code> object that contains the

  178.      *                value and typecode for the input/output argument added

  179.      */

  180. 

  181.     public abstract Any add_inout_arg();

  182. 

  183.     /**

  184.      * Adds an input/output argument with the given name to this

  185.      * <code>Request</code> object.

  186.      *

  187.      * @param name		the name of the argument being added

  188.      * @return		an <code>Any</code> object that contains the

  189.      *                value and typecode for the input/output argument added

  190.      */

  191. 

  192.     public abstract Any add_named_inout_arg(String name);

  193. 

  194. 

  195.     /**

  196.      * Adds an output argument to this <code>Request</code> object.

  197.      *

  198.      * @return		an <code>Any</code> object that contains the

  199.      *                value and typecode for the output argument added

  200.      */

  201. 

  202.     public abstract Any add_out_arg();

  203. 

  204.     /**

  205.      * Adds an output argument with the given name to this

  206.      * <code>Request</code> object.

  207.      *

  208.      * @param name		the name of the argument being added

  209.      * @return		an <code>Any</code> object that contains the

  210.      *                value and typecode for the output argument added

  211.      */

  212. 

  213.     public abstract Any add_named_out_arg(String name);

  214. 

  215.     /**

  216.      * Sets the typecode for the return

  217.      * value of the method.

  218.      *

  219.      * @param tc			the <code>TypeCode</code> object containing type information

  220.      *                   for the return value

  221.      */

  222. 

  223.     public abstract void set_return_type(TypeCode tc);

  224. 

  225.     /**

  226.      * Returns the <code>Any</code> object that contains the value for the

  227.      * result of the method.

  228.      *

  229.      * @return			an <code>Any</code> object containing the value and

  230.      *                   typecode for the return value

  231.      */

  232. 

  233.     public abstract Any return_value();

  234. 

  235.     /**

  236.      * Makes a synchronous invocation using the

  237.      * information in the <code>Request</code> object. Exception information is

  238.      * placed into the <code>Request</code> object's environment object.

  239.      */

  240. 

  241.     public abstract void invoke();

  242. 

  243.     /**

  244.      * Makes a oneway invocation on the

  245.      * request. In other words, it does not expect or wait for a

  246.      * response. Note that this can be used even if the operation was

  247.      * not declared as oneway in the IDL declaration. No response or

  248.      * exception information is returned.

  249.      */

  250. 

  251.     public abstract void send_oneway();

  252. 

  253.     /**

  254.      * Makes an asynchronous invocation on

  255.      * the request. In other words, it does not wait for a response before it

  256.      * returns to the user. The user can then later use the methods

  257.      * <code>poll_response</code> and <code>get_response</code> to get

  258.      * the result or exception information for the invocation.

  259.      */

  260. 

  261.     public abstract void send_deferred();

  262. 

  263.     /**

  264.      * Allows the user to determine

  265.      * whether a response has been received for the invocation triggered

  266.      * earlier with the <code>send_deferred</code> method.

  267.      *

  268.      * @return		<code>true</code> if the method response has

  269.      * 				been received; <code>false</code> otherwise

  270.      */

  271. 

  272.     public abstract boolean poll_response();

  273. 

  274.     /**

  275.      * Allows the user to access the

  276.      * response for the invocation triggered earlier with the

  277.      * <code>send_deferred</code> method.

  278.      *

  279.      * @exception WrongTransaction  if the method <code>get_response</code> was invoked

  280.      * from a different transaction's scope than the one from which the

  281.      * request was originally sent. See the OMG Transaction Service specification

  282.      * for details.

  283.      */

  284. 

  285.     public abstract void get_response() throws WrongTransaction;

  286. 

  287. };