001: /*
002: * Copyright 1995-1999 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package org.omg.CORBA;
027:
028: /**
029: * The definition for a CORBA object reference.
030: * <p>
031: * A CORBA object reference is a handle for a particular
032: * CORBA object implemented by a server. A CORBA object reference
033: * identifies the same CORBA object each time the reference is used to invoke
034: * a method on the object.
035: * A CORBA object may have multiple, distinct object references.
036: * <p>
037: * The <code>org.omg.CORBA.Object</code> interface is the root of
038: * the inheritance hierarchy for all CORBA object references in the Java
039: * programming language, analogous to <code>java.rmi.Remote</code>
040: * for RMI remote objects.
041: * <p>
042: * A CORBA object may be either local or remote.
043: * If it is a local object (that is, running in the same
044: * VM as the client), invocations may be directly serviced by
045: * the object instance, and the object reference could point to the actual
046: * instance of the object implementation class.
047: * If a CORBA object is a remote object (that is, running in a different
048: * VM from the client), the object reference points to a stub (proxy) which uses the
049: * ORB machinery to make a remote invocation on the server where the object
050: * implementation resides.
051: * <p>
052: * Default implementations of the methods in the interface
053: * <code>org.omg.CORBA.Object</code>
054: * are provided in the class <code>org.omg.CORBA.portable.ObjectImpl</code>,
055: * which is the base class for stubs and object implementations.
056: * <p>
057: * @see org.omg.CORBA.portable.ObjectImpl
058: */
059:
060: public interface Object {
061:
062: /**
063: * Checks whether this object is an instance of a class that
064: * implements the given interface.
065: *
066: * @param repositoryIdentifier the interface to check against
067: * @return <code>true</code> if this object reference is an instance
068: * of a class that implements the interface;
069: * <code>false</code> otherwise
070: */
071: boolean _is_a(String repositoryIdentifier);
072:
073: /**
074: * Determines whether the two object references are equivalent,
075: * so far as the ORB can easily determine. Two object references are equivalent
076: * if they are identical. Two distinct object references which in fact refer to
077: * the same object are also equivalent. However, ORBs are not required
078: * to attempt determination of whether two distinct object references
079: * refer to the same object, since such determination could be impractically
080: * expensive.
081: * @param other the other object reference with which to check for equivalence
082: * @return <code>true</code> if this object reference is known to be
083: * equivalent to the given object reference.
084: * Note that <code>false</code> indicates only that the two
085: * object references are distinct, not necessarily that
086: * they reference distinct objects.
087: */
088: boolean _is_equivalent(org.omg.CORBA.Object other);
089:
090: /**
091: * Determines whether the server object for this object reference has been
092: * destroyed.
093: * @return <code>true</code> if the ORB knows authoritatively that the
094: * server object does not exist; <code>false</code> otherwise
095: */
096: boolean _non_existent();
097:
098: /**
099: * Returns an ORB-internal identifier for this object reference.
100: * This is a hash identifier, which does
101: * not change during the lifetime of the object reference, and so
102: * neither will any hash function of that identifier change. The value returned
103: * is not guaranteed to be unique; in other words, another object
104: * reference may have the same hash value.
105: * If two object references hash differently,
106: * then they are distinct object references; however, both may still refer
107: * to the same CORBA object.
108: *
109: * @param maximum the upper bound on the hash value returned by the ORB
110: * @return the ORB-internal hash identifier for this object reference
111: */
112: int _hash(int maximum);
113:
114: /**
115: * Returns a duplicate of this CORBA object reference.
116: * The server object implementation is not involved in creating
117: * the duplicate, and the implementation cannot distinguish whether
118: * the original object reference or a duplicate was used to make a request.
119: * <P>
120: * Note that this method is not very useful in the Java platform,
121: * since memory management is handled by the VM.
122: * It is included for compliance with the CORBA APIs.
123: * <P>
124: * The method <code>_duplicate</code> may return this object reference itself.
125: *
126: * @return a duplicate of this object reference or this object reference
127: * itself
128: */
129: org.omg.CORBA.Object _duplicate();
130:
131: /**
132: * Signals that the caller is done using this object reference, so
133: * internal ORB resources associated with this object reference can be
134: * released. Note that the object implementation is not involved in
135: * this operation, and other references to the same object are not affected.
136: */
137: void _release();
138:
139: /**
140: * Obtains an <code>InterfaceDef</code> for the object implementation
141: * referenced by this object reference.
142: * The <code>InterfaceDef</code> object
143: * may be used to introspect on the methods, attributes, and other
144: * type information for the object referred to by this object reference.
145: *
146: * @return the <code>InterfaceDef</code> object in the Interface Repository
147: * which provides type information about the object referred to by
148: * this object reference
149: */
150: org.omg.CORBA.Object _get_interface_def();
151:
152: /**
153: * Creates a <code>Request</code> instance for use in the
154: * Dynamic Invocation Interface.
155: *
156: * @param operation the name of the method to be invoked using the
157: * <code>Request</code> instance
158: * @return the newly-created <code>Request</code> instance
159: */
160: Request _request(String operation);
161:
162: /**
163: * Creates a <code>Request</code> instance initialized with the
164: * given context, method name, list of arguments, and container
165: * for the method's return value.
166: *
167: * @param ctx a <code>Context</code> object containing
168: * a list of properties
169: * @param operation the name of the method to be invoked
170: * @param arg_list an <code>NVList</code> containing the actual arguments
171: * to the method being invoked
172: * @param result a <code>NamedValue</code> object to serve as a
173: * container for the method's return value
174: * @return the newly-created <code>Request</code> object
175: *
176: * @see Request
177: * @see NVList
178: * @see NamedValue
179: */
180:
181: Request _create_request(Context ctx, String operation,
182: NVList arg_list, NamedValue result);
183:
184: /**
185: * Creates a <code>Request</code> instance initialized with the
186: * given context, method name, list of arguments, container
187: * for the method's return value, list of possible exceptions,
188: * and list of context strings needing to be resolved.
189: *
190: * @param ctx a <code>Context</code> object containing
191: * a list of properties
192: * @param operation the name of the method to be invoked
193: * @param arg_list an <code>NVList</code> containing the actual arguments
194: * to the method being invoked
195: * @param result a <code>NamedValue</code> object to serve as a
196: * container for the method's return value
197: * @param exclist an <code>ExceptionList</code> object containing a
198: * list of possible exceptions the method can throw
199: * @param ctxlist a <code>ContextList</code> object containing a list of
200: * context strings that need to be resolved and sent with the
201: * <code>Request</code> instance
202: * @return the newly-created <code>Request</code> object
203: *
204: * @see Request
205: * @see NVList
206: * @see NamedValue
207: * @see ExceptionList
208: * @see ContextList
209: */
210:
211: Request _create_request(Context ctx, String operation,
212: NVList arg_list, NamedValue result, ExceptionList exclist,
213: ContextList ctxlist);
214:
215: /**
216: * Returns the <code>Policy</code> object of the specified type
217: * which applies to this object.
218: *
219: * @param policy_type the type of policy to be obtained
220: * @return A <code>Policy</code> object of the type specified by
221: * the policy_type parameter
222: * @exception org.omg.CORBA.BAD_PARAM when the value of policy type
223: * is not valid either because the specified type is not supported by this
224: * ORB or because a policy object of that type is not associated with this
225: * Object
226: */
227: Policy _get_policy(int policy_type);
228:
229: /**
230: * Retrieves the <code>DomainManagers</code> of this object.
231: * This allows administration services (and applications) to retrieve the
232: * domain managers, and hence the security and other policies applicable
233: * to individual objects that are members of the domain.
234: *
235: * @return the list of immediately enclosing domain managers of this object.
236: * At least one domain manager is always returned in the list since by
237: * default each object is associated with at least one domain manager at
238: * creation.
239: */
240: DomainManager[] _get_domain_managers();
241:
242: /**
243: * Returns a new <code>Object</code> with the given policies
244: * either replacing any existing policies in this
245: * <code>Object</code> or with the given policies added
246: * to the existing ones, depending on the value of the
247: * given <code>SetOverrideType</code> object.
248: *
249: * @param policies an array of <code>Policy</code> objects containing
250: * the policies to be added or to be used as replacements
251: * @param set_add either <code>SetOverrideType.SET_OVERRIDE</code>, indicating
252: * that the given policies will replace any existing ones, or
253: * <code>SetOverrideType.ADD_OVERRIDE</code>, indicating that
254: * the given policies should be added to any existing ones
255: * @return a new <code>Object</code> with the given policies replacing
256: * or added to those in this <code>Object</code>
257: */
258: org.omg.CORBA.Object _set_policy_override(Policy[] policies,
259: SetOverrideType set_add);
260:
261: }
|