1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/org/omg/CORBA/portable/Delegate.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,408 @@
1.4 +/*
1.5 + * Copyright 1997-2002 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 +package org.omg.CORBA.portable;
1.29 +
1.30 +import org.omg.CORBA.Request;
1.31 +import org.omg.CORBA.NamedValue;
1.32 +import org.omg.CORBA.NVList;
1.33 +import org.omg.CORBA.Context;
1.34 +import org.omg.CORBA.ContextList;
1.35 +import org.omg.CORBA.ExceptionList;
1.36 +import org.omg.CORBA.TypeCode;
1.37 +import org.omg.CORBA.SystemException;
1.38 +
1.39 +/**
1.40 + * Specifies a portable API for ORB-vendor-specific
1.41 + * implementation of the org.omg.CORBA.Object methods.
1.42 + *
1.43 + * Each stub (proxy) contains a delegate
1.44 + * object, to which all org.omg.CORBA.Object methods are forwarded.
1.45 + * This allows a stub generated by one vendor's ORB to work with the delegate
1.46 + * from another vendor's ORB.
1.47 + *
1.48 + * @see org.omg.CORBA.Object
1.49 + * @author OMG
1.50 + */
1.51 +
1.52 +public abstract class Delegate {
1.53 +
1.54 + /**
1.55 + * Return an InterfaceDef for the object reference provided.
1.56 + * @param self The object reference whose InterfaceDef needs to be returned
1.57 + * @return the InterfaceDef
1.58 + */
1.59 + public abstract org.omg.CORBA.Object get_interface_def(
1.60 + org.omg.CORBA.Object self);
1.61 +
1.62 + /**
1.63 + * Returns a duplicate of the object reference provided.
1.64 + * @param obj The object reference whose duplicate needs to be returned
1.65 + * @return the duplicate object reference
1.66 + */
1.67 + public abstract org.omg.CORBA.Object duplicate(org.omg.CORBA.Object obj);
1.68 +
1.69 + /**
1.70 + * Releases resources associated with the object reference provided.
1.71 + * @param obj The object reference whose resources need to be released
1.72 + */
1.73 + public abstract void release(org.omg.CORBA.Object obj);
1.74 +
1.75 + /**
1.76 + * Checks if the object reference is an instance of the given interface.
1.77 + * @param obj The object reference to be checked.
1.78 + * @param repository_id The repository identifier of the interface
1.79 + * to check against.
1.80 + * @return true if the object reference supports the interface
1.81 + */
1.82 + public abstract boolean is_a(org.omg.CORBA.Object obj, String repository_id);
1.83 +
1.84 + /**
1.85 + * Determines whether the server object for the object reference has been
1.86 + * destroyed.
1.87 + * @param obj The object reference which delegated to this delegate.
1.88 + * @return true if the ORB knows authoritatively that the server object does
1.89 + * not exist, false otherwise
1.90 + */
1.91 + public abstract boolean non_existent(org.omg.CORBA.Object obj);
1.92 +
1.93 + /**
1.94 + * Determines if the two object references are equivalent.
1.95 + * @param obj The object reference which delegated to this delegate.
1.96 + * @param other The object reference to check equivalence against.
1.97 + * @return true if the objects are CORBA-equivalent.
1.98 + */
1.99 + public abstract boolean is_equivalent(org.omg.CORBA.Object obj,
1.100 + org.omg.CORBA.Object other);
1.101 +
1.102 + /**
1.103 + * Returns an ORB-internal identifier (hashcode) for this object reference.
1.104 + * @param obj The object reference which delegated to this delegate.
1.105 + * @param max specifies an upper bound on the hash value returned by
1.106 + * the ORB.
1.107 + * @return ORB-internal hash identifier for object reference
1.108 + */
1.109 + public abstract int hash(org.omg.CORBA.Object obj, int max);
1.110 +
1.111 + /**
1.112 + * Creates a Request instance for use in the Dynamic Invocation Interface.
1.113 + * @param obj The object reference which delegated to this delegate.
1.114 + * @param operation The name of the operation to be invoked using the
1.115 + * Request instance.
1.116 + * @return the created Request instance
1.117 + */
1.118 + public abstract Request request(org.omg.CORBA.Object obj, String operation);
1.119 +
1.120 + /**
1.121 + * Creates a Request instance for use in the Dynamic Invocation Interface.
1.122 + *
1.123 + * @param obj The object reference which delegated to this delegate.
1.124 + * @param ctx The context to be used.
1.125 + * @param operation The name of the operation to be
1.126 + * invoked.
1.127 + * @param arg_list The arguments to the operation in the
1.128 + * form of an NVList.
1.129 + * @param result A container for the result as a NamedValue.
1.130 + * @return The created Request object.
1.131 + *
1.132 + */
1.133 + public abstract Request create_request(org.omg.CORBA.Object obj,
1.134 + Context ctx,
1.135 + String operation,
1.136 + NVList arg_list,
1.137 + NamedValue result);
1.138 +
1.139 + /**
1.140 + * Creates a Request instance for use in the Dynamic Invocation Interface.
1.141 + *
1.142 + * @param obj The object reference which delegated to this delegate.
1.143 + * @param ctx The context to be used.
1.144 + * @param operation The name of the operation to be
1.145 + * invoked.
1.146 + * @param arg_list The arguments to the operation in the
1.147 + * form of an NVList.
1.148 + * @param result A container for the result as a NamedValue.
1.149 + * @param exclist A list of possible exceptions the
1.150 + * operation can throw.
1.151 + * @param ctxlist A list of context strings that need
1.152 + * to be resolved and sent with the
1.153 + * Request.
1.154 + * @return The created Request object.
1.155 + */
1.156 + public abstract Request create_request(org.omg.CORBA.Object obj,
1.157 + Context ctx,
1.158 + String operation,
1.159 + NVList arg_list,
1.160 + NamedValue result,
1.161 + ExceptionList exclist,
1.162 + ContextList ctxlist);
1.163 +
1.164 + /**
1.165 + * Provides a reference to the orb associated with its parameter.
1.166 + *
1.167 + * @param obj the object reference which delegated to this delegate.
1.168 + * @return the associated orb.
1.169 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.170 + * package comments for unimplemented features</a>
1.171 + */
1.172 + public org.omg.CORBA.ORB orb(org.omg.CORBA.Object obj) {
1.173 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.174 + }
1.175 +
1.176 + /**
1.177 + * Returns the <code>Policy</code> object of the specified type
1.178 + * which applies to this object.
1.179 + *
1.180 + * @param self The object reference which delegated to this delegate.
1.181 + * @param policy_type The type of policy to be obtained.
1.182 + * @return A <code>Policy</code> object of the type specified by
1.183 + * the policy_type parameter.
1.184 + * @exception org.omg.CORBA.BAD_PARAM raised when the value of policy type
1.185 + * is not valid either because the specified type is not supported by this
1.186 + * ORB or because a policy object of that type is not associated with this
1.187 + * Object.
1.188 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.189 + * package comments for unimplemented features</a>
1.190 + */
1.191 + public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self,
1.192 + int policy_type) {
1.193 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.194 + }
1.195 +
1.196 +
1.197 + /**
1.198 + * Retrieves the <code>DomainManagers</code> of this object.
1.199 + * This allows administration services (and applications) to retrieve the
1.200 + * domain managers, and hence the security and other policies applicable
1.201 + * to individual objects that are members of the domain.
1.202 + *
1.203 + * @param self The object reference which delegated to this delegate.
1.204 + * @return The list of immediately enclosing domain managers of this object.
1.205 + * At least one domain manager is always returned in the list since by
1.206 + * default each object is associated with at least one domain manager at
1.207 + * creation.
1.208 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.209 + * package comments for unimplemented features</a>
1.210 + */
1.211 + public org.omg.CORBA.DomainManager[] get_domain_managers(
1.212 + org.omg.CORBA.Object
1.213 + self) {
1.214 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.215 + }
1.216 +
1.217 +
1.218 + /**
1.219 + * Associates the policies passed in
1.220 + * with a newly created object reference that it returns. Only certain
1.221 + * policies that pertain to the invocation of an operation at the client
1.222 + * end can be overridden using this operation. Attempts to override any
1.223 + * other policy will result in the raising of the CORBA::NO_PERMISSION
1.224 + * exception.
1.225 + *
1.226 + * @param self The object reference which delegated to this delegate.
1.227 + * @param policies A sequence of references to Policy objects.
1.228 + * @param set_add Indicates whether these policies should be added
1.229 + * onto any otheroverrides that already exist (ADD_OVERRIDE) in
1.230 + * the object reference, or they should be added to a clean
1.231 + * override free object reference (SET_OVERRIDE).
1.232 + * @return A new object reference with the new policies associated with it.
1.233 + *
1.234 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.235 + * package comments for unimplemented features</a>
1.236 + */
1.237 + public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self,
1.238 + org.omg.CORBA.Policy[] policies,
1.239 + org.omg.CORBA.SetOverrideType set_add) {
1.240 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.241 + }
1.242 +
1.243 +
1.244 + /**
1.245 + * Returns true if this object is implemented by a local servant.
1.246 + *
1.247 + * @param self The object reference which delegated to this delegate.
1.248 + * @return true only if the servant incarnating this object is located in
1.249 + * this Java VM. Return false if the servant is not local or the ORB
1.250 + * does not support local stubs for this particular servant. The default
1.251 + * behavior of is_local() is to return false.
1.252 + */
1.253 + public boolean is_local(org.omg.CORBA.Object self) {
1.254 + return false;
1.255 + }
1.256 +
1.257 + /**
1.258 + * Returns a Java reference to the servant which should be used for this
1.259 + * request. servant_preinvoke() is invoked by a local stub.
1.260 + * If a ServantObject object is returned, then its servant field
1.261 + * has been set to an object of the expected type (Note: the object may
1.262 + * or may not be the actual servant instance). The local stub may cast
1.263 + * the servant field to the expected type, and then invoke the operation
1.264 + * directly. The ServantRequest object is valid for only one invocation,
1.265 + * and cannot be used for more than one invocation.
1.266 + *
1.267 + * @param self The object reference which delegated to this delegate.
1.268 + *
1.269 + * @param operation a string containing the operation name.
1.270 + * The operation name corresponds to the operation name as it would be
1.271 + * encoded in a GIOP request.
1.272 + *
1.273 + * @param expectedType a Class object representing the expected type of the servant.
1.274 + * The expected type is the Class object associated with the operations
1.275 + * class of the stub's interface (e.g. A stub for an interface Foo,
1.276 + * would pass the Class object for the FooOperations interface).
1.277 + *
1.278 + * @return a ServantObject object.
1.279 + * The method may return a null value if it does not wish to support
1.280 + * this optimization (e.g. due to security, transactions, etc).
1.281 + * The method must return null if the servant is not of the expected type.
1.282 + */
1.283 + public ServantObject servant_preinvoke(org.omg.CORBA.Object self,
1.284 + String operation,
1.285 + Class expectedType) {
1.286 + return null;
1.287 + }
1.288 +
1.289 + /**
1.290 + * servant_postinvoke() is invoked by the local stub after the operation
1.291 + * has been invoked on the local servant.
1.292 + * This method must be called if servant_preinvoke() returned a non-null
1.293 + * value, even if an exception was thrown by the servant's method.
1.294 + * For this reason, the call to servant_postinvoke() should be placed
1.295 + * in a Java finally clause.
1.296 + *
1.297 + * @param self The object reference which delegated to this delegate.
1.298 + *
1.299 + * @param servant the instance of the ServantObject returned from
1.300 + * the servant_preinvoke() method.
1.301 + */
1.302 + public void servant_postinvoke(org.omg.CORBA.Object self,
1.303 + ServantObject servant) {
1.304 + }
1.305 +
1.306 + /**
1.307 + * request is called by a stub to obtain an OutputStream for
1.308 + * marshaling arguments. The stub must supply the operation name,
1.309 + * and indicate if a response is expected (i.e is this a oneway
1.310 + * call).
1.311 + *
1.312 + * @param self The object reference which delegated to this delegate.
1.313 + * @param operation a string containing the operation name.
1.314 + * The operation name corresponds to the operation name as it would be
1.315 + * encoded in a GIOP request.
1.316 + * @param responseExpected false if the operation is a one way operation,
1.317 + * and true otherwise.
1.318 + * @return OutputStream the OutputStream into which request arguments
1.319 + * can be marshaled.
1.320 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.321 + * package comments for unimplemented features</a>
1.322 + */
1.323 + public OutputStream request(org.omg.CORBA.Object self,
1.324 + String operation,
1.325 + boolean responseExpected) {
1.326 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.327 + }
1.328 +
1.329 + /**
1.330 + * invoke is called by a stub to invoke an operation. The stub provides an
1.331 + * OutputStream that was previously returned by a request()
1.332 + * call. invoke returns an InputStream which contains the
1.333 + * marshaled reply. If an exception occurs, invoke may throw an
1.334 + * ApplicationException object which contains an InputStream from
1.335 + * which the user exception state may be unmarshaled.
1.336 + *
1.337 + * @param self The object reference which delegated to this delegate.
1.338 + * @param output the OutputStream which contains marshaled arguments
1.339 + * @return input the InputStream from which reply parameters can be
1.340 + * unmarshaled.
1.341 + * @throws ApplicationException thrown when implementation throws
1.342 + * (upon invocation) an exception defined as part of its remote method
1.343 + * definition.
1.344 + * @throws RemarshalException thrown when remarshalling fails.
1.345 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.346 + * package comments for unimplemented features</a>
1.347 + */
1.348 + public InputStream invoke(org.omg.CORBA.Object self,
1.349 + OutputStream output)
1.350 + throws ApplicationException, RemarshalException {
1.351 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.352 + }
1.353 +
1.354 + /**
1.355 + * releaseReply may optionally be called by a stub to release a
1.356 + * reply stream back to the ORB when the unmarshaling has
1.357 + * completed. The stub passes the InputStream returned by
1.358 + * invoke() or ApplicationException.getInputStream(). A null
1.359 + * value may also be passed to releaseReply, in which case the
1.360 + * method is a noop.
1.361 + *
1.362 + * @param self The object reference which delegated to this delegate.
1.363 + * @param input the InputStream returned from invoke().
1.364 + * @see <a href="package-summary.html#unimpl"><code>portable</code>
1.365 + * package comments for unimplemented features</a>
1.366 + */
1.367 + public void releaseReply(org.omg.CORBA.Object self,
1.368 + InputStream input) {
1.369 + throw new org.omg.CORBA.NO_IMPLEMENT();
1.370 + }
1.371 +
1.372 + /**
1.373 + * Provides the implementation to override the toString() method
1.374 + * of the delegating CORBA object.
1.375 + *
1.376 + * @param self the object reference that delegated to this delegate
1.377 + * @return a <code>String</code> object that represents the object
1.378 + * reference that delegated to this <code>Delegate</code>
1.379 + * object
1.380 + */
1.381 +
1.382 + public String toString(org.omg.CORBA.Object self) {
1.383 + return self.getClass().getName() + ":" + this.toString();
1.384 + }
1.385 +
1.386 + /**
1.387 + * Provides the implementation to override the hashCode() method
1.388 + * of the delegating CORBA object.
1.389 + *
1.390 + * @param self the object reference that delegated to this delegate
1.391 + * @return an <code>int</code> that represents the hashcode for the
1.392 + * object reference that delegated to this <code>Delegate</code>
1.393 + * object
1.394 + */
1.395 + public int hashCode(org.omg.CORBA.Object self) {
1.396 + return System.identityHashCode(self);
1.397 + }
1.398 +
1.399 + /**
1.400 + * Provides the implementation to override the equals(java.lang.Object obj)
1.401 + * method of the delegating CORBA object.
1.402 + *
1.403 + * @param self the object reference that delegated to this delegate
1.404 + * @param obj the <code>Object</code> with which to compare
1.405 + * @return <code>true</code> if <code>obj</code> equals <code>self</code>;
1.406 + * <code>false</code> otherwise
1.407 + */
1.408 + public boolean equals(org.omg.CORBA.Object self, java.lang.Object obj) {
1.409 + return (self == obj);
1.410 + }
1.411 +}
