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