1 /*
2 * Copyright (c) 1995, 1999, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package org.omg.CORBA;
27
28 /**
29 * The definition for a CORBA object reference.
30 * <p>
31 * A CORBA object reference is a handle for a particular
32 * CORBA object implemented by a server. A CORBA object reference
33 * identifies the same CORBA object each time the reference is used to invoke
34 * a method on the object.
35 * A CORBA object may have multiple, distinct object references.
36 * <p>
37 * The <code>org.omg.CORBA.Object</code> interface is the root of
38 * the inheritance hierarchy for all CORBA object references in the Java
39 * programming language, analogous to <code>java.rmi.Remote</code>
40 * for RMI remote objects.
41 * <p>
42 * A CORBA object may be either local or remote.
43 * If it is a local object (that is, running in the same
44 * VM as the client), invocations may be directly serviced by
45 * the object instance, and the object reference could point to the actual
46 * instance of the object implementation class.
47 * If a CORBA object is a remote object (that is, running in a different
48 * VM from the client), the object reference points to a stub (proxy) which uses the
49 * ORB machinery to make a remote invocation on the server where the object
50 * implementation resides.
51 * <p>
52 * Default implementations of the methods in the interface
53 * <code>org.omg.CORBA.Object</code>
54 * are provided in the class <code>org.omg.CORBA.portable.ObjectImpl</code>,
55 * which is the base class for stubs and object implementations.
56 * <p>
57 * @see org.omg.CORBA.portable.ObjectImpl
58 */
59
60 public interface Object {
61
62 /**
63 * Checks whether this object is an instance of a class that
64 * implements the given interface.
65 *
66 * @param repositoryIdentifier the interface to check against
67 * @return <code>true</code> if this object reference is an instance
68 * of a class that implements the interface;
69 * <code>false</code> otherwise
70 */
71 boolean _is_a(String repositoryIdentifier);
72
73
74 /**
75 * Determines whether the two object references are equivalent,
76 * so far as the ORB can easily determine. Two object references are equivalent
77 * if they are identical. Two distinct object references which in fact refer to
78 * the same object are also equivalent. However, ORBs are not required
79 * to attempt determination of whether two distinct object references
80 * refer to the same object, since such determination could be impractically
81 * expensive.
82 * @param other the other object reference with which to check for equivalence
83 * @return <code>true</code> if this object reference is known to be
84 * equivalent to the given object reference.
85 * Note that <code>false</code> indicates only that the two
86 * object references are distinct, not necessarily that
87 * they reference distinct objects.
88 */
89 boolean _is_equivalent(org.omg.CORBA.Object other);
90
91
92 /**
93 * Determines whether the server object for this object reference has been
94 * destroyed.
95 * @return <code>true</code> if the ORB knows authoritatively that the
96 * server object does not exist; <code>false</code> otherwise
97 */
98 boolean _non_existent();
99
100
101 /**
102 * Returns an ORB-internal identifier for this object reference.
103 * This is a hash identifier, which does
104 * not change during the lifetime of the object reference, and so
105 * neither will any hash function of that identifier change. The value returned
106 * is not guaranteed to be unique; in other words, another object
107 * reference may have the same hash value.
108 * If two object references hash differently,
109 * then they are distinct object references; however, both may still refer
110 * to the same CORBA object.
111 *
112 * @param maximum the upper bound on the hash value returned by the ORB
113 * @return the ORB-internal hash identifier for this object reference
114 */
115 int _hash(int maximum);
116
117
118 /**
119 * Returns a duplicate of this CORBA object reference.
120 * The server object implementation is not involved in creating
121 * the duplicate, and the implementation cannot distinguish whether
122 * the original object reference or a duplicate was used to make a request.
123 * <P>
124 * Note that this method is not very useful in the Java platform,
125 * since memory management is handled by the VM.
126 * It is included for compliance with the CORBA APIs.
127 * <P>
128 * The method <code>_duplicate</code> may return this object reference itself.
129 *
130 * @return a duplicate of this object reference or this object reference
131 * itself
132 */
133 org.omg.CORBA.Object _duplicate();
134
135
136 /**
137 * Signals that the caller is done using this object reference, so
138 * internal ORB resources associated with this object reference can be
139 * released. Note that the object implementation is not involved in
140 * this operation, and other references to the same object are not affected.
141 */
142 void _release();
143
144
145 /**
146 * Obtains an <code>InterfaceDef</code> for the object implementation
147 * referenced by this object reference.
148 * The <code>InterfaceDef</code> object
149 * may be used to introspect on the methods, attributes, and other
150 * type information for the object referred to by this object reference.
151 *
152 * @return the <code>InterfaceDef</code> object in the Interface Repository
153 * which provides type information about the object referred to by
154 * this object reference
155 */
156 org.omg.CORBA.Object _get_interface_def();
157
158
159
160 /**
161 * Creates a <code>Request</code> instance for use in the
162 * Dynamic Invocation Interface.
163 *
164 * @param operation the name of the method to be invoked using the
165 * <code>Request</code> instance
166 * @return the newly-created <code>Request</code> instance
167 */
168 Request _request(String operation);
169
170
171
172 /**
173 * Creates a <code>Request</code> instance initialized with the
174 * given context, method name, list of arguments, and container
175 * for the method's return value.
176 *
177 * @param ctx a <code>Context</code> object containing
178 * a list of properties
179 * @param operation the name of the method to be invoked
180 * @param arg_list an <code>NVList</code> containing the actual arguments
181 * to the method being invoked
182 * @param result a <code>NamedValue</code> object to serve as a
183 * container for the method's return value
184 * @return the newly-created <code>Request</code> object
185 *
186 * @see Request
187 * @see NVList
188 * @see NamedValue
189 */
190
191 Request _create_request(Context ctx,
192 String operation,
193 NVList arg_list,
194 NamedValue result);
195
196 /**
197 * Creates a <code>Request</code> instance initialized with the
198 * given context, method name, list of arguments, container
199 * for the method's return value, list of possible exceptions,
200 * and list of context strings needing to be resolved.
201 *
202 * @param ctx a <code>Context</code> object containing
203 * a list of properties
204 * @param operation the name of the method to be invoked
205 * @param arg_list an <code>NVList</code> containing the actual arguments
206 * to the method being invoked
207 * @param result a <code>NamedValue</code> object to serve as a
208 * container for the method's return value
209 * @param exclist an <code>ExceptionList</code> object containing a
210 * list of possible exceptions the method can throw
211 * @param ctxlist a <code>ContextList</code> object containing a list of
212 * context strings that need to be resolved and sent with the
213 * <code>Request</code> instance
214 * @return the newly-created <code>Request</code> object
215 *
216 * @see Request
217 * @see NVList
218 * @see NamedValue
219 * @see ExceptionList
220 * @see ContextList
221 */
222
223 Request _create_request(Context ctx,
224 String operation,
225 NVList arg_list,
226 NamedValue result,
227 ExceptionList exclist,
228 ContextList ctxlist);
229
230
231
232
233 /**
234 * Returns the <code>Policy</code> object of the specified type
235 * which applies to this object.
236 *
237 * @param policy_type the type of policy to be obtained
238 * @return A <code>Policy</code> object of the type specified by
239 * the policy_type parameter
240 * @exception org.omg.CORBA.BAD_PARAM when the value of policy type
241 * is not valid either because the specified type is not supported by this
242 * ORB or because a policy object of that type is not associated with this
243 * Object
244 */
245 Policy _get_policy(int policy_type);
246
247
248 /**
249 * Retrieves the <code>DomainManagers</code> of this object.
250 * This allows administration services (and applications) to retrieve the
251 * domain managers, and hence the security and other policies applicable
252 * to individual objects that are members of the domain.
253 *
254 * @return the list of immediately enclosing domain managers of this object.
255 * At least one domain manager is always returned in the list since by
256 * default each object is associated with at least one domain manager at
257 * creation.
258 */
259 DomainManager[] _get_domain_managers();
260
261
262 /**
263 * Returns a new <code>Object</code> with the given policies
264 * either replacing any existing policies in this
265 * <code>Object</code> or with the given policies added
266 * to the existing ones, depending on the value of the
267 * given <code>SetOverrideType</code> object.
268 *
269 * @param policies an array of <code>Policy</code> objects containing
270 * the policies to be added or to be used as replacements
271 * @param set_add either <code>SetOverrideType.SET_OVERRIDE</code>, indicating
272 * that the given policies will replace any existing ones, or
273 * <code>SetOverrideType.ADD_OVERRIDE</code>, indicating that
274 * the given policies should be added to any existing ones
275 * @return a new <code>Object</code> with the given policies replacing
276 * or added to those in this <code>Object</code>
277 */
278 org.omg.CORBA.Object _set_policy_override(Policy[] policies,
279 SetOverrideType set_add);
280
281
282 }