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