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      @SuppressWarnings("unchecked") // Needed for API compatibility
271      public ServantObject _servant_preinvoke(String operation, Class expectedType)
272      {
273        throw new NO_IMPLEMENT(INAPPROPRIATE);
274      }
275    
276    
277      /**
278       * This method is called from <code>rmic</code> generated stubs if the
279       * {@link Util#isLocal}, called passing <code>this</code> as parameter,
280       * returns true, and the {@link #_servant_preinvoke} return non-null object.
281       * The stub then invokes the requrested method on that returned object and
282       * later calls _servant_postinvoke, passing that returned target as parameter.
283       *
284       * @param servant the object that has served as the invocation target for the
285       * current operation.
286       */
287      public void _servant_postinvoke(ServantObject servant)
288      {
289      }
290    
291      /**
292       * Invokes the operation. This method takes the OutputStream that was previously
293       * returned by a {@link #_request(String)} and returns an InputStream which
294       * contains the reply. Up till jdk 1.5 inclusive this method is marked as
295       * unimplemented.
296       *
297       * @throws NO_IMPLEMENT always.
298       */
299      public InputStream _invoke(OutputStream output)
300        throws ApplicationException, RemarshalException
301      {
302        throw new NO_IMPLEMENT(INAPPROPRIATE);
303      }
304    
305      /**
306       * While it may look that this should return true, the jdk 1.5 API states
307       * that it must throw NO_IMPLEMENT instead. The rmi stubs do not call this
308       * method to check if the object is local; they call {@link Util#isLocal}
309       * instead (passing <code>this</code> as parameter).
310       *
311       * @return never.
312       *
313       * @throws NO_IMPLEMENT always.
314       */
315      public boolean _is_local()
316      {
317        throw new NO_IMPLEMENT(INAPPROPRIATE);
318      }
319    
320    
321      /**
322       * This method is not appropriate for the local objects and just
323       * throws an exception.
324       *
325       * @throws NO_IMPLEMENT, always.
326       */
327      public ORB _orb()
328      {
329        throw new NO_IMPLEMENT(INAPPROPRIATE);
330      }
331    
332      /**
333       * This method is not appropriate for the local objects and just
334       * throws an exception.
335       *
336       * @throws NO_IMPLEMENT, always.
337       */
338      public void _releaseReply(InputStream input)
339      {
340        throw new NO_IMPLEMENT(INAPPROPRIATE);
341      }
342    
343      /**
344       * This method is not appropriate for the local objects and just
345       * throws an exception.
346       *
347       * @throws NO_IMPLEMENT, always.
348       */
349      public OutputStream _request(String operation, boolean responseExpected)
350      {
351        throw new NO_IMPLEMENT(INAPPROPRIATE);
352      }
353    
354      /**
355       * This method is not appropriate for the local objects and just
356       * throws an exception.
357       *
358       * @throws NO_IMPLEMENT, always.
359       */
360      public boolean validate_connection()
361      {
362        throw new NO_IMPLEMENT(INAPPROPRIATE);
363      }
364    }