001/* ORB.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 gnu.CORBA.OrbFocused;
042import gnu.CORBA.ObjectCreator;
043import gnu.CORBA.OrbRestricted;
044import gnu.CORBA.typecodes.FixedTypeCode;
045import gnu.CORBA.typecodes.GeneralTypeCode;
046import gnu.CORBA.typecodes.RecordTypeCode;
047import gnu.CORBA.typecodes.RecursiveTypeCode;
048
049import org.omg.CORBA.ORBPackage.InconsistentTypeCode;
050import org.omg.PortableInterceptor.ObjectReferenceTemplate;
051
052import java.applet.Applet;
053
054import java.io.BufferedInputStream;
055import java.io.File;
056import java.io.FileInputStream;
057import java.io.IOException;
058
059import java.util.Properties;
060
061/**
062 * A central class in CORBA implementation, responsible for sending and handling
063 * remote invocations. ORB also works as a factory for creating instances of
064 * certain CORBA classes.
065 *
066 * Despite the core library contains the fully working CORBA implementation, it
067 * also provides a simple way to plug-in the alternative CORBA support. This is
068 * done by replacing the ORB. The alternative ORB can be specified via
069 * properties, passed to ORB.Init(...).
070 *
071 * When creating an ORB instance, the class name is searched in the following
072 * locations:
073 * <p>
074 * 1. Applet parameter or application string array, if any.<br>
075 * 2. The properties parameter, if any.<br>
076 * 3. The System properties.<br>
077 * 4. The orb.properties file located in the user.home directory (if any).<br>
078 * 5. The orb.properties file located in the java.home/lib directory (if any).
079 * </p>
080 *
081 * The supported properties are: <table border="1">
082 * <tr>
083 * <td> org.omg.CORBA.ORBClass</td>
084 * <td>The class, implementing the functional ORB, returned by
085 * {@link #init(Applet, Properties)} or {@link #init(String[], Properties)}
086 * </td>
087 * </tr>
088 * <tr>
089 * <td>org.omg.CORBA.ORBSingletonClass</td>
090 * <td>The class, implementing the restricted ORB, returned by {@link #init()}.
091 * </td>
092 * </tr>
093 * <tr>
094 * <td>org.omg.CORBA.ORBInitRef</td>
095 * <td>Specifies the initial reference, accessible by name with the method
096 * {@link #resolve_initial_references(String)}.</td>
097 * </tr>
098 * <tr>
099 * <td>org.omg.CORBA.ORBid</td>
100 * <td>Specifies the name (ORB Id) of this ORB. The ORB Id is later accessible
101 * by {@link ObjectReferenceTemplate#orb_id}. The default value includes the
102 * hashcode of the ORB instance that is normally different for each ORB.
103 * </td>
104 * </tr>
105 * <tr>
106 * <td>org.omg.CORBA.ServerId</td>
107 * <td>Specifies the name (Server Id) of this server. This property assigns
108 * value to the <i>static</i> field, ensuring that all ORB's on the same jre
109 * have the same Server Id. It is normally set as the system property. The
110 * server Id is later accessible as {@link ObjectReferenceTemplate#server_id}.
111 * </td>
112 * </tr>
113 * <tr>
114 * <td>gnu.CORBA.ListenerPort</td>
115 * <td>Specifies that this ORB should serve all its objects on a single port
116 * (for example, "1234") or on a specified port range (for example,
117 * "1100-1108"). The property is used when working with firewals and serves as a
118 * replacement for the proprietary properties like com.ibm.CORBA.ListenerPort
119 * or com.sun.CORBA.POA.ORBPersistentServerPort. The specified port or range
120 * should not overlap with the values, specified for other ORB's.
121 * </td>
122 * </tr>
123 * <tr>
124 * <td>gnu.Corba.SocketFactory</td>
125 * <td>Sets the user-defined server and client socket factory for the ORB being
126 * currently instantiated. Serves as a replacement of the proprietary
127 * property com.sun.CORBA.connection.ORBSocketFactoryClass. To have multiple
128 * types of sockets, instantiate several ORB's with this property each time
129 * set to the different value.
130 * The factory must implement gnu.CORBA.interfaces.SocketFactory.
131 * </td>
132 * </tr>
133 * </table>
134 * <p>The command line accepts the same properties as a keys. When
135 * specifying in the command line, the prefix org.omg.CORBA can be omitted, for
136 * instance<code> -ORBInitRef NameService=IOR:aabbccdd....</code>
137 * </p>
138 *
139 * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
140 */
141public abstract class ORB
142{
143  /**
144  * By default, {@link #init(String[], Properties)} and
145  * {@link #init(Applet, Properties)} return
146  * the built-in fully functional ORB is returned. If the
147  * <code>props</code> contains the property org.omg.CORBA.ORBClass,
148  * the value of this property is used as a class name to instantiate
149  * a user-defined ORB.
150  */
151  private static final String FUNCTIONAL_ORB = "org.omg.CORBA.ORBClass";
152
153  /**
154   * The name of the restricted ORB property.
155   */
156  private static final String RESTRICTED_ORB =
157    "org.omg.CORBA.ORBSingletonClass";
158
159  private static final String LISTENER_PORT =
160    OrbFocused.LISTENER_PORT;
161
162  /**
163   * The class, implementing the default fully functional ORB.
164   */
165  private static final String DEFAULT_FUNCTIONAL_ORB =
166    gnu.CORBA.Poa.ORB_1_4.class.getName();
167
168  private static final String DEFAULT_FOCUSED_ORB =
169    gnu.CORBA.OrbFocused.class.getName();
170
171  // There is no need for name of the default restricted ORB as it is
172  // singleton and it is more effectively referred directly.
173
174  /**
175   * Connect the given CORBA object to this ORB. After the object is
176   * connected, it starts receiving remote invocations via this ORB.
177   *
178   * The OMG group recommends to use Portable Object Adapter (POA) instead
179   * of calling this method.
180   *
181   * This method is implemented in the derived Gnu Classpah classes,
182   * returned by ORB.init(..). In this abstract class, the implementation
183   * just throws {@link NO_IMPLEMENT}.
184   *
185   * @param object the org.omg.CORBA.Object to connect.
186   */
187  public void connect(org.omg.CORBA.Object object)
188  {
189    throw new NO_IMPLEMENT();
190  }
191
192  /**
193   * Disconnect the given CORBA object from this ORB. The object will be
194   * no longer receiving the remote invocations. In response to the
195   * remote invocation on this object, the ORB will send the
196   * exception {@link OBJECT_NOT_EXIST}. The object, however, is not
197   * destroyed and can receive the local invocations.
198   *
199   * This method is implemented in the derived Gnu Classpah classes,
200   * returned by ORB.init(..). In this abstract class, the implementation
201   * just throws {@link NO_IMPLEMENT}.
202   *
203   * @param object the object to disconnect.
204   */
205  public void disconnect(org.omg.CORBA.Object object)
206  {
207    throw new NO_IMPLEMENT();
208  }
209
210  /**
211   * Create a typecode, representing a tree-like structure.
212   * This structure contains a member that is a sequence of the same type,
213   * as the structure itself. You can imagine as if the folder definition
214   * contains a variable-length array of the enclosed (nested) folder
215   * definitions. In this way, it is possible to have a tree like
216   * structure that can be transferred via CORBA CDR stream.
217   *
218   * @deprecated It is easier and clearler to use a combination of
219   * create_recursive_tc and create_sequence_tc instead.
220   *
221   * @param bound the maximal expected number of the nested components
222   * on each node; 0 if not limited.
223   *
224   * @param offset the position of the field in the returned structure
225   * that contains the sequence of the structures of the same field.
226   * The members before this field are intialised using parameterless
227   * StructMember constructor.
228   *
229   * @return a typecode, defining a stucture, where a member at the
230   * <code>offset</code> position defines an array of the identical
231   * structures.
232   *
233   * @see #create_recursive_tc(String)
234   * @see #create_sequence_tc(int, TypeCode)
235   */
236  public abstract TypeCode create_recursive_sequence_tc(int bound, int offset);
237
238  /**
239   * Create alias typecode for the given typecode.
240   */
241  public abstract TypeCode create_alias_tc(String id, String name,
242                                           TypeCode typecode
243                                          );
244
245  /**
246   * Create an instance of the CORBA {@link Any} with the type, intialised
247   * to {@link TCKind#tk_null}
248   */
249  public abstract Any create_any();
250
251  /**
252   * Create a typecode, defining an array of the given elements.
253   *
254   * @param length the size of array
255   * @param element_type the array component type.
256   *
257   * @return the corresponding typecode.
258   */
259  public abstract TypeCode create_array_tc(int length, TypeCode element_type);
260
261  /**
262   * Creates an empty CORBA <code>ContextList</code>.
263   *
264   * @return the newly created context list.
265   */
266  public abstract ContextList create_context_list();
267
268  /**
269   * The support for {@link DynAny} and derived interfaces
270   * has never been implemented in Sun's java releases,
271   * at least till v1.4 inclusive.
272   *
273   * Since v1.4 this stil missing implementation was replaced
274   * by the new DynamicAny package.
275   *
276   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
277   *
278   * @throws NO_IMPLEMENT, always.
279   */
280  public DynAny create_basic_dyn_any(org.omg.CORBA.TypeCode t)
281                              throws InconsistentTypeCode
282  {
283    throw new NO_IMPLEMENT();
284  }
285
286  /**
287   * The support for {@link DynAny} and derived interfaces
288   * has never been implemented in Sun's java releases,
289   * at least till v1.4 inclusive.
290   *
291   * Since v1.4 this stil missing implementation was replaced
292   * by the new DynamicAny package.
293   *
294   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
295   *
296   * @throws NO_IMPLEMENT, always.
297   */
298  public DynAny create_dyn_any(org.omg.CORBA.Any a)
299  {
300    throw new NO_IMPLEMENT();
301  }
302
303  /**
304   * The support for {@link DynArray}
305   * has never been implemented in Sun's java releases,
306   * at least till v1.4 inclusive.
307   *
308   * Since v1.4 this stil missing implementation was replaced
309   * by the new DynamicAny package.
310   *
311   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
312   *
313   * @throws NO_IMPLEMENT, always.
314   */
315  public DynArray create_dyn_array(org.omg.CORBA.TypeCode t)
316                            throws InconsistentTypeCode
317  {
318    throw new NO_IMPLEMENT();
319  }
320
321  /**
322   * The support for {@link DynEnum}
323   * has never been implemented in Sun's java releases,
324   * at least till v1.4 inclusive.
325   *
326   * Since v1.4 this stil missing implementation was replaced
327   * by the new DynamicAny package.
328   *
329   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
330   *
331   * @throws NO_IMPLEMENT, always.
332   */
333  public DynEnum create_dyn_enum(org.omg.CORBA.TypeCode t)
334                          throws InconsistentTypeCode
335  {
336    throw new NO_IMPLEMENT();
337  }
338
339  /**
340   * The support for {@link DynSequence}
341   * has never been implemented in Sun's java releases,
342   * at least till v1.4 inclusive.
343   *
344   * Since v1.4 this stil missing implementation was replaced
345   * by the new DynamicAny package.
346   *
347   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
348   *
349   * @throws NO_IMPLEMENT, always.
350   */
351  public DynSequence create_dyn_sequence(org.omg.CORBA.TypeCode t)
352                                  throws InconsistentTypeCode
353  {
354    throw new NO_IMPLEMENT();
355  }
356
357  /**
358   * The support for {@link DynStruct} and derived interfaces
359   * has never been implemented in Sun's java releases,
360   * at least till v1.4 inclusive.
361   *
362   * Since v1.4 this stil missing implementation was replaced
363   * by the new DynamicAny package.
364   *
365   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
366   *
367   * @throws NO_IMPLEMENT, always.
368   */
369  public DynStruct create_dyn_struct(org.omg.CORBA.TypeCode t)
370                              throws InconsistentTypeCode
371  {
372    throw new NO_IMPLEMENT();
373  }
374
375  /**
376   * The support for {@link DynUnion} and derived interfaces
377   * has never been implemented in Sun's java releases,
378   * at least till v1.4 inclusive.
379   *
380   * Since v1.4 this stil missing implementation was replaced
381   * by the new DynamicAny package.
382   *
383   * @deprecated Use {@link org.omg.DynamicAny.DynAnyFactory}
384   *
385   * @throws NO_IMPLEMENT, always.
386   */
387  public DynUnion create_dyn_union(org.omg.CORBA.TypeCode t)
388                            throws InconsistentTypeCode
389  {
390    throw new NO_IMPLEMENT();
391  }
392
393  /**
394   * Create a typecode, defining the given enumeration.
395   *
396   * @param id the id.
397   * @param name the name.
398   * @param members the memebers
399   * @return the created enumeration.
400   */
401  public abstract TypeCode create_enum_tc(String id, String name,
402                                          String[] members
403                                         );
404
405  /**
406   * Create an environment (container for exceptions).
407   *
408   * @return the created container.
409   */
410  public abstract Environment create_environment();
411
412  /**
413   * Creates an empty exception list.
414   *
415   * @return the newly created list.
416   */
417  public abstract ExceptionList create_exception_list();
418
419  /**
420   * Create the exception typecode.
421   *
422   * @param id the id of exception.
423   * @param name the name of exception.
424   * @param members the members of exception.
425   */
426  public abstract TypeCode create_exception_tc(String id, String name,
427                                               StructMember[] members
428                                              );
429
430  /**
431   * Creates a TypeCode object for CORBA <code>fixed</code> that is
432   * mapped to java {@link java.math.BigDecimal}.
433   *
434   * @param digits the number of digits in that <code>fixed</code>.
435   * @param scale the number of digits after the decimal point.
436   *
437   * @return the corresponding TypeCode.
438   */
439  public TypeCode create_fixed_tc(short digits, short scale)
440  {
441    FixedTypeCode r = new FixedTypeCode();
442    r.setDigits(digits);
443    r.setScale(scale);
444    return r;
445  }
446
447  /**
448   * Creates a typecode, representing the IDL interface.
449   *
450   * @param id the interface repository id.
451   * @param name the interface name.
452   *
453   * @return the created typecode.
454   */
455  public abstract TypeCode create_interface_tc(String id, String name);
456
457  /**
458   * Create an instance of a new {@link NVList}.
459   *
460   * @param count the initial size of the list. If more elements are added,
461   * the list automatically expands.
462   *
463   * @return the created list.
464   */
465  public abstract NVList create_list(int count);
466
467  /**
468   * Create a new named value.
469   *
470   * @param name the name of the named value
471   * @param any the content of the named value.
472   * @param flags the flags of the named value
473   *
474   * @return the named value.
475   */
476  public abstract NamedValue create_named_value(String name, Any any, int flags);
477
478  /**
479   * Send multiple prepared requests one way, do not caring about the answer.
480   * The messages, containing requests, will be marked, indicating that
481   * the sender is not expecting to get a reply.
482   *
483   * @param requests the prepared array of requests.
484   *
485   * @see Request#send_oneway()
486   */
487  public abstract void send_multiple_requests_oneway(Request[] requests);
488
489  /**
490   * Send multiple prepared requests expecting to get a reply. All requests
491   * are send in parallel, each in its own separate thread. When the
492   * reply arrives, it is stored in the agreed fields of the corresponing
493   * request data structure. If this method is called repeatedly,
494   * the new requests are added to the set of the currently sent requests,
495   * but the old set is not discarded.
496   *
497   * @param requests the prepared array of requests.
498   *
499   * @see #poll_next_response()
500   * @see #get_next_response()
501   * @see Request#send_deferred()
502   */
503  public abstract void send_multiple_requests_deferred(Request[] requests);
504
505  /**
506   * Find if any of the requests that have been previously sent with
507   * {@link #send_multiple_requests_deferred}, have a response yet.
508   *
509   * @return true if there is at least one response to the previously
510   * sent request, false otherwise.
511   */
512  public abstract boolean poll_next_response();
513
514  /**
515   * Get the next instance with a response being received. If all currently
516   * sent responses not yet processed, this method pauses till at least one of
517   * them is complete. If there are no requests currently sent, the method
518   * pauses till some request is submitted and the response is received.
519   * This strategy is identical to the one accepted by Suns 1.4 ORB
520   * implementation.
521   *
522   * @return the previously sent request that now contains the received
523   * response.
524   *
525   * @throws WrongTransaction If the method was called from the transaction
526   * scope different than the one, used to send the request. The exception
527   * can be raised only if the request is implicitly associated with some
528   * particular transaction.
529   */
530  public abstract Request get_next_response()
531                                     throws WrongTransaction;
532
533  /**
534   * Create a new CDR output stream, where the parameter values can be written
535   * during the method invocation.
536   *
537   * @return a stream to write values into.
538   */
539  public abstract org.omg.CORBA.portable.OutputStream create_output_stream();
540
541  /**
542   * This should create the list, initialised with the argument descriptions
543   * for the given operation definition (CORBA <code>OperationDef</code>).
544   * The information should be obtained from the interface repository.
545   * However this method is oficially documented as not implemented at least
546   * till v1.4 inclusive.
547   *
548   * @param operation_definition the operation definition, must be
549   * CORBA <code>OperationDef</code>.
550   *
551   * @return never
552   *
553   * @throws NO_IMPLEMENT, always.
554   */
555  public NVList create_operation_list(Object operation_definition)
556  {
557    throw new NO_IMPLEMENT();
558  }
559
560  /**
561   * <p>Creates the new policy of the specified type, having the given value.
562   * This method looks for the policy factory that was previously registered
563   * during ORB initialization by
564   * {@link org.omg.PortableInterceptor#ORBInitialiser}.
565   *
566   * If the suitable factory is found, this factory creates the requested policy,
567   * otherwise the PolicyError is thrown.
568   * </p><p>
569   * The POA policies should be created by POA, not by this method.
570   * </p>
571   * @param type the policy type.
572   * @param value the policy value, wrapped into Any.
573   *
574   * @throws PolicyError if the ORB fails to instantiate the policy object.
575   *
576   * @throws NO_IMPLEMENT always (in this class). Overridden in derived classes
577   * returned by ORB.init(..).
578   *
579   * @see org.omg.PortableInterceptor.ORBInitInfoOperations#register_policy_factory
580   * @see org.omg.PortableInterceptor.PolicyFactoryOperations
581   */
582  public Policy create_policy(int type, Any value)
583                       throws PolicyError
584  {
585    throw new NO_IMPLEMENT();
586  }
587
588  /**
589   * Create typecode, defining the sequence of the elements, having
590   * the given type.
591   *
592   * @param bound the maximal length of the sequence, 0 if not restricted.
593   *
594   * @param element_type the sequence element type.
595   *
596   * @return the typecode.
597   */
598  public abstract TypeCode create_sequence_tc(int bound, TypeCode element_type);
599
600  /**
601   * Create a TypeCode, representing the CORBA <code>string</code>.
602   *
603   * @param bound the maximal length of the string, 0 is unlimited.
604   *
605   * @return the corresponding string typecode.
606   */
607  public abstract TypeCode create_string_tc(int bound);
608
609  /**
610   * Create the typecode, defining the given IDL structure.
611   *
612   * The TypeCode object is initialized with the given id, name, and members.
613   * @param id the Id of this type.
614   * @param name the name of this type.
615   * @param members the member list.
616   *
617   * @return the typecode.
618   */
619  public abstract TypeCode create_struct_tc(String id, String name,
620                                            StructMember[] members
621                                           );
622
623  /**
624   * Create the typecode, defining the given IDL union.
625   *
626   * The TypeCode object is initialized with the given id, name, discriminator
627   * and members.
628   *
629   * @param id the Id of this type.
630   * @param name the name of this type.
631   * @param discriminator the union discriminator.
632   * @param members the member list.
633   *
634   * @return the typecode.
635   */
636  public abstract TypeCode create_union_tc(String id, String name,
637                                           TypeCode discriminator,
638                                           UnionMember[] members
639                                          );
640
641  /**
642   * Create a TypeCode, representing the CORBA <code>wstring</code>.
643   *
644   * @param bound the maximal length of the string, 0 is unlimited.
645   *
646   * @return the corresponding string typecode.
647   */
648  public abstract TypeCode create_wstring_tc(int bound);
649
650  /**
651   * Create a typecode for an abstract interface. The abstract interface
652   * can be either CORBA object or CORBA value type.
653   *
654   * @param id the id of the abstract interface.
655   * @param name the name of the abstract interface.
656   *
657   * @return the created typecode.
658   */
659  public TypeCode create_abstract_interface_tc(String id, String name)
660  {
661    GeneralTypeCode t = new GeneralTypeCode(TCKind.tk_abstract_interface);
662    t.setName(name);
663    t.setId(id);
664    return t;
665  }
666
667  /**
668   * Create a typecode for a native interface.
669   *
670   * @param id the id of the native interface.
671   * @param name the name of the native interface.
672   *
673   * @return the created typecode.
674   */
675  public TypeCode create_native_tc(String id, String name)
676  {
677    GeneralTypeCode t = new GeneralTypeCode(TCKind.tk_native);
678    t.setName(name);
679    t.setId(id);
680    return t;
681  }
682
683
684  /**
685   * Create a typecode which serves as a placeholder for typcode, containing
686   * recursion.
687   *
688   * @param id the id of the recursive typecode, for that this typecode
689   * serves as a placeholder.
690   */
691  public TypeCode create_recursive_tc(String id)
692  {
693    return new RecursiveTypeCode(id);
694  }
695
696  /**
697   * Create value box typecode.
698   */
699  public TypeCode create_value_box_tc(String id, String name,
700                                      TypeCode boxed_type
701                                     )
702  {
703    GeneralTypeCode t = new GeneralTypeCode(TCKind.tk_value_box);
704    t.setName(name);
705    t.setId(id);
706    t.setContentType(boxed_type);
707    return t;
708  }
709
710  /**
711   * Create IDL value type code.
712   */
713  public TypeCode create_value_tc(String id, String name, short type_modifier,
714                                  TypeCode concrete_base, ValueMember[] members
715                                 )
716  {
717    RecordTypeCode r = new RecordTypeCode(TCKind.tk_value);
718    r.setId(id);
719    r.setName(name);
720    r.setTypeModifier(type_modifier);
721    r.setConcreteBase_type(concrete_base);
722
723    for (int i = 0; i < members.length; i++)
724      {
725        r.add(members [ i ]);
726      }
727
728    return r;
729  }
730
731  /**
732   * This should return the information, related to the current thread.
733   * The information is needed, for instance, to get the current object
734   * from the code that serves several objects in parallel threads.
735   * The {@link Current} is very general interface, with no fields and
736   * operations defined. This method is not implemented in Suns
737   * releases at least till v1.5 inclusive. To obtain the
738   * {@link org.omg.PortableServer.Current}, use
739   * {@link #resolve_initial_references}, passing "POACurrent".
740   *
741   * @deprecated since 1.2, use {@link #resolve_initial_references}.
742   *
743   * @return never
744   *
745   * @throws NO_IMPLEMENT always.
746   */
747  public Current get_current()
748  {
749    throw new NO_IMPLEMENT();
750  }
751
752  /**
753   * This should return the information about the CORBA facilities and
754   * services, available from this ORB. However this method is oficially
755   * documented as not implemented at least till v1.5 inclusive.
756   *
757   * @param service_type a type of the service being requested. The OMG
758   * specification currently defines only one value, 1, for security
759   * related services.
760   *
761   * @param service_info a holder, where the returned information should
762   * be stored.
763   *
764   * @return should return true if the service information is available
765   * from the ORB, but this method never returns.
766   *
767   * @throws NO_IMPLEMENT always.
768   */
769  public boolean get_service_information(short service_type,
770                                         ServiceInformationHolder service_info
771                                        )
772  {
773    throw new NO_IMPLEMENT();
774  }
775
776  /**
777   * Get the default context of this ORB. This is an initial root of all
778   * contexts.
779   *
780   * The default method returns a new context with the empty name and
781   * no parent context.
782   *
783   * @return the default context of this ORB.
784   *
785   * @throws NO_IMPLEMENT for the Singleton ORB, returned by
786   * the parameterless {@link #init()}.
787   */
788  public abstract Context get_default_context();
789
790  /**
791   * Return thg typecode, representing the given primitive object type.
792   *
793   * @param tcKind the kind of the primitive typecode.
794   *
795   * @return the typecode of the primitve typecode.
796   */
797  public abstract TypeCode get_primitive_tc(TCKind tcKind);
798
799  /**
800   * Returns so-called Singleton ORB, a highly restricted version
801   * that cannot communicate over network. This ORB is provided
802   * for the potentially malicious applets with heavy security restrictions.
803   *
804   * The returned Singleton ORB can only create typecodes,
805   * {@link Any}, {@link ContextList}, {@link NVList} and
806   * {@link org.omg.CORBA.portable.OutputStream} that writes to an
807   * internal buffer.
808   *
809   * All other methods throw the {@link NO_IMPLEMENT} exception, additionally
810   * printing the error message about the potential attempt to violate
811   * the security rules.
812   *
813   * The implementing ORB class, used in this method, is found as described
814   * in the header.
815   *
816   * @return the working derivative of ORB, implementing the methods
817   * of this abstract class.
818   */
819  public static ORB init()
820  {
821    String orb_cn = getCumulatedProperty(null, RESTRICTED_ORB);
822    if (orb_cn == null)
823      return OrbRestricted.Singleton;
824    else
825      return createORB(null, orb_cn);
826  }
827
828  /**
829   * Creates the working instance of ORB for an applet.
830   *
831   * By default the built-in fully functional ORB is returned. The ORB class
832   * is found as described in the header of this class.
833   *
834   * @param applet the applet. The property org.omg.CORBA.ORBClass,
835   * if present, defines the used ORB implementation class. If this
836   * property is not present, the ORB class is found as described in the
837   * class header.
838   *
839   * @param props the properties, may be <code>null</code>.
840   *
841   * @return a newly created functional derivative of this abstract class.
842   */
843  public static ORB init(Applet applet, Properties props)
844  {
845    String ocn = applet.getParameter(FUNCTIONAL_ORB);
846    String lp = applet.getParameter(LISTENER_PORT);
847
848    if (ocn==null && lp!=null)
849      ocn = DEFAULT_FOCUSED_ORB;
850
851    ORB orb = createORB(props, ocn);
852    orb.set_parameters(applet, props);
853
854    return orb;
855  }
856
857  /**
858   * Creates the working instance of ORB for a standalone application.
859   *
860   * By default the built-in fully functional ORB is returned. The ORB class is
861   * found as described in the header of this class.
862   *
863   * @param args the parameters, passed to the applications
864   * <code>main(String[] args)</code> method, may be <code>null</code>. The
865   * parameter -org.omg.CORBA.ORBClass <class name> if present, defines the used
866   * ORB implementation class. If this property is not present, the ORB class is
867   * found as described in the class header.
868   *
869   * @param props application specific properties, may be <code>null</code>.
870   *
871   * @return a newly created functional derivative of this abstract class.
872   */
873  public static ORB init(String[] args, Properties props)
874  {
875    String ocn = null;
876    String lp = null;
877
878    String orbKey = "-" + FUNCTIONAL_ORB;
879    String lpKey = "-" + LISTENER_PORT;
880
881    if (args != null)
882      if (args.length >= 2)
883        {
884          for (int i = 0; i < args.length - 1; i++)
885            {
886              if (args[i].equals(orbKey))
887                ocn = args[i + 1];
888              if (args[i].equals(lpKey))
889                lp = args[i + 1];
890            }
891        }
892
893    if (lp != null && ocn == null)
894      ocn = DEFAULT_FOCUSED_ORB;
895
896    ORB orb = createORB(props, ocn);
897
898    orb.set_parameters(args, props);
899    return orb;
900  }
901
902  /**
903   * List the initially available CORBA objects (services).
904   *
905   * @return a list of services.
906   *
907   * @see #resolve_initial_references(String)
908   */
909  public abstract String[] list_initial_services();
910
911  /**
912   * Find and return the easily accessible CORBA object, addressed
913   * by name.  The returned object is typically casted to the more
914   * specific reference using the <code>narrow(Object)</code> method
915   * of its helper. The method resolves the following string values,
916   * returning the working objects:
917   * <table border="1"><tr><th>String</th><th>Object class</th>
918   * <th>Object use</th></tr>
919   *
920   * <tr><td>NameService</td><td>{@link org.omg.CosNaming.NamingContextExt}</td>
921   * <td>Finds (usually remote) object by its name.</td></tr>
922   *
923   * <tr><td>RootPOA</td><td>{@link org.omg.PortableServer.POA}</td>
924   * <td>Holds the POA tree for this ORB, where since 1.4 all servants
925   * should be connected.</td></tr>
926   *
927   * <tr><td>RootPOAManager</td><td>{@link org.omg.PortableServer.POAManager}
928   * </td><td>Regulates (suspends/resumes) the root POA
929   * activity</td></tr>
930   *
931   * <tr><td>POACurrent</td><td>{@link org.omg.PortableServer.Current}
932   * </td><td>Informs the current thread about the Id and POA of the
933   * object being currently served (the methods of
934   * <code>Current</code> return different values for
935   * different threads).
936   * </td></tr>
937   *
938   * <tr><td>CodecFactory</td><td>{@link org.omg.IOP.Codec}</td>
939   * <td>Encodes/decodes IDL data types into/from byte arrays.</td>
940   * </tr>
941   *
942   * <tr><td>DynAnyFactory</td><td>{@link org.omg.DynamicAny.DynAnyFactory}</td>
943   * <td>Creates DynAny's.</td>
944   * </tr>
945   *
946   * <tr><td>PICurrent</td><td>{@link org.omg.PortableInterceptor.Current}</td>
947   * <td>Contains multiple slots where an interceptor can rememeber the
948   * request - specific values between subsequent
949   * calls of the interceptor methods.</td>
950   * </tr>
951   *
952   * </table>
953   *
954   * @param name the object name.
955   * @return the object
956   * @throws org.omg.CORBA.ORBPackage.InvalidName if the given name
957   * is not associated with the known object.
958   */
959  public abstract Object resolve_initial_references(String name)
960    throws org.omg.CORBA.ORBPackage.InvalidName;
961
962  /**
963   * Get the IOR reference string for the given object.
964   * IOR can be compared with the Internet address for a web page,
965   * it provides means to locate the CORBA service on the web.
966   * IOR contains the host address, port number, the object identifier
967   * (key) inside the server, the communication protocol version,
968   * supported charsets and so on.
969   *
970   * @param forObject the CORBA object
971   * @return the object IOR representation.
972   * @see #string_to_object(String)
973   */
974  public abstract String object_to_string(Object forObject);
975
976  /**
977   * This should perform the implementation dependent unit of work in the
978   * main thread.
979   *
980   * This method is part of the support for the distribute use of the
981   * single execution thread.
982   *
983   * Same as in Suns releases at least till 1.4 inclusive,
984   * the distribute use of the single thread is not implemented.
985   * Use multiple threads, provided by jre.
986   *
987   * The method returns without action.
988   */
989  public void perform_work()
990  {
991  }
992
993  /**
994  * Checks if the ORB needs the main thread to perform some work.
995  * The method should return true if the ORB needs the main thread,
996  * and false if it does not.
997  *
998  * This method is part of the support for the distribute use of the
999  * single execution thread.
1000  *
1001  * Same as in Suns releases at least till 1.4 inclusive,
1002  * the distributed use of the single thread is not implemented.
1003  * Use multiple threads, provided by jre.
1004  *
1005  * @return false, always.
1006  */
1007  public boolean work_pending()
1008  {
1009    return false;
1010  }
1011
1012  /**
1013   * <p>Find and return the CORBA object, addressed by the given
1014   * string representation. The object can be (an usually is)
1015   * located on a remote computer, possibly running a different
1016   * (not necessary java) CORBA implementation. The returned
1017   * object is typically casted to the more specific reference
1018   * using the <code>narrow(Object)</code> method of its helper.
1019   * </p><p>
1020   * This function supports the following input formats:<br>
1021   * 1. IOR reference (<b>ior:</b>nnnnn ..), usually computer generated.<br>
1022   * 2. <b>corbaloc:</b>[<b>iiop</b>][version.subversion<b>@</b>]<b>:</b>host[<b>:</b>port]<b>/</b><i>key</i>
1023   * defines similar information as IOR reference, but is more human readable.
1024   * This type of reference may also contain multiple addresses (see
1025   * OMG documentation for complete format).<br>
1026   * 3. <b>corbaloc:rir:/</b><i>name</i> defines internal reference on this
1027   * ORB that is resolved using {@link #resolve_initial_references}, passing
1028   * the given <i>name</i> as parameter.<br>
1029   * 4. <b>corbaname:rir:#</b><i>name</i> states that the given <i>name</i>
1030   * must be resolved using the naming service, default for this ORB.<br>
1031   * 5. <b>corbaname:</b>[<b>iiop</b>][version.subversion<b>@</b>]<b>:</b>host[<b>:</b>port]<b>#</b><i>name</i>
1032   * states that the <i>name</i> must be resolved using the naming service
1033   * that runs on the given host at the given port. The ORB expects to find
1034   * there the {@link org.omg.CosNaming.NamingContext} under the key
1035   * "NameService.<br>
1036   * 7. file://[file name] Read the object definition string from the
1037   * file system<br>
1038   * 8. http://[url] Read the object definition string from the provided
1039   * url.<br>
1040   * 9. ftp://[url] Read the object definition string from the provided
1041   * url.<br>
1042   *
1043   * <p>The default port is always 2809. The default iiop version is 1.0
1044   * that now may not always be supported, so we would recommend to specify
1045   * the version explicitly.</p>
1046   * <p>
1047   * The examples of the corbaloc and corbaname addresses:<br>
1048   * corbaname:rir:#xobj - ask local naming service for "xobj".<br>
1049   * corbaname:rir:/NameService#xobj - same (long form).<br>
1050   * corbaname:iiop:1.2@localhost:900#xobj - same, assuming that the naming
1051   * service runs at port 900 on the local host and supports iiop 1.2.<br>
1052   * corbaname:iiop:localhost#xobj - same, assuming that the naming
1053   * service runs at port 2809 on the local host and supports iiop 1.0.<br>
1054   * corbaloc::gnu.xxx.yy/Prod/TradingService - the object exists on the
1055   * host gnu.xxx.yy, port 2809 having the key "Prod/TradingService". Its ORB
1056   * supports iiop 1.0.<br>
1057   * corbaloc::gnu.xxx.yy/Prod/TradingService:801 - the object exists on the
1058   * host gnu.xxx.yy, port 801 having the key "Prod/TradingService". Its ORB
1059   * supports iiop 1.0 (iiop keyword ommitted).<br>
1060   * corbaloc:iiop:1.1@gnu.xxx.yy/Prod/TradingService - the object exists on the
1061   * host gnu.xxx.yy, port 801 having the key "Prod/TradingService". Its ORB
1062   * supports iiop 1.1.<br>
1063   * corbaloc:rir:/NameService - the default naming service.
1064   *
1065   * @param IOR the object IOR representation string.
1066   *
1067   * @return the found CORBA object.
1068   *
1069   * @throws BAD_PARAM if the string being parsed is invalid.
1070   * @throws DATA_CONVERSION if the string being parsed contains unsupported
1071   * prefix or protocol.
1072   *
1073   * @see #object_to_string(org.omg.CORBA.Object)
1074   */
1075  public abstract Object string_to_object(String IOR);
1076
1077  /**
1078   * Start listening on the input socket. This method
1079   * blocks the current thread until {@link #shutdown(boolean)}
1080   * is called and shutdown process is completed.
1081   */
1082  public void run()
1083  {
1084  }
1085
1086  /**
1087   * Shutdown the ORB server.
1088   *
1089   * @param wait_for_completion if true, the current thread is
1090   * suspended untile the shutdown process is complete.
1091   */
1092  public void shutdown(boolean wait_for_completion)
1093  {
1094  }
1095
1096  /**
1097   * Destroy this server, releasing the occupied resources.
1098   * The default method returns without action.
1099   */
1100  public void destroy()
1101  {
1102  }
1103
1104  /**
1105   * Set the ORB parameters. This method is normally called from
1106   * {@link #init(String[], Properties)}.
1107   *
1108   * @param para the parameters, that were passed as the parameters
1109   * to the  <code>main(String[] args)</code> method of the current standalone
1110   * application.
1111   *
1112   * @param props application specific properties that were passed
1113   * as a second parameter in {@link #init(String[], Properties)}).
1114   * Can be <code>null</code>.
1115   */
1116  protected abstract void set_parameters(String[] para, Properties props);
1117
1118  /**
1119   * Set the ORB parameters. This method is normally called from
1120   * {@link #init(Applet, Properties)}.
1121   *
1122   * @param app the current applet.
1123   *
1124   * @param props application specific properties, passed as the second
1125   * parameter in {@link #init(Applet, Properties)}.
1126   * Can be <code>null</code>.
1127   */
1128  protected abstract void set_parameters(Applet app, Properties props);
1129
1130  /**
1131   * Get the property with the given name, searching in the standard
1132   * places for the ORB properties.
1133   */
1134  private static String getCumulatedProperty(Properties props, String property)
1135  {
1136    String orb_cn = null;
1137
1138    if (props != null)
1139      orb_cn = props.getProperty(property, null);
1140
1141    if (orb_cn == null)
1142      orb_cn = System.getProperty(property, null);
1143
1144    if (orb_cn == null)
1145      orb_cn = checkFile(property, "user.home", null);
1146
1147    if (orb_cn == null)
1148      orb_cn = checkFile(property, "java.home", "lib");
1149
1150    return orb_cn;
1151  }
1152
1153  /**
1154   * Check if the property is defined in the existsting file orb.properties.
1155   *
1156   * @param property the property
1157   * @param dir the system property, defining the folder where the
1158   * file could be expected.
1159   * @param subdir subfolder where to look for the file.
1160   *
1161   * @return the property value, null if not found or file does not exist.
1162   */
1163  private static String checkFile(String property, String dir, String subdir)
1164  {
1165    try
1166      {
1167        File f = new File(dir);
1168        if (!f.exists())
1169          return null;
1170
1171        if (subdir != null)
1172          f = new File(f, subdir);
1173
1174        f = new File(f, "orb.properties");
1175
1176        if (!f.exists())
1177          return null;
1178
1179        Properties p = new Properties();
1180        p.load(new BufferedInputStream(new FileInputStream(f)));
1181
1182        return p.getProperty(property, null);
1183      }
1184    catch (IOException ex)
1185      {
1186        return null;
1187      }
1188  }
1189
1190  /**
1191   * Create ORB when its name is possibly known.
1192   *
1193   * @param props properties, possibly containing the ORB name.
1194   * @param orbClassName the direct ORB class name, overriding other possible
1195   * locations, or null if not specified.
1196   */
1197  private static ORB createORB(Properties props, String orbClassName)
1198  {
1199    ORB orb = null;
1200
1201    if (orbClassName == null)
1202      {
1203        orbClassName = getCumulatedProperty(props, FUNCTIONAL_ORB);
1204
1205        if (orbClassName == null)
1206          {
1207            String lp = getCumulatedProperty(props, LISTENER_PORT);
1208            if (lp != null)
1209              orbClassName = DEFAULT_FOCUSED_ORB;
1210            else
1211              orbClassName = DEFAULT_FUNCTIONAL_ORB;
1212          }
1213      }
1214
1215    try
1216      {
1217        orb = (ORB) ObjectCreator.forName(orbClassName).newInstance();
1218      }
1219    catch (ClassNotFoundException ex)
1220      {
1221        noORB(orbClassName, ex);
1222      }
1223    catch (IllegalAccessException ex)
1224      {
1225        noORB(orbClassName, ex);
1226      }
1227    catch (InstantiationException ex)
1228      {
1229        noORB(orbClassName, ex);
1230      }
1231
1232    return orb;
1233  }
1234
1235  /**
1236   * Throw the runtime exception.
1237   *
1238   * @param orb_c the ORB class name.
1239   * @param why the explaining chained exception.
1240   */
1241  private static void noORB(String orb_c, Throwable why)
1242  {
1243    throw new RuntimeException("The ORB " + orb_c + " cannot be instantiated.",
1244                               why
1245                              );
1246  }
1247}