Object.java revision 608:7e06bf1dcb09
1/* 2 * Copyright (c) 1995, 1999, 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 */ 25 26package org.omg.CORBA; 27 28/** 29 * The definition for a CORBA object reference. 30 * <p> 31 * A CORBA object reference is a handle for a particular 32 * CORBA object implemented by a server. A CORBA object reference 33 * identifies the same CORBA object each time the reference is used to invoke 34 * a method on the object. 35 * A CORBA object may have multiple, distinct object references. 36 * <p> 37 * The <code>org.omg.CORBA.Object</code> interface is the root of 38 * the inheritance hierarchy for all CORBA object references in the Java 39 * programming language, analogous to <code>java.rmi.Remote</code> 40 * for RMI remote objects. 41 * <p> 42 * A CORBA object may be either local or remote. 43 * If it is a local object (that is, running in the same 44 * VM as the client), invocations may be directly serviced by 45 * the object instance, and the object reference could point to the actual 46 * instance of the object implementation class. 47 * If a CORBA object is a remote object (that is, running in a different 48 * VM from the client), the object reference points to a stub (proxy) which uses the 49 * ORB machinery to make a remote invocation on the server where the object 50 * implementation resides. 51 * <p> 52 * Default implementations of the methods in the interface 53 * <code>org.omg.CORBA.Object</code> 54 * are provided in the class <code>org.omg.CORBA.portable.ObjectImpl</code>, 55 * which is the base class for stubs and object implementations. 56 * <p> 57 * @see org.omg.CORBA.portable.ObjectImpl 58 */ 59 60public interface Object { 61 62 /** 63 * Checks whether this object is an instance of a class that 64 * implements the given interface. 65 * 66 * @param repositoryIdentifier the interface to check against 67 * @return <code>true</code> if this object reference is an instance 68 * of a class that implements the interface; 69 * <code>false</code> otherwise 70 */ 71 boolean _is_a(String repositoryIdentifier); 72 73 74 /** 75 * Determines whether the two object references are equivalent, 76 * so far as the ORB can easily determine. Two object references are equivalent 77 * if they are identical. Two distinct object references which in fact refer to 78 * the same object are also equivalent. However, ORBs are not required 79 * to attempt determination of whether two distinct object references 80 * refer to the same object, since such determination could be impractically 81 * expensive. 82 * @param other the other object reference with which to check for equivalence 83 * @return <code>true</code> if this object reference is known to be 84 * equivalent to the given object reference. 85 * Note that <code>false</code> indicates only that the two 86 * object references are distinct, not necessarily that 87 * they reference distinct objects. 88 */ 89 boolean _is_equivalent(org.omg.CORBA.Object other); 90 91 92 /** 93 * Determines whether the server object for this object reference has been 94 * destroyed. 95 * @return <code>true</code> if the ORB knows authoritatively that the 96 * server object does not exist; <code>false</code> otherwise 97 */ 98 boolean _non_existent(); 99 100 101 /** 102 * Returns an ORB-internal identifier for this object reference. 103 * This is a hash identifier, which does 104 * not change during the lifetime of the object reference, and so 105 * neither will any hash function of that identifier change. The value returned 106 * is not guaranteed to be unique; in other words, another object 107 * reference may have the same hash value. 108 * If two object references hash differently, 109 * then they are distinct object references; however, both may still refer 110 * to the same CORBA object. 111 * 112 * @param maximum the upper bound on the hash value returned by the ORB 113 * @return the ORB-internal hash identifier for this object reference 114 */ 115 int _hash(int maximum); 116 117 118 /** 119 * Returns a duplicate of this CORBA object reference. 120 * The server object implementation is not involved in creating 121 * the duplicate, and the implementation cannot distinguish whether 122 * the original object reference or a duplicate was used to make a request. 123 * <P> 124 * Note that this method is not very useful in the Java platform, 125 * since memory management is handled by the VM. 126 * It is included for compliance with the CORBA APIs. 127 * <P> 128 * The method <code>_duplicate</code> may return this object reference itself. 129 * 130 * @return a duplicate of this object reference or this object reference 131 * itself 132 */ 133 org.omg.CORBA.Object _duplicate(); 134 135 136 /** 137 * Signals that the caller is done using this object reference, so 138 * internal ORB resources associated with this object reference can be 139 * released. Note that the object implementation is not involved in 140 * this operation, and other references to the same object are not affected. 141 */ 142 void _release(); 143 144 145 /** 146 * Obtains an <code>InterfaceDef</code> for the object implementation 147 * referenced by this object reference. 148 * The <code>InterfaceDef</code> object 149 * may be used to introspect on the methods, attributes, and other 150 * type information for the object referred to by this object reference. 151 * 152 * @return the <code>InterfaceDef</code> object in the Interface Repository 153 * which provides type information about the object referred to by 154 * this object reference 155 */ 156 org.omg.CORBA.Object _get_interface_def(); 157 158 159 160 /** 161 * Creates a <code>Request</code> instance for use in the 162 * Dynamic Invocation Interface. 163 * 164 * @param operation the name of the method to be invoked using the 165 * <code>Request</code> instance 166 * @return the newly-created <code>Request</code> instance 167 */ 168 Request _request(String operation); 169 170 171 172 /** 173 * Creates a <code>Request</code> instance initialized with the 174 * given context, method name, list of arguments, and container 175 * for the method's return value. 176 * 177 * @param ctx a <code>Context</code> object containing 178 * a list of properties 179 * @param operation the name of the method to be invoked 180 * @param arg_list an <code>NVList</code> containing the actual arguments 181 * to the method being invoked 182 * @param result a <code>NamedValue</code> object to serve as a 183 * container for the method's return value 184 * @return the newly-created <code>Request</code> object 185 * 186 * @see Request 187 * @see NVList 188 * @see NamedValue 189 */ 190 191 Request _create_request(Context ctx, 192 String operation, 193 NVList arg_list, 194 NamedValue result); 195 196 /** 197 * Creates a <code>Request</code> instance initialized with the 198 * given context, method name, list of arguments, container 199 * for the method's return value, list of possible exceptions, 200 * and list of context strings needing to be resolved. 201 * 202 * @param ctx a <code>Context</code> object containing 203 * a list of properties 204 * @param operation the name of the method to be invoked 205 * @param arg_list an <code>NVList</code> containing the actual arguments 206 * to the method being invoked 207 * @param result a <code>NamedValue</code> object to serve as a 208 * container for the method's return value 209 * @param exclist an <code>ExceptionList</code> object containing a 210 * list of possible exceptions the method can throw 211 * @param ctxlist a <code>ContextList</code> object containing a list of 212 * context strings that need to be resolved and sent with the 213 * <code>Request</code> instance 214 * @return the newly-created <code>Request</code> object 215 * 216 * @see Request 217 * @see NVList 218 * @see NamedValue 219 * @see ExceptionList 220 * @see ContextList 221 */ 222 223 Request _create_request(Context ctx, 224 String operation, 225 NVList arg_list, 226 NamedValue result, 227 ExceptionList exclist, 228 ContextList ctxlist); 229 230 231 232 233 /** 234 * Returns the <code>Policy</code> object of the specified type 235 * which applies to this object. 236 * 237 * @param policy_type the type of policy to be obtained 238 * @return A <code>Policy</code> object of the type specified by 239 * the policy_type parameter 240 * @exception org.omg.CORBA.BAD_PARAM when the value of policy type 241 * is not valid either because the specified type is not supported by this 242 * ORB or because a policy object of that type is not associated with this 243 * Object 244 */ 245 Policy _get_policy(int policy_type); 246 247 248 /** 249 * Retrieves the <code>DomainManagers</code> of this object. 250 * This allows administration services (and applications) to retrieve the 251 * domain managers, and hence the security and other policies applicable 252 * to individual objects that are members of the domain. 253 * 254 * @return the list of immediately enclosing domain managers of this object. 255 * At least one domain manager is always returned in the list since by 256 * default each object is associated with at least one domain manager at 257 * creation. 258 */ 259 DomainManager[] _get_domain_managers(); 260 261 262 /** 263 * Returns a new <code>Object</code> with the given policies 264 * either replacing any existing policies in this 265 * <code>Object</code> or with the given policies added 266 * to the existing ones, depending on the value of the 267 * given <code>SetOverrideType</code> object. 268 * 269 * @param policies an array of <code>Policy</code> objects containing 270 * the policies to be added or to be used as replacements 271 * @param set_add either <code>SetOverrideType.SET_OVERRIDE</code>, indicating 272 * that the given policies will replace any existing ones, or 273 * <code>SetOverrideType.ADD_OVERRIDE</code>, indicating that 274 * the given policies should be added to any existing ones 275 * @return a new <code>Object</code> with the given policies replacing 276 * or added to those in this <code>Object</code> 277 */ 278 org.omg.CORBA.Object _set_policy_override(Policy[] policies, 279 SetOverrideType set_add); 280 281 282} 283