1 /*
   2  * Copyright (c) 1997, 2001, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 #include "corba.idl"
  27 #include "CORBAX.idl"
  28 
  29 #pragma prefix "omg.org"
  30 /**
  31  * All Mapping corresponds to the Chapter 11 of 
  32  * CORBA V2.3.1 specified by OMG document formal/99-10-07.pdf.
  33  * The exception to this is the id attribute, which is added in ptc/00-08-06, 
  34  * section 11.3.8.26.
  35  */
  36 module PortableServer { 
  37 
  38         #pragma version PortableServer 2.3
  39 
  40         // forward reference 
  41         interface POA; 
  42 
  43         /**
  44          * List of POAs
  45          */
  46         typedef sequence<POA> POAList;
  47 
  48         /**
  49          * Values of type Servant support a language specific
  50          * programming interface that can be used by the ORB to
  51          * obtain a default POA for that servant.  
  52          * Some language mappings may allow Servant values to 
  53          * be implicitly converted to object references under 
  54          * appropriate conditions.
  55          */
  56         native Servant;
  57 
  58         /**
  59          * ObjectId value associated with the object reference.
  60          */
  61         typedef sequence<octet> ObjectId; 
  62 
  63         /**
  64          * ForwardRequest to indicate to the ORB 
  65          * that it is responsible for delivering 
  66          * the current request and subsequent 
  67          * requests to the object denoted in the 
  68          * forward_reference member of the exception.
  69          */
  70         exception ForwardRequest { Object forward_reference; }; 
  71         
  72         // ********************************************** 
  73         // 
  74         // Policy interfaces 
  75         // 
  76         // ********************************************** 
  77 
  78         /**
  79          * The value representing THREAD_POLICY_ID.
  80          */
  81         const CORBA::PolicyType THREAD_POLICY_ID = 16; 
  82         /**
  83          * The value representing LIFESPAN_POLICY_ID.
  84          */
  85         const CORBA::PolicyType LIFESPAN_POLICY_ID = 17; 
  86         /**
  87          * The value representing ID_UNIQUENESS_POLICY_ID.
  88          */
  89         const CORBA::PolicyType ID_UNIQUENESS_POLICY_ID = 18; 
  90         /**
  91          * The value representing ID_ASSIGNMENT_POLICY_ID.
  92          */
  93         const CORBA::PolicyType ID_ASSIGNMENT_POLICY_ID = 19; 
  94         /**
  95          * The value representing IMPLICIT_ACTIVATION_POLICY_ID.
  96          */
  97         const CORBA::PolicyType IMPLICIT_ACTIVATION_POLICY_ID = 20;
  98         /**
  99          * The value representing SERVANT_RETENTION_POLICY_ID.
 100          */
 101         const CORBA::PolicyType SERVANT_RETENTION_POLICY_ID = 21; 
 102         /**
 103          * The value representing REQUEST_PROCESSING_POLICY_ID.
 104          */
 105         const CORBA::PolicyType REQUEST_PROCESSING_POLICY_ID = 22;
 106 
 107         /**
 108          * The ThreadPolicyValue can have the following values.
 109          * ORB_CTRL_MODEL - The ORB is responsible for assigning 
 110          * requests for an ORB- controlled POA to threads. 
 111          * SINGLE_THREAD_MODEL - Requests for a single-threaded 
 112          * POA are processed sequentially. 
 113          */
 114         enum ThreadPolicyValue { ORB_CTRL_MODEL, SINGLE_THREAD_MODEL }; 
 115 
 116         /**
 117          * The ThreadPolicy specifies the threading model 
 118          * used with the created POA. The default is 
 119          * ORB_CTRL_MODEL.
 120          */
 121         interface ThreadPolicy : CORBA::Policy { 
 122                 #pragma sun_local ThreadPolicy ""
 123         /**
 124          * specifies the policy value
 125          */
 126                 readonly attribute ThreadPolicyValue value; 
 127         }; 
 128 
 129         /**
 130          * The LifespanPolicyValue can have the following values.
 131          * TRANSIENT - The objects implemented in the POA 
 132          * cannot outlive the POA instance in which they are 
 133          * first created. 
 134          * PERSISTENT - The objects implemented in the POA can 
 135          * outlive the process in which they are first created. 
 136          */
 137         enum LifespanPolicyValue { TRANSIENT, PERSISTENT }; 
 138 
 139         /**
 140          * The LifespanPolicy specifies the lifespan of the 
 141          * objects implemented in the created POA. The default 
 142          * is TRANSIENT.
 143          */
 144         interface LifespanPolicy : CORBA::Policy { 
 145                 #pragma sun_local LifespanPolicy ""
 146         /**
 147          * specifies the policy value
 148          */
 149                 readonly attribute LifespanPolicyValue value; 
 150         }; 
 151 
 152         /**
 153          * IdUniquenessPolicyValue can have the following values.
 154          * UNIQUE_ID - Servants activated with that POA support 
 155          * exactly one Object Id.  MULTIPLE_ID - a servant 
 156          * activated with that POA may support one or more 
 157          * Object Ids.
 158          */
 159         enum IdUniquenessPolicyValue { UNIQUE_ID, MULTIPLE_ID }; 
 160 
 161         /**
 162          * The IdUniquenessPolicy specifies whether the servants 
 163          * activated in the created POA must have unique object i
 164          * identities. The default is UNIQUE_ID.
 165          */
 166         interface IdUniquenessPolicy : CORBA::Policy { 
 167                 #pragma sun_local IdUniquenessPolicy ""
 168         /**
 169          * specifies the policy value
 170          */
 171                 readonly attribute IdUniquenessPolicyValue value; 
 172         }; 
 173 
 174         /**
 175          * The IdAssignmentPolicyValue can have the following
 176          * values. USER_ID - Objects created with that POA are 
 177          * assigned Object Ids only by the application. 
 178          *  SYSTEM_ID - Objects created with that POA are 
 179          * assigned Object Ids only by the POA. If the POA also 
 180          * has the PERSISTENT policy, assigned Object Ids must 
 181          * be unique across all instantiations of the same POA.
 182          */
 183         enum IdAssignmentPolicyValue { USER_ID, SYSTEM_ID }; 
 184 
 185         /**
 186          * IdAssignmentPolicy specifies whether Object Ids in 
 187          * the created POA are generated by the application or 
 188          * by the ORB. The default is SYSTEM_ID.
 189          */
 190         interface IdAssignmentPolicy : CORBA::Policy { 
 191                 #pragma sun_local IdAssignmentPolicy ""
 192         /**
 193          * specifies the policy value
 194          */
 195                 readonly attribute IdAssignmentPolicyValue value; 
 196         }; 
 197 
 198         /**
 199          * ImplicitActivationPolicyValue has the following
 200          * semantics.
 201          * IMPLICIT_ACTIVATION to indicate implicit activation
 202          * of servants.  This requires SYSTEM_ID and RETAIN 
 203          * policies to be set.
 204          * NO_IMPLICIT_ACTIVATION to indicate no implicit 
 205          * servant activation.
 206          */
 207         enum ImplicitActivationPolicyValue { 
 208                 IMPLICIT_ACTIVATION, NO_IMPLICIT_ACTIVATION 
 209         }; 
 210 
 211         /**
 212          * This policy specifies whether implicit activation 
 213          * of servants is supported in the created POA.
 214          */
 215         interface ImplicitActivationPolicy : CORBA::Policy { 
 216                 #pragma sun_local ImplicitActivationPolicy ""
 217         /**
 218          * specifies the policy value
 219          */
 220                 readonly attribute ImplicitActivationPolicyValue value; 
 221         }; 
 222 
 223         /**
 224          * ServantRetentionPolicyValue can have the following 
 225          * values. RETAIN - to indicate that the POA will retain 
 226          * active servants in its Active Object Map. 
 227          * NON_RETAIN - to indicate Servants are not retained by 
 228          * the POA. If no ServantRetentionPolicy is specified at 
 229          * POA creation, the default is RETAIN.
 230          */
 231         enum ServantRetentionPolicyValue { RETAIN, NON_RETAIN }; 
 232 
 233         /**
 234          * This policy specifies whether the created POA retains 
 235          * active servants in an Active Object Map. 
 236          */
 237         interface ServantRetentionPolicy : CORBA::Policy { 
 238                 #pragma sun_local ServantRetentionPolicy ""
 239         /**
 240          * specifies the policy value
 241          */
 242                 readonly attribute ServantRetentionPolicyValue value; 
 243         }; 
 244 
 245         /**
 246          * The RequestProcessingPolicyValue can have the following
 247          * values.  USE_ACTIVE_OBJECT_MAP_ONLY - If the Object Id 
 248          * is not found in the Active Object Map, 
 249          * an OBJECT_NOT_EXIST exception is returned to the 
 250          * client. The RETAIN policy is also required.
 251          * USE_DEFAULT_SERVANT - If the Object Id is not found in 
 252          * the Active Object Map or the NON_RETAIN policy is 
 253          * present, and a default servant has been registered 
 254          * with the POA using the set_servant operation, 
 255          * the request is dispatched to the default servant. 
 256          * USE_SERVANT_MANAGER - If the Object Id is not found 
 257          * in the Active Object Map or the NON_RETAIN policy 
 258          * is present, and a servant manager has been registered 
 259          * with the POA using the set_servant_manager operation, 
 260          * the servant manager is given the opportunity to 
 261          * locate a servant or raise an exception. 
 262          */
 263         enum RequestProcessingPolicyValue { 
 264         USE_ACTIVE_OBJECT_MAP_ONLY, USE_DEFAULT_SERVANT, USE_SERVANT_MANAGER 
 265         }; 
 266 
 267         /**
 268          * This policy specifies how requests are processed by 
 269          * the created POA.  The default is 
 270          * USE_ACTIVE_OBJECT_MAP_ONLY.
 271          */
 272         interface RequestProcessingPolicy : CORBA::Policy { 
 273                 #pragma sun_local RequestProcessingPolicy ""
 274         /**
 275          * specifies the policy value
 276          */
 277                 readonly attribute RequestProcessingPolicyValue value; 
 278         }; 
 279 
 280 
 281         // ************************************************** 
 282         // 
 283         // POAManager interface 
 284         // 
 285         // **********************************
 286         /**
 287          * Each POA object has an associated POAManager object. 
 288          * A POA manager may be associated with one or more 
 289          * POA objects. A POA manager encapsulates the processing 
 290          * state of the POAs it is associated with.
 291          */
 292         interface POAManager { 
 293                 #pragma sun_local POAManager ""
 294                 exception AdapterInactive{ }; 
 295         /**
 296          * Specifies the states for the POAManager
 297          */
 298                 enum State {HOLDING, ACTIVE, DISCARDING, INACTIVE};
 299 
 300         /**
 301          * This operation changes the state of the POA manager 
 302          * to active, causing associated POAs to start processing
 303          * requests.
 304          * @exception AdapterInactive is raised if the operation is
 305          *            invoked on the POAManager in inactive state.
 306          */
 307                 void activate() 
 308                         raises(AdapterInactive); 
 309         /**
 310          * This operation changes the state of the POA manager 
 311          * to holding, causing associated POAs to queue incoming
 312          * requests.
 313          * @param wait_for_completion if FALSE, the operation 
 314          *            returns immediately after changing state.  
 315          *            If TRUE, it waits for all active requests 
 316          *            to complete. 
 317          * @exception AdapterInactive is raised if the operation is
 318          *            invoked on the POAManager in inactive state.
 319          */
 320                 void hold_requests(in boolean wait_for_completion) 
 321                         raises(AdapterInactive); 
 322         /**
 323          * This operation changes the state of the POA manager 
 324          * to discarding. This causes associated POAs to discard
 325          * incoming requests.
 326          * @param wait_for_completion if FALSE, the operation 
 327          *            returns immediately after changing state.  
 328          *            If TRUE, it waits for all active requests 
 329          *            to complete. 
 330          * @exception AdapterInactive is raised if the operation is
 331          *            invoked on the POAManager in inactive state.
 332          */
 333                 void discard_requests(in boolean wait_for_completion)
 334                         raises(AdapterInactive); 
 335 
 336         /**
 337          * This operation changes the state of the POA manager 
 338          * to inactive, causing associated POAs to reject the
 339          * requests that have not begun executing as well as
 340          * as any new requests.
 341          * @param etherealize_objects a flag to indicate whether
 342          *        to invoke the etherealize operation of the
 343          *        associated servant manager for all active 
 344          *        objects.
 345          * @param wait_for_completion if FALSE, the operation 
 346          *            returns immediately after changing state.  
 347          *            If TRUE, it waits for all active requests 
 348          *            to complete. 
 349          * @exception AdapterInactive is raised if the operation is
 350          *            invoked on the POAManager in inactive state.
 351          */
 352                 void deactivate(in boolean etherealize_objects, 
 353                                 in boolean wait_for_completion) 
 354                         raises(AdapterInactive); 
 355         /**
 356          * This operation returns the state of the POA manager.
 357          */
 358                 State get_state();
 359         }; 
 360 
 361 
 362         // ************************************************** 
 363         // 
 364         // AdapterActivator interface 
 365         // 
 366         // ****************************
 367 
 368         /**
 369          * An adapter activator supplies a POA with the ability 
 370          * to create child POAs on demand, as a side-effect of 
 371          * receiving a request that names the child POA 
 372          * (or one of its children), or when find_POA is called 
 373          * with an activate parameter value of TRUE.
 374          */
 375 
 376         interface AdapterActivator { 
 377                 #pragma sun_local AdapterActivator ""
 378                 #pragma version AdapterActivator 2.3
 379         /**
 380          * This operation is invoked when the ORB receives 
 381          * a request for an object reference that identifies 
 382          * a target POA that does not exist. The ORB invokes 
 383          * this operation once for each POA that must be 
 384          * created in order for the target POA to exist.
 385          * @param parent indicates the parent POA for the POA
 386          *               that needs to be created.
 387          * @param name identifies the name of the POA relative to
 388          *             the parent.
 389          * @return returns TRUE if the POA was created or FALSE
 390          *         otherwise.
 391          */
 392                 boolean unknown_adapter(in POA parent, in string name); 
 393         }; 
 394 
 395 
 396         // ************************************************** 
 397         // 
 398         // ServantManager interface 
 399         // 
 400         // ******************************
 401 
 402         /**
 403          * A servant manager supplies a POA with the ability 
 404          * to activate objects on demand when the POA receives 
 405          * a request targeted at an inactive object. A servant 
 406          * manager is registered with a POA as a callback object, 
 407          * to be invoked by the POA when necessary.
 408          * ServantManagers can either be ServantActivators or
 409          * ServantLocators. A ServantManager object must be 
 410          * local to the process containing the POA objects 
 411          * it is registered with.
 412          */
 413 
 414         interface ServantManager 
 415         { #pragma sun_local ServantManager "" }; 
 416 
 417 
 418         /**
 419          * When the POA has the RETAIN policy it uses servant 
 420          * managers that are ServantActivators. 
 421          */
 422         interface ServantActivator : ServantManager { 
 423                 #pragma version ServantActivator 2.3
 424                 #pragma sun_localservant ServantActivator ""
 425         /**
 426          * This operation is invoked by the POA whenever the 
 427          * POA receives a request for an object that is not 
 428          * currently active, assuming the POA has the 
 429          * USE_SERVANT_MANAGER and RETAIN policies.
 430          * @param oid object Id associated with the object on 
 431          *            the request was made.
 432          * @param adapter object reference for the POA in which
 433          *                the object is being activated.
 434          * @return Servant corresponding to oid is created or 
 435          *         located by the user supplied servant manager.
 436          * @exception ForwardRequest to indicate to the ORB 
 437          *            that it is responsible for delivering 
 438          *            the current request and subsequent 
 439          *            requests to the object denoted in the 
 440          *            forward_reference member of the exception.
 441          */
 442                 Servant incarnate ( in ObjectId oid, in POA adapter ) 
 443                                 raises (ForwardRequest); 
 444         /**
 445          * This operation is invoked whenever a servant for 
 446          * an object is deactivated, assuming the POA has 
 447          * the USE_SERVANT_MANAGER and RETAIN policies.
 448          * @param oid object Id associated with the object 
 449          *            being deactivated.
 450          * @param adapter object reference for the POA in which
 451          *                the object was active.
 452          * @param serv contains reference to the servant
 453          *        associated with the object being deactivated.
 454          * @param cleanup_in_progress if TRUE indicates that
 455          *        destroy or deactivate is called with 
 456          *        etherealize_objects param of TRUE.  FALSE
 457          *        indicates that etherealize was called due to
 458          *        other reasons.
 459          * @param remaining_activations indicates whether the
 460          *        Servant Manager can destroy a servant.  If
 461          *        set to TRUE, the Servant Manager should wait
 462          *        until all invocations in progress have
 463          *        completed.
 464          */
 465                 void etherealize ( in ObjectId oid, 
 466                                    in POA adapter, 
 467                                    in Servant serv, 
 468                                    in boolean cleanup_in_progress, 
 469                                    in boolean remaining_activations); 
 470         }; 
 471 
 472 
 473         /**
 474          * When the POA has the NON_RETAIN policy it uses servant 
 475          * managers that are ServantLocators. Because the POA 
 476          * knows that the servant returned by this servant 
 477          * manager will be used only for a single request, 
 478          * it can supply extra information to the servant 
 479          * manager's operations and the servant manager's pair 
 480          * of operations may be able to cooperate to do 
 481          * something different than a ServantActivator. 
 482          * When the POA uses the ServantLocator interface, 
 483          * immediately after performing the operation invocation 
 484          * on the servant returned by preinvoke, the POA will 
 485          * invoke postinvoke on the servant manager, passing the 
 486          * ObjectId value and the Servant value as parameters 
 487          * (among others). This feature may be used to force 
 488          * every request for objects associated with a POA to 
 489          * be mediated by the servant manager.
 490          */
 491         interface ServantLocator : ServantManager { 
 492                 #pragma sun_localservant ServantLocator ""
 493         /**
 494          * Opaque data used to pass the information from
 495          * preinvoke to postinvoke hooks.  This specific
 496          * by the language mapping, that is why it is
 497          * specified as native.
 498          */
 499                 native Cookie;
 500         /**
 501          * This operations is used to get a servant that will be
 502          * used to process the request that caused preinvoke to
 503          * be called.
 504          * @param oid the object id associated with object on
 505          *            which the request was made. 
 506          * @param adapter the reference for POA in which the
 507          *                object is being activated.
 508          * @param operation the operation name.
 509          * @param the_cookie  an opaque value that can be set
 510          *                    by the servant manager to be used
 511          *                    during postinvoke.
 512          * @return Servant used to process incoming request.
 513          * @exception ForwardRequest to indicate to the ORB 
 514          *            that it is responsible for delivering 
 515          *            the current request and subsequent 
 516          *            requests to the object denoted in the 
 517          *            forward_reference member of the exception.
 518          */
 519                 Servant preinvoke( in ObjectId oid, in POA adapter, 
 520                                    in CORBA::Identifier operation, 
 521                                    out Cookie the_cookie ) 
 522                                 raises (ForwardRequest); 
 523         /**
 524          * This operation is invoked whenener a servant completes
 525          * a request.
 526          * @param oid the object id ssociated with object on which
 527          *            the request was made.
 528          * @param adapter the reference for POA in which the
 529          *                object was active.
 530          * @param the_cookie  an opaque value that contains
 531          *                    the data set by preinvoke.
 532          * @param the_servant reference to the servant that is
 533          *                    associated with the object.
 534          */
 535                 void postinvoke( in ObjectId oid, in POA adapter, 
 536                                  in CORBA::Identifier operation, 
 537                                  in Cookie the_cookie, 
 538                                  in Servant the_servant); 
 539         }; 
 540 
 541 
 542         // ************************************************** 
 543         // 
 544         // POA interface 
 545         // 
 546         // *****************************************
 547 
 548         /**
 549          * A POA object manages the implementation of a 
 550          * collection of objects. The POA supports a name space 
 551          * for the objects, which are identified by Object Ids. 
 552          * A POA also provides a name space for POAs. A POA is 
 553          * created as a child of an existing POA, which forms a 
 554          * hierarchy starting with the root POA. A POA object 
 555          * must not be exported to other processes, or 
 556          * externalized with ORB::object_to_string.
 557          */
 558         interface POA { 
 559                 #pragma sun_local POA ""
 560                 #pragma version POA 2.3
 561         /**
 562          * specifies that an child POA with the specified
 563          * name already exists.
 564          */
 565                 exception AdapterAlreadyExists { }; 
 566 
 567         /**
 568          * This is raised if the POA with a specified Name cannot
 569          * be found.
 570          */
 571                 exception AdapterNonExistent { }; 
 572 
 573         /**
 574          * This is raised if any of the policy objects are
 575          * not valid for the ORB
 576          */
 577                 exception InvalidPolicy { 
 578                         unsigned short index; 
 579                 }; 
 580 
 581         /**
 582          * This is raised if no default servant is associated
 583          * with the POA.
 584          */
 585                 exception NoServant { }; 
 586 
 587         /**
 588          * specifies that an object is already active or
 589          * exists in the Active Object Map.
 590          */
 591                 exception ObjectAlreadyActive { }; 
 592         /**
 593          * specifies that the object is not active or its
 594          * mapping does not exist in the Active Object Map.
 595          */
 596 
 597                 exception ObjectNotActive { }; 
 598 
 599         /**
 600          * This is raised when an attempt is made to activate
 601          * a servant that is already active or has a mapping in
 602          * the Active Object Map.
 603          */
 604                 exception ServantAlreadyActive { }; 
 605 
 606         /**
 607          * This is raised when an attempt is made to access a
 608          * servant that is not active or is not registered in
 609          * the Active Object Map.
 610          */
 611                 exception ServantNotActive { }; 
 612 
 613         /**
 614          * This is raised if the reference was not created by 
 615          * the POA 
 616          * specified in the reference.
 617          */
 618                 exception WrongAdapter { }; 
 619 
 620         /**
 621          * WrongPolicy is specified when the POA does not
 622          * specify the policy appropriate for its operations.
 623          */
 624                 exception WrongPolicy { }; 
 625 
 626                 
 627                 //---------------------------------------- 
 628                 // 
 629                 // POA creation and destruction 
 630                 // 
 631                 //-------------------------------
 632 
 633         /**
 634          * This operation creates a new POA as a child of the 
 635          * target POA.
 636          * @param adapter_name identifies the new POA with 
 637          *        respect to other POAs with the same parent POA.
 638          * @param a_POAManager specifies the POA Manager to be
 639          *        associated with the new POA.
 640          * @param policies specifies policy objects to be 
 641          *        associated with the POA to control its behavior.
 642          * @exception AdapterAlreadyExists specifies that the
 643          *            target POA already has a child POA with 
 644          *            the specified name.
 645          * @exception InvalidPolicy is raised if any of the
 646          *            policy objects are not valid for the ORB,
 647          *            or are in conflict, or require an 
 648          *            administrative action that has not been
 649          *            performed.
 650          */
 651                 POA create_POA(in string adapter_name, 
 652                                in POAManager a_POAManager, 
 653                                in CORBA::PolicyList policies) 
 654                         raises (AdapterAlreadyExists, InvalidPolicy); 
 655 
 656         /**
 657          * If the target POA is the parent of a child POA with 
 658          * the specified name (relative to the target POA), that 
 659          * child POA is returned. 
 660          * @param adapter_name POA name to be found.
 661          * @param activate_it  if a POA with the specified 
 662          *        name does not exist and the value of 
 663          *        the activate_it parameter is TRUE, the target 
 664          *        POA's AdapterActivator, if one exists, 
 665          *        is invoked.
 666          * @return POA if one exists or is activated by the
 667          *         AdapterActivator.
 668          * @return AdapterNonExistent is raised if POA with
 669          *         a specified name cannot be found or
 670          *         activated using AdapaterActivator.
 671          */
 672                 POA find_POA(in string adapter_name, 
 673                              in boolean activate_it) 
 674                         raises (AdapterNonExistent); 
 675 
 676         /**
 677          * This operation destroys the POA and all descendant 
 678          * POAs. All descendant POAs are destroyed (recursively) 
 679          * before the destruction of the containing POA. The POA 
 680          * so destroyed (that is, the POA with its name) may be 
 681          * re-created later in the same process.
 682          * @param etherealize_objects flag to indicate whether
 683          *        etherealize operation on servant manager needs
 684          *        to be called.
 685          * @param wait_for_completion flag to indicate whether
 686          *        POA and its children need to wait for active
 687          *        requests and the etherealization to complete.
 688          *
 689          */
 690                 void destroy( in boolean etherealize_objects, 
 691                               in boolean wait_for_completion); 
 692                 
 693                 // ************************************************** 
 694                 // 
 695                 // Factories for Policy objects 
 696                 // 
 697                 // ************ 
 698         /**
 699          * These operations each return a reference to a policy 
 700          * object with the specified value.
 701          * @param value policy type
 702          * @return ThreadPolcy Object
 703          */
 704                 ThreadPolicy create_thread_policy(
 705                                         in ThreadPolicyValue value); 
 706         /**
 707          * These operations each return a reference to a policy 
 708          * object with the specified value.
 709          * @param value policy type
 710          * @return LifespanPolicy Object.
 711          */
 712                 LifespanPolicy create_lifespan_policy(
 713                                         in LifespanPolicyValue value); 
 714         /**
 715          * These operations each return a reference to a policy 
 716          * object with the specified value.
 717          * @param value policy type
 718          * @return IdUniquenessPolicy Object.
 719          */
 720                 IdUniquenessPolicy create_id_uniqueness_policy(
 721                                         in IdUniquenessPolicyValue value); 
 722         /**
 723          * These operations each return a reference to a policy 
 724          * object with the specified value. 
 725          * @param value policy type
 726          * @return IdAssignmentPolicy Object.
 727          */
 728                 IdAssignmentPolicy create_id_assignment_policy(
 729                                         in IdAssignmentPolicyValue value); 
 730         /**
 731          * These operations each return a reference to a policy 
 732          * object with the specified value. 
 733          * @param value policy type
 734          * @return ImplicitActivationPolicy Object.
 735          */
 736                 ImplicitActivationPolicy create_implicit_activation_policy(
 737                                         in ImplicitActivationPolicyValue value);
 738         /**
 739          * These operations each return a reference to a policy 
 740          * object with the specified value.
 741          * @param value policy type
 742          * @return ServantRetentionPolicy Object.
 743          */
 744                 ServantRetentionPolicy create_servant_retention_policy(
 745                                         in ServantRetentionPolicyValue value); 
 746         /**
 747          * These operations each return a reference to a policy 
 748          * object with the specified value. 
 749          * @param value policy type
 750          * @return RequestProcessingPolicy Object.
 751          */
 752 
 753                 RequestProcessingPolicy create_request_processing_policy(
 754                                         in RequestProcessingPolicyValue value); 
 755                 
 756                 //-------------------------------------------------- 
 757                 // 
 758                 // POA attributes 
 759                 // 
 760                 //-----------------------------------
 761         /**
 762          * This attribute identifies the POA relative to its 
 763          * parent. This name is assigned when the POA is created.
 764          */
 765                 readonly attribute string the_name; 
 766         /**
 767          * This attribute identifies the parent of the POA. 
 768          * The parent of the root POA is null. 
 769          */
 770                 readonly attribute POA the_parent; 
 771         /**
 772          * This attribute identifies the current set of all 
 773          * child POAs of the POA. The set of child POAs 
 774          * includes only the POA's immediate children, and 
 775          * not their descendants.
 776          */
 777                 readonly attribute POAList the_children;
 778         /**
 779          * This attribute identifies the POA manager 
 780          * associated with the POA.
 781          */
 782                 readonly attribute POAManager the_POAManager; 
 783 
 784         /**
 785          * This attribute identifies the adapter activator 
 786          * associated with the POA.
 787          */
 788                 attribute AdapterActivator the_activator; 
 789 
 790                 //-------------------------------------------------- 
 791                 // 
 792                 // Servant Manager registration: 
 793                 // 
 794                 //-------------------------------------------------- 
 795         /**
 796          *
 797          * If the ServantRetentionPolicy of the POA is RETAIN, 
 798          * then the ServantManager argument (imgr) shall support 
 799          * the ServantActivator interface. For a NON_RETAIN policy,
 800          * the ServantManager shall support the ServantLocator 
 801          * interface. If the argument is nil, or does not support 
 802          * the required interface, then the OBJ_ADAPTER 
 803          * exception is raised.
 804          * @return ServantManager associated with a POA or null if
 805          *         none exists.
 806          * @exception WrongPolicy raised if the 
 807          *            USE_SERVANT_MANAGER policy is not specified.
 808          */
 809                 ServantManager get_servant_manager() 
 810                         raises (WrongPolicy); 
 811         /**
 812          *
 813          * This operation sets the default servant manager 
 814          * associated with the POA. This operation may only be 
 815          * invoked once after a POA has been created. Attempting 
 816          * to set the servant manager after one has already 
 817          * been set will result in the BAD_INV_ORDER exception 
 818          * being raised.
 819          * @param imgr servant manager to be used as a default.
 820          * @exception WrongPolicy raised if the 
 821          *            USE_SERVANT_MANAGER policy is not specified.
 822          */
 823                 void set_servant_manager( in ServantManager imgr) 
 824                         raises (WrongPolicy); 
 825                 
 826                 //-------------------------------------------------- 
 827                 // 
 828                 // operations for the USE_DEFAULT_SERVANT policy 
 829                 // 
 830                 //---------- 
 831         /**
 832          * This operation returns the default servant associated 
 833          * with the POA. 
 834          * @return p_servant default servant associated with a POA.
 835          * @exception NoServant raised if no default servant is
 836          *            associated with the POA.
 837          * @exception WrongPolicy raised if the 
 838          *            USE_DEFAULT_SERVANT policy is not specified.
 839          */
 840                 Servant get_servant() 
 841                         raises (NoServant, WrongPolicy);
 842 
 843         /**
 844          *
 845          * This operation registers the specified servant with 
 846          * the POA as the default servant. This servant will 
 847          * be used for all requests for which no servant is 
 848          * found in the Active Object Map.
 849          * @param p_servant servant to be used as a default.
 850          * @exception WrongPolicy raised if the 
 851          *            USE_DEFAULT_SERVANT policy is not specified.
 852          */
 853                 void set_servant(in Servant p_servant) 
 854                         raises (WrongPolicy); 
 855                 
 856                 // ************************************************** 
 857                 // 
 858                 // object activation and deactivation 
 859                 // 
 860                 // ************
 861 
 862         /**
 863          *
 864          * This operation generates an Object Id and enters 
 865          * the Object Id and the specified servant in the 
 866          * Active Object Map.
 867          * @param p_servant servant to be associated with an
 868          *            object to be activated.
 869          * @return POA generated object id.
 870          * @exception ServantAlreadyActive is raised if the
 871          *            POA has UNIQUE_ID policy and servant is
 872          *            is already in the Active Object Map.
 873          * @exception WrongPolicy raised if the SYSTEM_ID and 
 874          *            RETAIN policies are not specified.
 875          */
 876                 ObjectId activate_object( in Servant p_servant ) 
 877                         raises (ServantAlreadyActive, WrongPolicy); 
 878         /**
 879          * This operation enters an association between the 
 880          * specified Object Id and the specified servant in the 
 881          * Active Object Map.
 882          * @param id object id for the object to be activated.
 883          * @param p_servant servant to be associated with the
 884          *                  object.
 885          * @exception ServantAlreadyActive raised if the POA 
 886          *            has the UNIQUE_ID policy and the servant 
 887          *            is already in the Active Object Map.
 888          * @exception ObjectAlreadyActive raised if the object is
 889          *            already active in the POA.
 890          * @exception WrongPolicy raised if the RETAIN policy is
 891          *            is not specified.
 892          */
 893 
 894                 void activate_object_with_id( in ObjectId id, 
 895                                               in Servant p_servant) 
 896                         raises ( ServantAlreadyActive, ObjectAlreadyActive,
 897                                      WrongPolicy); 
 898         /**
 899          *
 900          * This operation causes the ObjectId specified in the 
 901          * oid parameter to be deactivated. An ObjectId which 
 902          * has been deactivated continues to process requests 
 903          * until there are no active requests for that ObjectId. 
 904          * A deactivated ObjectId is removed from the Active 
 905          * Object Map when all requests executing for that 
 906          * ObjectId have completed. 
 907          * @param oid Object Id for the object to be deactivated.
 908          * @exception ObjectNotActive if the object with the
 909          *            specified oid is not in the Active Object
 910          *            Map.
 911          * @exception WrongPolicy raised if the RETAIN policy is
 912          *            is not specified.
 913          */
 914                 void deactivate_object(in ObjectId oid) 
 915                         raises (ObjectNotActive, WrongPolicy); 
 916                 
 917                 // ************************************************** 
 918                 // 
 919                 // reference creation operations 
 920                 // 
 921                 // *****************
 922         /**
 923          * This operation creates an object reference that 
 924          * encapsulates a POA-generated Object Id value and 
 925          * the specified interface repository id. 
 926          *
 927          * @param intf rep id for creating an object reference.
 928          * @return object reference created using intf.
 929          * @exception WrongPolicy if SYSTEM_ID policy is not 
 930          *            specified.
 931          */
 932                 Object create_reference ( in CORBA::RepositoryId intf ) 
 933                         raises (WrongPolicy); 
 934 
 935         /**
 936          * This operation creates an object reference that 
 937          * encapsulates the specified Object Id and interface 
 938          * repository Id values. It does not cause an activation 
 939          * to take place. The resulting reference may be passed 
 940          * to clients, so that subsequent requests on those 
 941          * references will cause the object to be activated 
 942          * if necessary, or the default servant used, depending 
 943          * on the applicable policies. 
 944          * @param oid object id for creating an objref
 945          * @param intf rep id for creating an objref
 946          * @return object reference created using oid and intf
 947          * @exception BAD_PARAM is raised if the POA has the 
 948          *             SYSTEM_ID policy and it detects that the 
 949          *             Object Id value was not generated by the 
 950          *             system or for this POA.
 951          */
 952                 Object create_reference_with_id ( in ObjectId oid, 
 953                                                   in CORBA::RepositoryId intf ); 
 954                 // not specified in 11.3.8.19 raises (WrongPolicy);
 955 
 956                 //-------------------------------------------------- 
 957                 // 
 958                 // Identity mapping operations: 
 959                 // 
 960                 //-------------------------------------------------- 
 961         /**
 962          * This operation has four possible behaviors. 
 963          * 1. If the POA has the UNIQUE_ID policy and the 
 964          * specified servant is active, the Object Id associated 
 965          * with that servant is returned.
 966          * 2. If the POA has the IMPLICIT_ACTIVATION policy and 
 967          * either the POA has the MULTIPLE_ID policy or the 
 968          * specified servant is not active, the servant is 
 969          * activated using a POA-generated Object Id and the 
 970          * Interface Id associated with the servant, and that 
 971          * Object Id is returned. 
 972          * 3. If the POA has the USE_DEFAULT_SERVANT policy, 
 973          * the servant specified is the default servant, and the 
 974          * operation is being invoked in the context of executing 
 975          * a request on the default servant, then the ObjectId 
 976          * associated with the current invocation is returned. 
 977          * 4. Otherwise, the ServantNotActive exception is raised.
 978          *
 979          * @param p_servant servant for which the object disi returned.
 980          * @return object id associated with the servant.
 981          * @exception ServantNotActive if the above rules and
 982          *            policy combination is not met. 
 983          * @exception WrongPolicy if the USE_DEFAULT_SERVANT policy
 984          *            or a combination of the RETAIN policy and 
 985          *            either the UNIQUE_ID or IMPLICIT_ACTIVATION 
 986          *            policies are not present. 
 987          */
 988                 ObjectId servant_to_id(in Servant p_servant) 
 989                         raises (ServantNotActive, WrongPolicy); 
 990         
 991         /**
 992          * This operation requires the RETAIN policy and either 
 993          * the UNIQUE_ID or IMPLICIT_ACTIVATION policies if 
 994          * invoked outside the context of an operation dispatched 
 995          * by this POA. It has four possible behaviors.
 996          * 1. If the POA has both the RETAIN and the 
 997          * UNIQUE_ID policy and the specified servant is active, 
 998          * an object reference encapsulating the information used 
 999          * to activate the servant is returned. 
1000          * 2. If the POA has both the RETAIN and the 
1001          * IMPLICIT_ACTIVATION policy and either the POA has the 
1002          * MULTIPLE_ID policy or the specified servant is not 
1003          * active, the servant is activated using a POA-generated 
1004          * Object Id and the Interface Id associated with the 
1005          * servant, and a corresponding object reference is 
1006          * returned. 
1007          * 3. If the operation was invoked in the context of 
1008          * executing a request on the specified servant, the 
1009          * reference associated with the current invocation 
1010          * is returned. 
1011          * 4. Otherwise, the ServantNotActive exception is raised.
1012          *
1013          * @param p_servant servant for which the object reference
1014          *                  needs to be obtained.
1015          * @return object reference associated with the servant.
1016          * @exception WrongPolicy if the operation is not invoked 
1017          *            in the context of executing a request on 
1018          *            the specified servant and the required 
1019          *            policies are not present.
1020          * @exception ServantNotActive if the above specified
1021          *            policies and rules are not met.
1022          */
1023                 Object servant_to_reference(in Servant p_servant) 
1024                         raises (ServantNotActive, WrongPolicy); 
1025 
1026         /**
1027          * If the POA has the RETAIN policy and the specified 
1028          * object is present in the Active Object Map, this 
1029          * operation returns the servant associated with that 
1030          * object in the Active Object Map. Otherwise, if the 
1031          * POA has the USE_DEFAULT_SERVANT policy and a default 
1032          * servant has been registered with the POA, this 
1033          * operation returns the default servant. If the object 
1034          * reference was not created by this POA, 
1035          * the WrongAdapter exception is raised. (OMG Issue
1036          * on inconsistency with the POA.IDL.
1037          *
1038          * @param reference object reference for which the
1039          *                  servant is returned.
1040          * @return servant associated with the reference.
1041          * @exception WrongPolicy if neither the RETAIN policy or 
1042          *            the USE_DEFAULT_SERVANT policy is present. 
1043          * @exception ObjectNotActive if the servant is not
1044          *            present in the Active Object Map (for RETAIN)
1045          *            or no default servant is registered (for
1046          *            USE_DEFAULT_POLICY).
1047          * @exception WrongAdapter if reference was not created by
1048          *            this POA instance.
1049          */
1050                 Servant reference_to_servant(in Object reference)
1051                     raises (ObjectNotActive, WrongPolicy, WrongAdapter); 
1052 
1053         /**
1054          * This operation returns the Object Id value 
1055          * encapsulated by the specified reference. This 
1056          * operation is valid only if the reference was created 
1057          * by the POA on which the operation is being performed. 
1058          * The object denoted by the reference does not have 
1059          * to be active for this operation to succeed.
1060          *
1061          * @param reference the object reference from which the
1062          *                  object id needs to be returned.
1063          * @return object id encapsulated in the reference.
1064          * @exception WrongAdapter if the reference was not 
1065          *            created by the POA specified in the 
1066          *            reference.
1067          * @exception WrongPolicy declared to allow future 
1068          *            extensions. 
1069          *
1070          */
1071                 ObjectId reference_to_id(in Object reference) 
1072                         raises (WrongAdapter, WrongPolicy); 
1073 
1074         /**
1075          * If the POA has the RETAIN policy and the specified 
1076          * ObjectId is in the Active Object Map, this operation 
1077          * returns the servant associated with that object in 
1078          * the Active Object Map. Otherwise, if the POA has 
1079          * the USE_DEFAULT_SERVANT policy and a default servant 
1080          * has been registered with the POA, this operation 
1081          * returns the default servant. 
1082          *
1083          * @param oid object id for the which the servant is
1084          *            returned.
1085          * @return servant associated with oid.
1086          * @exception ObjectNotActive is raised if ObjectId is
1087          *            is not in the Active Object Map (for RETAIN
1088          *            policy), or no default servant is registered
1089          *            (for USE_DEFAULT_SERVANT policy).
1090          *
1091          * @exception WrongPolicy is raised if the RETAIN policy
1092          *                        or the USE_DEFAULT_SERVANT 
1093          *                        policy is not present. 
1094          */
1095                 Servant id_to_servant(in ObjectId oid) 
1096                         raises (ObjectNotActive, WrongPolicy); 
1097 
1098         /**
1099          * If an object with the specified Object Id value is 
1100          * currently active, a reference encapsulating the 
1101          * information used to activate the object is returned. 
1102          *
1103          * @param oid id of the object for which the
1104          *                 reference is returned.
1105          * @return the object reference 
1106          *
1107          * @exception ObjectNotActive if the Object Id value 
1108          *             is not active in the POA.
1109          * @exception WrongPolicy if the RETAIN policy is not 
1110          *             present.
1111          */
1112                 Object id_to_reference(in ObjectId oid) 
1113                         raises (ObjectNotActive, WrongPolicy); 
1114 
1115         /**
1116          * This returns the unique id of the POA in the process in which it 
1117          * is created.  It is for use by portable interceptors.
1118          * <p>
1119          * This id is guaranteed unique for the life span of the POA in the
1120          * process.  For persistent POAs, this means that if a POA is created 
1121          * in the same path with the same name as another POA, these POAs 
1122          * are identical and, therefore, have the same id.  For transient 
1123          * POAs, each POA is unique.
1124          */
1125                 readonly attribute ::org::omg::CORBA::OctetSeq id;
1126 
1127         }; 
1128 
1129         // *****************************************************
1130         // 
1131         // Current interface: 
1132         // 
1133         // *****************************************************
1134 
1135         /**
1136          * The PortableServer::Current interface, derived from 
1137          * CORBA::Current, provides method implementations with 
1138          * access to the identity of the object on which the 
1139          * method was invoked. The Current interface is provided 
1140          * to support servants that implement multiple objects, 
1141          * but can be used within the context of POA-dispatched 
1142          * method invocations on any servant. To provide location 
1143          * transparency, ORBs are required to support use of 
1144          * Current in the context of both locally and remotely 
1145          * invoked operations. An instance of Current can be 
1146          * obtained by the application by issuing the 
1147          * CORBA::ORB::resolve_initial_references("POACurrent") 
1148          * operation. Thereafter, it can be used within the 
1149          * context of a method dispatched by the POA to obtain 
1150          * the POA and ObjectId that identify the object on 
1151          * which that operation was invoked.
1152          */
1153         interface Current : CORBA::Current { 
1154                 #pragma sun_local Current ""
1155                 #pragma version Current 2.3
1156         /**
1157          * The exception that is used to indicate that the
1158          * operation is invoked outside the context of the
1159          * POA-dispatched operation.
1160          */
1161 
1162                 exception NoContext { }; 
1163         
1164         /**
1165          * Returns reference to the POA implementing the 
1166          * object in whose context it is called. 
1167          *
1168          * @return The poa implementing the object
1169          * 
1170          * @exception NoContext is raised when the operation is
1171          *            outside the context of a POA-dispatched 
1172          *            operation
1173          */
1174                 POA get_POA() 
1175                         raises (NoContext); 
1176 
1177         /** 
1178          * Returns the ObjectId identifying the object in 
1179          * whose context it is called. 
1180          *
1181          * @return the ObjectId of the object
1182          *
1183          * @exception NoContext is raised when the operation
1184          * is called outside the context of a POA-dispatched 
1185          * operation.
1186          */
1187 
1188                 ObjectId get_object_id() 
1189                         raises (NoContext); 
1190         }; 
1191 };