1 /*
   2  * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package org.omg.CORBA;
  27 
  28 /**
  29  * An object containing the information necessary for
  30  * invoking a method.  This class is
  31  * the cornerstone of the ORB Dynamic
  32  * Invocation Interface (DII), which allows dynamic creation and
  33  * invocation of requests.
  34  * A server cannot tell the difference between a client
  35  * invocation using a client stub and a request using the DII.
  36  * <P>
  37  * A <code>Request</code> object consists of:
  38  * <UL>
  39  * <LI>the name of the operation to be invoked
  40  * <LI>an <code>NVList</code> containing arguments for the operation.<BR>
  41  * Each item in the list is a <code>NamedValue</code> object, which has three
  42  * parts:
  43  *  <OL>
  44  *    <LI>the name of the argument
  45  *    <LI>the value of the argument (as an <code>Any</code> object)
  46  *    <LI>the argument mode flag indicating whether the argument is
  47  *        for input, output, or both
  48  *  </OL>
  49  * </UL>
  50  * <P>
  51  * <code>Request</code> objects may also contain additional information,
  52  * depending on how an operation was defined in the original IDL
  53  * interface definition.  For example, where appropriate, they may contain
  54  * a <code>NamedValue</code> object to hold the return value or exception,
  55  * a context, a list of possible exceptions, and a list of
  56  * context strings that need to be resolved.
  57  * <P>
  58  * New <code>Request</code> objects are created using one of the
  59  * <code>create_request</code> methods in the <code>Object</code> class.
  60  * In other words, a <code>create_request</code> method is performed on the
  61  * object which is to be invoked.
  62  *
  63  * @see org.omg.CORBA.NamedValue
  64  *
  65  */
  66 
  67 public abstract class Request {
  68 
  69     /**
  70      * Retrieves the the target object reference.
  71      *
  72      * @return                  the object reference that points to the
  73      *                    object implementation for the method
  74      *                    to be invoked
  75      */
  76 
  77     public abstract org.omg.CORBA.Object target();
  78 
  79     /**
  80      * Retrieves the name of the method to be invoked.
  81      *
  82      * @return                  the name of the method to be invoked
  83      */
  84 
  85     public abstract String operation();
  86 
  87     /**
  88      * Retrieves the <code>NVList</code> object containing the arguments
  89      * to the method being invoked.  The elements in the list are
  90      * <code>NamedValue</code> objects, with each one describing an argument
  91      * to the method.
  92      *
  93      * @return  the <code>NVList</code> object containing the arguments
  94      *                  for the method
  95      *
  96      */
  97 
  98     public abstract NVList arguments();
  99 
 100     /**
 101      * Retrieves the <code>NamedValue</code> object containing the return
 102      * value for the method.
 103      *
 104      * @return          the <code>NamedValue</code> object containing the result
 105      *                          of the method
 106      */
 107 
 108     public abstract NamedValue result();
 109 
 110     /**
 111      * Retrieves the <code>Environment</code> object for this request.
 112      * It contains the exception that the method being invoked has
 113      * thrown (after the invocation returns).
 114      *
 115      *
 116      * @return  the <code>Environment</code> object for this request
 117      */
 118 
 119     public abstract Environment env();
 120 
 121     /**
 122      * Retrieves the <code>ExceptionList</code> object for this request.
 123      * This list contains <code>TypeCode</code> objects describing the
 124      * exceptions that may be thrown by the method being invoked.
 125      *
 126      * @return  the <code>ExceptionList</code> object describing the exceptions
 127      *            that may be thrown by the method being invoked
 128      */
 129 
 130     public abstract ExceptionList exceptions();
 131 
 132     /**
 133      * Retrieves the <code>ContextList</code> object for this request.
 134      * This list contains context <code>String</code>s that need to
 135      * be resolved and sent with the invocation.
 136      *
 137      *
 138      * @return                  the list of context strings whose values
 139      *                          need to be resolved and sent with the
 140      *                          invocation.
 141      */
 142 
 143     public abstract ContextList contexts();
 144 
 145     /**
 146      * Retrieves the <code>Context</code> object for this request.
 147      * This is a list of properties giving information about the
 148      * client, the environment, or the circumstances of this request.
 149      *
 150      * @return          the <code>Context</code> object that is to be used
 151      *                          to resolve any context strings whose
 152      *                          values need to be sent with the invocation
 153      */
 154 
 155     public abstract Context ctx();
 156 
 157     /**
 158      * Sets this request's <code>Context</code> object to the one given.
 159      *
 160      * @param c         the new <code>Context</code> object to be used for
 161      *                          resolving context strings
 162      */
 163 
 164     public abstract void ctx(Context c);
 165 
 166 
 167     /**
 168      * Creates an input argument and adds it to this <code>Request</code>
 169      * object.
 170      *
 171      * @return          an <code>Any</code> object that contains the
 172      *                value and typecode for the input argument added
 173      */
 174 
 175     public abstract Any add_in_arg();
 176 
 177     /**
 178      * Creates an input argument with the given name and adds it to
 179      * this <code>Request</code> object.
 180      *
 181      * @param name              the name of the argument being added
 182      * @return          an <code>Any</code> object that contains the
 183      *                value and typecode for the input argument added
 184      */
 185 
 186     public abstract Any add_named_in_arg(String name);
 187 
 188     /**
 189      * Adds an input/output argument to this <code>Request</code> object.
 190      *
 191      * @return          an <code>Any</code> object that contains the
 192      *                value and typecode for the input/output argument added
 193      */
 194 
 195     public abstract Any add_inout_arg();
 196 
 197     /**
 198      * Adds an input/output argument with the given name to this
 199      * <code>Request</code> object.
 200      *
 201      * @param name              the name of the argument being added
 202      * @return          an <code>Any</code> object that contains the
 203      *                value and typecode for the input/output argument added
 204      */
 205 
 206     public abstract Any add_named_inout_arg(String name);
 207 
 208 
 209     /**
 210      * Adds an output argument to this <code>Request</code> object.
 211      *
 212      * @return          an <code>Any</code> object that contains the
 213      *                value and typecode for the output argument added
 214      */
 215 
 216     public abstract Any add_out_arg();
 217 
 218     /**
 219      * Adds an output argument with the given name to this
 220      * <code>Request</code> object.
 221      *
 222      * @param name              the name of the argument being added
 223      * @return          an <code>Any</code> object that contains the
 224      *                value and typecode for the output argument added
 225      */
 226 
 227     public abstract Any add_named_out_arg(String name);
 228 
 229     /**
 230      * Sets the typecode for the return
 231      * value of the method.
 232      *
 233      * @param tc                        the <code>TypeCode</code> object containing type information
 234      *                   for the return value
 235      */
 236 
 237     public abstract void set_return_type(TypeCode tc);
 238 
 239     /**
 240      * Returns the <code>Any</code> object that contains the value for the
 241      * result of the method.
 242      *
 243      * @return                  an <code>Any</code> object containing the value and
 244      *                   typecode for the return value
 245      */
 246 
 247     public abstract Any return_value();
 248 
 249     /**
 250      * Makes a synchronous invocation using the
 251      * information in the <code>Request</code> object. Exception information is
 252      * placed into the <code>Request</code> object's environment object.
 253      */
 254 
 255     public abstract void invoke();
 256 
 257     /**
 258      * Makes a oneway invocation on the
 259      * request. In other words, it does not expect or wait for a
 260      * response. Note that this can be used even if the operation was
 261      * not declared as oneway in the IDL declaration. No response or
 262      * exception information is returned.
 263      */
 264 
 265     public abstract void send_oneway();
 266 
 267     /**
 268      * Makes an asynchronous invocation on
 269      * the request. In other words, it does not wait for a response before it
 270      * returns to the user. The user can then later use the methods
 271      * <code>poll_response</code> and <code>get_response</code> to get
 272      * the result or exception information for the invocation.
 273      */
 274 
 275     public abstract void send_deferred();
 276 
 277     /**
 278      * Allows the user to determine
 279      * whether a response has been received for the invocation triggered
 280      * earlier with the <code>send_deferred</code> method.
 281      *
 282      * @return          <code>true</code> if the method response has
 283      *                          been received; <code>false</code> otherwise
 284      */
 285 
 286     public abstract boolean poll_response();
 287 
 288     /**
 289      * Allows the user to access the
 290      * response for the invocation triggered earlier with the
 291      * <code>send_deferred</code> method.
 292      *
 293      * @exception WrongTransaction  if the method <code>get_response</code> was invoked
 294      * from a different transaction's scope than the one from which the
 295      * request was originally sent. See the OMG Transaction Service specification
 296      * for details.
 297      */
 298 
 299     public abstract void get_response() throws WrongTransaction;
 300 
 301 };