001    /* LocalObject.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;
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.Policy;
050    import org.omg.CORBA.Request;
051    import org.omg.CORBA.SetOverrideType;
052    import org.omg.CORBA.portable.ApplicationException;
053    import org.omg.CORBA.portable.InputStream;
054    import org.omg.CORBA.portable.OutputStream;
055    import org.omg.CORBA.portable.RemarshalException;
056    import org.omg.CORBA.portable.ServantObject;
057    
058    import javax.rmi.CORBA.Util;
059    
060    /**
061     * An object, formally implementing the CORBA {@link Object}, but actually
062     * handling all invocations locally.
063     * Various calls to the remote object specific methods throw the
064     * {@link NO_IMPLEMENT}. The explaining message for this exception is
065     * specified in java API as <code>"This is a locally constrained object."</code>.
066     * It is not possible to get a stringified reference of the local object, or
067     * invoke a method using DII (by name via {@link Request} class).
068     *
069     * However narrowing and widening methods will work with local objects.
070     *
071     * @since 1.4
072     *
073     * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
074     */
075    public class LocalObject
076      implements org.omg.CORBA.Object
077    {
078      /**
079       * The explaining message for the exception, thrown in response to call
080       * the method, not appropriate for the local object.
081       */
082      private static final String INAPPROPRIATE =
083        "This is a locally constrained object.";
084    
085      /**
086       * This method is not appropriate for the local objects and just
087       * throws an exception.
088       *
089       * @throws NO_IMPLEMENT, always.
090       */
091      public Request _create_request(Context context, String operation,
092                                     NVList parameters, NamedValue returns
093                                    )
094      {
095        throw new NO_IMPLEMENT(INAPPROPRIATE);
096      }
097    
098      /**
099       * This method is not appropriate for the local objects and just
100       * throws an exception.
101       *
102       * @throws NO_IMPLEMENT, always.
103       */
104      public Request _create_request(Context context, String operation,
105                                     NVList parameters, NamedValue returns,
106                                     ExceptionList exceptions, ContextList ctx_list
107                                    )
108      {
109        throw new NO_IMPLEMENT(INAPPROPRIATE);
110      }
111    
112      /**
113       * This method is not appropriate for the local objects and just
114       * throws an exception.
115       *
116       * @throws NO_IMPLEMENT, always.
117       */
118      public org.omg.CORBA.Object _duplicate()
119      {
120        throw new NO_IMPLEMENT(INAPPROPRIATE);
121      }
122    
123      /**
124       * This method is not appropriate for the local objects and just
125       * throws an exception.
126       *
127       * @throws NO_IMPLEMENT, always.
128       */
129      public DomainManager[] _get_domain_managers()
130      {
131        throw new NO_IMPLEMENT(INAPPROPRIATE);
132      }
133    
134      /**
135       * This method is not appropriate for the local objects and just
136       * throws an exception.
137       *
138       * @throws NO_IMPLEMENT, always.
139       */
140      public org.omg.CORBA.Object _get_interface_def()
141      {
142        throw new NO_IMPLEMENT(INAPPROPRIATE);
143      }
144    
145      /**
146       * This method is not appropriate for the local objects and just
147       * throws an exception.
148       *
149       * @throws NO_IMPLEMENT, always.
150       */
151      public org.omg.CORBA.Object _get_interface()
152      {
153        throw new NO_IMPLEMENT(INAPPROPRIATE);
154      }
155    
156      /**
157       * This method is not appropriate for the local objects and just
158       * throws an exception.
159       *
160       * @throws NO_IMPLEMENT, always.
161       */
162      public Policy _get_policy(int a_policy_type)
163                         throws BAD_PARAM
164      {
165        throw new NO_IMPLEMENT(INAPPROPRIATE);
166      }
167    
168      /**
169       * {@inheritDoc}
170       */
171      public int _hash(int maximum)
172      {
173        return Math.abs(hashCode()) % maximum;
174      }
175    
176      /**
177       * This method is not appropriate for the local objects and just
178       * throws an exception.
179       *
180       * @throws NO_IMPLEMENT, always.
181       */
182      public boolean _is_a(String repositoryIdentifer)
183      {
184        throw new NO_IMPLEMENT(INAPPROPRIATE);
185      }
186    
187      /**
188       * Determines if the object is equal to another object, so far as it is
189       * possible to determine easily.
190       *
191       * @param other the other object.
192       *
193       * @return true if the pased object is not null and
194       * java.lang.Object.equals(other) returns true. False otherwise.
195       */
196      public boolean _is_equivalent(org.omg.CORBA.Object other)
197      {
198        if (other != null)
199          if (other.equals(this))
200            return true;
201    
202        return false;
203      }
204    
205      /**
206       * Always returs false.
207       *
208       * @return false, always.
209       */
210      public boolean _non_existent()
211      {
212        return false;
213      }
214    
215      /**
216       * This method is not appropriate for the local objects and just
217       * throws an exception.
218       *
219       * @throws NO_IMPLEMENT, always.
220       */
221      public void _release()
222      {
223        throw new NO_IMPLEMENT(INAPPROPRIATE);
224      }
225    
226      /**
227       * This method is not appropriate for the local objects and just
228       * throws an exception.
229       *
230       * @specnote it is possible to implement a local handling of the _request(),
231       * but the API clearly states that NO_IMPLEMENT
232       * must be thrown instead.
233       *
234       * @throws NO_IMPLEMENT, always.
235       */
236      public Request _request(String operation)
237      {
238        throw new NO_IMPLEMENT(INAPPROPRIATE);
239      }
240    
241      /**
242       * This method is not appropriate for the local objects and just
243       * throws an exception.
244       *
245       * @throws NO_IMPLEMENT, always.
246       */
247      public org.omg.CORBA.Object _set_policy_override(Policy[] policies,
248                                                       SetOverrideType how
249                                                      )
250      {
251        throw new NO_IMPLEMENT(INAPPROPRIATE);
252      }
253      
254      /**
255       * This method is called from <code>rmic</code> generated stubs if the
256       * {@link Util#isLocal}, called passing <code>this</code> as parameter,
257       * returns true. If the method returns null, the requested method is then
258       * invoked on <code>this</code>. Else it is invoked on the returned object,
259       * casting it into the interface that the local object implements. In this
260       * case, the generated stub also later calls 
261       * {@link #_servant_postinvoke(ServantObject)}, passing that returned target
262       * as parameter.
263       * 
264       * @param operation the name of the method being invoked.
265       * @param expectedType the interface that the returned servant 
266       * object must implement.
267       * 
268       * @throws NO_IMPLEMENT always. If used, the method must be overridden.
269       */
270      public ServantObject _servant_preinvoke(String operation, Class expectedType)
271      {
272        throw new NO_IMPLEMENT(INAPPROPRIATE);
273      }
274      
275      
276      /**
277       * This method is called from <code>rmic</code> generated stubs if the
278       * {@link Util#isLocal}, called passing <code>this</code> as parameter,
279       * returns true, and the {@link #_servant_preinvoke} return non-null object.
280       * The stub then invokes the requrested method on that returned object and
281       * later calls _servant_postinvoke, passing that returned target as parameter.
282       * 
283       * @param servant the object that has served as the invocation target for the
284       * current operation.
285       */
286      public void _servant_postinvoke(ServantObject servant)
287      {
288      }
289      
290      /**
291       * Invokes the operation. This method takes the OutputStream that was previously 
292       * returned by a {@link #_request(String)} and returns an InputStream which 
293       * contains the reply. Up till jdk 1.5 inclusive this method is marked as
294       * unimplemented.
295       * 
296       * @throws NO_IMPLEMENT always.
297       */
298      public InputStream _invoke(OutputStream output)
299        throws ApplicationException, RemarshalException
300      {
301        throw new NO_IMPLEMENT(INAPPROPRIATE);
302      }
303      
304      /**
305       * While it may look that this should return true, the jdk 1.5 API states
306       * that it must throw NO_IMPLEMENT instead. The rmi stubs do not call this
307       * method to check if the object is local; they call {@link Util#isLocal}
308       * instead (passing <code>this</code> as parameter).  
309       * 
310       * @return never.
311       * 
312       * @throws NO_IMPLEMENT always.
313       */
314      public boolean _is_local()
315      {
316        throw new NO_IMPLEMENT(INAPPROPRIATE);
317      }
318      
319      
320      /**
321       * This method is not appropriate for the local objects and just
322       * throws an exception.
323       *
324       * @throws NO_IMPLEMENT, always.
325       */
326      public ORB _orb()
327      {
328        throw new NO_IMPLEMENT(INAPPROPRIATE);    
329      }
330      
331      /**
332       * This method is not appropriate for the local objects and just
333       * throws an exception.
334       *
335       * @throws NO_IMPLEMENT, always.
336       */
337      public void _releaseReply(InputStream input) 
338      {
339        throw new NO_IMPLEMENT(INAPPROPRIATE);    
340      }
341      
342      /**
343       * This method is not appropriate for the local objects and just
344       * throws an exception.
345       *
346       * @throws NO_IMPLEMENT, always.
347       */
348      public OutputStream _request(String operation, boolean responseExpected) 
349      {
350        throw new NO_IMPLEMENT(INAPPROPRIATE);    
351      }
352      
353      /**
354       * This method is not appropriate for the local objects and just
355       * throws an exception.
356       *
357       * @throws NO_IMPLEMENT, always.
358       */
359      public boolean validate_connection()
360      {
361        throw new NO_IMPLEMENT(INAPPROPRIATE);
362      }
363    }