Request


1   /*
2    * @(#)Request.java 1.25 03/12/19
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 containing the information necessary for
12   * invoking a method.  This class is
13   * the cornerstone of the ORB Dynamic
14   * Invocation Interface (DII), which allows dynamic creation and
15   * invocation of requests.
16   * A server cannot tell the difference between a client
17   * invocation using a client stub and a request using the DII.
18   * <P>
19   * A <code>Request</code> object consists of:
20   * <UL>
21   * <LI>the name of the operation to be invoked
22   * <LI>an <code>NVList</code> containing arguments for the operation.<BR>
23   * Each item in the list is a <code>NamedValue</code> object, which has three
24   * parts:
25   *  <OL>
26   *    <LI>the name of the argument
27   *    <LI>the value of the argument (as an <code>Any</code> object)
28   *    <LI>the argument mode flag indicating whether the argument is
29   *        for input, output, or both
30   *  </OL>
31   * </UL>
32   * <P>
33   * <code>Request</code> objects may also contain additional information,
34   * depending on how an operation was defined in the original IDL
35   * interface definition.  For example, where appropriate, they may contain
36   * a <code>NamedValue</code> object to hold the return value or exception,
37   * a context, a list of possible exceptions, and a list of
38   * context strings that need to be resolved.
39   * <P>
40   * New <code>Request</code> objects are created using one of the
41   * <code>create_request</code> methods in the <code>Object</code> class.
42   * In other words, a <code>create_request</code> method is performed on the
43   * object which is to be invoked.
44   *
45   * @see org.omg.CORBA.NamedValue
46   *
47   * @version 1.13 09/09/97
48   */
49  
50  public abstract class Request {
51  
52      /**
53       * Retrieves the the target object reference.
54       *
55       * @return          the object reference that points to the
56       *                    object implementation for the method
57       *                    to be invoked
58       */
59  
60      public abstract org.omg.CORBA.Object   target();
61  
62      /**
63       * Retrieves the name of the method to be invoked.
64       *
65       * @return          the name of the method to be invoked
66       */
67  
68      public abstract String   operation();
69  
70      /**
71       * Retrieves the <code>NVList</code> object containing the arguments
72       * to the method being invoked.  The elements in the list are
73       * <code>NamedValue</code> objects, with each one describing an argument
74       * to the method.
75       *
76       * @return  the <code>NVList</code> object containing the arguments
77       *          for the method
78       *
79       */
80  
81      public abstract NVList   arguments();
82  
83      /**
84       * Retrieves the <code>NamedValue</code> object containing the return
85       * value for the method.
86       *
87       * @return      the <code>NamedValue</code> object containing the result
88       *              of the method
89       */
90  
91      public abstract NamedValue   result();
92  
93      /**
94       * Retrieves the <code>Environment</code> object for this request.
95       * It contains the exception that the method being invoked has
96       * thrown (after the invocation returns).
97       *
98       *
99       * @return  the <code>Environment</code> object for this request
100      */
101 
102     public abstract Environment   env();
103 
104     /**
105      * Retrieves the <code>ExceptionList</code> object for this request.
106      * This list contains <code>TypeCode</code> objects describing the
107      * exceptions that may be thrown by the method being invoked.
108      *
109      * @return  the <code>ExceptionList</code> object describing the exceptions
110      *            that may be thrown by the method being invoked
111      */
112 
113     public abstract ExceptionList   exceptions();
114 
115     /**
116      * Retrieves the <code>ContextList</code> object for this request.
117      * This list contains context <code>String</code>s that need to
118      * be resolved and sent with the invocation.
119      *
120      *
121      * @return          the list of context strings whose values
122      *              need to be resolved and sent with the
123      *              invocation.
124      */
125 
126     public abstract ContextList   contexts();
127 
128     /**
129      * Retrieves the <code>Context</code> object for this request.
130      * This is a list of properties giving information about the
131      * client, the environment, or the circumstances of this request.
132      *
133      * @return      the <code>Context</code> object that is to be used
134      *              to resolve any context strings whose
135      *              values need to be sent with the invocation
136      */
137 
138     public abstract Context   ctx();
139 
140     /**
141      * Sets this request's <code>Context</code> object to the one given.
142      *
143      * @param c     the new <code>Context</code> object to be used for
144      *              resolving context strings
145      */
146 
147     public abstract void ctx(Context   c);
148 
149 
150     /**
151      * Creates an input argument and adds it to this <code>Request</code>
152      * object.
153      *
154      * @return      an <code>Any</code> object that contains the
155      *                value and typecode for the input argument added
156      */
157 
158     public abstract Any   add_in_arg();
159 
160     /**
161      * Creates an input argument with the given name and adds it to
162      * this <code>Request</code> object.
163      *
164      * @param name      the name of the argument being added
165      * @return      an <code>Any</code> object that contains the
166      *                value and typecode for the input argument added
167      */
168 
169     public abstract Any   add_named_in_arg(String   name);
170 
171     /**
172      * Adds an input/output argument to this <code>Request</code> object.
173      *
174      * @return      an <code>Any</code> object that contains the
175      *                value and typecode for the input/output argument added
176      */
177 
178     public abstract Any   add_inout_arg();
179 
180     /**
181      * Adds an input/output argument with the given name to this
182      * <code>Request</code> object.
183      *
184      * @param name      the name of the argument being added
185      * @return      an <code>Any</code> object that contains the
186      *                value and typecode for the input/output argument added
187      */
188 
189     public abstract Any   add_named_inout_arg(String   name);
190 
191 
192     /**
193      * Adds an output argument to this <code>Request</code> object.
194      *
195      * @return      an <code>Any</code> object that contains the
196      *                value and typecode for the output argument added
197      */
198 
199     public abstract Any   add_out_arg();
200 
201     /**
202      * Adds an output argument with the given name to this
203      * <code>Request</code> object.
204      *
205      * @param name      the name of the argument being added
206      * @return      an <code>Any</code> object that contains the
207      *                value and typecode for the output argument added
208      */
209 
210     public abstract Any   add_named_out_arg(String   name);
211 
212     /**
213      * Sets the typecode for the return
214      * value of the method.
215      *
216      * @param tc            the <code>TypeCode</code> object containing type information
217      *                   for the return value
218      */
219 
220     public abstract void set_return_type(TypeCode   tc);
221 
222     /**
223      * Returns the <code>Any</code> object that contains the value for the
224      * result of the method.
225      *
226      * @return          an <code>Any</code> object containing the value and
227      *                   typecode for the return value
228      */
229 
230     public abstract Any   return_value();
231 
232     /**
233      * Makes a synchronous invocation using the
234      * information in the <code>Request</code> object. Exception information is
235      * placed into the <code>Request</code> object's environment object.
236      */
237 
238     public abstract void invoke();
239 
240     /**
241      * Makes a oneway invocation on the
242      * request. In other words, it does not expect or wait for a
243      * response. Note that this can be used even if the operation was
244      * not declared as oneway in the IDL declaration. No response or
245      * exception information is returned.
246      */
247 
248     public abstract void send_oneway();
249 
250     /**
251      * Makes an asynchronous invocation on
252      * the request. In other words, it does not wait for a response before it
253      * returns to the user. The user can then later use the methods
254      * <code>poll_response</code> and <code>get_response</code> to get
255      * the result or exception information for the invocation.
256      */
257 
258     public abstract void send_deferred();
259 
260     /**
261      * Allows the user to determine
262      * whether a response has been received for the invocation triggered
263      * earlier with the <code>send_deferred</code> method.
264      *
265      * @return      <code>true</code> if the method response has
266      *              been received; <code>false</code> otherwise
267      */
268 
269     public abstract boolean poll_response();
270 
271     /**
272      * Allows the user to access the
273      * response for the invocation triggered earlier with the
274      * <code>send_deferred</code> method.
275      *
276      * @exception WrongTransaction  if the method <code>get_response</code> was invoked
277      * from a different transaction's scope than the one from which the
278      * request was originally sent. See the OMG Transaction Service specification
279      * for details.
280      */
281 
282     public abstract void get_response() throws WrongTransaction  ;
283 
284 };
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags