001    /* Delegate.java --
002    Copyright (C) 2005, 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package org.omg.CORBA.portable;
040    
041    import org.omg.CORBA.BAD_PARAM;
042    import org.omg.CORBA.Context;
043    import org.omg.CORBA.ContextList;
044    import org.omg.CORBA.DomainManager;
045    import org.omg.CORBA.ExceptionList;
046    import org.omg.CORBA.NO_IMPLEMENT;
047    import org.omg.CORBA.NVList;
048    import org.omg.CORBA.NamedValue;
049    import org.omg.CORBA.ORB;
050    import org.omg.CORBA.Policy;
051    import org.omg.CORBA.Request;
052    import org.omg.CORBA.SetOverrideType;
053    
054    /**
055     * Specifies a vendor specific implementation of the
056     * {@link org.omg.CORBA.Object} methods. The calls to these
057     * methods are forwarded to the object delegate that can be
058     * replaced, if needed. The first parameter is the actual
059     * CORBA object to that the operation must be applied.
060     *
061     * Some methods in this class are not abstract, but no implemented,
062     * thowing the {@link NO_IMPLEMENT}. This, however, does not mean that
063     * they are not implemented in the derived classes as well.
064     *
065     * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
066     */
067    public abstract class Delegate
068    {
069      /**
070       * Explains the reason of throwing the NO_IMPLEMENT.
071       */
072      private static final String WHY =
073        "Following 1.4 API, this Delegate method must not be implemented. Override.";
074    
075      /**
076       * Create a request to invoke the method of this object.
077       *
078       * @param target the CORBA object, to that this operation must be applied.
079       * @param context a list of additional properties.
080       * @param operation the name of method to be invoked.
081       * @param parameters the method parameters.
082       * @param returns the container for tge method returned value.
083       *
084       * @return the created reaquest.
085       */
086      public abstract Request create_request(org.omg.CORBA.Object target,
087                                             Context context, String operation,
088                                             NVList parameters, NamedValue returns
089                                            );
090    
091      /**
092       * Create a request to invoke the method of this object, specifying
093       * context list and the list of the expected exception.
094       *
095       * @param target the CORBA object, to that this operation must be applied.
096       * @param context a list of additional properties.
097       * @param operation the name of method to be invoked.
098       * @param parameters the method parameters.
099       * @param returns the container for tge method returned value.
100       * @param exceptions the list of the possible exceptions that the method
101       * can throw.
102       * @param ctx_list the list of the context strings that need to be
103       * resolved and send as a context instance.
104       *
105       * @return the created reaquest.
106       */
107      public abstract Request create_request(org.omg.CORBA.Object target,
108                                             Context context, String operation,
109                                             NVList parameters, NamedValue returns,
110                                             ExceptionList exceptions,
111                                             ContextList ctx_list
112                                            );
113    
114      /**
115       * Duplicate the object reference. This does not make much sense for
116       * java platform and is just included for the sake of compliance with
117       * CORBA APIs.
118       *
119       * @param target the CORBA object, to that this operation must be applied.
120       *
121       * The method may return the object reference itself.
122       *
123       * @return as a rule, <code>this</code>.
124       */
125      public abstract org.omg.CORBA.Object duplicate(org.omg.CORBA.Object target);
126    
127      /**
128       * Retrieve the domain managers for this object.
129       *
130       * @param target the CORBA object, to that this operation must be applied.
131       *
132       * @return the domain managers.
133       *
134       * @throws NO_IMPLEMENT, always (following the 1.4 specification).
135       */
136      public DomainManager[] get_domain_managers(org.omg.CORBA.Object target)
137      {
138        throw new NO_IMPLEMENT(WHY);
139      }
140    
141      /**
142       *
143       * @param target the CORBA object, to that this operation must be applied.
144       *
145       * Get the <code>InterfaceDef</code> for this Object.
146       */
147      public abstract org.omg.CORBA.Object get_interface_def(org.omg.CORBA.Object target);
148    
149      /**
150       * Returns the {@link Policy}, applying to this object.
151       *
152       * @param target the CORBA object, to that this operation must be applied.
153       * @param a_policy_type a type of policy to be obtained.
154       * @return a corresponding Policy object.
155       *
156       * @throws NO_IMPLEMENT, always (following the 1.4 specification).
157       */
158      public Policy get_policy(org.omg.CORBA.Object target, int a_policy_type)
159                        throws BAD_PARAM
160      {
161        throw new NO_IMPLEMENT(WHY);
162      }
163    
164      /**
165       * Get the hashcode this object reference. The same hashcode still
166       * does not means that the references are the same. From the other
167       * side, two different references may still refer to the same CORBA
168       * object. The returned value must not change during the object
169       * lifetime.
170       *
171       * @param target the CORBA object, to that this operation must be applied.
172       * @param maximum the maximal value to return.
173       *
174       * @return the hashcode.
175       */
176      public abstract int hash(org.omg.CORBA.Object target, int maximum);
177    
178      /**
179       * Check if this object can be referenced by the given repository id.
180       *
181       * @param target the CORBA object, to that this operation must be applied.
182       * @param repositoryIdentifer the repository id.
183       *
184       * @return true if the passed parameter is a repository id of this
185       * CORBA object.
186       */
187      public abstract boolean is_a(org.omg.CORBA.Object target,
188                                   String repositoryIdentifer
189                                  );
190    
191      /**
192       * Return true if the other object references are equivalent, so far as
193       * it is possible to determine this easily.
194       *
195       * @param target the CORBA object, to that this operation must be applied.
196       * @param other the other object reference.
197       *
198       * @return true if both references refer the same object, false
199       * if they probably can refer different objects.
200       *
201       */
202      public abstract boolean is_equivalent(org.omg.CORBA.Object target,
203                                            org.omg.CORBA.Object other
204                                           );
205    
206      /**
207       * Returns true if the object is local.
208       *
209       * @param self the object to check.
210       *
211       * @return false, always (following 1.4 specs). Override to get
212       * functionality.
213       */
214      public boolean is_local(org.omg.CORBA.Object self)
215      {
216        return false;
217      }
218    
219      /**
220       * Determines if the server object for this reference has already
221       * been destroyed.
222       *
223       * @param target the CORBA object, to that this operation must be applied.
224       *
225       * @return true if the object has been destroyed, false otherwise.
226       */
227      public abstract boolean non_existent(org.omg.CORBA.Object target);
228    
229      /**
230       * Compares two objects for equality. The default implementations
231       * delegated call to {@link java.lang.Object#equals(java.lang.Object)}.
232       *
233       * @param self this CORBA object.
234       * @param other the other CORBA object.
235       *
236       * @return true if the objects are equal.
237       */
238      public boolean equals(org.omg.CORBA.Object self, java.lang.Object other)
239      {
240        return self==other;
241      }
242    
243      /**
244       * Return the hashcode for this CORBA object. The default implementation
245       * delegates call to {@link #hash(org.omg.CORBA.Object, int)}, passing Integer.MAX_VALUE as an
246       * argument.
247       *
248       * @param target the object, for that the hash code must be computed.
249       *
250       * @return the hashcode.
251       */
252      public int hashCode(org.omg.CORBA.Object target)
253      {
254        return hash(target, Integer.MAX_VALUE);
255      }
256    
257      /**
258       * Invoke the operation.
259       *
260       * @param target the invocation target.
261       * @param output the stream, containing the written arguments.
262       *
263       * @return the stream, from where the input parameters could be read.
264       *
265       * @throws ApplicationException if the application throws an exception,
266       * defined as a part of its remote method definition.
267       *
268       * @throws RemarshalException if reading(remarshalling) fails.
269       *
270       * @throws NO_IMPLEMENT, always (following the 1.4 specification).
271       */
272      public InputStream invoke(org.omg.CORBA.Object target,
273                                org.omg.CORBA.portable.OutputStream output
274                               )
275                         throws ApplicationException, RemarshalException
276      {
277        throw new NO_IMPLEMENT(WHY);
278      }
279    
280      /**
281       * Provides the reference to ORB.
282       *
283       * @param target the object reference.
284       *
285       * @return the associated ORB.
286       *
287       * @throws NO_IMPLEMENT, always (following the 1.4 specification).
288       */
289      public ORB orb(org.omg.CORBA.Object target)
290      {
291        throw new NO_IMPLEMENT(WHY);
292      }
293    
294      /**
295       * Free resoureces, occupied by this reference. The object implementation
296       * is not notified, and the other references to the same object are not
297       * affected.
298       *
299       * @param target the CORBA object, to that this operation must be applied.
300       */
301      public abstract void release(org.omg.CORBA.Object target);
302    
303      /**
304       * Release the reply stream back to ORB after finishing reading the data
305       * from it.
306       *
307       * @param target the CORBA object, to that this operation must be applied.
308       * @param input the stream, normally returned by {@link #invoke} or
309       * {@link ApplicationException#getInputStream()}, can be null.
310       *
311       * The default method returns without action.
312       */
313      public void releaseReply(org.omg.CORBA.Object target,
314                               org.omg.CORBA.portable.InputStream input
315                              )
316      {
317      }
318    
319      /**
320       * Create a request to invoke the method of this CORBA object.
321       *
322       * @param target the CORBA object, to that this operation must be applied.
323       * @param operation the name of the method to invoke.
324       *
325       * @return the request.
326       */
327      public abstract Request request(org.omg.CORBA.Object target, String operation);
328    
329      /**
330       * Create a request to invoke the method of this CORBA object.
331       *
332       * @param target the CORBA object, to that this operation must be applied.
333       * @param operation the name of the method to invoke.
334       * @param response_expected specifies if this is one way message or the
335       * response to the message is expected.
336       *
337       * @return the stream where the method arguments should be written.
338       */
339      public org.omg.CORBA.portable.OutputStream request(org.omg.CORBA.Object target,
340                                                         String operation,
341                                                         boolean response_expected
342                                                        )
343      {
344        throw new NO_IMPLEMENT(WHY);
345      }
346    
347      /**
348       * This method is always called after invoking the operation on the
349       * local servant.
350       *
351       * The default method returns without action.
352       *
353       * @param self the object.
354       * @param servant the servant.
355       */
356      public void servant_postinvoke(org.omg.CORBA.Object self,
357                                     ServantObject servant
358                                    )
359      {
360      }
361    
362      /**
363       * Returns a servant that should be used for this request.
364       * The servant can also be casted to the expected type, calling the
365       * required method directly.
366       *
367       * @param self the object
368       * @param operation the operation
369       * @param expectedType the expected type of the servant.
370       *
371       * This implementation always returns null; override for different
372       * behavior.
373       *
374       * @return the servant or null if the servant is not an expected type
375       * of the method is not supported, for example, due security reasons.
376       */
377      public ServantObject servant_preinvoke(org.omg.CORBA.Object self,
378                                             String operation, Class expectedType
379                                            )
380      {
381        return null;
382      }
383    
384      /**
385       * Returns a new object with the new policies either replacing or
386       * extending the current policies, depending on the second parameter.
387       *
388       * @param target the CORBA object, to that this operation must be applied.
389       * @param policies the policy additions or replacements.
390       * @param how either {@link SetOverrideType#SET_OVERRIDE} to override the
391       * current policies of {@link SetOverrideType#ADD_OVERRIDE} to replace
392       * them.
393       *
394       * @throws NO_IMPLEMENT, always (following the 1.4 specification).
395       *
396       * @return the new reference with the changed policies.
397       */
398      public org.omg.CORBA.Object set_policy_override(org.omg.CORBA.Object target,
399                                                      Policy[] policies,
400                                                      SetOverrideType how
401                                                     )
402      {
403        throw new NO_IMPLEMENT(WHY);
404      }
405    
406      /**
407       * Return a string representation of the passed object.
408       *
409       * @param self the CORBA object, to that the string representation must be
410       * returned. By default, the call is delegated to
411       * {@link java.lang.Object#toString()}.
412       *
413       * @return the string representation.
414       */
415      public String toString(org.omg.CORBA.Object self)
416      {
417        if (self instanceof ObjectImpl)
418          {
419            ObjectImpl x = (ObjectImpl) self;
420            StringBuffer b = new StringBuffer(x.getClass().getName());
421            b.append(": [");
422            for (int i = 0; i < x._ids().length; i++)
423              {
424                b.append(x._ids() [ i ]);
425                b.append(" ");
426              }
427            b.append("]");
428            return b.toString();
429          }
430        else
431          return self.getClass().getName();
432      }
433    }