duke@1: /* ohair@158: * Copyright (c) 1995, 1999, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@158: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@158: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@158: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@158: * or visit www.oracle.com if you need additional information or have any ohair@158: * questions. duke@1: */ duke@1: duke@1: package org.omg.CORBA; duke@1: duke@1: /** duke@1: * The definition for a CORBA object reference. duke@1: *
duke@1: * A CORBA object reference is a handle for a particular duke@1: * CORBA object implemented by a server. A CORBA object reference duke@1: * identifies the same CORBA object each time the reference is used to invoke duke@1: * a method on the object. duke@1: * A CORBA object may have multiple, distinct object references. duke@1: *
duke@1: * The org.omg.CORBA.Object
interface is the root of
duke@1: * the inheritance hierarchy for all CORBA object references in the Java
duke@1: * programming language, analogous to java.rmi.Remote
duke@1: * for RMI remote objects.
duke@1: *
duke@1: * A CORBA object may be either local or remote. duke@1: * If it is a local object (that is, running in the same duke@1: * VM as the client), invocations may be directly serviced by duke@1: * the object instance, and the object reference could point to the actual duke@1: * instance of the object implementation class. duke@1: * If a CORBA object is a remote object (that is, running in a different duke@1: * VM from the client), the object reference points to a stub (proxy) which uses the duke@1: * ORB machinery to make a remote invocation on the server where the object duke@1: * implementation resides. duke@1: *
duke@1: * Default implementations of the methods in the interface
duke@1: * org.omg.CORBA.Object
duke@1: * are provided in the class org.omg.CORBA.portable.ObjectImpl
,
duke@1: * which is the base class for stubs and object implementations.
duke@1: *
duke@1: * @see org.omg.CORBA.portable.ObjectImpl
duke@1: */
duke@1:
duke@1: public interface Object {
duke@1:
duke@1: /**
duke@1: * Checks whether this object is an instance of a class that
duke@1: * implements the given interface.
duke@1: *
duke@1: * @param repositoryIdentifier the interface to check against
duke@1: * @return true
if this object reference is an instance
duke@1: * of a class that implements the interface;
duke@1: * false
otherwise
duke@1: */
duke@1: boolean _is_a(String repositoryIdentifier);
duke@1:
duke@1:
duke@1: /**
duke@1: * Determines whether the two object references are equivalent,
duke@1: * so far as the ORB can easily determine. Two object references are equivalent
duke@1: * if they are identical. Two distinct object references which in fact refer to
duke@1: * the same object are also equivalent. However, ORBs are not required
duke@1: * to attempt determination of whether two distinct object references
duke@1: * refer to the same object, since such determination could be impractically
duke@1: * expensive.
duke@1: * @param other the other object reference with which to check for equivalence
duke@1: * @return true
if this object reference is known to be
duke@1: * equivalent to the given object reference.
duke@1: * Note that false
indicates only that the two
duke@1: * object references are distinct, not necessarily that
duke@1: * they reference distinct objects.
duke@1: */
duke@1: boolean _is_equivalent(org.omg.CORBA.Object other);
duke@1:
duke@1:
duke@1: /**
duke@1: * Determines whether the server object for this object reference has been
duke@1: * destroyed.
duke@1: * @return true
if the ORB knows authoritatively that the
duke@1: * server object does not exist; false
otherwise
duke@1: */
duke@1: boolean _non_existent();
duke@1:
duke@1:
duke@1: /**
duke@1: * Returns an ORB-internal identifier for this object reference.
duke@1: * This is a hash identifier, which does
duke@1: * not change during the lifetime of the object reference, and so
duke@1: * neither will any hash function of that identifier change. The value returned
duke@1: * is not guaranteed to be unique; in other words, another object
duke@1: * reference may have the same hash value.
duke@1: * If two object references hash differently,
duke@1: * then they are distinct object references; however, both may still refer
duke@1: * to the same CORBA object.
duke@1: *
duke@1: * @param maximum the upper bound on the hash value returned by the ORB
duke@1: * @return the ORB-internal hash identifier for this object reference
duke@1: */
duke@1: int _hash(int maximum);
duke@1:
duke@1:
duke@1: /**
duke@1: * Returns a duplicate of this CORBA object reference.
duke@1: * The server object implementation is not involved in creating
duke@1: * the duplicate, and the implementation cannot distinguish whether
duke@1: * the original object reference or a duplicate was used to make a request.
duke@1: *
duke@1: * Note that this method is not very useful in the Java platform, duke@1: * since memory management is handled by the VM. duke@1: * It is included for compliance with the CORBA APIs. duke@1: *
duke@1: * The method _duplicate
may return this object reference itself.
duke@1: *
duke@1: * @return a duplicate of this object reference or this object reference
duke@1: * itself
duke@1: */
duke@1: org.omg.CORBA.Object _duplicate();
duke@1:
duke@1:
duke@1: /**
duke@1: * Signals that the caller is done using this object reference, so
duke@1: * internal ORB resources associated with this object reference can be
duke@1: * released. Note that the object implementation is not involved in
duke@1: * this operation, and other references to the same object are not affected.
duke@1: */
duke@1: void _release();
duke@1:
duke@1:
duke@1: /**
duke@1: * Obtains an InterfaceDef
for the object implementation
duke@1: * referenced by this object reference.
duke@1: * The InterfaceDef
object
duke@1: * may be used to introspect on the methods, attributes, and other
duke@1: * type information for the object referred to by this object reference.
duke@1: *
duke@1: * @return the InterfaceDef
object in the Interface Repository
duke@1: * which provides type information about the object referred to by
duke@1: * this object reference
duke@1: */
duke@1: org.omg.CORBA.Object _get_interface_def();
duke@1:
duke@1:
duke@1:
duke@1: /**
duke@1: * Creates a Request
instance for use in the
duke@1: * Dynamic Invocation Interface.
duke@1: *
duke@1: * @param operation the name of the method to be invoked using the
duke@1: * Request
instance
duke@1: * @return the newly-created Request
instance
duke@1: */
duke@1: Request _request(String operation);
duke@1:
duke@1:
duke@1:
duke@1: /**
duke@1: * Creates a Request
instance initialized with the
duke@1: * given context, method name, list of arguments, and container
duke@1: * for the method's return value.
duke@1: *
duke@1: * @param ctx a Context
object containing
duke@1: * a list of properties
duke@1: * @param operation the name of the method to be invoked
duke@1: * @param arg_list an NVList
containing the actual arguments
duke@1: * to the method being invoked
duke@1: * @param result a NamedValue
object to serve as a
duke@1: * container for the method's return value
duke@1: * @return the newly-created Request
object
duke@1: *
duke@1: * @see Request
duke@1: * @see NVList
duke@1: * @see NamedValue
duke@1: */
duke@1:
duke@1: Request _create_request(Context ctx,
duke@1: String operation,
duke@1: NVList arg_list,
duke@1: NamedValue result);
duke@1:
duke@1: /**
duke@1: * Creates a Request
instance initialized with the
duke@1: * given context, method name, list of arguments, container
duke@1: * for the method's return value, list of possible exceptions,
duke@1: * and list of context strings needing to be resolved.
duke@1: *
duke@1: * @param ctx a Context
object containing
duke@1: * a list of properties
duke@1: * @param operation the name of the method to be invoked
duke@1: * @param arg_list an NVList
containing the actual arguments
duke@1: * to the method being invoked
duke@1: * @param result a NamedValue
object to serve as a
duke@1: * container for the method's return value
duke@1: * @param exclist an ExceptionList
object containing a
duke@1: * list of possible exceptions the method can throw
duke@1: * @param ctxlist a ContextList
object containing a list of
duke@1: * context strings that need to be resolved and sent with the
duke@1: * Request
instance
duke@1: * @return the newly-created Request
object
duke@1: *
duke@1: * @see Request
duke@1: * @see NVList
duke@1: * @see NamedValue
duke@1: * @see ExceptionList
duke@1: * @see ContextList
duke@1: */
duke@1:
duke@1: Request _create_request(Context ctx,
duke@1: String operation,
duke@1: NVList arg_list,
duke@1: NamedValue result,
duke@1: ExceptionList exclist,
duke@1: ContextList ctxlist);
duke@1:
duke@1:
duke@1:
duke@1:
duke@1: /**
duke@1: * Returns the Policy
object of the specified type
duke@1: * which applies to this object.
duke@1: *
duke@1: * @param policy_type the type of policy to be obtained
duke@1: * @return A Policy
object of the type specified by
duke@1: * the policy_type parameter
duke@1: * @exception org.omg.CORBA.BAD_PARAM when the value of policy type
duke@1: * is not valid either because the specified type is not supported by this
duke@1: * ORB or because a policy object of that type is not associated with this
duke@1: * Object
duke@1: */
duke@1: Policy _get_policy(int policy_type);
duke@1:
duke@1:
duke@1: /**
duke@1: * Retrieves the DomainManagers
of this object.
duke@1: * This allows administration services (and applications) to retrieve the
duke@1: * domain managers, and hence the security and other policies applicable
duke@1: * to individual objects that are members of the domain.
duke@1: *
duke@1: * @return the list of immediately enclosing domain managers of this object.
duke@1: * At least one domain manager is always returned in the list since by
duke@1: * default each object is associated with at least one domain manager at
duke@1: * creation.
duke@1: */
duke@1: DomainManager[] _get_domain_managers();
duke@1:
duke@1:
duke@1: /**
duke@1: * Returns a new Object
with the given policies
duke@1: * either replacing any existing policies in this
duke@1: * Object
or with the given policies added
duke@1: * to the existing ones, depending on the value of the
duke@1: * given SetOverrideType
object.
duke@1: *
duke@1: * @param policies an array of Policy
objects containing
duke@1: * the policies to be added or to be used as replacements
duke@1: * @param set_add either SetOverrideType.SET_OVERRIDE
, indicating
duke@1: * that the given policies will replace any existing ones, or
duke@1: * SetOverrideType.ADD_OVERRIDE
, indicating that
duke@1: * the given policies should be added to any existing ones
duke@1: * @return a new Object
with the given policies replacing
duke@1: * or added to those in this Object
duke@1: */
duke@1: org.omg.CORBA.Object _set_policy_override(Policy[] policies,
duke@1: SetOverrideType set_add);
duke@1:
duke@1:
duke@1: }