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