|
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 } |