Request.java revision 608:7e06bf1dcb09
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 26package 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 67public 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}; 302