1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/org/omg/CORBA/Object.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,282 @@
1.4 +/*
1.5 + * Copyright 1995-1999 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package org.omg.CORBA;
1.30 +
1.31 +/**
1.32 + * The definition for a CORBA object reference.
1.33 + * <p>
1.34 + * A CORBA object reference is a handle for a particular
1.35 + * CORBA object implemented by a server. A CORBA object reference
1.36 + * identifies the same CORBA object each time the reference is used to invoke
1.37 + * a method on the object.
1.38 + * A CORBA object may have multiple, distinct object references.
1.39 + * <p>
1.40 + * The <code>org.omg.CORBA.Object</code> interface is the root of
1.41 + * the inheritance hierarchy for all CORBA object references in the Java
1.42 + * programming language, analogous to <code>java.rmi.Remote</code>
1.43 + * for RMI remote objects.
1.44 + * <p>
1.45 + * A CORBA object may be either local or remote.
1.46 + * If it is a local object (that is, running in the same
1.47 + * VM as the client), invocations may be directly serviced by
1.48 + * the object instance, and the object reference could point to the actual
1.49 + * instance of the object implementation class.
1.50 + * If a CORBA object is a remote object (that is, running in a different
1.51 + * VM from the client), the object reference points to a stub (proxy) which uses the
1.52 + * ORB machinery to make a remote invocation on the server where the object
1.53 + * implementation resides.
1.54 + * <p>
1.55 + * Default implementations of the methods in the interface
1.56 + * <code>org.omg.CORBA.Object</code>
1.57 + * are provided in the class <code>org.omg.CORBA.portable.ObjectImpl</code>,
1.58 + * which is the base class for stubs and object implementations.
1.59 + * <p>
1.60 + * @see org.omg.CORBA.portable.ObjectImpl
1.61 + */
1.62 +
1.63 +public interface Object {
1.64 +
1.65 + /**
1.66 + * Checks whether this object is an instance of a class that
1.67 + * implements the given interface.
1.68 + *
1.69 + * @param repositoryIdentifier the interface to check against
1.70 + * @return <code>true</code> if this object reference is an instance
1.71 + * of a class that implements the interface;
1.72 + * <code>false</code> otherwise
1.73 + */
1.74 + boolean _is_a(String repositoryIdentifier);
1.75 +
1.76 +
1.77 + /**
1.78 + * Determines whether the two object references are equivalent,
1.79 + * so far as the ORB can easily determine. Two object references are equivalent
1.80 + * if they are identical. Two distinct object references which in fact refer to
1.81 + * the same object are also equivalent. However, ORBs are not required
1.82 + * to attempt determination of whether two distinct object references
1.83 + * refer to the same object, since such determination could be impractically
1.84 + * expensive.
1.85 + * @param other the other object reference with which to check for equivalence
1.86 + * @return <code>true</code> if this object reference is known to be
1.87 + * equivalent to the given object reference.
1.88 + * Note that <code>false</code> indicates only that the two
1.89 + * object references are distinct, not necessarily that
1.90 + * they reference distinct objects.
1.91 + */
1.92 + boolean _is_equivalent(org.omg.CORBA.Object other);
1.93 +
1.94 +
1.95 + /**
1.96 + * Determines whether the server object for this object reference has been
1.97 + * destroyed.
1.98 + * @return <code>true</code> if the ORB knows authoritatively that the
1.99 + * server object does not exist; <code>false</code> otherwise
1.100 + */
1.101 + boolean _non_existent();
1.102 +
1.103 +
1.104 + /**
1.105 + * Returns an ORB-internal identifier for this object reference.
1.106 + * This is a hash identifier, which does
1.107 + * not change during the lifetime of the object reference, and so
1.108 + * neither will any hash function of that identifier change. The value returned
1.109 + * is not guaranteed to be unique; in other words, another object
1.110 + * reference may have the same hash value.
1.111 + * If two object references hash differently,
1.112 + * then they are distinct object references; however, both may still refer
1.113 + * to the same CORBA object.
1.114 + *
1.115 + * @param maximum the upper bound on the hash value returned by the ORB
1.116 + * @return the ORB-internal hash identifier for this object reference
1.117 + */
1.118 + int _hash(int maximum);
1.119 +
1.120 +
1.121 + /**
1.122 + * Returns a duplicate of this CORBA object reference.
1.123 + * The server object implementation is not involved in creating
1.124 + * the duplicate, and the implementation cannot distinguish whether
1.125 + * the original object reference or a duplicate was used to make a request.
1.126 + * <P>
1.127 + * Note that this method is not very useful in the Java platform,
1.128 + * since memory management is handled by the VM.
1.129 + * It is included for compliance with the CORBA APIs.
1.130 + * <P>
1.131 + * The method <code>_duplicate</code> may return this object reference itself.
1.132 + *
1.133 + * @return a duplicate of this object reference or this object reference
1.134 + * itself
1.135 + */
1.136 + org.omg.CORBA.Object _duplicate();
1.137 +
1.138 +
1.139 + /**
1.140 + * Signals that the caller is done using this object reference, so
1.141 + * internal ORB resources associated with this object reference can be
1.142 + * released. Note that the object implementation is not involved in
1.143 + * this operation, and other references to the same object are not affected.
1.144 + */
1.145 + void _release();
1.146 +
1.147 +
1.148 + /**
1.149 + * Obtains an <code>InterfaceDef</code> for the object implementation
1.150 + * referenced by this object reference.
1.151 + * The <code>InterfaceDef</code> object
1.152 + * may be used to introspect on the methods, attributes, and other
1.153 + * type information for the object referred to by this object reference.
1.154 + *
1.155 + * @return the <code>InterfaceDef</code> object in the Interface Repository
1.156 + * which provides type information about the object referred to by
1.157 + * this object reference
1.158 + */
1.159 + org.omg.CORBA.Object _get_interface_def();
1.160 +
1.161 +
1.162 +
1.163 + /**
1.164 + * Creates a <code>Request</code> instance for use in the
1.165 + * Dynamic Invocation Interface.
1.166 + *
1.167 + * @param operation the name of the method to be invoked using the
1.168 + * <code>Request</code> instance
1.169 + * @return the newly-created <code>Request</code> instance
1.170 + */
1.171 + Request _request(String operation);
1.172 +
1.173 +
1.174 +
1.175 + /**
1.176 + * Creates a <code>Request</code> instance initialized with the
1.177 + * given context, method name, list of arguments, and container
1.178 + * for the method's return value.
1.179 + *
1.180 + * @param ctx a <code>Context</code> object containing
1.181 + * a list of properties
1.182 + * @param operation the name of the method to be invoked
1.183 + * @param arg_list an <code>NVList</code> containing the actual arguments
1.184 + * to the method being invoked
1.185 + * @param result a <code>NamedValue</code> object to serve as a
1.186 + * container for the method's return value
1.187 + * @return the newly-created <code>Request</code> object
1.188 + *
1.189 + * @see Request
1.190 + * @see NVList
1.191 + * @see NamedValue
1.192 + */
1.193 +
1.194 + Request _create_request(Context ctx,
1.195 + String operation,
1.196 + NVList arg_list,
1.197 + NamedValue result);
1.198 +
1.199 + /**
1.200 + * Creates a <code>Request</code> instance initialized with the
1.201 + * given context, method name, list of arguments, container
1.202 + * for the method's return value, list of possible exceptions,
1.203 + * and list of context strings needing to be resolved.
1.204 + *
1.205 + * @param ctx a <code>Context</code> object containing
1.206 + * a list of properties
1.207 + * @param operation the name of the method to be invoked
1.208 + * @param arg_list an <code>NVList</code> containing the actual arguments
1.209 + * to the method being invoked
1.210 + * @param result a <code>NamedValue</code> object to serve as a
1.211 + * container for the method's return value
1.212 + * @param exclist an <code>ExceptionList</code> object containing a
1.213 + * list of possible exceptions the method can throw
1.214 + * @param ctxlist a <code>ContextList</code> object containing a list of
1.215 + * context strings that need to be resolved and sent with the
1.216 + * <code>Request</code> instance
1.217 + * @return the newly-created <code>Request</code> object
1.218 + *
1.219 + * @see Request
1.220 + * @see NVList
1.221 + * @see NamedValue
1.222 + * @see ExceptionList
1.223 + * @see ContextList
1.224 + */
1.225 +
1.226 + Request _create_request(Context ctx,
1.227 + String operation,
1.228 + NVList arg_list,
1.229 + NamedValue result,
1.230 + ExceptionList exclist,
1.231 + ContextList ctxlist);
1.232 +
1.233 +
1.234 +
1.235 +
1.236 + /**
1.237 + * Returns the <code>Policy</code> object of the specified type
1.238 + * which applies to this object.
1.239 + *
1.240 + * @param policy_type the type of policy to be obtained
1.241 + * @return A <code>Policy</code> object of the type specified by
1.242 + * the policy_type parameter
1.243 + * @exception org.omg.CORBA.BAD_PARAM when the value of policy type
1.244 + * is not valid either because the specified type is not supported by this
1.245 + * ORB or because a policy object of that type is not associated with this
1.246 + * Object
1.247 + */
1.248 + Policy _get_policy(int policy_type);
1.249 +
1.250 +
1.251 + /**
1.252 + * Retrieves the <code>DomainManagers</code> of this object.
1.253 + * This allows administration services (and applications) to retrieve the
1.254 + * domain managers, and hence the security and other policies applicable
1.255 + * to individual objects that are members of the domain.
1.256 + *
1.257 + * @return the list of immediately enclosing domain managers of this object.
1.258 + * At least one domain manager is always returned in the list since by
1.259 + * default each object is associated with at least one domain manager at
1.260 + * creation.
1.261 + */
1.262 + DomainManager[] _get_domain_managers();
1.263 +
1.264 +
1.265 + /**
1.266 + * Returns a new <code>Object</code> with the given policies
1.267 + * either replacing any existing policies in this
1.268 + * <code>Object</code> or with the given policies added
1.269 + * to the existing ones, depending on the value of the
1.270 + * given <code>SetOverrideType</code> object.
1.271 + *
1.272 + * @param policies an array of <code>Policy</code> objects containing
1.273 + * the policies to be added or to be used as replacements
1.274 + * @param set_add either <code>SetOverrideType.SET_OVERRIDE</code>, indicating
1.275 + * that the given policies will replace any existing ones, or
1.276 + * <code>SetOverrideType.ADD_OVERRIDE</code>, indicating that
1.277 + * the given policies should be added to any existing ones
1.278 + * @return a new <code>Object</code> with the given policies replacing
1.279 + * or added to those in this <code>Object</code>
1.280 + */
1.281 + org.omg.CORBA.Object _set_policy_override(Policy[] policies,
1.282 + SetOverrideType set_add);
1.283 +
1.284 +
1.285 +}
