Source for org.omg.CORBA.ORB

   1: /* ORB.java --
   2:    Copyright (C) 2005 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package org.omg.CORBA;
  40: 
  41: import gnu.CORBA.Restricted_ORB;
  42: import gnu.CORBA.primitiveTypeCode;
  43: import gnu.CORBA.fixedTypeCode;
  44: import gnu.CORBA.generalTypeCode;
  45: import gnu.CORBA.gnuContext;
  46: import gnu.CORBA.recordTypeCode;
  47: import gnu.CORBA.recursiveTypeCode;
  48: 
  49: import org.omg.CORBA.ORBPackage.InconsistentTypeCode;
  50: 
  51: import java.applet.Applet;
  52: 
  53: import java.io.BufferedInputStream;
  54: import java.io.File;
  55: import java.io.FileInputStream;
  56: import java.io.IOException;
  57: 
  58: import java.util.Properties;
  59: 
  60: /**
  61:  * A central class in CORBA implementation, responsible for sending and
  62:  * handling remote invocations. ORB also works as a factory for
  63:  * creating instances of certain CORBA classes.
  64:  *
  65:  * Despite the core library contains the fully working CORBA implementation,
  66:  * it also provides a simple way to plug-in the alternative CORBA support.
  67:  * This is done by replacing the ORB. The alternative ORB can be specified
  68:  * via properties, passed to ORB.Init(...).
  69:  *
  70:  * When creating an ORB instance, the class name
  71:  * is searched in the following locations:
  72:  * <p>
  73:  * 1. Applet parameter or application string array, if any.<br>
  74:  * 2. The properties parameter, if any.<br>
  75:  * 3. The System properties.<br>
  76:  * 4. The orb.properties file located in the user.home directory (if any).<br>
  77:  * 5. The orb.properties file located in the java.home/lib directory (if any).
  78:  * </p>
  79:  *
  80:  * The supported properties are:
  81:  * <table border="1">
  82:  * <tr><td> org.omg.CORBA.ORBClass</td><td>The class,
  83:  *   implementing the functional ORB, returned by
  84:  *   {@link #init(Applet, Properties)} or
  85:  *   {@link #init(String[], Properties)} </td></tr>
  86:  * <tr><td>org.omg.CORBA.ORBSingletonClass</td><td>The class,
  87:  *   implementing the restricted ORB, returned by
  88:  *   {@link #init()}.
  89:  * </td></tr>
  90:  * <tr><td>org.omg.CORBA.ORBInitRef</td><td>Specifies the
  91:  * initial reference, accessible by name with the method
  92:  * {@link resolve_initial_references(String)}.
  93:  * </table>
  94:  * The command line accepts the same properties as a keys. When specifying
  95:  * in the command line, the prefix org.omg.CORBA can be omitted,
  96:  * for instance<code> -ORBInitRef NameService=IOR:aabbccdd....</code>
  97:  *
  98:  * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
  99:  */
 100: public abstract class ORB
 101: {
 102:   /**
 103:   * By default, {@link init(String[], Properties)} and
 104:   * {@link init(Applet, Properties} return
 105:   * the built-in fully functional ORB is returned. If the
 106:   * <code>props</code> contains the property org.omg.CORBA.ORBClass,
 107:   * the value of this property is used as a class name to instantiate
 108:   * a user-defined ORB.
 109:   */
 110:   private static final String FUNCTIONAL_ORB = "org.omg.CORBA.ORBClass";
 111: 
 112:   /**
 113:    * The name of the restricted ORB property.
 114:    */
 115:   private static final String RESTRICTED_ORB =
 116:     "org.omg.CORBA.ORBSingletonClass";
 117: 
 118:   /**
 119:    * The class, implementing the default fully functional ORB.
 120:    */
 121:   private static final String DEFAULT_FUNCTIONAL_ORB = "gnu.CORBA.Functional_ORB";
 122: 
 123:   /**
 124:    * The class, implementing the default restricted ORB.
 125:    */
 126:   private static final String DEFAULT_RESTRICTED_ORB = "gnu.CORBA.Restricted_ORB";
 127: 
 128: 
 129:   /**
 130:    * Connect the given CORBA object to this ORB. After the object is
 131:    * connected, it starts receiving remote invocations via this ORB.
 132:    *
 133:    * The OMG group recommends to use Portable Object Adapter (POA) instead
 134:    * of calling this method.
 135:    *
 136:    * This method is implemented in the derived Gnu Classpah classes,
 137:    * returned by ORB.init(..). In this abstract class, the implementation
 138:    * just throws {@link NO_IMPLEMENT}.
 139:    *
 140:    * @param object the org.omg.CORBA.Object to connect.
 141:    */
 142:   public void connect(org.omg.CORBA.Object object)
 143:   {
 144:     throw new NO_IMPLEMENT();
 145:   }
 146: 
 147:   /**
 148:    * Disconnect the given CORBA object from this ORB. The object will be
 149:    * no longer receiving the remote invocations. In response to the
 150:    * remote invocation on this object, the ORB will send the
 151:    * exception {@link OBJECT_NOT_EXIST}. The object, however, is not
 152:    * destroyed and can receive the local invocations.
 153:    *
 154:    * This method is implemented in the derived Gnu Classpah classes,
 155:    * returned by ORB.init(..). In this abstract class, the implementation
 156:    * just throws {@link NO_IMPLEMENT}.
 157:    *
 158:    * @param object the object to disconnect.
 159:    */
 160:   public void disconnect(org.omg.CORBA.Object object)
 161:   {
 162:     throw new NO_IMPLEMENT();
 163:   }
 164: 
 165: 
 166:   /**
 167:    * Create alias typecode for the given typecode.
 168:    */
 169:   public abstract TypeCode create_alias_tc(String id, String name,
 170:                                            TypeCode typecode
 171:                                           );
 172: 
 173:   /**
 174:    * Create an instance of the CORBA {@link Any} with the type, intialised
 175:    * to {@link TCKind#tc_null}
 176:    */
 177:   public abstract Any create_any();
 178: 
 179:   /**
 180:    * Create a typecode, defining an array of the given elements.
 181:    *
 182:    * @param length the size of array
 183:    * @param element_type the array component type.
 184:    *
 185:    * @return the corresponding typecode.
 186:    */
 187:   public abstract TypeCode create_array_tc(int length, TypeCode element_type);
 188: 
 189:   /**
 190:    * Creates an empty CORBA <code>ContextList</code>.
 191:    *
 192:    * @return the newly created context list.
 193:    */
 194:   public abstract ContextList create_context_list();
 195: 
 196:   /**
 197:    * The support for {@link DynAny} and derived interfaces
 198:    * has never been implemented in Sun's java releases,
 199:    * at least till v1.4 inclusive.
 200:    *
 201:    * Since v1.4 this stil missing implementation was replaced
 202:    * by the new DynamicAny package.
 203:    *
 204:    * @throws NO_IMPLEMENT, always.
 205:    */
 206:   public DynAny create_basic_dyn_any(org.omg.CORBA.TypeCode t)
 207:                              throws InconsistentTypeCode
 208:   {
 209:     throw new NO_IMPLEMENT();
 210:   };
 211: 
 212:   /**
 213:    * The support for {@link DynAny} and derived interfaces
 214:    * has never been implemented in Sun's java releases,
 215:    * at least till v1.4 inclusive.
 216:    *
 217:    * Since v1.4 this stil missing implementation was replaced
 218:    * by the new DynamicAny package.
 219:    *
 220:    * @throws NO_IMPLEMENT, always.
 221:    */
 222:   public DynAny create_dyn_any(org.omg.CORBA.Any a)
 223:   {
 224:     throw new NO_IMPLEMENT();
 225:   };
 226: 
 227:   /**
 228:    * The support for {@link DynArray}
 229:    * has never been implemented in Sun's java releases,
 230:    * at least till v1.4 inclusive.
 231:    *
 232:    * Since v1.4 this stil missing implementation was replaced
 233:    * by the new DynamicAny package.
 234:    *
 235:    * @throws NO_IMPLEMENT, always.
 236:    */
 237:   public DynArray create_dyn_array(org.omg.CORBA.TypeCode t)
 238:                        throws InconsistentTypeCode
 239:    {
 240:      throw new NO_IMPLEMENT();
 241:    };
 242: 
 243:   /**
 244:    * The support for {@link DynEnum}
 245:    * has never been implemented in Sun's java releases,
 246:    * at least till v1.4 inclusive.
 247:    *
 248:    * Since v1.4 this stil missing implementation was replaced
 249:    * by the new DynamicAny package.
 250:    *
 251:    * @throws NO_IMPLEMENT, always.
 252:    */
 253:   public DynEnum create_dyn_enum(org.omg.CORBA.TypeCode t)
 254:                        throws InconsistentTypeCode
 255:   {
 256:     throw new NO_IMPLEMENT();
 257:   };
 258: 
 259:   /**
 260:    * The support for {@link DynSequence}
 261:    * has never been implemented in Sun's java releases,
 262:    * at least till v1.4 inclusive.
 263:    *
 264:    * Since v1.4 this stil missing implementation was replaced
 265:    * by the new DynamicAny package.
 266:    *
 267:    * @throws NO_IMPLEMENT, always.
 268:    */
 269:   public DynSequence create_dyn_sequence(org.omg.CORBA.TypeCode t)
 270:                        throws InconsistentTypeCode
 271:   {
 272:     throw new NO_IMPLEMENT();
 273:   };
 274: 
 275:   /**
 276:    * The support for {@link DynStruct} and derived interfaces
 277:    * has never been implemented in Sun's java releases,
 278:    * at least till v1.4 inclusive.
 279:    *
 280:    * Since v1.4 this stil missing implementation was replaced
 281:    * by the new DynamicAny package.
 282:    *
 283:    * @throws NO_IMPLEMENT, always.
 284:    */
 285:   public DynStruct create_dyn_struct(org.omg.CORBA.TypeCode t)
 286:                        throws InconsistentTypeCode
 287:   {
 288:     throw new NO_IMPLEMENT();
 289:   };
 290: 
 291:   /**
 292:    * The support for {@link DynUnion} and derived interfaces
 293:    * has never been implemented in Sun's java releases,
 294:    * at least till v1.4 inclusive.
 295:    *
 296:    * Since v1.4 this stil missing implementation was replaced
 297:    * by the new DynamicAny package.
 298:    *
 299:    * @throws NO_IMPLEMENT, always.
 300:    */
 301:   public DynUnion create_dyn_union(org.omg.CORBA.TypeCode t)
 302:                        throws InconsistentTypeCode
 303:   {
 304:     throw new NO_IMPLEMENT();
 305:   };
 306: 
 307:   /**
 308:    * Create a typecode, defining the given enumeration.
 309:    *
 310:    * @param id the id.
 311:    * @param name the name.
 312:    * @param members the memebers
 313:    * @return the created enumeration.
 314:    */
 315:   public abstract TypeCode create_enum_tc(String id, String name,
 316:                                           String[] members
 317:                                          );
 318: 
 319:   /**
 320:    * Create an environment (container for exceptions).
 321:    *
 322:    * @return the created container.
 323:    */
 324:   public abstract Environment create_environment();
 325: 
 326:   /**
 327:    * Creates an empty exception list.
 328:    *
 329:    * @return the newly created list.
 330:    */
 331:   public abstract ExceptionList create_exception_list();
 332: 
 333:   /**
 334:    * Create the exception typecode.
 335:    *
 336:    * @param id the id of exception.
 337:    * @param name the name of exception.
 338:    * @param members the members of exception.
 339:    */
 340:   public abstract TypeCode create_exception_tc(String id, String name,
 341:                                                StructMember[] members
 342:                                               );
 343: 
 344:   /**
 345:    * Creates a TypeCode object for CORBA <code>fixed</code> that is
 346:    * mapped to java {@link java.math.BigDecimal}.
 347:    *
 348:    * @param digits the number of digits in that <code>fixed</code>.
 349:    * @param scale the number of digits after the decimal point.
 350:    *
 351:    * @return the corresponding TypeCode.
 352:    */
 353:   public TypeCode create_fixed_tc(short digits, short scale)
 354:   {
 355:     fixedTypeCode r = new fixedTypeCode();
 356:     r.setDigits(digits);
 357:     r.setScale(scale);
 358:     return r;
 359:   }
 360: 
 361:   /**
 362:    * Creates a typecode, representing the IDL interface.
 363:    *
 364:    * @param id the interface repository id.
 365:    * @param name the interface name.
 366:    *
 367:    * @return the created typecode.
 368:    */
 369:   public abstract TypeCode create_interface_tc(String id, String name);
 370: 
 371:   /**
 372:    * Create an instance of a new {@link NVList}.
 373:    *
 374:    * @param count the initial size of the list. If more elements are added,
 375:    * the list automatically expands.
 376:    *
 377:    * @return the created list.
 378:    */
 379:   public abstract NVList create_list(int count);
 380: 
 381:   /**
 382:    * Create a new named value.
 383:    *
 384:    * @param name the name of the named value
 385:    * @param any the content of the named value.
 386:    * @param flags the flags of the named value
 387:    *
 388:    * @return the named value.
 389:    */
 390:   public abstract NamedValue create_named_value(String s, Any any, int flags);
 391: 
 392:   /**
 393:    * Send multiple prepared requests one way, do not caring about the answer.
 394:    * The messages, containing requests, will be marked, indicating that
 395:    * the sender is not expecting to get a reply.
 396:    *
 397:    * @param requests the prepared array of requests.
 398:    *
 399:    * @see Request#send_oneway()
 400:    */
 401:   public abstract void send_multiple_requests_oneway(Request[] requests);
 402: 
 403:   /**
 404:    * Send multiple prepared requests expecting to get a reply. All requests
 405:    * are send in parallel, each in its own separate thread. When the
 406:    * reply arrives, it is stored in the agreed fields of the corresponing
 407:    * request data structure. If this method is called repeatedly,
 408:    * the new requests are added to the set of the currently sent requests,
 409:    * but the old set is not discarded.
 410:    *
 411:    * @param requests the prepared array of requests.
 412:    *
 413:    * @see #poll_next_response()
 414:    * @see #get_next_response()
 415:    * @see Request#send_deferred()
 416:    */
 417:   public abstract void send_multiple_requests_deferred(Request[] requests);
 418: 
 419:   /**
 420:    * Find if any of the requests that have been previously sent with
 421:    * {@link #send_multiple_requests_deferred}, have a response yet.
 422:    *
 423:    * @return true if there is at least one response to the previously
 424:    * sent request, false otherwise.
 425:    */
 426:   public abstract boolean poll_next_response();
 427: 
 428:   /**
 429:    * Get the next instance with a response being received. If all currently
 430:    * sent responses not yet processed, this method pauses till at least one of
 431:    * them is complete. If there are no requests currently sent, the method
 432:    * pauses till some request is submitted and the response is received.
 433:    * This strategy is identical to the one accepted by Suns 1.4 ORB
 434:    * implementation.
 435:    *
 436:    * @return the previously sent request that now contains the received
 437:    * response.
 438:    *
 439:    * @throws WrongTransaction If the method was called from the transaction
 440:    * scope different than the one, used to send the request. The exception
 441:    * can be raised only if the request is implicitly associated with some
 442:    * particular transaction.
 443:    */
 444:   public abstract Request get_next_response()
 445:                                    throws WrongTransaction;
 446: 
 447: 
 448:   /**
 449:    * Create a new CDR output stream, where the parameter values can be written
 450:    * during the method invocation.
 451:    *
 452:    * @return a stream to write values into.
 453:    */
 454:   public abstract org.omg.CORBA.portable.OutputStream create_output_stream();
 455: 
 456:   /**
 457:    * This should create the list, initialised with the argument descriptions
 458:    * for the given operation definition (CORBA <code>OperationDef</code>).
 459:    * The information should be obtained from the interface repository.
 460:    * However this method is oficially documented as not implemented at least
 461:    * till v1.4 inclusive.
 462:    *
 463:    * @param peration_definition the operation definition, must be
 464:    * CORBA <code>OperationDef</code>.
 465:    *
 466:    * @return never
 467:    *
 468:    * @throws NO_IMPLEMENT, always.
 469:    */
 470:   public NVList create_operation_list(Object operation_definition)
 471:   {
 472:     throw new NO_IMPLEMENT();
 473:   }
 474: 
 475:   /**
 476:    * This should create the new policy with the specified type and initial
 477:    * state. The policies and methods for getting them are not implemented till
 478:    * v1.4 inclusive.
 479:    *
 480:    * @param type the policy type.
 481:    * @param value the policy value.
 482:    *
 483:    * @return never
 484:    *
 485:    * @throws NO_IMPLEMENT, always.
 486:    */
 487:   public Policy create_policy(int type, Any value)
 488:                        throws PolicyError
 489:   {
 490:     throw new NO_IMPLEMENT();
 491:   }
 492: 
 493: 
 494: 
 495:   /**
 496:    * Create typecode, defining the sequence of the elements, having
 497:    * the given type.
 498:    *
 499:    * @param bound the maximal length of the sequence, 0 if not restricted.
 500:    *
 501:    * @param element_type the sequence element type.
 502:    *
 503:    * @return the typecode.
 504:    */
 505:   public abstract TypeCode create_sequence_tc(int bound, TypeCode element_type);
 506: 
 507:   /**
 508:    * Create a TypeCode, representing the CORBA <code>string</code>.
 509:    *
 510:    * @param bound the maximal length of the string, 0 is unlimited.
 511:    *
 512:    * @return the corresponding string typecode.
 513:    */
 514:   public abstract TypeCode create_string_tc(int bound);
 515: 
 516:   /**
 517:    * Create the typecode, defining the given IDL structure.
 518:    *
 519:    * The TypeCode object is initialized with the given id, name, and members.
 520:    * @param id the Id of this type.
 521:    * @param the name of this type.
 522:    * @param members the member list.
 523:    *
 524:    * @return the typecode.
 525:    */
 526:   public abstract TypeCode create_struct_tc(String id, String name,
 527:                                             StructMember[] members
 528:                                            );
 529: 
 530:   /**
 531:    * Create the typecode, defining the given IDL union.
 532:    *
 533:    * The TypeCode object is initialized with the given id, name, discriminator
 534:    * and members.
 535:    *
 536:    * @param id the Id of this type.
 537:    * @param the name of this type.
 538:    * @param discriminator the union discriminator.
 539:    * @param members the member list.
 540:    *
 541:    * @return the typecode.
 542:    */
 543:   public abstract TypeCode create_union_tc(String id, String name,
 544:                                            TypeCode discriminator,
 545:                                            UnionMember[] members
 546:                                           );
 547: 
 548:   /**
 549:    * Create a TypeCode, representing the CORBA <code>wstring</code>.
 550:    *
 551:    * @param bound the maximal length of the string, 0 is unlimited.
 552:    *
 553:    * @return the corresponding string typecode.
 554:    */
 555:   public abstract TypeCode create_wstring_tc(int bound);
 556: 
 557: 
 558:   /**
 559:    * Create a typecode for an abstract interface. The abstract interface
 560:    * can be either CORBA object or CORBA value type.
 561:    *
 562:    * @param id the id of the abstract interface.
 563:    * @param name the name of the abstract interface.
 564:    *
 565:    * @return the created typecode.
 566:    */
 567:   public TypeCode create_abstract_interface_tc(String id, String name)
 568:   {
 569:     generalTypeCode t = new generalTypeCode(TCKind.tk_abstract_interface);
 570:     t.setName(name);
 571:     t.setId(id);
 572:     return t;
 573:   }
 574: 
 575:   /**
 576:    * Create a typecode for a native interface.
 577:    *
 578:    * @param id the id of the native interface.
 579:    * @param name the name of the native interface.
 580:    *
 581:    * @return the created typecode.
 582:    */
 583:   public TypeCode create_native_tc(String id, String name)
 584:   {
 585:     generalTypeCode t = new generalTypeCode(TCKind.tk_native);
 586:     t.setName(name);
 587:     t.setId(id);
 588:     return t;
 589:   }
 590: 
 591:   /**
 592:    * Create a typecode, representing a tree-like structure.
 593:    * This structure contains a member that is a sequence of the same type,
 594:    * as the structure itself. You can imagine as if the folder definition
 595:    * contains a variable-length array of the enclosed (nested) folder
 596:    * definitions. In this way, it is possible to have a tree like
 597:    * structure that can be transferred via CORBA CDR stream.
 598:    *
 599:    * @deprecated It is easier and clearler to use a combination of
 600:    * create_recursive_tc and create_sequence_tc instead.
 601:    *
 602:    * @param bound the maximal expected number of the nested components
 603:    * on each node; 0 if not limited.
 604:    *
 605:    * @param offset the position of the field in the returned structure
 606:    * that contains the sequence of the structures of the same field.
 607:    * The members before this field are intialised using parameterless
 608:    * StructMember constructor.
 609:    *
 610:    * @return a typecode, defining a stucture, where a member at the
 611:    * <code>offset</code> position defines an array of the identical
 612:    * structures.
 613:    *
 614:    * @see #create_recursive_tc(String)
 615:    * @see #create_sequence_tc(int, TypeCode)
 616:    */
 617:   public TypeCode create_recursive_sequence_tc(int bound, int offset)
 618:   {
 619:     recordTypeCode r = new recordTypeCode(TCKind.tk_struct);
 620:     for (int i = 0; i < offset; i++)
 621:       r.add(new StructMember());
 622: 
 623:     TypeCode recurs = new primitiveTypeCode(TCKind.tk_sequence);
 624: 
 625:     r.add(new StructMember("", recurs, null));
 626:     return r;
 627:   }
 628: 
 629:   /**
 630:    * Create a typecode which serves as a placeholder for typcode, containing
 631:    * recursion.
 632:    *
 633:    * @param id the id of the recursive typecode, for that this typecode
 634:    * serves as a placeholder.
 635:    */
 636:   public TypeCode create_recursive_tc(String id)
 637:   {
 638:     return new recursiveTypeCode(id);
 639:   }
 640: 
 641:   /**
 642:    * Create value box typecode.
 643:    */
 644:   public TypeCode create_value_box_tc(String id, String name,
 645:                                       TypeCode boxed_type
 646:                                      )
 647:   {
 648:     generalTypeCode t = new generalTypeCode(TCKind.tk_value_box);
 649:     t.setName(name);
 650:     t.setId(id);
 651:     t.setContentType(boxed_type);
 652:     return t;
 653:   }
 654: 
 655:   /**
 656:    * Create IDL value type code.
 657:    */
 658:   public TypeCode create_value_tc(String id, String name, short type_modifier,
 659:                                   TypeCode concrete_base, ValueMember[] members
 660:                                  )
 661:   {
 662:     recordTypeCode r = new recordTypeCode(TCKind.tk_value);
 663:     r.setId(id);
 664:     r.setName(name);
 665:     r.setTypeModifier(type_modifier);
 666:     r.setConcreteBase_type(concrete_base);
 667: 
 668:     for (int i = 0; i < members.length; i++)
 669:       {
 670:         r.add(members [ i ]);
 671:       }
 672: 
 673:     return r;
 674:   }
 675: 
 676:   /**
 677:    * This should return the information, related to the current thread.
 678:    * The {@link Current} is very general interface, with no fields and
 679:    * operations defined. This method is not implemented in Suns
 680:    * releases at least till v1.4 inclusive.
 681:    *
 682:    * @deprecated since 1.2
 683:    *
 684:    * @return never
 685:    *
 686:    * @throws NO_IMPLEMENT, always.
 687:    */
 688:   public Current get_current()
 689:   {
 690:     throw new NO_IMPLEMENT();
 691:   }
 692: 
 693:   /**
 694:    * This should return the information about the CORBA facilities and
 695:    * services, available from this ORB. However this method is oficially
 696:    * documented as not implemented at least till v1.4 inclusive.
 697:    *
 698:    * @param service_type a type of the service being requested. The OMG
 699:    * specification currently defines only one value, 1, for security
 700:    * related services.
 701:    *
 702:    * @param service_info a holder, where the returned information should
 703:    * be stored.
 704:    *
 705:    * @return should return true if the service information is available
 706:    * from the ORB, but this method never returns.
 707:    *
 708:    * @throws NO_IMPLEMENT, always.
 709:    */
 710:   public boolean get_service_information(short service_type,
 711:                                        ServiceInformationHolder service_info)
 712:   {
 713:     throw new NO_IMPLEMENT();
 714:   }
 715: 
 716:   /**
 717:    * Get the default context of this ORB. This is an initial root of all
 718:    * contexts.
 719:    *
 720:    * The default method returns a new context with the empty name and
 721:    * no parent context.
 722:    *
 723:    * @return the default context of this ORB.
 724:    *
 725:    * @throws NO_IMPLEMENT for the Singleton ORB, returned by
 726:    * the parameterless {@link init()}.
 727:    */
 728:   public Context get_default_context()
 729:   {
 730:     return new gnuContext("", null);
 731:   }
 732: 
 733:   /**
 734:    * Return thg typecode, representing the given primitive object type.
 735:    *
 736:    * @param the kind of the primitive typecode.
 737:    *
 738:    * @return the typecode of the primitve typecode.
 739:    */
 740:   public abstract TypeCode get_primitive_tc(TCKind tcKind);
 741: 
 742:   /**
 743:    * Returns so-called Singleton ORB, a highly restricted version
 744:    * that cannot communicate over network. This ORB is provided
 745:    * for the potentially malicious applets with heavy security restrictions.
 746:    *
 747:    * The returned Singleton ORB can only create typecodes,
 748:    * {@link Any}, {@link ContextList}, {@link NVList} and
 749:    * {@link org.omg.CORBA.portable.OutputStream} that writes to an
 750:    * internal buffer.
 751:    *
 752:    * All other methods throw the {@link NO_IMPLEMENT} exception, additionally
 753:    * printing the error message about the potential attempt to violate
 754:    * the security rules.
 755:    *
 756:    * The implementing ORB class, used in this method, is found as described
 757:    * in the header.
 758:    *
 759:    * @return the working derivative of ORB, implementing the methods
 760:    * of this abstract class.
 761:    */
 762:   public static ORB init()
 763:   {
 764:     String orb_cn = getORBName(null, RESTRICTED_ORB);
 765:     if (orb_cn == null)
 766:       return Restricted_ORB.Singleton;
 767:     else
 768:       return createORB(null, orb_cn);
 769:   }
 770: 
 771:   /**
 772:    * Creates the working instance of ORB for an applet.
 773:    *
 774:    * By default the built-in fully functional ORB is returned. The ORB class
 775:    * is found as described in the header of this class.
 776:    *
 777:    * @param applet the applet. The property org.omg.CORBA.ORBClass,
 778:    * if present, defines the used ORB implementation class. If this
 779:    * property is not present, the ORB class is found as described in the
 780:    * class header.
 781:    *
 782:    * @param props the properties, may be <code>null</code>.
 783:    *
 784:    * @return a newly created functional derivative of this abstract class.
 785:    */
 786:   public static ORB init(Applet applet, Properties props)
 787:   {
 788:     String ocn = applet.getParameter(FUNCTIONAL_ORB);
 789:     ORB orb = createORB(props, ocn);
 790:     orb.set_parameters(applet, props);
 791: 
 792:     return orb;
 793:   }
 794: 
 795:   /**
 796:    * Creates the working instance of ORB for a
 797:    * standalone application.
 798:    *
 799:    * By default the built-in fully functional ORB is returned. The ORB class
 800:    * is found as described in the header of this class.
 801:    *
 802:    * @param the parameters, passed to the applications
 803:    * <code>main(String[] args)</code> method, may be <code>null</code>.
 804:    * The parameter -org.omg.CORBA.ORBClass <class name>
 805:    * if present, defines the used ORB implementation class. If this
 806:    * property is not present, the ORB class is found as described in the
 807:    * class header.
 808: 
 809:    *
 810:    * @param props application specific properties, may be <code>null</code>.
 811:    *
 812:    * @return a newly created functional derivative of this abstract class.
 813:    */
 814:   public static ORB init(String[] args, Properties props)
 815:   {
 816:     String ocn = null;
 817: 
 818:     String orbKey = "-" + FUNCTIONAL_ORB;
 819: 
 820:     if (args != null)
 821:       if (args.length >= 2)
 822:         {
 823:           for (int i = 0; i < args.length - 1; i++)
 824:             {
 825:               if (args [ i ].equals(orbKey))
 826:                 ocn = args [ i + 1 ];
 827:             }
 828:         }
 829: 
 830:     ORB orb = createORB(props, ocn);
 831: 
 832:     orb.set_parameters(args, props);
 833:     return orb;
 834:   }
 835: 
 836:   /**
 837:    * List the initially available CORBA objects (services).
 838:    *
 839:    * @return a list of services.
 840:    *
 841:    * @see resolve_initial_references(String)
 842:    */
 843:   public abstract String[] list_initial_services();
 844: 
 845:   /**
 846:    * Find and return the easily accessible CORBA object, addressed
 847:    * by name.  The returned object is typically casted to the more
 848:    * specific reference using the <code>narrow(Object)</code> method
 849:    * of its helper.
 850:    *
 851:    * @param name the object name.
 852:    * @return the object
 853:    * @throws org.omg.CORBA.ORBPackage.InvalidName if the given name
 854:    * is not associated with the known object.
 855:    */
 856:   public abstract Object resolve_initial_references(String name)
 857:     throws org.omg.CORBA.ORBPackage.InvalidName;
 858: 
 859:   /**
 860:    * Get the IOR reference string for the given object.
 861:    * IOR can be compared with the Internet address for a web page,
 862:    * it provides means to locate the CORBA service on the web.
 863:    * IOR contains the host address, port number, the object identifier
 864:    * (key) inside the server, the communication protocol version,
 865:    * supported charsets and so on.
 866:    *
 867:    * @param the CORBA object
 868:    * @return the object IOR representation.
 869:    * @see string_to_object(String)
 870:    */
 871:   public abstract String object_to_string(Object forObject);
 872: 
 873:   /**
 874:    * This should perform the implementation dependent unit of work in the
 875:    * main thread.
 876:    *
 877:    * This method is part of the support for the distribute use of the
 878:    * single execution thread.
 879:    *
 880:    * Same as in Suns releases at least till 1.4 inclusive,
 881:    * the distribute use of the single thread is not implemented.
 882:    * Use multiple threads, provided by jre.
 883:    *
 884:    * The method returns without action.
 885:    */
 886:   public void perform_work()
 887:   {
 888:   }
 889: 
 890:    /**
 891:    * Checks if the ORB needs the main thread to perform some work.
 892:    * The method should return true if the ORB needs the main thread,
 893:    * and false if it does not.
 894:    *
 895:    * This method is part of the support for the distribute use of the
 896:    * single execution thread.
 897:    *
 898:    * Same as in Suns releases at least till 1.4 inclusive,
 899:    * the distributed use of the single thread is not implemented.
 900:    * Use multiple threads, provided by jre.
 901:    *
 902:    * @return false, always.
 903:    */
 904:   public boolean work_pending()
 905:   {
 906:     return false;
 907:   }
 908: 
 909:   /**
 910:    * Find and return the CORBA object, addressed by the given
 911:    * IOR string representation. The object can (an usually is)
 912:    * located on a remote computer, possibly running a different
 913:    * (not necessary java) CORBA implementation. The returned
 914:    * object is typically casted to the more specific reference
 915:    * using the <code>narrow(Object)</code> method of its helper.
 916:    *
 917:    * @param IOR the object IOR representation string.
 918:    *
 919:    * @return the found CORBA object.
 920:    * @see object_to_string(org.omg.CORBA.Object)
 921:    */
 922:   public abstract Object string_to_object(String IOR);
 923: 
 924:   /**
 925:    * Start listening on the input socket. This method
 926:    * blocks the current thread until {@link #shutdown(boolean)}
 927:    * is called and shutdown process is completed.
 928:    */
 929:   public void run()
 930:   {
 931:   }
 932: 
 933:   /**
 934:    * Shutdown the ORB server.
 935:    *
 936:    * @param wait_for_completion if true, the current thread is
 937:    * suspended untile the shutdown process is complete.
 938:    */
 939:   public void shutdown(boolean wait_for_completion)
 940:   {
 941:   }
 942: 
 943:   /**
 944:    * Destroy this server, releasing the occupied resources.
 945:    * The default method returns without action.
 946:    */
 947:   public void destroy()
 948:   {
 949:   }
 950: 
 951:   /**
 952:    * Set the ORB parameters. This method is normally called from
 953:    * {@link #init(String[], Properties)}.
 954:    *
 955:    * @param para the parameters, that were passed as the parameters
 956:    * to the  <code>main(String[] args)</code> method of the current standalone
 957:    * application.
 958:    *
 959:    * @param props application specific properties that were passed
 960:    * as a second parameter in {@link init(String[], Properties)}).
 961:    * Can be <code>null</code>.
 962:    */
 963:   protected abstract void set_parameters(String[] para, Properties props);
 964: 
 965:   /**
 966:    * Set the ORB parameters. This method is normally called from
 967:    * {@link #init(Applet, Properties)}.
 968:    *
 969:    * @param app the current applet.
 970:    *
 971:    * @param props application specific properties, passed as the second
 972:    * parameter in {@link #init(Applet, Properties)}.
 973:    * Can be <code>null</code>.
 974:    */
 975:   protected abstract void set_parameters(Applet app, Properties props);
 976: 
 977:   /**
 978:    * Checks if the communication over network is allowed.
 979:    * @throws java.lang.SecurityException
 980:    */
 981:   private static final void checkNetworkingPermission(String host, int port)
 982:                                                throws SecurityException
 983:   {
 984:     SecurityManager security = System.getSecurityManager();
 985:     if (security != null)
 986:       {
 987:         security.checkConnect(host, port);
 988:       }
 989:   }
 990: 
 991:   /**
 992:    * Get the ORB class name.
 993:    */
 994:   private static String getORBName(Properties props, String property)
 995:   {
 996:     String orb_cn = null;
 997: 
 998:     if (props != null)
 999:       orb_cn = props.getProperty(property, null);
1000: 
1001:     if (orb_cn == null)
1002:       orb_cn = System.getProperty(property, null);
1003: 
1004:     if (orb_cn == null)
1005:       orb_cn = checkFile(property, "user.home", null);
1006: 
1007:     if (orb_cn == null)
1008:       orb_cn = checkFile(property, "java.home", "lib");
1009: 
1010:     return orb_cn;
1011:   }
1012: 
1013:   /**
1014:    * Check if the property is defined in the existsting file orb.properties.
1015:    *
1016:    * @param property the property
1017:    * @param dir the system property, defining the folder where the
1018:    * file could be expected.
1019:    * @param subdir subfolder where to look for the file.
1020:    *
1021:    * @return the property value, null if not found or file does not exist.
1022:    */
1023:   private static String checkFile(String property, String dir, String subdir)
1024:   {
1025:     try
1026:       {
1027:         File f = new File(dir);
1028:         if (!f.exists())
1029:           return null;
1030: 
1031:         if (subdir != null)
1032:           f = new File(f, subdir);
1033: 
1034:         f = new File(f, "orb.properties");
1035: 
1036:         if (!f.exists())
1037:           return null;
1038: 
1039:         Properties p = new Properties();
1040:         p.load(new BufferedInputStream(new FileInputStream(f)));
1041: 
1042:         return p.getProperty(property, null);
1043:       }
1044:     catch (IOException ex)
1045:       {
1046:         return null;
1047:       }
1048:   }
1049: 
1050:   /**
1051:    * Create ORB when its name is possibly known.
1052:    *
1053:    * @param props properties, possibly containing the ORB name.
1054:    * @param orbClassName the direct ORB class name, overriding
1055:    * other possible locations, or null if not specified.
1056:    */
1057:   private static ORB createORB(Properties props, String orbClassName)
1058:   {
1059:     ORB orb = null;
1060: 
1061:     if (orbClassName == null)
1062:       {
1063:         orbClassName = getORBName(props, FUNCTIONAL_ORB);
1064: 
1065:         if (orbClassName == null)
1066:           orbClassName = DEFAULT_FUNCTIONAL_ORB;
1067:       }
1068: 
1069:     try
1070:       {
1071:         orb = (ORB) Class.forName(orbClassName).newInstance();
1072:       }
1073:     catch (ClassNotFoundException ex)
1074:       {
1075:         noORB(orbClassName, ex);
1076:       }
1077:     catch (IllegalAccessException ex)
1078:       {
1079:         noORB(orbClassName, ex);
1080:       }
1081:     catch (InstantiationException ex)
1082:       {
1083:         noORB(orbClassName, ex);
1084:       }
1085: 
1086:     return orb;
1087:   }
1088: 
1089:   /**
1090:    * Throw the runtime exception.
1091:    *
1092:    * @param orb_c the ORB class name.
1093:    * @param why the explaining chained exception.
1094:    */
1095:   private static void noORB(String orb_c, Throwable why)
1096:   {
1097:     throw new RuntimeException("The ORB " + orb_c + " cannot be instantiated.",
1098:                                why
1099:                               );
1100:   }
1101: }