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