1. /*

  2.  * @(#)Object.java	1.48 00/02/02

  3.  *

  4.  * Copyright 1995-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package org.omg.CORBA;

  12. 

  13. /**

  14.  * The definition for a CORBA object reference.

  15.  * <p>

  16.  * A CORBA object reference is a handle for a particular

  17.  * CORBA object implemented by a server. A CORBA object reference

  18.  * identifies the same CORBA object each time the reference is used to invoke

  19.  * a method on the object.

  20.  * A CORBA object may have multiple, distinct object references.

  21.  * <p>

  22.  * The <code>org.omg.CORBA.Object</code> interface is the root of

  23.  * the inheritance hierarchy for all CORBA object references in the Java

  24.  * programming language, analogous to <code>java.rmi.Remote</code>

  25.  * for RMI remote objects.

  26.  * <p>

  27.  * A CORBA object may be either local or remote.

  28.  * If it is a local object (that is, running in the same

  29.  * VM as the client), invocations may be directly serviced by

  30.  * the object instance, and the object reference could point to the actual

  31.  * instance of the object implementation class.

  32.  * If a CORBA object is a remote object (that is, running in a different

  33.  * VM from the client), the object reference points to a stub (proxy) which uses the

  34.  * ORB machinery to make a remote invocation on the server where the object

  35.  * implementation resides.

  36.  * <p>

  37.  * Default implementations of the methods in the interface

  38.  * <code>org.omg.CORBA.Object</code>

  39.  * are provided in the class <code>org.omg.CORBA.portable.ObjectImpl</code>,

  40.  * which is the base class for stubs and object implementations.

  41.  * <p>

  42.  * @see org.omg.CORBA.portable.ObjectImpl

  43.  */

  44. 

  45. public interface Object {

  46. 

  47.     /**

  48.      * Checks whether this object is an instance of a class that

  49.      * implements the given interface.

  50.      *

  51.      * @param repositoryIdentifier the interface to check against

  52.      * @return <code>true</code> if this object reference is an instance

  53.      *         of a class that implements the interface;

  54.      *         <code>false</code> otherwise

  55.      */

  56.     boolean _is_a(String repositoryIdentifier);

  57. 

  58. 

  59.     /**

  60.      * Determines whether the two object references are equivalent,

  61.      * so far as the ORB can easily determine. Two object references are equivalent

  62.      * if they are identical. Two distinct object references which in fact refer to

  63.      * the same object are also equivalent. However, ORBs are not required

  64.      * to attempt determination of whether two distinct object references

  65.      * refer to the same object, since such determination could be impractically

  66.      * expensive.

  67.      * @param other the other object reference with which to check for equivalence

  68.      * @return <code>true</code> if this object reference is known to be

  69.      *         equivalent to the given object reference.

  70.      *         Note that <code>false</code> indicates only that the two

  71.      *         object references are distinct, not necessarily that

  72.      *         they reference distinct objects.

  73.      */

  74.     boolean _is_equivalent(org.omg.CORBA.Object other);

  75. 

  76. 

  77.     /**

  78.      * Determines whether the server object for this object reference has been

  79.      * destroyed.

  80.      * @return <code>true</code> if the ORB knows authoritatively that the

  81.      *         server object does not exist; <code>false</code> otherwise

  82.      */

  83.     boolean _non_existent();

  84. 

  85. 

  86.     /**

  87.      * Returns an ORB-internal identifier for this object reference.

  88.      * This is a hash identifier, which does

  89.      * not change during the lifetime of the object reference, and so

  90.      * neither will any hash function of that identifier change. The value returned

  91.      * is not guaranteed to be unique; in other words, another object

  92.      * reference may have the same hash value.

  93.      * If two object references hash differently,

  94.      * then they are distinct object references; however, both may still refer

  95.      * to the same CORBA object.

  96.      *

  97.      * @param maximum the upper bound on the hash value returned by the ORB

  98.      * @return the ORB-internal hash identifier for this object reference

  99.      */

  100.     int _hash(int maximum);

  101. 

  102. 

  103.     /**

  104.      * Returns a duplicate of this CORBA object reference.

  105.      * The server object implementation is not involved in creating

  106.      * the duplicate, and the implementation cannot distinguish whether

  107.      * the original object reference or a duplicate was used to make a request.

  108.      * <P>

  109.      * Note that this method is not very useful in the Java platform,

  110.      * since memory management is handled by the VM.

  111.      * It is included for compliance with the CORBA APIs.

  112.      * <P>

  113.      * The method <code>_duplicate</code> may return this object reference itself.

  114.      *

  115.      * @return a duplicate of this object reference or this object reference

  116.      *         itself

  117.      */

  118.     org.omg.CORBA.Object _duplicate();

  119. 

  120. 

  121.     /**

  122.      * Signals that the caller is done using this object reference, so

  123.      * internal ORB resources associated with this object reference can be

  124.      * released. Note that the object implementation is not involved in

  125.      * this operation, and other references to the same object are not affected.

  126.      */

  127.     void _release();

  128. 

  129. 

  130.     /**

  131.      * Obtains an <code>InterfaceDef</code> for the object implementation

  132.      * referenced by this object reference.

  133.      * The <code>InterfaceDef</code> object

  134.      * may be used to introspect on the methods, attributes, and other

  135.      * type information for the object referred to by this object reference.

  136.      *

  137.      * @return the <code>InterfaceDef</code> object in the Interface Repository

  138.      *         which provides type information about the object referred to by

  139.      *         this object reference

  140.      */

  141.     org.omg.CORBA.Object _get_interface_def();

  142. 

  143. 

  144. 

  145.     /**

  146.      * Creates a <code>Request</code> instance for use in the

  147.      * Dynamic Invocation Interface.

  148.      *

  149.      * @param operation  the name of the method to be invoked using the

  150.      *		              <code>Request</code> instance

  151.      * @return the newly-created <code>Request</code> instance

  152.      */

  153.     Request _request(String operation);

  154. 

  155. 

  156. 

  157.     /**

  158.      * Creates a <code>Request</code> instance initialized with the

  159.      * given context, method name, list of arguments, and container

  160.      * for the method's return value.

  161.      *

  162.      * @param ctx			a <code>Context</code> object containing

  163.      *                     a list of properties

  164.      * @param operation    the name of the method to be invoked

  165.      * @param arg_list		an <code>NVList</code> containing the actual arguments

  166.      *                     to the method being invoked

  167.      * @param result		a <code>NamedValue</code> object to serve as a

  168.      *                     container for the method's return value

  169.      * @return			the newly-created <code>Request</code> object

  170.      *

  171.      * @see Request

  172.      * @see NVList

  173.      * @see NamedValue

  174.      */

  175. 

  176.     Request _create_request(Context ctx,

  177. 			    String operation,

  178. 			    NVList arg_list,

  179. 			    NamedValue result);

  180. 

  181.     /**

  182.      * Creates a <code>Request</code> instance initialized with the

  183.      * given context, method name, list of arguments, container

  184.      * for the method's return value, list of possible exceptions,

  185.      * and list of context strings needing to be resolved.

  186.      *

  187.      * @param ctx			a <code>Context</code> object containing

  188.      *                     a list of properties

  189.      * @param operation    the name of the method to be invoked

  190.      * @param arg_list		an <code>NVList</code> containing the actual arguments

  191.      *                     to the method being invoked

  192.      * @param result		a <code>NamedValue</code> object to serve as a

  193.      *                     container for the method's return value

  194.      * @param exclist		an <code>ExceptionList</code> object containing a

  195.      *                     list of possible exceptions the method can throw

  196.      * @param ctxlist		a <code>ContextList</code> object containing a list of

  197.      *                     context strings that need to be resolved and sent with the

  198.      * 			     	<code>Request</code> instance

  199.      * @return			the newly-created <code>Request</code> object

  200.      *

  201.      * @see Request

  202.      * @see NVList

  203.      * @see NamedValue

  204.      * @see ExceptionList

  205.      * @see ContextList

  206.      */

  207. 

  208.     Request _create_request(Context ctx,

  209. 			    String operation,

  210. 			    NVList arg_list,

  211. 			    NamedValue result,

  212. 			    ExceptionList exclist,

  213. 			    ContextList ctxlist);

  214. 

  215. 

  216. 

  217. 

  218.     /**

  219.      * Returns the <code>Policy</code> object of the specified type 

  220.      * which applies to this object.

  221.      * 

  222.      * @param policy_type the type of policy to be obtained

  223.      * @return A <code>Policy</code> object of the type specified by 

  224.      *         the policy_type parameter

  225.      * @exception org.omg.CORBA.BAD_PARAM when the value of policy type 

  226.      * is not valid either because the specified type is not supported by this 

  227.      * ORB or because a policy object of that type is not associated with this 

  228.      * Object

  229.      */

  230.     Policy _get_policy(int policy_type);

  231. 

  232. 

  233.     /**

  234.      * Retrieves the <code>DomainManagers</code> of this object.

  235.      * This allows administration services (and applications) to retrieve the 

  236.      * domain managers, and hence the security and other policies applicable 

  237.      * to individual objects that are members of the domain.

  238.      * 

  239.      * @return the list of immediately enclosing domain managers of this object.

  240.      *  At least one domain manager is always returned in the list since by 

  241.      * default each object is associated with at least one domain manager at 

  242.      * creation.

  243.      */

  244.     DomainManager[] _get_domain_managers();

  245. 

  246. 

  247.     /**

  248.      * Returns a new <code>Object</code> with the given policies

  249. 	 * either replacing any existing policies in this

  250. 	 * <code>Object</code> or with the given policies added 

  251. 	 * to the existing ones, depending on the value of the

  252. 	 * given <code>SetOverrideType</code> object.

  253. 	 * 

  254. 	 * @param policies an array of <code>Policy</code> objects containing

  255. 	 *                 the policies to be added or to be used as replacements

  256. 	 * @param set_add either <code>SetOverrideType.SET_OVERRIDE</code>, indicating

  257. 	 *                that the given policies will replace any existing ones, or

  258. 	 *                <code>SetOverrideType.ADD_OVERRIDE</code>, indicating that

  259. 	 *                the given policies should be added to any existing ones

  260. 	 * @return a new <code>Object</code> with the given policies replacing

  261. 	 *         or added to those in this <code>Object</code>

  262.      */

  263.     org.omg.CORBA.Object _set_policy_override(Policy[] policies,

  264.                                               SetOverrideType set_add);

  265. 

  266. 

  267. }