1. /*

  2.  * @(#)ServerRequest.java	1.31 04/05/18

  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.  * An object that captures the explicit state of a request

  12.  * for the Dynamic Skeleton Interface (DSI).  This class, the

  13.  * cornerstone of the DSI, is analogous to the <code>Request</code>

  14.  * object in the DII.

  15.  * <P>

  16.  * The ORB is responsible for creating this embodiment of a request,

  17.  * and delivering it to a Dynamic Implementation Routine (DIR).

  18.  * A dynamic servant (a DIR) is created by implementing the

  19.  * <code>DynamicImplementation</code> class,

  20.  * which has a single <code>invoke</code> method.  This method accepts a

  21.  * <code>ServerRequest</code> object.

  22.  *

  23.  * The abstract class <code>ServerRequest</code> defines

  24.  * methods for accessing the

  25.  * method name, the arguments and the context of the request, as

  26.  * well as methods for setting the result of the request either as a

  27.  * return value or an exception. <p>

  28.  *

  29.  * A subtlety with accessing the arguments of the request is that the

  30.  * DIR needs to provide type information about the

  31.  * expected arguments, since there is no compiled information about

  32.  * these. This information is provided through an <code>NVList</code>,

  33.  * which is a list of <code>NamedValue</code> objects.

  34.  * Each <code>NamedValue</code> object

  35.  * contains an <code>Any</code> object, which in turn

  36.  * has a <code>TypeCode</code> object representing the type

  37.  * of the argument. <p>

  38.  *

  39.  * Similarly, type information needs to be provided for the response,

  40.  * for either the expected result or for an exception, so the methods

  41.  * <code>result</code> and <code>except</code> take an <code>Any</code>

  42.  * object as a parameter. <p>

  43.  *

  44.  * @see org.omg.CORBA.DynamicImplementation

  45.  * @see org.omg.CORBA.NVList

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

  47.  *

  48.  * @version 1.15 09/09/97

  49.  */

  50. 

  51. public abstract class ServerRequest {

  52. 

  53.     /**

  54.      * Retrieves the name of the operation being

  55.      * invoked. According to OMG IDL's rules, these names must be unique

  56.      * among all operations supported by this object's "most-derived"

  57.      * interface. Note that the operation names for getting and setting

  58.      * attributes are <code>_get_<attribute_name></code>

  59.      * and <code>_set_<attribute_name></code>,

  60.      * respectively.

  61.      *

  62.      * @return     the name of the operation to be invoked

  63.      * @deprecated use operation()

  64.      */

  65.     @Deprecated

  66.     public String op_name()

  67.     {

  68.         return operation();

  69.     }

  70. 

  71. 

  72.     /**

  73.      * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.

  74.      * <P>

  75.      * Retrieves the name of the operation being

  76.      * invoked. According to OMG IDL's rules, these names must be unique

  77.      * among all operations supported by this object's "most-derived"

  78.      * interface. Note that the operation names for getting and setting

  79.      * attributes are <code>_get_<attribute_name></code>

  80.      * and <code>_set_<attribute_name></code>,

  81.      * respectively.

  82.      *

  83.      * @return     the name of the operation to be invoked

  84.      * @see <a href="package-summary.html#unimpl"><code>CORBA</code>

  85.      *      package comments for unimplemented features</a>

  86.      */

  87.     public String operation()

  88.     {

  89.         throw new org.omg.CORBA.NO_IMPLEMENT();

  90.     }

  91. 

  92. 

  93.     /**

  94.      * Specifies method parameter types and retrieves "in" and "inout"

  95.      * argument values.

  96.      * <P>

  97.      * Note that this method is deprecated; use the method

  98.      * <code>arguments</code> in its place.

  99.      * <P>

  100.      * Unless it calls the method <code>set_exception</code>,

  101.      * the DIR must call this method exactly once, even if the

  102.      * method signature contains no parameters. Once the method <code>

  103.      * arguments</code> or <code>set_exception</code>

  104.      * has been called, calling <code>arguments</code> on the same

  105.      * <code>ServerRequest</code> object 

  106.      * will result in a <code>BAD_INV_ORDER</code> system exception.

  107.      * The DIR must pass in to the method <code>arguments</code>

  108.      * an NVList initialized with TypeCodes and Flags

  109.      * describing the parameter types for the operation, in the order in which

  110.      * they appear in the IDL specification (left to right). A

  111.      * potentially-different NVList will be returned from

  112.      * <code>arguments</code>, with the

  113.      * "in" and "inout" argument values supplied. If it does not call

  114.      * the method <code>set_exception</code>,

  115.      * the DIR must supply the returned NVList with return

  116.      * values for any "out" arguments before returning, and may also change

  117.      * the return values for any "inout" arguments.

  118.      *

  119.      * @param params		the arguments of the method, in the

  120.      *				form of an <code>NVList</code> object

  121.      * @deprecated use the method <code>arguments</code>

  122.      */

  123.     @Deprecated

  124.     public void params(NVList params)

  125.     {

  126.         arguments(params);

  127.     }

  128. 

  129.     /**

  130.      * Specifies method parameter types and retrieves "in" and "inout"

  131.      * argument values.

  132.      * Unless it calls the method <code>set_exception</code>,

  133.      * the DIR must call this method exactly once, even if the

  134.      * method signature contains no parameters. Once the method <code>

  135.      * arguments</code> or <code>set_exception</code>

  136.      * has been called, calling <code>arguments</code> on the same

  137.      * <code>ServerRequest</code> object 

  138.      * will result in a <code>BAD_INV_ORDER</code> system exception.

  139.      * The DIR must pass in to the method <code>arguments</code>

  140.      * an NVList initialized with TypeCodes and Flags

  141.      * describing the parameter types for the operation, in the order in which

  142.      * they appear in the IDL specification (left to right). A

  143.      * potentially-different NVList will be returned from

  144.      * <code>arguments</code>, with the

  145.      * "in" and "inout" argument values supplied. If it does not call

  146.      * the method <code>set_exception</code>,

  147.      * the DIR must supply the returned NVList with return

  148.      * values for any "out" arguments before returning, and it may also change

  149.      * the return values for any "inout" arguments.

  150.      *

  151.      * @param args              the arguments of the method, in the

  152.      *                            form of an NVList

  153.      * @see <a href="package-summary.html#unimpl"><code>CORBA</code>

  154.      *      package comments for unimplemented features</a>

  155.      */

  156.     public void arguments(org.omg.CORBA.NVList args) {

  157.         throw new org.omg.CORBA.NO_IMPLEMENT();

  158.     }

  159. 

  160. 

  161. 

  162.     /**

  163.      * Specifies any return value for the call. 

  164.      * <P>

  165.      * Note that this method is deprecated; use the method

  166.      * <code>set_result</code> in its place.

  167.      * <P>

  168.      * Unless the method 

  169.      * <code>set_exception</code> is called, if the invoked method

  170.      * has a non-void result type, the method <code>set_result</code>

  171.      * must be called exactly once before the DIR returns.

  172.      * If the operation has a void result type, the method 

  173.      * <code>set_result</code> may optionally be

  174.      * called once with an <code>Any</code> object whose type is 

  175.      * <code>tk_void</code>. Calling the method <code>set_result</code> before

  176.      * the method <code>arguments</code> has been called or after

  177.      * the method <code>set_result</code> or <code>set_exception</code> has been

  178.      * called will result in a BAD_INV_ORDER exception. Calling the method

  179.      * <code>set_result</code> without having previously called

  180.      * the method <code>ctx</code> when the IDL operation contains a

  181.      * context expression, or when the NVList passed to arguments did not

  182.      * describe all parameters passed by the client, may result in a MARSHAL

  183.      * system exception.

  184.      *

  185.      * @param any an <code>Any</code> object containing the return value to be set

  186.      * @deprecated use the method <code>set_result</code>

  187.      */

  188.     @Deprecated

  189.     public void result(Any any)

  190.     {

  191.         set_result(any);

  192.     }

  193. 

  194. 

  195.     /**

  196.      * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.

  197.      * <P>

  198.      * Specifies any return value for the call. Unless the method 

  199.      * <code>set_exception</code> is called, if the invoked method

  200.      * has a non-void result type, the method <code>set_result</code>

  201.      * must be called exactly once before the DIR returns.

  202.      * If the operation has a void result type, the method 

  203.      * <code>set_result</code> may optionally be

  204.      * called once with an <code>Any</code> object whose type is 

  205.      * <code>tk_void</code>. Calling the method <code>set_result</code> before

  206.      * the method <code>arguments</code> has been called or after

  207.      * the method <code>set_result</code> or <code>set_exception</code> has been

  208.      * called will result in a BAD_INV_ORDER exception. Calling the method

  209.      * <code>set_result</code> without having previously called

  210.      * the method <code>ctx</code> when the IDL operation contains a

  211.      * context expression, or when the NVList passed to arguments did not

  212.      * describe all parameters passed by the client, may result in a MARSHAL

  213.      * system exception.

  214.      *

  215.      * @param any an <code>Any</code> object containing the return value to be set

  216.      * @see <a href="package-summary.html#unimpl"><code>CORBA</code>

  217.      *      package comments for unimplemented features</a>

  218.      */

  219.     public void set_result(org.omg.CORBA.Any any)

  220.     {

  221.         throw new org.omg.CORBA.NO_IMPLEMENT();

  222.     }

  223. 

  224. 

  225.     /**

  226.      * The DIR may call set_exception at any time to return an exception to the

  227.      * client. The Any passed to set_exception must contain either a system

  228.      * exception or a user exception specified in the raises expression

  229.      * of the invoked operation's IDL definition. Passing in an Any that does

  230.      * not

  231.      * contain an exception will result in a BAD_PARAM system exception. Passing

  232.      * in an unlisted user exception will result in either the DIR receiving a

  233.      * BAD_PARAM system exception or in the client receiving an

  234.      * UNKNOWN_EXCEPTION system exception.

  235.      *

  236.      * @param any	the <code>Any</code> object containing the exception

  237.      * @deprecated use set_exception()

  238.      */

  239.     @Deprecated

  240.     public void except(Any any)

  241.     {

  242.         set_exception(any);

  243.     }

  244. 

  245.     /**

  246.      * Throws an <code>org.omg.CORBA.NO_IMPLEMENT</code> exception.

  247.      * <P>

  248.      * Returns the given exception to the client.  This method 

  249.      * is invoked by the DIR, which may call it at any time.

  250.      * The <code>Any</code> object  passed to this method must

  251.      * contain either a system

  252.      * exception or one of the user exceptions specified in the 

  253.      * invoked operation's IDL definition. Passing in an

  254.      * <code>Any</code> object that does not contain an exception 

  255.      * will cause a BAD_PARAM system exception to be thrown. Passing

  256.      * in an unlisted user exception will result in either the DIR receiving a

  257.      * BAD_PARAM system exception or in the client receiving an

  258.      * UNKNOWN_EXCEPTION system exception.

  259.      *

  260.      * @param any	the <code>Any</code> object containing the exception

  261.      * @exception BAD_PARAM if the given <code>Any</code> object does not

  262.      *                      contain an exception or the exception is an

  263.      *                      unlisted user exception

  264.      * @exception UNKNOWN_EXCEPTION if the given exception is an unlisted

  265.      *                              user exception and the DIR did not

  266.      *                              receive a BAD_PARAM exception

  267.      * @see <a href="package-summary.html#unimpl"><code>CORBA</code>

  268.      *      package comments for unimplemented features</a>

  269.      */

  270.     public void set_exception(Any any)

  271.     {

  272.         throw new org.omg.CORBA.NO_IMPLEMENT();

  273.     }

  274. 

  275.     /**

  276.      * Returns the context information specified in IDL for the operation

  277.      * when the operation is not an attribute access and the operation's IDL

  278.      * definition contains a context expression; otherwise it returns

  279.      * a nil <code>Context</code> reference. Calling the method

  280.      * <code>ctx</code> before the method <code>arguments</code> has

  281.      * been called or after the method <code>ctx</code>,

  282.      * <code>set_result</code>, or <code>set_exception</code>

  283.      * has been called will result in a

  284.      * BAD_INV_ORDER system exception.

  285.      *

  286.      * @return			the context object that is to be used

  287.      *				to resolve any context strings whose

  288.      *				values need to be sent with the invocation.

  289.      * @exception BAD_INV_ORDER if (1) the method <code>ctx</code> is called

  290.      *                          before the method <code>arguments</code> or

  291.      *                          (2) the method <code>ctx</code> is called

  292.      *                          after calling <code>set_result</code> or

  293.      *                          <code>set_exception</code>

  294.      */

  295.     public abstract Context ctx();

  296. 

  297. }