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