1. /*
  2. * @(#)Delegate.java 1.37 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.portable;
  8. import org.omg.CORBA.Request;
  9. import org.omg.CORBA.NamedValue;
  10. import org.omg.CORBA.NVList;
  11. import org.omg.CORBA.Context;
  12. import org.omg.CORBA.ContextList;
  13. import org.omg.CORBA.ExceptionList;
  14. import org.omg.CORBA.TypeCode;
  15. import org.omg.CORBA.SystemException;
  16. /**
  17. * Specifies a portable API for ORB-vendor-specific
  18. * implementation of the org.omg.CORBA.Object methods.
  19. *
  20. * Each stub (proxy) contains a delegate
  21. * object, to which all org.omg.CORBA.Object methods are forwarded.
  22. * This allows a stub generated by one vendor's ORB to work with the delegate
  23. * from another vendor's ORB.
  24. *
  25. * @see org.omg.CORBA.Object
  26. * @author OMG
  27. * @version 1.37 12/19/03
  28. */
  29. public abstract class Delegate {
  30. /**
  31. * Return an InterfaceDef for the object reference provided.
  32. * @param self The object reference whose InterfaceDef needs to be returned
  33. * @return the InterfaceDef
  34. */
  35. public abstract org.omg.CORBA.Object get_interface_def(
  36. org.omg.CORBA.Object self);
  37. /**
  38. * Returns a duplicate of the object reference provided.
  39. * @param obj The object reference whose duplicate needs to be returned
  40. * @return the duplicate object reference
  41. */
  42. public abstract org.omg.CORBA.Object duplicate(org.omg.CORBA.Object obj);
  43. /**
  44. * Releases resources associated with the object reference provided.
  45. * @param obj The object reference whose resources need to be released
  46. */
  47. public abstract void release(org.omg.CORBA.Object obj);
  48. /**
  49. * Checks if the object reference is an instance of the given interface.
  50. * @param obj The object reference to be checked.
  51. * @param repository_id The repository identifier of the interface
  52. * to check against.
  53. * @return true if the object reference supports the interface
  54. */
  55. public abstract boolean is_a(org.omg.CORBA.Object obj, String repository_id);
  56. /**
  57. * Determines whether the server object for the object reference has been
  58. * destroyed.
  59. * @param obj The object reference which delegated to this delegate.
  60. * @return true if the ORB knows authoritatively that the server object does
  61. * not exist, false otherwise
  62. */
  63. public abstract boolean non_existent(org.omg.CORBA.Object obj);
  64. /**
  65. * Determines if the two object references are equivalent.
  66. * @param obj The object reference which delegated to this delegate.
  67. * @param other The object reference to check equivalence against.
  68. * @return true if the objects are CORBA-equivalent.
  69. */
  70. public abstract boolean is_equivalent(org.omg.CORBA.Object obj,
  71. org.omg.CORBA.Object other);
  72. /**
  73. * Returns an ORB-internal identifier (hashcode) for this object reference.
  74. * @param obj The object reference which delegated to this delegate.
  75. * @param max specifies an upper bound on the hash value returned by
  76. * the ORB.
  77. * @return ORB-internal hash identifier for object reference
  78. */
  79. public abstract int hash(org.omg.CORBA.Object obj, int max);
  80. /**
  81. * Creates a Request instance for use in the Dynamic Invocation Interface.
  82. * @param obj The object reference which delegated to this delegate.
  83. * @param operation The name of the operation to be invoked using the
  84. * Request instance.
  85. * @return the created Request instance
  86. */
  87. public abstract Request request(org.omg.CORBA.Object obj, String operation);
  88. /**
  89. * Creates a Request instance for use in the Dynamic Invocation Interface.
  90. *
  91. * @param obj The object reference which delegated to this delegate.
  92. * @param ctx The context to be used.
  93. * @param operation The name of the operation to be
  94. * invoked.
  95. * @param arg_list The arguments to the operation in the
  96. * form of an NVList.
  97. * @param result A container for the result as a NamedValue.
  98. * @return The created Request object.
  99. *
  100. */
  101. public abstract Request create_request(org.omg.CORBA.Object obj,
  102. Context ctx,
  103. String operation,
  104. NVList arg_list,
  105. NamedValue result);
  106. /**
  107. * Creates a Request instance for use in the Dynamic Invocation Interface.
  108. *
  109. * @param obj The object reference which delegated to this delegate.
  110. * @param ctx The context to be used.
  111. * @param operation The name of the operation to be
  112. * invoked.
  113. * @param arg_list The arguments to the operation in the
  114. * form of an NVList.
  115. * @param result A container for the result as a NamedValue.
  116. * @param exclist A list of possible exceptions the
  117. * operation can throw.
  118. * @param ctxlist A list of context strings that need
  119. * to be resolved and sent with the
  120. * Request.
  121. * @return The created Request object.
  122. */
  123. public abstract Request create_request(org.omg.CORBA.Object obj,
  124. Context ctx,
  125. String operation,
  126. NVList arg_list,
  127. NamedValue result,
  128. ExceptionList exclist,
  129. ContextList ctxlist);
  130. /**
  131. * Provides a reference to the orb associated with its parameter.
  132. *
  133. * @param obj the object reference which delegated to this delegate.
  134. * @return the associated orb.
  135. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  136. * package comments for unimplemented features</a>
  137. */
  138. public org.omg.CORBA.ORB orb(org.omg.CORBA.Object obj) {
  139. throw new org.omg.CORBA.NO_IMPLEMENT();
  140. }
  141. /**
  142. * Returns the <code>Policy</code> object of the specified type
  143. * which applies to this object.
  144. *
  145. * @param self The object reference which delegated to this delegate.
  146. * @param policy_type The type of policy to be obtained.
  147. * @return A <code>Policy</code> object of the type specified by
  148. * the policy_type parameter.
  149. * @exception org.omg.CORBA.BAD_PARAM raised when the value of policy type
  150. * is not valid either because the specified type is not supported by this
  151. * ORB or because a policy object of that type is not associated with this
  152. * Object.
  153. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  154. * package comments for unimplemented features</a>
  155. */
  156. public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self,
  157. int policy_type) {
  158. throw new org.omg.CORBA.NO_IMPLEMENT();
  159. }
  160. /**
  161. * Retrieves the <code>DomainManagers</code> of this object.
  162. * This allows administration services (and applications) to retrieve the
  163. * domain managers, and hence the security and other policies applicable
  164. * to individual objects that are members of the domain.
  165. *
  166. * @param self The object reference which delegated to this delegate.
  167. * @return The list of immediately enclosing domain managers of this object.
  168. * At least one domain manager is always returned in the list since by
  169. * default each object is associated with at least one domain manager at
  170. * creation.
  171. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  172. * package comments for unimplemented features</a>
  173. */
  174. public org.omg.CORBA.DomainManager[] get_domain_managers(
  175. org.omg.CORBA.Object
  176. self) {
  177. throw new org.omg.CORBA.NO_IMPLEMENT();
  178. }
  179. /**
  180. * Associates the policies passed in
  181. * with a newly created object reference that it returns. Only certain
  182. * policies that pertain to the invocation of an operation at the client
  183. * end can be overridden using this operation. Attempts to override any
  184. * other policy will result in the raising of the CORBA::NO_PERMISSION
  185. * exception.
  186. *
  187. * @param self The object reference which delegated to this delegate.
  188. * @param policies A sequence of references to Policy objects.
  189. * @param set_add Indicates whether these policies should be added
  190. * onto any otheroverrides that already exist (ADD_OVERRIDE) in
  191. * the object reference, or they should be added to a clean
  192. * override free object reference (SET_OVERRIDE).
  193. * @return A new object reference with the new policies associated with it.
  194. *
  195. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  196. * package comments for unimplemented features</a>
  197. */
  198. public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self,
  199. org.omg.CORBA.Policy[] policies,
  200. org.omg.CORBA.SetOverrideType set_add) {
  201. throw new org.omg.CORBA.NO_IMPLEMENT();
  202. }
  203. /**
  204. * Returns true if this object is implemented by a local servant.
  205. *
  206. * @param self The object reference which delegated to this delegate.
  207. * @return true only if the servant incarnating this object is located in
  208. * this Java VM. Return false if the servant is not local or the ORB
  209. * does not support local stubs for this particular servant. The default
  210. * behavior of is_local() is to return false.
  211. */
  212. public boolean is_local(org.omg.CORBA.Object self) {
  213. return false;
  214. }
  215. /**
  216. * Returns a Java reference to the servant which should be used for this
  217. * request. servant_preinvoke() is invoked by a local stub.
  218. * If a ServantObject object is returned, then its servant field
  219. * has been set to an object of the expected type (Note: the object may
  220. * or may not be the actual servant instance). The local stub may cast
  221. * the servant field to the expected type, and then invoke the operation
  222. * directly. The ServantRequest object is valid for only one invocation,
  223. * and cannot be used for more than one invocation.
  224. *
  225. * @param self The object reference which delegated to this delegate.
  226. *
  227. * @param operation a string containing the operation name.
  228. * The operation name corresponds to the operation name as it would be
  229. * encoded in a GIOP request.
  230. *
  231. * @param expectedType a Class object representing the expected type of the servant.
  232. * The expected type is the Class object associated with the operations
  233. * class of the stub's interface (e.g. A stub for an interface Foo,
  234. * would pass the Class object for the FooOperations interface).
  235. *
  236. * @return a ServantObject object.
  237. * The method may return a null value if it does not wish to support
  238. * this optimization (e.g. due to security, transactions, etc).
  239. * The method must return null if the servant is not of the expected type.
  240. */
  241. public ServantObject servant_preinvoke(org.omg.CORBA.Object self,
  242. String operation,
  243. Class expectedType) {
  244. return null;
  245. }
  246. /**
  247. * servant_postinvoke() is invoked by the local stub after the operation
  248. * has been invoked on the local servant.
  249. * This method must be called if servant_preinvoke() returned a non-null
  250. * value, even if an exception was thrown by the servant's method.
  251. * For this reason, the call to servant_postinvoke() should be placed
  252. * in a Java finally clause.
  253. *
  254. * @param self The object reference which delegated to this delegate.
  255. *
  256. * @param servant the instance of the ServantObject returned from
  257. * the servant_preinvoke() method.
  258. */
  259. public void servant_postinvoke(org.omg.CORBA.Object self,
  260. ServantObject servant) {
  261. }
  262. /**
  263. * request is called by a stub to obtain an OutputStream for
  264. * marshaling arguments. The stub must supply the operation name,
  265. * and indicate if a response is expected (i.e is this a oneway
  266. * call).
  267. *
  268. * @param self The object reference which delegated to this delegate.
  269. * @param operation a string containing the operation name.
  270. * The operation name corresponds to the operation name as it would be
  271. * encoded in a GIOP request.
  272. * @param responseExpected false if the operation is a one way operation,
  273. * and true otherwise.
  274. * @return OutputStream the OutputStream into which request arguments
  275. * can be marshaled.
  276. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  277. * package comments for unimplemented features</a>
  278. */
  279. public OutputStream request(org.omg.CORBA.Object self,
  280. String operation,
  281. boolean responseExpected) {
  282. throw new org.omg.CORBA.NO_IMPLEMENT();
  283. }
  284. /**
  285. * invoke is called by a stub to invoke an operation. The stub provides an
  286. * OutputStream that was previously returned by a request()
  287. * call. invoke returns an InputStream which contains the
  288. * marshaled reply. If an exception occurs, invoke may throw an
  289. * ApplicationException object which contains an InputStream from
  290. * which the user exception state may be unmarshaled.
  291. *
  292. * @param self The object reference which delegated to this delegate.
  293. * @param output the OutputStream which contains marshaled arguments
  294. * @return input the InputStream from which reply parameters can be
  295. * unmarshaled.
  296. * @throws ApplicationException thrown when implementation throws
  297. * (upon invocation) an exception defined as part of its remote method
  298. * definition.
  299. * @throws RemarshalException thrown when remarshalling fails.
  300. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  301. * package comments for unimplemented features</a>
  302. */
  303. public InputStream invoke(org.omg.CORBA.Object self,
  304. OutputStream output)
  305. throws ApplicationException, RemarshalException {
  306. throw new org.omg.CORBA.NO_IMPLEMENT();
  307. }
  308. /**
  309. * releaseReply may optionally be called by a stub to release a
  310. * reply stream back to the ORB when the unmarshaling has
  311. * completed. The stub passes the InputStream returned by
  312. * invoke() or ApplicationException.getInputStream(). A null
  313. * value may also be passed to releaseReply, in which case the
  314. * method is a noop.
  315. *
  316. * @param self The object reference which delegated to this delegate.
  317. * @param input the InputStream returned from invoke().
  318. * @see <a href="package-summary.html#unimpl"><code>portable</code>
  319. * package comments for unimplemented features</a>
  320. */
  321. public void releaseReply(org.omg.CORBA.Object self,
  322. InputStream input) {
  323. throw new org.omg.CORBA.NO_IMPLEMENT();
  324. }
  325. /**
  326. * Provides the implementation to override the toString() method
  327. * of the delegating CORBA object.
  328. *
  329. * @param self the object reference that delegated to this delegate
  330. * @return a <code>String</code> object that represents the object
  331. * reference that delegated to this <code>Delegate</code>
  332. * object
  333. */
  334. public String toString(org.omg.CORBA.Object self) {
  335. return self.getClass().getName() + ":" + this.toString();
  336. }
  337. /**
  338. * Provides the implementation to override the hashCode() method
  339. * of the delegating CORBA object.
  340. *
  341. * @param self the object reference that delegated to this delegate
  342. * @return an <code>int</code> that represents the hashcode for the
  343. * object reference that delegated to this <code>Delegate</code>
  344. * object
  345. */
  346. public int hashCode(org.omg.CORBA.Object self) {
  347. return System.identityHashCode(self);
  348. }
  349. /**
  350. * Provides the implementation to override the equals(java.lang.Object obj)
  351. * method of the delegating CORBA object.
  352. *
  353. * @param self the object reference that delegated to this delegate
  354. * @param obj the <code>Object</code> with which to compare
  355. * @return <code>true</code> if <code>obj</code> equals <code>self</code>
  356. * <code>false</code> otherwise
  357. */
  358. public boolean equals(org.omg.CORBA.Object self, java.lang.Object obj) {
  359. return (self == obj);
  360. }
  361. }