1 /*
2 * Copyright (c) 1997, 2002, 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 package org.omg.CORBA.portable;
26
27 import org.omg.CORBA.Request;
28 import org.omg.CORBA.NamedValue;
29 import org.omg.CORBA.NVList;
30 import org.omg.CORBA.Context;
31 import org.omg.CORBA.ContextList;
32 import org.omg.CORBA.ExceptionList;
33 import org.omg.CORBA.TypeCode;
34 import org.omg.CORBA.SystemException;
35
36 /**
37 * Specifies a portable API for ORB-vendor-specific
38 * implementation of the org.omg.CORBA.Object methods.
39 *
40 * Each stub (proxy) contains a delegate
41 * object, to which all org.omg.CORBA.Object methods are forwarded.
42 * This allows a stub generated by one vendor's ORB to work with the delegate
43 * from another vendor's ORB.
44 *
45 * @see org.omg.CORBA.Object
46 * @author OMG
47 */
48
49 public abstract class Delegate {
50
51 /**
52 * Return an InterfaceDef for the object reference provided.
53 * @param self The object reference whose InterfaceDef needs to be returned
54 * @return the InterfaceDef
55 */
56 public abstract org.omg.CORBA.Object get_interface_def(
57 org.omg.CORBA.Object self);
58
59 /**
60 * Returns a duplicate of the object reference provided.
61 * @param obj The object reference whose duplicate needs to be returned
62 * @return the duplicate object reference
63 */
64 public abstract org.omg.CORBA.Object duplicate(org.omg.CORBA.Object obj);
65
66 /**
67 * Releases resources associated with the object reference provided.
68 * @param obj The object reference whose resources need to be released
69 */
70 public abstract void release(org.omg.CORBA.Object obj);
71
72 /**
73 * Checks if the object reference is an instance of the given interface.
74 * @param obj The object reference to be checked.
75 * @param repository_id The repository identifier of the interface
76 * to check against.
77 * @return true if the object reference supports the interface
78 */
79 public abstract boolean is_a(org.omg.CORBA.Object obj, String repository_id);
80
81 /**
82 * Determines whether the server object for the object reference has been
83 * destroyed.
84 * @param obj The object reference which delegated to this delegate.
85 * @return true if the ORB knows authoritatively that the server object does
86 * not exist, false otherwise
87 */
88 public abstract boolean non_existent(org.omg.CORBA.Object obj);
89
90 /**
91 * Determines if the two object references are equivalent.
92 * @param obj The object reference which delegated to this delegate.
93 * @param other The object reference to check equivalence against.
94 * @return true if the objects are CORBA-equivalent.
95 */
96 public abstract boolean is_equivalent(org.omg.CORBA.Object obj,
97 org.omg.CORBA.Object other);
98
99 /**
100 * Returns an ORB-internal identifier (hashcode) for this object reference.
101 * @param obj The object reference which delegated to this delegate.
102 * @param max specifies an upper bound on the hash value returned by
103 * the ORB.
104 * @return ORB-internal hash identifier for object reference
105 */
106 public abstract int hash(org.omg.CORBA.Object obj, int max);
107
108 /**
109 * Creates a Request instance for use in the Dynamic Invocation Interface.
110 * @param obj The object reference which delegated to this delegate.
111 * @param operation The name of the operation to be invoked using the
112 * Request instance.
113 * @return the created Request instance
114 */
115 public abstract Request request(org.omg.CORBA.Object obj, String operation);
116
117 /**
118 * Creates a Request instance for use in the Dynamic Invocation Interface.
119 *
120 * @param obj The object reference which delegated to this delegate.
121 * @param ctx The context to be used.
122 * @param operation The name of the operation to be
123 * invoked.
124 * @param arg_list The arguments to the operation in the
125 * form of an NVList.
126 * @param result A container for the result as a NamedValue.
127 * @return The created Request object.
128 *
129 */
130 public abstract Request create_request(org.omg.CORBA.Object obj,
131 Context ctx,
132 String operation,
133 NVList arg_list,
134 NamedValue result);
135
136 /**
137 * Creates a Request instance for use in the Dynamic Invocation Interface.
138 *
139 * @param obj The object reference which delegated to this delegate.
140 * @param ctx The context to be used.
141 * @param operation The name of the operation to be
142 * invoked.
143 * @param arg_list The arguments to the operation in the
144 * form of an NVList.
145 * @param result A container for the result as a NamedValue.
146 * @param exclist A list of possible exceptions the
147 * operation can throw.
148 * @param ctxlist A list of context strings that need
149 * to be resolved and sent with the
150 * Request.
151 * @return The created Request object.
152 */
153 public abstract Request create_request(org.omg.CORBA.Object obj,
154 Context ctx,
155 String operation,
156 NVList arg_list,
157 NamedValue result,
158 ExceptionList exclist,
159 ContextList ctxlist);
160
161 /**
162 * Provides a reference to the orb associated with its parameter.
163 *
164 * @param obj the object reference which delegated to this delegate.
165 * @return the associated orb.
166 * @see <a href="package-summary.html#unimpl"><code>portable</code>
167 * package comments for unimplemented features</a>
168 */
169 public org.omg.CORBA.ORB orb(org.omg.CORBA.Object obj) {
170 throw new org.omg.CORBA.NO_IMPLEMENT();
171 }
172
173 /**
174 * Returns the <code>Policy</code> object of the specified type
175 * which applies to this object.
176 *
177 * @param self The object reference which delegated to this delegate.
178 * @param policy_type The type of policy to be obtained.
179 * @return A <code>Policy</code> object of the type specified by
180 * the policy_type parameter.
181 * @exception org.omg.CORBA.BAD_PARAM raised when the value of policy type
182 * is not valid either because the specified type is not supported by this
183 * ORB or because a policy object of that type is not associated with this
184 * Object.
185 * @see <a href="package-summary.html#unimpl"><code>portable</code>
186 * package comments for unimplemented features</a>
187 */
188 public org.omg.CORBA.Policy get_policy(org.omg.CORBA.Object self,
189 int policy_type) {
190 throw new org.omg.CORBA.NO_IMPLEMENT();
191 }
192
193
194 /**
195 * Retrieves the <code>DomainManagers</code> of this object.
196 * This allows administration services (and applications) to retrieve the
197 * domain managers, and hence the security and other policies applicable
198 * to individual objects that are members of the domain.
199 *
200 * @param self The object reference which delegated to this delegate.
201 * @return The list of immediately enclosing domain managers of this object.
202 * At least one domain manager is always returned in the list since by
203 * default each object is associated with at least one domain manager at
204 * creation.
205 * @see <a href="package-summary.html#unimpl"><code>portable</code>
206 * package comments for unimplemented features</a>
207 */
208 public org.omg.CORBA.DomainManager[] get_domain_managers(
209 org.omg.CORBA.Object
210 self) {
211 throw new org.omg.CORBA.NO_IMPLEMENT();
212 }
213
214
215 /**
216 * Associates the policies passed in
217 * with a newly created object reference that it returns. Only certain
218 * policies that pertain to the invocation of an operation at the client
219 * end can be overridden using this operation. Attempts to override any
220 * other policy will result in the raising of the CORBA::NO_PERMISSION
221 * exception.
222 *
223 * @param self The object reference which delegated to this delegate.
224 * @param policies A sequence of references to Policy objects.
225 * @param set_add Indicates whether these policies should be added
226 * onto any otheroverrides that already exist (ADD_OVERRIDE) in
227 * the object reference, or they should be added to a clean
228 * override free object reference (SET_OVERRIDE).
229 * @return A new object reference with the new policies associated with it.
230 *
231 * @see <a href="package-summary.html#unimpl"><code>portable</code>
232 * package comments for unimplemented features</a>
233 */
234 public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object self,
235 org.omg.CORBA.Policy[] policies,
236 org.omg.CORBA.SetOverrideType set_add) {
237 throw new org.omg.CORBA.NO_IMPLEMENT();
238 }
239
240
241 /**
242 * Returns true if this object is implemented by a local servant.
243 *
244 * @param self The object reference which delegated to this delegate.
245 * @return true only if the servant incarnating this object is located in
246 * this Java VM. Return false if the servant is not local or the ORB
247 * does not support local stubs for this particular servant. The default
248 * behavior of is_local() is to return false.
249 */
250 public boolean is_local(org.omg.CORBA.Object self) {
251 return false;
252 }
253
254 /**
255 * Returns a Java reference to the servant which should be used for this
256 * request. servant_preinvoke() is invoked by a local stub.
257 * If a ServantObject object is returned, then its servant field
258 * has been set to an object of the expected type (Note: the object may
259 * or may not be the actual servant instance). The local stub may cast
260 * the servant field to the expected type, and then invoke the operation
261 * directly. The ServantRequest object is valid for only one invocation,
262 * and cannot be used for more than one invocation.
263 *
264 * @param self The object reference which delegated to this delegate.
265 *
266 * @param operation a string containing the operation name.
267 * The operation name corresponds to the operation name as it would be
268 * encoded in a GIOP request.
269 *
270 * @param expectedType a Class object representing the expected type of the servant.
271 * The expected type is the Class object associated with the operations
272 * class of the stub's interface (e.g. A stub for an interface Foo,
273 * would pass the Class object for the FooOperations interface).
274 *
275 * @return a ServantObject object.
276 * The method may return a null value if it does not wish to support
277 * this optimization (e.g. due to security, transactions, etc).
278 * The method must return null if the servant is not of the expected type.
279 */
280 public ServantObject servant_preinvoke(org.omg.CORBA.Object self,
281 String operation,
282 Class expectedType) {
283 return null;
284 }
285
286 /**
287 * servant_postinvoke() is invoked by the local stub after the operation
288 * has been invoked on the local servant.
289 * This method must be called if servant_preinvoke() returned a non-null
290 * value, even if an exception was thrown by the servant's method.
291 * For this reason, the call to servant_postinvoke() should be placed
292 * in a Java finally clause.
293 *
294 * @param self The object reference which delegated to this delegate.
295 *
296 * @param servant the instance of the ServantObject returned from
297 * the servant_preinvoke() method.
298 */
299 public void servant_postinvoke(org.omg.CORBA.Object self,
300 ServantObject servant) {
301 }
302
303 /**
304 * request is called by a stub to obtain an OutputStream for
305 * marshaling arguments. The stub must supply the operation name,
306 * and indicate if a response is expected (i.e is this a oneway
307 * call).
308 *
309 * @param self The object reference which delegated to this delegate.
310 * @param operation a string containing the operation name.
311 * The operation name corresponds to the operation name as it would be
312 * encoded in a GIOP request.
313 * @param responseExpected false if the operation is a one way operation,
314 * and true otherwise.
315 * @return OutputStream the OutputStream into which request arguments
316 * can be marshaled.
317 * @see <a href="package-summary.html#unimpl"><code>portable</code>
318 * package comments for unimplemented features</a>
319 */
320 public OutputStream request(org.omg.CORBA.Object self,
321 String operation,
322 boolean responseExpected) {
323 throw new org.omg.CORBA.NO_IMPLEMENT();
324 }
325
326 /**
327 * invoke is called by a stub to invoke an operation. The stub provides an
328 * OutputStream that was previously returned by a request()
329 * call. invoke returns an InputStream which contains the
330 * marshaled reply. If an exception occurs, invoke may throw an
331 * ApplicationException object which contains an InputStream from
332 * which the user exception state may be unmarshaled.
333 *
334 * @param self The object reference which delegated to this delegate.
335 * @param output the OutputStream which contains marshaled arguments
336 * @return input the InputStream from which reply parameters can be
337 * unmarshaled.
338 * @throws ApplicationException thrown when implementation throws
339 * (upon invocation) an exception defined as part of its remote method
340 * definition.
341 * @throws RemarshalException thrown when remarshalling fails.
342 * @see <a href="package-summary.html#unimpl"><code>portable</code>
343 * package comments for unimplemented features</a>
344 */
345 public InputStream invoke(org.omg.CORBA.Object self,
346 OutputStream output)
347 throws ApplicationException, RemarshalException {
348 throw new org.omg.CORBA.NO_IMPLEMENT();
349 }
350
351 /**
352 * releaseReply may optionally be called by a stub to release a
353 * reply stream back to the ORB when the unmarshaling has
354 * completed. The stub passes the InputStream returned by
355 * invoke() or ApplicationException.getInputStream(). A null
356 * value may also be passed to releaseReply, in which case the
357 * method is a noop.
358 *
359 * @param self The object reference which delegated to this delegate.
360 * @param input the InputStream returned from invoke().
361 * @see <a href="package-summary.html#unimpl"><code>portable</code>
362 * package comments for unimplemented features</a>
363 */
364 public void releaseReply(org.omg.CORBA.Object self,
365 InputStream input) {
366 throw new org.omg.CORBA.NO_IMPLEMENT();
367 }
368
369 /**
370 * Provides the implementation to override the toString() method
371 * of the delegating CORBA object.
372 *
373 * @param self the object reference that delegated to this delegate
374 * @return a <code>String</code> object that represents the object
375 * reference that delegated to this <code>Delegate</code>
376 * object
377 */
378
379 public String toString(org.omg.CORBA.Object self) {
380 return self.getClass().getName() + ":" + this.toString();
381 }
382
383 /**
384 * Provides the implementation to override the hashCode() method
385 * of the delegating CORBA object.
386 *
387 * @param self the object reference that delegated to this delegate
388 * @return an <code>int</code> that represents the hashcode for the
389 * object reference that delegated to this <code>Delegate</code>
390 * object
391 */
392 public int hashCode(org.omg.CORBA.Object self) {
393 return System.identityHashCode(self);
394 }
395
396 /**
397 * Provides the implementation to override the equals(java.lang.Object obj)
398 * method of the delegating CORBA object.
399 *
400 * @param self the object reference that delegated to this delegate
401 * @param obj the <code>Object</code> with which to compare
402 * @return <code>true</code> if <code>obj</code> equals <code>self</code>;
403 * <code>false</code> otherwise
404 */
405 public boolean equals(org.omg.CORBA.Object self, java.lang.Object obj) {
406 return (self == obj);
407 }
408 }