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