Delegate.java revision 608:7e06bf1dcb09
1139969Simp/* 21556Srgrimes * Copyright (c) 1997, 2002, Oracle and/or its affiliates. All rights reserved. 31556Srgrimes * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 41556Srgrimes * 51556Srgrimes * This code is free software; you can redistribute it and/or modify it 61556Srgrimes * under the terms of the GNU General Public License version 2 only, as 71556Srgrimes * published by the Free Software Foundation. Oracle designates this 81556Srgrimes * particular file as subject to the "Classpath" exception as provided 91556Srgrimes * by Oracle in the LICENSE file that accompanied this code. 101556Srgrimes * 111556Srgrimes * This code is distributed in the hope that it will be useful, but WITHOUT 121556Srgrimes * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 131556Srgrimes * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 141556Srgrimes * version 2 for more details (a copy is included in the LICENSE file that 151556Srgrimes * accompanied this code). 161556Srgrimes * 171556Srgrimes * You should have received a copy of the GNU General Public License version 181556Srgrimes * 2 along with this work; if not, write to the Free Software Foundation, 191556Srgrimes * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 201556Srgrimes * 211556Srgrimes * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 221556Srgrimes * or visit www.oracle.com if you need additional information or have any 231556Srgrimes * questions. 241556Srgrimes */ 251556Srgrimespackage org.omg.CORBA.portable; 261556Srgrimes 271556Srgrimesimport org.omg.CORBA.Request; 281556Srgrimesimport org.omg.CORBA.NamedValue; 291556Srgrimesimport org.omg.CORBA.NVList; 301556Srgrimesimport org.omg.CORBA.Context; 311556Srgrimesimport org.omg.CORBA.ContextList; 321556Srgrimesimport org.omg.CORBA.ExceptionList; 33114433Sobrienimport org.omg.CORBA.TypeCode; 341556Srgrimesimport org.omg.CORBA.SystemException; 3520420Ssteve 361556Srgrimes/** 371556Srgrimes * Specifies a portable API for ORB-vendor-specific 381556Srgrimes * implementation of the org.omg.CORBA.Object methods. 391556Srgrimes * 401556Srgrimes * Each stub (proxy) contains a delegate 4136049Scharnier * object, to which all org.omg.CORBA.Object methods are forwarded. 42114433Sobrien * This allows a stub generated by one vendor's ORB to work with the delegate 4336049Scharnier * from another vendor's ORB. 4492974Sobrien * 4592974Sobrien * @see org.omg.CORBA.Object 461556Srgrimes * @author OMG 47149790Scsjp */ 48149790Scsjp 491556Srgrimespublic abstract class Delegate { 501556Srgrimes 511556Srgrimes /** 521556Srgrimes * Return an InterfaceDef for the object reference provided. 5331664Seivind * @param self The object reference whose InterfaceDef needs to be returned 541556Srgrimes * @return the InterfaceDef 551556Srgrimes */ 561556Srgrimes public abstract org.omg.CORBA.Object get_interface_def( 571556Srgrimes org.omg.CORBA.Object self); 5890644Simp 5977409Simp /** 6096806Sjmallett * Returns a duplicate of the object reference provided. 6190644Simp * @param obj The object reference whose duplicate needs to be returned 621556Srgrimes * @return the duplicate object reference 631556Srgrimes */ 641556Srgrimes public abstract org.omg.CORBA.Object duplicate(org.omg.CORBA.Object obj); 6550544Smharo 661556Srgrimes /** 671556Srgrimes * Releases resources associated with the object reference provided. 68174935Sdds * @param obj The object reference whose resources need to be released 69174935Sdds */ 70174935Sdds public abstract void release(org.omg.CORBA.Object obj); 71239951Sjhb 721556Srgrimes /** 73180604Sdelphij * Checks if the object reference is an instance of the given interface. 74180604Sdelphij * @param obj The object reference to be checked. 75180604Sdelphij * @param repository_id The repository identifier of the interface 76180604Sdelphij * to check against. 77196841Strasz * @return true if the object reference supports the interface 78196841Strasz */ 791556Srgrimes public abstract boolean is_a(org.omg.CORBA.Object obj, String repository_id); 801556Srgrimes 8190110Simp /** 821556Srgrimes * Determines whether the server object for the object reference has been 8391085Smarkm * destroyed. 8491085Smarkm * @param obj The object reference which delegated to this delegate. 8590114Simp * @return true if the ORB knows authoritatively that the server object does 861556Srgrimes * not exist, false otherwise 871556Srgrimes */ 8877409Simp public abstract boolean non_existent(org.omg.CORBA.Object obj); 891556Srgrimes 90239951Sjhb /** 911556Srgrimes * Determines if the two object references are equivalent. 92239951Sjhb * @param obj The object reference which delegated to this delegate. 93239951Sjhb * @param other The object reference to check equivalence against. 94239951Sjhb * @return true if the objects are CORBA-equivalent. 951556Srgrimes */ 9614154Swosch public abstract boolean is_equivalent(org.omg.CORBA.Object obj, 9792935Sobrien org.omg.CORBA.Object other); 981556Srgrimes 991556Srgrimes /** 1001556Srgrimes * Returns an ORB-internal identifier (hashcode) for this object reference. 10192935Sobrien * @param obj The object reference which delegated to this delegate. 1021556Srgrimes * @param max specifies an upper bound on the hash value returned by 10392935Sobrien * the ORB. 10492935Sobrien * @return ORB-internal hash identifier for object reference 10592935Sobrien */ 10692935Sobrien public abstract int hash(org.omg.CORBA.Object obj, int max); 10750544Smharo 10850544Smharo /** 10950544Smharo * Creates a Request instance for use in the Dynamic Invocation Interface. 1101556Srgrimes * @param obj The object reference which delegated to this delegate. 1111556Srgrimes * @param operation The name of the operation to be invoked using the 1121556Srgrimes * Request instance. 11314305Swosch * @return the created Request instance 1141556Srgrimes */ 1151556Srgrimes public abstract Request request(org.omg.CORBA.Object obj, String operation); 1161556Srgrimes 1171556Srgrimes /** 1181556Srgrimes * Creates a Request instance for use in the Dynamic Invocation Interface. 1191556Srgrimes * 1201556Srgrimes * @param obj The object reference which delegated to this delegate. 1211556Srgrimes * @param ctx The context to be used. 1221556Srgrimes * @param operation The name of the operation to be 1231556Srgrimes * invoked. 1241556Srgrimes * @param arg_list The arguments to the operation in the 125287027Sjilles * form of an NVList. 1261556Srgrimes * @param result A container for the result as a NamedValue. 1271556Srgrimes * @return The created Request object. 1281556Srgrimes * 129239951Sjhb */ 130239951Sjhb public abstract Request create_request(org.omg.CORBA.Object obj, 131239951Sjhb Context ctx, 132239951Sjhb String operation, 133239951Sjhb NVList arg_list, 134239951Sjhb NamedValue result); 135239951Sjhb 136239951Sjhb /** 137239951Sjhb * Creates a Request instance for use in the Dynamic Invocation Interface. 138239951Sjhb * 139239951Sjhb * @param obj The object reference which delegated to this delegate. 1401556Srgrimes * @param ctx The context to be used. 14136785Simp * @param operation The name of the operation to be 14236785Simp * invoked. 1431556Srgrimes * @param arg_list The arguments to the operation in the 1441556Srgrimes * form of an NVList. 1451556Srgrimes * @param result A container for the result as a NamedValue. 14636383Ssteve * @param exclist A list of possible exceptions the 14736383Ssteve * operation can throw. 14836383Ssteve * @param ctxlist A list of context strings that need 14936383Ssteve * to be resolved and sent with the 1501556Srgrimes * Request. 15111298Sbde * @return The created Request object. 15211298Sbde */ 15311298Sbde public abstract Request create_request(org.omg.CORBA.Object obj, 15411298Sbde Context ctx, 15511298Sbde String operation, 15611298Sbde NVList arg_list, 15711298Sbde NamedValue result, 15811298Sbde ExceptionList exclist, 15911298Sbde ContextList ctxlist); 16011298Sbde 16177409Simp /** 1621556Srgrimes * Provides a reference to the orb associated with its parameter. 1631556Srgrimes * 1641556Srgrimes * @param obj the object reference which delegated to this delegate. 16576878Skris * @return the associated orb. 1661556Srgrimes * @see <a href="package-summary.html#unimpl"><code>portable</code> 1671556Srgrimes * package comments for unimplemented features</a> 1681556Srgrimes */ 1691556Srgrimes public org.omg.CORBA.ORB orb(org.omg.CORBA.Object obj) { 1701556Srgrimes throw new org.omg.CORBA.NO_IMPLEMENT(); 1711556Srgrimes } 1721556Srgrimes 173180604Sdelphij /** 174180604Sdelphij * Returns the <code>Policy</code> object of the specified type 1751556Srgrimes * which applies to this object. 1761556Srgrimes * 17729933Swosch * @param self The object reference which delegated to this delegate. 1781556Srgrimes * @param policy_type The type of policy to be obtained. 1791556Srgrimes * @return A <code>Policy</code> object of the type specified by 1801556Srgrimes * the policy_type parameter. 1811556Srgrimes * @exception org.omg.CORBA.BAD_PARAM raised when the value of policy type 1821556Srgrimes * is not valid either because the specified type is not supported by this 1831556Srgrimes * ORB or because a policy object of that type is not associated with this 1841556Srgrimes * Object. 1851556Srgrimes * @see <a href="package-summary.html#unimpl"><code>portable</code> 18614166Swosch * package comments for unimplemented features</a> 18714166Swosch */ 18814166Swosch public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self, 18914305Swosch int policy_type) { 19014305Swosch throw new org.omg.CORBA.NO_IMPLEMENT(); 19114166Swosch } 19230106Swosch 19330106Swosch 1941556Srgrimes /** 19592935Sobrien * Retrieves the <code>DomainManagers</code> of this object. 19692935Sobrien * This allows administration services (and applications) to retrieve the 19792935Sobrien * domain managers, and hence the security and other policies applicable 19892935Sobrien * to individual objects that are members of the domain. 19992935Sobrien * 20030106Swosch * @param self The object reference which delegated to this delegate. 2011556Srgrimes * @return The list of immediately enclosing domain managers of this object. 202243072Seadler * At least one domain manager is always returned in the list since by 2031556Srgrimes * default each object is associated with at least one domain manager at 20430106Swosch * creation. 2051556Srgrimes * @see <a href="package-summary.html#unimpl"><code>portable</code> 20676878Skris * package comments for unimplemented features</a> 20776878Skris */ 2081556Srgrimes public org.omg.CORBA.DomainManager[] get_domain_managers( 2091556Srgrimes org.omg.CORBA.Object 2101556Srgrimes self) { 21129933Swosch throw new org.omg.CORBA.NO_IMPLEMENT(); 21229933Swosch } 21329933Swosch 21430106Swosch 21530106Swosch /** 2161556Srgrimes * Associates the policies passed in 21730106Swosch * with a newly created object reference that it returns. Only certain 2181556Srgrimes * policies that pertain to the invocation of an operation at the client 2191556Srgrimes * end can be overridden using this operation. Attempts to override any 220174935Sdds * other policy will result in the raising of the CORBA::NO_PERMISSION 221174935Sdds * exception. 222174935Sdds * 223174935Sdds * @param self The object reference which delegated to this delegate. 224174935Sdds * @param policies A sequence of references to Policy objects. 22550544Smharo * @param set_add Indicates whether these policies should be added 22650544Smharo * onto any otheroverrides that already exist (ADD_OVERRIDE) in 22750544Smharo * the object reference, or they should be added to a clean 2281556Srgrimes * override free object reference (SET_OVERRIDE). 22950544Smharo * @return A new object reference with the new policies associated with it. 2301556Srgrimes * 23131664Seivind * @see <a href="package-summary.html#unimpl"><code>portable</code> 23231664Seivind * package comments for unimplemented features</a> 23377409Simp */ 23431664Seivind public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self, 235127272Spjd org.omg.CORBA.Policy[] policies, 236127272Spjd org.omg.CORBA.SetOverrideType set_add) { 237127272Spjd throw new org.omg.CORBA.NO_IMPLEMENT(); 238127272Spjd } 239127272Spjd 240127272Spjd 24131664Seivind /** 24231664Seivind * Returns true if this object is implemented by a local servant. 243127272Spjd * 244127272Spjd * @param self The object reference which delegated to this delegate. 245127272Spjd * @return true only if the servant incarnating this object is located in 246174935Sdds * this Java VM. Return false if the servant is not local or the ORB 247127272Spjd * does not support local stubs for this particular servant. The default 248127272Spjd * behavior of is_local() is to return false. 249127272Spjd */ 250127272Spjd public boolean is_local(org.omg.CORBA.Object self) { 251127272Spjd return false; 252127272Spjd } 253127272Spjd 25431664Seivind /** 25531664Seivind * Returns a Java reference to the servant which should be used for this 2561556Srgrimes * request. servant_preinvoke() is invoked by a local stub. 2571556Srgrimes * If a ServantObject object is returned, then its servant field 2581556Srgrimes * has been set to an object of the expected type (Note: the object may 2591556Srgrimes * or may not be the actual servant instance). The local stub may cast 2601556Srgrimes * the servant field to the expected type, and then invoke the operation 2611556Srgrimes * directly. The ServantRequest object is valid for only one invocation, 2621556Srgrimes * and cannot be used for more than one invocation. 2631556Srgrimes * 2641556Srgrimes * @param self The object reference which delegated to this delegate. 26562963Sdwmalone * 2661556Srgrimes * @param operation a string containing the operation name. 2671556Srgrimes * The operation name corresponds to the operation name as it would be 2681556Srgrimes * encoded in a GIOP request. 2691556Srgrimes * 2701556Srgrimes * @param expectedType a Class object representing the expected type of the servant. 2711556Srgrimes * The expected type is the Class object associated with the operations 2721556Srgrimes * class of the stub's interface (e.g. A stub for an interface Foo, 273180604Sdelphij * would pass the Class object for the FooOperations interface). 274180604Sdelphij * 2751556Srgrimes * @return a ServantObject object. 2761556Srgrimes * The method may return a null value if it does not wish to support 277225954Sivoras * this optimization (e.g. due to security, transactions, etc). 278225954Sivoras * The method must return null if the servant is not of the expected type. 27923525Sguido */ 28090114Simp public ServantObject servant_preinvoke(org.omg.CORBA.Object self, 2811556Srgrimes String operation, 2821556Srgrimes Class expectedType) { 283225954Sivoras return null; 2841556Srgrimes } 2851556Srgrimes 286225954Sivoras /** 287225954Sivoras * servant_postinvoke() is invoked by the local stub after the operation 288225954Sivoras * has been invoked on the local servant. 28923525Sguido * This method must be called if servant_preinvoke() returned a non-null 29023525Sguido * value, even if an exception was thrown by the servant's method. 29123525Sguido * For this reason, the call to servant_postinvoke() should be placed 29223525Sguido * in a Java finally clause. 29323525Sguido * 294225954Sivoras * @param self The object reference which delegated to this delegate. 2951556Srgrimes * 2961556Srgrimes * @param servant the instance of the ServantObject returned from 2971556Srgrimes * the servant_preinvoke() method. 29876878Skris */ 29976878Skris public void servant_postinvoke(org.omg.CORBA.Object self, 300225954Sivoras ServantObject servant) { 3011556Srgrimes } 3021556Srgrimes 3031556Srgrimes /** 304225954Sivoras * request is called by a stub to obtain an OutputStream for 3051556Srgrimes * marshaling arguments. The stub must supply the operation name, 3061556Srgrimes * and indicate if a response is expected (i.e is this a oneway 3071556Srgrimes * call). 3081556Srgrimes * 3091556Srgrimes * @param self The object reference which delegated to this delegate. 3101556Srgrimes * @param operation a string containing the operation name. 3111556Srgrimes * The operation name corresponds to the operation name as it would be 31223525Sguido * encoded in a GIOP request. 31323525Sguido * @param responseExpected false if the operation is a one way operation, 31437245Sbde * and true otherwise. 31537245Sbde * @return OutputStream the OutputStream into which request arguments 31623525Sguido * can be marshaled. 31723525Sguido * @see <a href="package-summary.html#unimpl"><code>portable</code> 31823525Sguido * package comments for unimplemented features</a> 31923525Sguido */ 32023525Sguido public OutputStream request(org.omg.CORBA.Object self, 32123525Sguido String operation, 32223525Sguido boolean responseExpected) { 323196841Strasz throw new org.omg.CORBA.NO_IMPLEMENT(); 324196841Strasz } 325149790Scsjp 326149790Scsjp /** 327174935Sdds * invoke is called by a stub to invoke an operation. The stub provides an 328149790Scsjp * OutputStream that was previously returned by a request() 329149790Scsjp * call. invoke returns an InputStream which contains the 330196841Strasz * marshaled reply. If an exception occurs, invoke may throw an 331149790Scsjp * ApplicationException object which contains an InputStream from 33263680Ssada * which the user exception state may be unmarshaled. 33363680Ssada * 33463680Ssada * @param self The object reference which delegated to this delegate. 33563680Ssada * @param output the OutputStream which contains marshaled arguments 33663680Ssada * @return input the InputStream from which reply parameters can be 33763680Ssada * unmarshaled. 33863680Ssada * @throws ApplicationException thrown when implementation throws 33963680Ssada * (upon invocation) an exception defined as part of its remote method 340248597Spjd * definition. 34163680Ssada * @throws RemarshalException thrown when remarshalling fails. 34263680Ssada * @see <a href="package-summary.html#unimpl"><code>portable</code> 3431556Srgrimes * package comments for unimplemented features</a> 3441556Srgrimes */ 3451556Srgrimes public InputStream invoke(org.omg.CORBA.Object self, 3461556Srgrimes OutputStream output) 3471556Srgrimes throws ApplicationException, RemarshalException { 3481556Srgrimes throw new org.omg.CORBA.NO_IMPLEMENT(); 3491556Srgrimes } 3501556Srgrimes 3511556Srgrimes /** 3521556Srgrimes * releaseReply may optionally be called by a stub to release a 3531556Srgrimes * reply stream back to the ORB when the unmarshaling has 3541556Srgrimes * completed. The stub passes the InputStream returned by 3551556Srgrimes * invoke() or ApplicationException.getInputStream(). A null 3561556Srgrimes * value may also be passed to releaseReply, in which case the 3571556Srgrimes * method is a noop. 3581556Srgrimes * 35950544Smharo * @param self The object reference which delegated to this delegate. 36050544Smharo * @param input the InputStream returned from invoke(). 3611556Srgrimes * @see <a href="package-summary.html#unimpl"><code>portable</code> 3621556Srgrimes * package comments for unimplemented features</a> 3631556Srgrimes */ 364180604Sdelphij public void releaseReply(org.omg.CORBA.Object self, 365180604Sdelphij InputStream input) { 3661556Srgrimes throw new org.omg.CORBA.NO_IMPLEMENT(); 367174664Sdds } 368174667Sdds 3691556Srgrimes /** 370174935Sdds * Provides the implementation to override the toString() method 371174935Sdds * of the delegating CORBA object. 372174935Sdds * 373174935Sdds * @param self the object reference that delegated to this delegate 374174935Sdds * @return a <code>String</code> object that represents the object 375174935Sdds * reference that delegated to this <code>Delegate</code> 376174935Sdds * object 377174935Sdds */ 378174935Sdds 379174935Sdds public String toString(org.omg.CORBA.Object self) { 380174935Sdds return self.getClass().getName() + ":" + this.toString(); 381174935Sdds } 382174664Sdds 383174935Sdds /** 384174935Sdds * Provides the implementation to override the hashCode() method 385174935Sdds * of the delegating CORBA object. 386174664Sdds * 387174935Sdds * @param self the object reference that delegated to this delegate 388174664Sdds * @return an <code>int</code> that represents the hashcode for the 389174935Sdds * object reference that delegated to this <code>Delegate</code> 39098280Stjr * object 39179452Sbrian */ 392174935Sdds public int hashCode(org.omg.CORBA.Object self) { 3931556Srgrimes return System.identityHashCode(self); 3941556Srgrimes } 395174935Sdds 396174935Sdds /** 3971556Srgrimes * Provides the implementation to override the equals(java.lang.Object obj) 3981556Srgrimes * method of the delegating CORBA object. 399174935Sdds * 400174935Sdds * @param self the object reference that delegated to this delegate 401174935Sdds * @param obj the <code>Object</code> with which to compare 4021556Srgrimes * @return <code>true</code> if <code>obj</code> equals <code>self</code>; 403174935Sdds * <code>false</code> otherwise 404174935Sdds */ 405174935Sdds public boolean equals(org.omg.CORBA.Object self, java.lang.Object obj) { 406174935Sdds return (self == obj); 407174935Sdds } 408174935Sdds} 409174935Sdds