001: /*
002: * Copyright 1996-1999 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package org.omg.CORBA;
027:
028: /**
029: * An object containing the information necessary for
030: * invoking a method. This class is
031: * the cornerstone of the ORB Dynamic
032: * Invocation Interface (DII), which allows dynamic creation and
033: * invocation of requests.
034: * A server cannot tell the difference between a client
035: * invocation using a client stub and a request using the DII.
036: * <P>
037: * A <code>Request</code> object consists of:
038: * <UL>
039: * <LI>the name of the operation to be invoked
040: * <LI>an <code>NVList</code> containing arguments for the operation.<BR>
041: * Each item in the list is a <code>NamedValue</code> object, which has three
042: * parts:
043: * <OL>
044: * <LI>the name of the argument
045: * <LI>the value of the argument (as an <code>Any</code> object)
046: * <LI>the argument mode flag indicating whether the argument is
047: * for input, output, or both
048: * </OL>
049: * </UL>
050: * <P>
051: * <code>Request</code> objects may also contain additional information,
052: * depending on how an operation was defined in the original IDL
053: * interface definition. For example, where appropriate, they may contain
054: * a <code>NamedValue</code> object to hold the return value or exception,
055: * a context, a list of possible exceptions, and a list of
056: * context strings that need to be resolved.
057: * <P>
058: * New <code>Request</code> objects are created using one of the
059: * <code>create_request</code> methods in the <code>Object</code> class.
060: * In other words, a <code>create_request</code> method is performed on the
061: * object which is to be invoked.
062: *
063: * @see org.omg.CORBA.NamedValue
064: *
065: * @version 1.13 09/09/97
066: */
067:
068: public abstract class Request {
069:
070: /**
071: * Retrieves the the target object reference.
072: *
073: * @return the object reference that points to the
074: * object implementation for the method
075: * to be invoked
076: */
077:
078: public abstract org.omg.CORBA.Object target();
079:
080: /**
081: * Retrieves the name of the method to be invoked.
082: *
083: * @return the name of the method to be invoked
084: */
085:
086: public abstract String operation();
087:
088: /**
089: * Retrieves the <code>NVList</code> object containing the arguments
090: * to the method being invoked. The elements in the list are
091: * <code>NamedValue</code> objects, with each one describing an argument
092: * to the method.
093: *
094: * @return the <code>NVList</code> object containing the arguments
095: * for the method
096: *
097: */
098:
099: public abstract NVList arguments();
100:
101: /**
102: * Retrieves the <code>NamedValue</code> object containing the return
103: * value for the method.
104: *
105: * @return the <code>NamedValue</code> object containing the result
106: * of the method
107: */
108:
109: public abstract NamedValue result();
110:
111: /**
112: * Retrieves the <code>Environment</code> object for this request.
113: * It contains the exception that the method being invoked has
114: * thrown (after the invocation returns).
115: *
116: *
117: * @return the <code>Environment</code> object for this request
118: */
119:
120: public abstract Environment env();
121:
122: /**
123: * Retrieves the <code>ExceptionList</code> object for this request.
124: * This list contains <code>TypeCode</code> objects describing the
125: * exceptions that may be thrown by the method being invoked.
126: *
127: * @return the <code>ExceptionList</code> object describing the exceptions
128: * that may be thrown by the method being invoked
129: */
130:
131: public abstract ExceptionList exceptions();
132:
133: /**
134: * Retrieves the <code>ContextList</code> object for this request.
135: * This list contains context <code>String</code>s that need to
136: * be resolved and sent with the invocation.
137: *
138: *
139: * @return the list of context strings whose values
140: * need to be resolved and sent with the
141: * invocation.
142: */
143:
144: public abstract ContextList contexts();
145:
146: /**
147: * Retrieves the <code>Context</code> object for this request.
148: * This is a list of properties giving information about the
149: * client, the environment, or the circumstances of this request.
150: *
151: * @return the <code>Context</code> object that is to be used
152: * to resolve any context strings whose
153: * values need to be sent with the invocation
154: */
155:
156: public abstract Context ctx();
157:
158: /**
159: * Sets this request's <code>Context</code> object to the one given.
160: *
161: * @param c the new <code>Context</code> object to be used for
162: * resolving context strings
163: */
164:
165: public abstract void ctx(Context c);
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: * Adds an output argument to this <code>Request</code> object.
210: *
211: * @return an <code>Any</code> object that contains the
212: * value and typecode for the output argument added
213: */
214:
215: public abstract Any add_out_arg();
216:
217: /**
218: * Adds an output argument with the given name to this
219: * <code>Request</code> object.
220: *
221: * @param name the name of the argument being added
222: * @return an <code>Any</code> object that contains the
223: * value and typecode for the output argument added
224: */
225:
226: public abstract Any add_named_out_arg(String name);
227:
228: /**
229: * Sets the typecode for the return
230: * value of the method.
231: *
232: * @param tc the <code>TypeCode</code> object containing type information
233: * for the return value
234: */
235:
236: public abstract void set_return_type(TypeCode tc);
237:
238: /**
239: * Returns the <code>Any</code> object that contains the value for the
240: * result of the method.
241: *
242: * @return an <code>Any</code> object containing the value and
243: * typecode for the return value
244: */
245:
246: public abstract Any return_value();
247:
248: /**
249: * Makes a synchronous invocation using the
250: * information in the <code>Request</code> object. Exception information is
251: * placed into the <code>Request</code> object's environment object.
252: */
253:
254: public abstract void invoke();
255:
256: /**
257: * Makes a oneway invocation on the
258: * request. In other words, it does not expect or wait for a
259: * response. Note that this can be used even if the operation was
260: * not declared as oneway in the IDL declaration. No response or
261: * exception information is returned.
262: */
263:
264: public abstract void send_oneway();
265:
266: /**
267: * Makes an asynchronous invocation on
268: * the request. In other words, it does not wait for a response before it
269: * returns to the user. The user can then later use the methods
270: * <code>poll_response</code> and <code>get_response</code> to get
271: * the result or exception information for the invocation.
272: */
273:
274: public abstract void send_deferred();
275:
276: /**
277: * Allows the user to determine
278: * whether a response has been received for the invocation triggered
279: * earlier with the <code>send_deferred</code> method.
280: *
281: * @return <code>true</code> if the method response has
282: * been received; <code>false</code> otherwise
283: */
284:
285: public abstract boolean poll_response();
286:
287: /**
288: * Allows the user to access the
289: * response for the invocation triggered earlier with the
290: * <code>send_deferred</code> method.
291: *
292: * @exception WrongTransaction if the method <code>get_response</code> was invoked
293: * from a different transaction's scope than the one from which the
294: * request was originally sent. See the OMG Transaction Service specification
295: * for details.
296: */
297:
298: public abstract void get_response() throws WrongTransaction;
299:
300: };
|