001/* LocalObject.java --
002   Copyright (C) 2005, 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package org.omg.CORBA;
040
041import org.omg.CORBA.BAD_PARAM;
042import org.omg.CORBA.Context;
043import org.omg.CORBA.ContextList;
044import org.omg.CORBA.DomainManager;
045import org.omg.CORBA.ExceptionList;
046import org.omg.CORBA.NO_IMPLEMENT;
047import org.omg.CORBA.NVList;
048import org.omg.CORBA.NamedValue;
049import org.omg.CORBA.Policy;
050import org.omg.CORBA.Request;
051import org.omg.CORBA.SetOverrideType;
052import org.omg.CORBA.portable.ApplicationException;
053import org.omg.CORBA.portable.InputStream;
054import org.omg.CORBA.portable.OutputStream;
055import org.omg.CORBA.portable.RemarshalException;
056import org.omg.CORBA.portable.ServantObject;
057
058import 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 */
075public 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("rawtypes") // 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}