/[classpath]/classpath/org/omg/CORBA/ORB.java
ViewVC logotype

Diff of /classpath/org/omg/CORBA/ORB.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.2 by mkoch, Wed Mar 9 09:56:54 2005 UTC revision 1.3 by audriusa, Sun May 15 01:09:29 2005 UTC
# Line 38  exception statement from your version. * Line 38  exception statement from your version. *
38    
39  package org.omg.CORBA;  package org.omg.CORBA;
40    
41    import gnu.CORBA.Restricted_ORB;
42    import gnu.CORBA.fixedTypeCode;
43    import gnu.CORBA.generalTypeCode;
44    import gnu.CORBA.gnuContext;
45    import gnu.CORBA.recordTypeCode;
46    import gnu.CORBA.recursiveTypeCode;
47    
48    import java.applet.Applet;
49    
50    import java.io.BufferedInputStream;
51    import java.io.File;
52    import java.io.FileInputStream;
53    import java.io.IOException;
54    
55    import java.util.Properties;
56    
57  /**  /**
58   * FIXME   * When creating an ORB instance is being created, the class name
59   * Not implemented yet, defined here to keep the package code compilable.   * is searched in the following locations:
60     * <p>
61     * 1. Applet parameter or application string array, if any.<br>
62     * 2. The properties parameter, if any.<br>
63     * 3. The System properties.<br>
64     * 4. The orb.properties file located in the user.home directory (if any).<br>
65     * 5. The orb.properties file located in the java.home/lib directory (if any).
66     * </p>
67     *
68     * The supported properties are:
69     * <table border="1">
70     * <tr><td> org.omg.CORBA.ORBClass</td><td>The class,
71     *   implementing the functional ORB, returned by
72     *   {@link #init(Applet, Properties)} or
73     *   {@link #init(String[], Properties)} </td></tr>
74     * <tr><td>org.omg.CORBA.ORBSingletonClass</td><td>The class,
75     *   implementing the restricted ORB, returned by
76     *   {@link #init()}.
77     * </td></tr>
78     * <tr><td>org.omg.CORBA.ORBInitRef</td><td>Specifies the
79     * initial reference, accessible by name with the method
80     * {@link resolve_initial_references(String)}.
81     * </table>
82     * The command line accepts the same properties as a keys. When specifying
83     * in the command line, the prefix org.omg.CORBA can be omitted,
84     * for instance<code> -ORBInitRef NameService=IOR:aabbccdd....</code>
85     *
86     * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
87   */   */
88  public class ORB  public abstract class ORB
89  {  {
90    public ORB()    /**
91      * By default, {@link init(String[], Properties)} and
92      * {@link init(Applet, Properties} return
93      * the built-in fully functional ORB is returned. If the
94      * <code>props</code> contains the property org.omg.CORBA.ORBClass,
95      * the value of this property is used as a class name to instantiate
96      * a user-defined ORB.
97      */
98      private static final String FUNCTIONAL_ORB = "org.omg.CORBA.ORBClass";
99    
100      /**
101       * The name of the restricted ORB property.
102       */
103      private static final String RESTRICTED_ORB =
104        "org.omg.CORBA.ORBSingletonClass";
105    
106      /**
107       * The class, implementing the default fully functional ORB.
108       */
109      private static final String DEFAULT_FUNCTIONAL_ORB = "gnu.CORBA.Functional_ORB";
110    
111      /**
112       * The class, implementing the default restricted ORB.
113       */
114      private static final String DEFAULT_RESTRICTED_ORB = "gnu.CORBA.Restricted_ORB";
115    
116    
117      /**
118       * Connect the given CORBA object to this ORB. After the object is
119       * connected, it starts receiving remote invocations via this ORB.
120       *
121       * The OMG group recommends to use Portable Object Adapter (POA) instead
122       * of calling this method.
123       *
124       * This method is implemented in the derived Gnu Classpah classes,
125       * returned by ORB.init(..). In this abstract class, the implementation
126       * just throws {@link NO_IMPLEMENT}.
127       *
128       * @param object the org.omg.CORBA.Object to connect.
129       */
130      public void connect(org.omg.CORBA.Object object)
131      {
132        throw new NO_IMPLEMENT();
133      }
134    
135      /**
136       * Disconnect the given CORBA object from this ORB. The object will be
137       * no longer receiving the remote invocations. In response to the
138       * remote invocation on this object, the ORB will send the
139       * exception {@link OBJECT_NOT_EXIST}. The object, however, is not
140       * destroyed and can receive the local invocations.
141       *
142       * This method is implemented in the derived Gnu Classpah classes,
143       * returned by ORB.init(..). In this abstract class, the implementation
144       * just throws {@link NO_IMPLEMENT}.
145       *
146       * @param object the object to disconnect.
147       */
148      public void disconnect(org.omg.CORBA.Object object)
149      {
150        throw new NO_IMPLEMENT();
151      }
152    
153    
154      /**
155       * Create alias typecode for the given typecode.
156       */
157      public abstract TypeCode create_alias_tc(String id, String name,
158                                               TypeCode typecode
159                                              );
160    
161      /**
162       * Create an instance of the CORBA {@link Any} with the type, intialised
163       * to {@link TCKind#tc_null}
164       */
165      public abstract Any create_any();
166    
167      /**
168       * Create a typecode, defining an array of the given elements.
169       *
170       * @param length the size of array
171       * @param element_type the array component type.
172       *
173       * @return the corresponding typecode.
174       */
175      public abstract TypeCode create_array_tc(int length, TypeCode element_type);
176    
177      /**
178       * Creates an empty CORBA <code>ContextList</code>.
179       *
180       * @return the newly created context list.
181       */
182      public abstract ContextList create_context_list();
183    
184      /**
185       * Create a typecode, defining the given enumeration.
186       *
187       * @param id the id.
188       * @param name the name.
189       * @param members the memebers
190       * @return the created enumeration.
191       */
192      public abstract TypeCode create_enum_tc(String id, String name,
193                                              String[] members
194                                             );
195    
196      /**
197       * Create an environment (container for exceptions).
198       *
199       * @return the created container.
200       */
201      public abstract Environment create_environment();
202    
203      /**
204       * Creates an empty exception list.
205       *
206       * @return the newly created list.
207       */
208      public abstract ExceptionList create_exception_list();
209    
210      /**
211       * Create the exception typecode.
212       *
213       * @param id the id of exception.
214       * @param name the name of exception.
215       * @param members the members of exception.
216       */
217      public abstract TypeCode create_exception_tc(String id, String name,
218                                                   StructMember[] members
219                                                  );
220    
221      /**
222       * Creates a TypeCode object for CORBA <code>fixed</code> that is
223       * mapped to java {@link java.math.BigDecimal}.
224       *
225       * @param digits the number of digits in that <code>fixed</code>.
226       * @param scale the number of digits after the decimal point.
227       *
228       * @return the corresponding TypeCode.
229       */
230      public TypeCode create_fixed_tc(short digits, short scale)
231      {
232        fixedTypeCode r = new fixedTypeCode();
233        r.setDigits(digits);
234        r.setScale(scale);
235        return r;
236      }
237    
238      /**
239       * Creates a typecode, representing the IDL interface.
240       *
241       * @param id the interface repository id.
242       * @param name the interface name.
243       *
244       * @return the created typecode.
245       */
246      public abstract TypeCode create_interface_tc(String id, String name);
247    
248      /**
249       * Create an instance of a new {@link NVList}.
250       *
251       * @param count the initial size of the list. If more elements are added,
252       * the list automatically expands.
253       *
254       * @return the created list.
255       */
256      public abstract NVList create_list(int count);
257    
258      /**
259       * Create a new named value.
260       *
261       * @param name the name of the named value
262       * @param any the content of the named value.
263       * @param flags the flags of the named value
264       *
265       * @return the named value.
266       */
267      public abstract NamedValue create_named_value(String s, Any any, int flags);
268    
269      /**
270       * Create a new CDR output stream, where the parameter values can be written
271       * during the method invocation.
272       *
273       * @return a stream to write values into.
274       */
275      public abstract org.omg.CORBA.portable.OutputStream create_output_stream();
276    
277      /**
278       * Create typecode, defining the sequence of the elements, having
279       * the given type.
280       *
281       * @param bound the maximal length of the sequence, 0 if not restricted.
282       *
283       * @param element_type the sequence element type.
284       *
285       * @return the typecode.
286       */
287      public abstract TypeCode create_sequence_tc(int bound, TypeCode element_type);
288    
289      /**
290       * Create a TypeCode, representing the CORBA <code>string</code>.
291       *
292       * @param bound the maximal length of the string, 0 is unlimited.
293       *
294       * @return the corresponding string typecode.
295       */
296      public abstract TypeCode create_string_tc(int bound);
297    
298      /**
299       * Create the typecode, defining the given IDL structure.
300       *
301       * The TypeCode object is initialized with the given id, name, and members.
302       * @param id the Id of this type.
303       * @param the name of this type.
304       * @param members the member list.
305       *
306       * @return the typecode.
307       */
308      public abstract TypeCode create_struct_tc(String id, String name,
309                                                StructMember[] members
310                                               );
311    
312      /**
313       * Create the typecode, defining the given IDL union.
314       *
315       * The TypeCode object is initialized with the given id, name, discriminator
316       * and members.
317       *
318       * @param id the Id of this type.
319       * @param the name of this type.
320       * @param discriminator the union discriminator.
321       * @param members the member list.
322       *
323       * @return the typecode.
324       */
325      public abstract TypeCode create_union_tc(String id, String name,
326                                               TypeCode discriminator,
327                                               UnionMember[] members
328                                              );
329    
330      /**
331       * Create a TypeCode, representing the CORBA <code>wstring</code>.
332       *
333       * @param bound the maximal length of the string, 0 is unlimited.
334       *
335       * @return the corresponding string typecode.
336       */
337      public abstract TypeCode create_wstring_tc(int bound);
338    
339      /**
340       * Create a typecode which serves as a placeholder for typcode, containing
341       * recursion.
342       *
343       * @param id the id of the recursive typecode, for that this typecode
344       * serves as a placeholder.
345       */
346      public TypeCode create_recursive_tc(String id)
347      {
348        return new recursiveTypeCode(id);
349      }
350    
351      /**
352       * Create value box typecode.
353       */
354      public TypeCode create_value_box_tc(String id, String name,
355                                          TypeCode boxed_type
356                                         )
357      {
358        generalTypeCode t = new generalTypeCode(TCKind.tk_value_box);
359        t.setName(name);
360        t.setId(id);
361        t.setContentType(boxed_type);
362        return t;
363      }
364    
365      /**
366       * Create IDL value type code.
367       */
368      public TypeCode create_value_tc(String id, String name, short type_modifier,
369                                      TypeCode concrete_base, ValueMember[] members
370                                     )
371      {
372        recordTypeCode r = new recordTypeCode(TCKind.tk_value);
373        r.setId(id);
374        r.setName(name);
375        r.setTypeModifier(type_modifier);
376        r.setConcreteBase_type(concrete_base);
377    
378        for (int i = 0; i < members.length; i++)
379          {
380            r.add(members [ i ]);
381          }
382    
383        return r;
384      }
385    
386      /**
387       * Get the default context of this ORB. This is an initial root of all
388       * contexts.
389       *
390       * The default method returns a new context with the empty name and
391       * no parent context.
392       *
393       * @return the default context of this ORB.
394       *
395       * @throws NO_IMPLEMENT for the Singleton ORB, returned by
396       * the parameterless {@link init()}.
397       */
398      public Context get_default_context()
399      {
400        return new gnuContext("", null);
401      }
402    
403      /**
404       * Return thg typecode, representing the given primitive object type.
405       *
406       * @param the kind of the primitive typecode.
407       *
408       * @return the typecode of the primitve typecode.
409       */
410      public abstract TypeCode get_primitive_tc(TCKind tcKind);
411    
412      /**
413       * Returns so-called Singleton ORB, a highly restricted version
414       * that cannot communicate over network. This ORB is provided
415       * for the potentially malicious applets with heavy security restrictions.
416       *
417       * The returned Singleton ORB can only create typecodes,
418       * {@link Any}, {@link ContextList}, {@link NVList} and
419       * {@link org.omg.CORBA.portable.OutputStream} that writes to an
420       * internal buffer.
421       *
422       * All other methods throw the {@link NO_IMPLEMENT} exception, additionally
423       * printing the error message about the potential attempt to violate
424       * the security rules.
425       *
426       * The implementing ORB class, used in this method, is found as described
427       * in the header.
428       *
429       * @return the working derivative of ORB, implementing the methods
430       * of this abstract class.
431       */
432      public static ORB init()
433      {
434        String orb_cn = getORBName(null, RESTRICTED_ORB);
435        if (orb_cn == null)
436          return Restricted_ORB.Singleton;
437        else
438          return createORB(null, orb_cn);
439      }
440    
441      /**
442       * Creates the working instance of ORB for an applet.
443       *
444       * By default the built-in fully functional ORB is returned. The ORB class
445       * is found as described in the header of this class.
446       *
447       * @param applet the applet. The property org.omg.CORBA.ORBClass,
448       * if present, defines the used ORB implementation class. If this
449       * property is not present, the ORB class is found as described in the
450       * class header.
451       *
452       * @param props the properties, may be <code>null</code>.
453       *
454       * @return a newly created functional derivative of this abstract class.
455       */
456      public static ORB init(Applet applet, Properties props)
457      {
458        String ocn = applet.getParameter(FUNCTIONAL_ORB);
459        ORB orb = createORB(props, ocn);
460        orb.set_parameters(applet, props);
461    
462        return orb;
463      }
464    
465      /**
466       * Creates the working instance of ORB for a
467       * standalone application.
468       *
469       * By default the built-in fully functional ORB is returned. The ORB class
470       * is found as described in the header of this class.
471       *
472       * @param the parameters, passed to the applications
473       * <code>main(String[] args)</code> method, may be <code>null</code>.
474       * The parameter -org.omg.CORBA.ORBClass <class name>
475       * if present, defines the used ORB implementation class. If this
476       * property is not present, the ORB class is found as described in the
477       * class header.
478    
479       *
480       * @param props application specific properties, may be <code>null</code>.
481       *
482       * @return a newly created functional derivative of this abstract class.
483       */
484      public static ORB init(String[] args, Properties props)
485      {
486        String ocn = null;
487    
488        String orbKey = "-" + FUNCTIONAL_ORB;
489    
490        if (args != null)
491          if (args.length >= 2)
492            {
493              for (int i = 0; i < args.length - 1; i++)
494                {
495                  if (args [ i ].equals(orbKey))
496                    ocn = args [ i + 1 ];
497                }
498            }
499    
500        ORB orb = createORB(props, ocn);
501    
502        orb.set_parameters(args, props);
503        return orb;
504      }
505    
506      /**
507       * List the initially available CORBA objects (services).
508       *
509       * @return a list of services.
510       *
511       * @see resolve_initial_references(String)
512       */
513      public abstract String[] list_initial_services();
514    
515      /**
516       * Find and return the easily accessible CORBA object, addressed
517       * by name.  The returned object is typically casted to the more
518       * specific reference using the <code>narrow(Object)</code> method
519       * of its helper.
520       *
521       * @param name the object name.
522       * @return the object
523       * @throws org.omg.CORBA.ORBPackage.InvalidName if the given name
524       * is not associated with the known object.
525       */
526      public abstract Object resolve_initial_references(String name)
527        throws org.omg.CORBA.ORBPackage.InvalidName;
528    
529      /**
530       * Get the IOR reference string for the given object.
531       * IOR can be compared with the Internet address for a web page,
532       * it provides means to locate the CORBA service on the web.
533       * IOR contains the host address, port number, the object identifier
534       * (key) inside the server, the communication protocol version,
535       * supported charsets and so on.
536       *
537       * @param the CORBA object
538       * @return the object IOR representation.
539       * @see string_to_object(String)
540       */
541      public abstract String object_to_string(Object forObject);
542    
543      /**
544       * Find and return the CORBA object, addressed by the given
545       * IOR string representation. The object can (an usually is)
546       * located on a remote computer, possibly running a different
547       * (not necessary java) CORBA implementation. The returned
548       * object is typically casted to the more specific reference
549       * using the <code>narrow(Object)</code> method of its helper.
550       *
551       * @param IOR the object IOR representation string.
552       *
553       * @return the found CORBA object.
554       * @see object_to_string(org.omg.CORBA.Object)
555       */
556      public abstract Object string_to_object(String IOR);
557    
558      /**
559       * Start listening on the input socket. This method
560       * blocks the current thread until {@link #shutdown(boolean)}
561       * is called and shutdown process is completed.
562       */
563      public void run()
564      {
565      }
566    
567      /**
568       * Shutdown the ORB server.
569       *
570       * @param wait_for_completion if true, the current thread is
571       * suspended untile the shutdown process is complete.
572       */
573      public void shutdown(boolean wait_for_completion)
574      {
575      }
576    
577      /**
578       * Destroy this server, releasing the occupied resources.
579       * The default method returns without action.
580       */
581      public void destroy()
582      {
583      }
584    
585      /**
586       * Set the ORB parameters. This method is normally called from
587       * {@link #init(String[], Properties)}.
588       *
589       * @param para the parameters, that were passed as the parameters
590       * to the  <code>main(String[] args)</code> method of the current standalone
591       * application.
592       *
593       * @param props application specific properties that were passed
594       * as a second parameter in {@link init(String[], Properties)}).
595       * Can be <code>null</code>.
596       */
597      protected abstract void set_parameters(String[] para, Properties props);
598    
599      /**
600       * Set the ORB parameters. This method is normally called from
601       * {@link #init(Applet, Properties)}.
602       *
603       * @param app the current applet.
604       *
605       * @param props application specific properties, passed as the second
606       * parameter in {@link #init(Applet, Properties)}.
607       * Can be <code>null</code>.
608       */
609      protected abstract void set_parameters(Applet app, Properties props);
610    
611      /**
612       * Checks if the communication over network is allowed.
613       * @throws java.lang.SecurityException
614       */
615      private static final void checkNetworkingPermission(String host, int port)
616                                                   throws SecurityException
617      {
618        SecurityManager security = System.getSecurityManager();
619        if (security != null)
620          {
621            security.checkConnect(host, port);
622          }
623      }
624    
625      /**
626       * Get the ORB class name.
627       */
628      private static String getORBName(Properties props, String property)
629      {
630        String orb_cn = null;
631    
632        if (props != null)
633          orb_cn = props.getProperty(property, null);
634    
635        if (orb_cn == null)
636          orb_cn = System.getProperty(property, null);
637    
638        if (orb_cn == null)
639          orb_cn = checkFile(property, "user.home", null);
640    
641        if (orb_cn == null)
642          orb_cn = checkFile(property, "java.home", "lib");
643    
644        return orb_cn;
645      }
646    
647      /**
648       * Check if the property is defined in the existsting file orb.properties.
649       *
650       * @param property the property
651       * @param dir the system property, defining the folder where the
652       * file could be expected.
653       * @param subdir subfolder where to look for the file.
654       *
655       * @return the property value, null if not found or file does not exist.
656       */
657      private static String checkFile(String property, String dir, String subdir)
658      {
659        try
660          {
661            File f = new File(dir);
662            if (!f.exists())
663              return null;
664    
665            if (subdir != null)
666              f = new File(f, subdir);
667    
668            f = new File(f, "orb.properties");
669    
670            if (!f.exists())
671              return null;
672    
673            Properties p = new Properties();
674            p.load(new BufferedInputStream(new FileInputStream(f)));
675    
676            return p.getProperty(property, null);
677          }
678        catch (IOException ex)
679          {
680            return null;
681          }
682      }
683    
684      /**
685       * Create ORB when its name is possibly known.
686       *
687       * @param props properties, possibly containing the ORB name.
688       * @param orbClassName the direct ORB class name, overriding
689       * other possible locations, or null if not specified.
690       */
691      private static ORB createORB(Properties props, String orbClassName)
692      {
693        ORB orb = null;
694    
695        if (orbClassName == null)
696          {
697            orbClassName = getORBName(props, FUNCTIONAL_ORB);
698    
699            if (orbClassName == null)
700              orbClassName = DEFAULT_FUNCTIONAL_ORB;
701          }
702    
703        try
704          {
705            orb = (ORB) Class.forName(orbClassName).newInstance();
706          }
707        catch (ClassNotFoundException ex)
708          {
709            noORB(orbClassName, ex);
710          }
711        catch (IllegalAccessException ex)
712          {
713            noORB(orbClassName, ex);
714          }
715        catch (InstantiationException ex)
716          {
717            noORB(orbClassName, ex);
718          }
719    
720        return orb;
721      }
722    
723      /**
724       * Throw the runtime exception.
725       *
726       * @param orb_c the ORB class name.
727       * @param why the explaining chained exception.
728       */
729      private static void noORB(String orb_c, Throwable why)
730    {    {
731        throw new RuntimeException("The ORB " + orb_c + " cannot be instantiated.",
732                                   why
733                                  );
734    }    }
735  }  }

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26