duke@1: /* ohair@158: * Copyright (c) 1997, 2001, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@158: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@158: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@158: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@158: * or visit www.oracle.com if you need additional information or have any ohair@158: * questions. duke@1: */ duke@1: duke@1: #include "corba.idl" duke@1: #include "CORBAX.idl" duke@1: duke@1: #pragma prefix "omg.org" duke@1: /** duke@1: * All Mapping corresponds to the Chapter 11 of duke@1: * CORBA V2.3.1 specified by OMG document formal/99-10-07.pdf. duke@1: * The exception to this is the id attribute, which is added in ptc/00-08-06, duke@1: * section 11.3.8.26. duke@1: */ duke@1: module PortableServer { duke@1: duke@1: #pragma version PortableServer 2.3 duke@1: duke@1: // forward reference duke@1: interface POA; duke@1: duke@1: /** duke@1: * List of POAs duke@1: */ duke@1: typedef sequence POAList; duke@1: duke@1: /** duke@1: * Values of type Servant support a language specific duke@1: * programming interface that can be used by the ORB to duke@1: * obtain a default POA for that servant. duke@1: * Some language mappings may allow Servant values to duke@1: * be implicitly converted to object references under duke@1: * appropriate conditions. duke@1: */ duke@1: native Servant; duke@1: duke@1: /** duke@1: * ObjectId value associated with the object reference. duke@1: */ duke@1: typedef sequence ObjectId; duke@1: duke@1: /** duke@1: * ForwardRequest to indicate to the ORB duke@1: * that it is responsible for delivering duke@1: * the current request and subsequent duke@1: * requests to the object denoted in the duke@1: * forward_reference member of the exception. duke@1: */ duke@1: exception ForwardRequest { Object forward_reference; }; duke@1: duke@1: // ********************************************** duke@1: // duke@1: // Policy interfaces duke@1: // duke@1: // ********************************************** duke@1: duke@1: /** duke@1: * The value representing THREAD_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType THREAD_POLICY_ID = 16; duke@1: /** duke@1: * The value representing LIFESPAN_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType LIFESPAN_POLICY_ID = 17; duke@1: /** duke@1: * The value representing ID_UNIQUENESS_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType ID_UNIQUENESS_POLICY_ID = 18; duke@1: /** duke@1: * The value representing ID_ASSIGNMENT_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType ID_ASSIGNMENT_POLICY_ID = 19; duke@1: /** duke@1: * The value representing IMPLICIT_ACTIVATION_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType IMPLICIT_ACTIVATION_POLICY_ID = 20; duke@1: /** duke@1: * The value representing SERVANT_RETENTION_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType SERVANT_RETENTION_POLICY_ID = 21; duke@1: /** duke@1: * The value representing REQUEST_PROCESSING_POLICY_ID. duke@1: */ duke@1: const CORBA::PolicyType REQUEST_PROCESSING_POLICY_ID = 22; duke@1: duke@1: /** duke@1: * The ThreadPolicyValue can have the following values. duke@1: * ORB_CTRL_MODEL - The ORB is responsible for assigning duke@1: * requests for an ORB- controlled POA to threads. duke@1: * SINGLE_THREAD_MODEL - Requests for a single-threaded duke@1: * POA are processed sequentially. duke@1: */ duke@1: enum ThreadPolicyValue { ORB_CTRL_MODEL, SINGLE_THREAD_MODEL }; duke@1: duke@1: /** duke@1: * The ThreadPolicy specifies the threading model duke@1: * used with the created POA. The default is duke@1: * ORB_CTRL_MODEL. duke@1: */ duke@1: interface ThreadPolicy : CORBA::Policy { duke@1: #pragma sun_local ThreadPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute ThreadPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * The LifespanPolicyValue can have the following values. duke@1: * TRANSIENT - The objects implemented in the POA duke@1: * cannot outlive the POA instance in which they are duke@1: * first created. duke@1: * PERSISTENT - The objects implemented in the POA can duke@1: * outlive the process in which they are first created. duke@1: */ duke@1: enum LifespanPolicyValue { TRANSIENT, PERSISTENT }; duke@1: duke@1: /** duke@1: * The LifespanPolicy specifies the lifespan of the duke@1: * objects implemented in the created POA. The default duke@1: * is TRANSIENT. duke@1: */ duke@1: interface LifespanPolicy : CORBA::Policy { duke@1: #pragma sun_local LifespanPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute LifespanPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * IdUniquenessPolicyValue can have the following values. duke@1: * UNIQUE_ID - Servants activated with that POA support duke@1: * exactly one Object Id. MULTIPLE_ID - a servant duke@1: * activated with that POA may support one or more duke@1: * Object Ids. duke@1: */ duke@1: enum IdUniquenessPolicyValue { UNIQUE_ID, MULTIPLE_ID }; duke@1: duke@1: /** duke@1: * The IdUniquenessPolicy specifies whether the servants duke@1: * activated in the created POA must have unique object i duke@1: * identities. The default is UNIQUE_ID. duke@1: */ duke@1: interface IdUniquenessPolicy : CORBA::Policy { duke@1: #pragma sun_local IdUniquenessPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute IdUniquenessPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * The IdAssignmentPolicyValue can have the following duke@1: * values. USER_ID - Objects created with that POA are duke@1: * assigned Object Ids only by the application. duke@1: * SYSTEM_ID - Objects created with that POA are duke@1: * assigned Object Ids only by the POA. If the POA also duke@1: * has the PERSISTENT policy, assigned Object Ids must duke@1: * be unique across all instantiations of the same POA. duke@1: */ duke@1: enum IdAssignmentPolicyValue { USER_ID, SYSTEM_ID }; duke@1: duke@1: /** duke@1: * IdAssignmentPolicy specifies whether Object Ids in duke@1: * the created POA are generated by the application or duke@1: * by the ORB. The default is SYSTEM_ID. duke@1: */ duke@1: interface IdAssignmentPolicy : CORBA::Policy { duke@1: #pragma sun_local IdAssignmentPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute IdAssignmentPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * ImplicitActivationPolicyValue has the following duke@1: * semantics. duke@1: * IMPLICIT_ACTIVATION to indicate implicit activation duke@1: * of servants. This requires SYSTEM_ID and RETAIN duke@1: * policies to be set. duke@1: * NO_IMPLICIT_ACTIVATION to indicate no implicit duke@1: * servant activation. duke@1: */ duke@1: enum ImplicitActivationPolicyValue { duke@1: IMPLICIT_ACTIVATION, NO_IMPLICIT_ACTIVATION duke@1: }; duke@1: duke@1: /** duke@1: * This policy specifies whether implicit activation duke@1: * of servants is supported in the created POA. duke@1: */ duke@1: interface ImplicitActivationPolicy : CORBA::Policy { duke@1: #pragma sun_local ImplicitActivationPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute ImplicitActivationPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * ServantRetentionPolicyValue can have the following duke@1: * values. RETAIN - to indicate that the POA will retain duke@1: * active servants in its Active Object Map. duke@1: * NON_RETAIN - to indicate Servants are not retained by duke@1: * the POA. If no ServantRetentionPolicy is specified at duke@1: * POA creation, the default is RETAIN. duke@1: */ duke@1: enum ServantRetentionPolicyValue { RETAIN, NON_RETAIN }; duke@1: duke@1: /** duke@1: * This policy specifies whether the created POA retains duke@1: * active servants in an Active Object Map. duke@1: */ duke@1: interface ServantRetentionPolicy : CORBA::Policy { duke@1: #pragma sun_local ServantRetentionPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute ServantRetentionPolicyValue value; duke@1: }; duke@1: duke@1: /** duke@1: * The RequestProcessingPolicyValue can have the following duke@1: * values. USE_ACTIVE_OBJECT_MAP_ONLY - If the Object Id duke@1: * is not found in the Active Object Map, duke@1: * an OBJECT_NOT_EXIST exception is returned to the duke@1: * client. The RETAIN policy is also required. duke@1: * USE_DEFAULT_SERVANT - If the Object Id is not found in duke@1: * the Active Object Map or the NON_RETAIN policy is duke@1: * present, and a default servant has been registered duke@1: * with the POA using the set_servant operation, duke@1: * the request is dispatched to the default servant. duke@1: * USE_SERVANT_MANAGER - If the Object Id is not found duke@1: * in the Active Object Map or the NON_RETAIN policy duke@1: * is present, and a servant manager has been registered duke@1: * with the POA using the set_servant_manager operation, duke@1: * the servant manager is given the opportunity to duke@1: * locate a servant or raise an exception. duke@1: */ duke@1: enum RequestProcessingPolicyValue { duke@1: USE_ACTIVE_OBJECT_MAP_ONLY, USE_DEFAULT_SERVANT, USE_SERVANT_MANAGER duke@1: }; duke@1: duke@1: /** duke@1: * This policy specifies how requests are processed by duke@1: * the created POA. The default is duke@1: * USE_ACTIVE_OBJECT_MAP_ONLY. duke@1: */ duke@1: interface RequestProcessingPolicy : CORBA::Policy { duke@1: #pragma sun_local RequestProcessingPolicy "" duke@1: /** duke@1: * specifies the policy value duke@1: */ duke@1: readonly attribute RequestProcessingPolicyValue value; duke@1: }; duke@1: duke@1: duke@1: // ************************************************** duke@1: // duke@1: // POAManager interface duke@1: // duke@1: // ********************************** duke@1: /** duke@1: * Each POA object has an associated POAManager object. duke@1: * A POA manager may be associated with one or more duke@1: * POA objects. A POA manager encapsulates the processing duke@1: * state of the POAs it is associated with. duke@1: */ duke@1: interface POAManager { duke@1: #pragma sun_local POAManager "" duke@1: exception AdapterInactive{ }; duke@1: /** duke@1: * Specifies the states for the POAManager duke@1: */ duke@1: enum State {HOLDING, ACTIVE, DISCARDING, INACTIVE}; duke@1: duke@1: /** duke@1: * This operation changes the state of the POA manager duke@1: * to active, causing associated POAs to start processing duke@1: * requests. duke@1: * @exception AdapterInactive is raised if the operation is duke@1: * invoked on the POAManager in inactive state. duke@1: */ duke@1: void activate() duke@1: raises(AdapterInactive); duke@1: /** duke@1: * This operation changes the state of the POA manager duke@1: * to holding, causing associated POAs to queue incoming duke@1: * requests. duke@1: * @param wait_for_completion if FALSE, the operation duke@1: * returns immediately after changing state. duke@1: * If TRUE, it waits for all active requests duke@1: * to complete. duke@1: * @exception AdapterInactive is raised if the operation is duke@1: * invoked on the POAManager in inactive state. duke@1: */ duke@1: void hold_requests(in boolean wait_for_completion) duke@1: raises(AdapterInactive); duke@1: /** duke@1: * This operation changes the state of the POA manager duke@1: * to discarding. This causes associated POAs to discard duke@1: * incoming requests. duke@1: * @param wait_for_completion if FALSE, the operation duke@1: * returns immediately after changing state. duke@1: * If TRUE, it waits for all active requests duke@1: * to complete. duke@1: * @exception AdapterInactive is raised if the operation is duke@1: * invoked on the POAManager in inactive state. duke@1: */ duke@1: void discard_requests(in boolean wait_for_completion) duke@1: raises(AdapterInactive); duke@1: duke@1: /** duke@1: * This operation changes the state of the POA manager duke@1: * to inactive, causing associated POAs to reject the duke@1: * requests that have not begun executing as well as duke@1: * as any new requests. duke@1: * @param etherealize_objects a flag to indicate whether duke@1: * to invoke the etherealize operation of the duke@1: * associated servant manager for all active duke@1: * objects. duke@1: * @param wait_for_completion if FALSE, the operation duke@1: * returns immediately after changing state. duke@1: * If TRUE, it waits for all active requests duke@1: * to complete. duke@1: * @exception AdapterInactive is raised if the operation is duke@1: * invoked on the POAManager in inactive state. duke@1: */ duke@1: void deactivate(in boolean etherealize_objects, duke@1: in boolean wait_for_completion) duke@1: raises(AdapterInactive); duke@1: /** duke@1: * This operation returns the state of the POA manager. duke@1: */ duke@1: State get_state(); duke@1: }; duke@1: duke@1: duke@1: // ************************************************** duke@1: // duke@1: // AdapterActivator interface duke@1: // duke@1: // **************************** duke@1: duke@1: /** duke@1: * An adapter activator supplies a POA with the ability duke@1: * to create child POAs on demand, as a side-effect of duke@1: * receiving a request that names the child POA duke@1: * (or one of its children), or when find_POA is called duke@1: * with an activate parameter value of TRUE. duke@1: */ duke@1: duke@1: interface AdapterActivator { duke@1: #pragma sun_local AdapterActivator "" duke@1: #pragma version AdapterActivator 2.3 duke@1: /** duke@1: * This operation is invoked when the ORB receives duke@1: * a request for an object reference that identifies duke@1: * a target POA that does not exist. The ORB invokes duke@1: * this operation once for each POA that must be duke@1: * created in order for the target POA to exist. duke@1: * @param parent indicates the parent POA for the POA duke@1: * that needs to be created. duke@1: * @param name identifies the name of the POA relative to duke@1: * the parent. duke@1: * @return returns TRUE if the POA was created or FALSE duke@1: * otherwise. duke@1: */ duke@1: boolean unknown_adapter(in POA parent, in string name); duke@1: }; duke@1: duke@1: duke@1: // ************************************************** duke@1: // duke@1: // ServantManager interface duke@1: // duke@1: // ****************************** duke@1: duke@1: /** duke@1: * A servant manager supplies a POA with the ability duke@1: * to activate objects on demand when the POA receives duke@1: * a request targeted at an inactive object. A servant duke@1: * manager is registered with a POA as a callback object, duke@1: * to be invoked by the POA when necessary. duke@1: * ServantManagers can either be ServantActivators or duke@1: * ServantLocators. A ServantManager object must be duke@1: * local to the process containing the POA objects duke@1: * it is registered with. duke@1: */ duke@1: duke@1: interface ServantManager duke@1: { #pragma sun_local ServantManager "" }; duke@1: duke@1: duke@1: /** duke@1: * When the POA has the RETAIN policy it uses servant duke@1: * managers that are ServantActivators. duke@1: */ duke@1: interface ServantActivator : ServantManager { duke@1: #pragma version ServantActivator 2.3 duke@1: #pragma sun_localservant ServantActivator "" duke@1: /** duke@1: * This operation is invoked by the POA whenever the duke@1: * POA receives a request for an object that is not duke@1: * currently active, assuming the POA has the duke@1: * USE_SERVANT_MANAGER and RETAIN policies. duke@1: * @param oid object Id associated with the object on duke@1: * the request was made. duke@1: * @param adapter object reference for the POA in which duke@1: * the object is being activated. duke@1: * @return Servant corresponding to oid is created or duke@1: * located by the user supplied servant manager. duke@1: * @exception ForwardRequest to indicate to the ORB duke@1: * that it is responsible for delivering duke@1: * the current request and subsequent duke@1: * requests to the object denoted in the duke@1: * forward_reference member of the exception. duke@1: */ duke@1: Servant incarnate ( in ObjectId oid, in POA adapter ) duke@1: raises (ForwardRequest); duke@1: /** duke@1: * This operation is invoked whenever a servant for duke@1: * an object is deactivated, assuming the POA has duke@1: * the USE_SERVANT_MANAGER and RETAIN policies. duke@1: * @param oid object Id associated with the object duke@1: * being deactivated. duke@1: * @param adapter object reference for the POA in which duke@1: * the object was active. duke@1: * @param serv contains reference to the servant duke@1: * associated with the object being deactivated. duke@1: * @param cleanup_in_progress if TRUE indicates that duke@1: * destroy or deactivate is called with duke@1: * etherealize_objects param of TRUE. FALSE duke@1: * indicates that etherealize was called due to duke@1: * other reasons. duke@1: * @param remaining_activations indicates whether the duke@1: * Servant Manager can destroy a servant. If duke@1: * set to TRUE, the Servant Manager should wait duke@1: * until all invocations in progress have duke@1: * completed. duke@1: */ duke@1: void etherealize ( in ObjectId oid, duke@1: in POA adapter, duke@1: in Servant serv, duke@1: in boolean cleanup_in_progress, duke@1: in boolean remaining_activations); duke@1: }; duke@1: duke@1: duke@1: /** duke@1: * When the POA has the NON_RETAIN policy it uses servant duke@1: * managers that are ServantLocators. Because the POA duke@1: * knows that the servant returned by this servant duke@1: * manager will be used only for a single request, duke@1: * it can supply extra information to the servant duke@1: * manager's operations and the servant manager's pair duke@1: * of operations may be able to cooperate to do duke@1: * something different than a ServantActivator. duke@1: * When the POA uses the ServantLocator interface, duke@1: * immediately after performing the operation invocation duke@1: * on the servant returned by preinvoke, the POA will duke@1: * invoke postinvoke on the servant manager, passing the duke@1: * ObjectId value and the Servant value as parameters duke@1: * (among others). This feature may be used to force duke@1: * every request for objects associated with a POA to duke@1: * be mediated by the servant manager. duke@1: */ duke@1: interface ServantLocator : ServantManager { duke@1: #pragma sun_localservant ServantLocator "" duke@1: /** duke@1: * Opaque data used to pass the information from duke@1: * preinvoke to postinvoke hooks. This specific duke@1: * by the language mapping, that is why it is duke@1: * specified as native. duke@1: */ duke@1: native Cookie; duke@1: /** duke@1: * This operations is used to get a servant that will be duke@1: * used to process the request that caused preinvoke to duke@1: * be called. duke@1: * @param oid the object id associated with object on duke@1: * which the request was made. duke@1: * @param adapter the reference for POA in which the duke@1: * object is being activated. duke@1: * @param operation the operation name. duke@1: * @param the_cookie an opaque value that can be set duke@1: * by the servant manager to be used duke@1: * during postinvoke. duke@1: * @return Servant used to process incoming request. duke@1: * @exception ForwardRequest to indicate to the ORB duke@1: * that it is responsible for delivering duke@1: * the current request and subsequent duke@1: * requests to the object denoted in the duke@1: * forward_reference member of the exception. duke@1: */ duke@1: Servant preinvoke( in ObjectId oid, in POA adapter, duke@1: in CORBA::Identifier operation, duke@1: out Cookie the_cookie ) duke@1: raises (ForwardRequest); duke@1: /** duke@1: * This operation is invoked whenener a servant completes duke@1: * a request. duke@1: * @param oid the object id ssociated with object on which duke@1: * the request was made. duke@1: * @param adapter the reference for POA in which the duke@1: * object was active. duke@1: * @param the_cookie an opaque value that contains duke@1: * the data set by preinvoke. duke@1: * @param the_servant reference to the servant that is duke@1: * associated with the object. duke@1: */ duke@1: void postinvoke( in ObjectId oid, in POA adapter, duke@1: in CORBA::Identifier operation, duke@1: in Cookie the_cookie, duke@1: in Servant the_servant); duke@1: }; duke@1: duke@1: duke@1: // ************************************************** duke@1: // duke@1: // POA interface duke@1: // duke@1: // ***************************************** duke@1: duke@1: /** duke@1: * A POA object manages the implementation of a duke@1: * collection of objects. The POA supports a name space duke@1: * for the objects, which are identified by Object Ids. duke@1: * A POA also provides a name space for POAs. A POA is duke@1: * created as a child of an existing POA, which forms a duke@1: * hierarchy starting with the root POA. A POA object duke@1: * must not be exported to other processes, or duke@1: * externalized with ORB::object_to_string. duke@1: */ duke@1: interface POA { duke@1: #pragma sun_local POA "" duke@1: #pragma version POA 2.3 duke@1: /** duke@1: * specifies that an child POA with the specified duke@1: * name already exists. duke@1: */ duke@1: exception AdapterAlreadyExists { }; duke@1: duke@1: /** duke@1: * This is raised if the POA with a specified Name cannot duke@1: * be found. duke@1: */ duke@1: exception AdapterNonExistent { }; duke@1: duke@1: /** duke@1: * This is raised if any of the policy objects are duke@1: * not valid for the ORB duke@1: */ duke@1: exception InvalidPolicy { duke@1: unsigned short index; duke@1: }; duke@1: duke@1: /** duke@1: * This is raised if no default servant is associated duke@1: * with the POA. duke@1: */ duke@1: exception NoServant { }; duke@1: duke@1: /** duke@1: * specifies that an object is already active or duke@1: * exists in the Active Object Map. duke@1: */ duke@1: exception ObjectAlreadyActive { }; duke@1: /** duke@1: * specifies that the object is not active or its duke@1: * mapping does not exist in the Active Object Map. duke@1: */ duke@1: duke@1: exception ObjectNotActive { }; duke@1: duke@1: /** duke@1: * This is raised when an attempt is made to activate duke@1: * a servant that is already active or has a mapping in duke@1: * the Active Object Map. duke@1: */ duke@1: exception ServantAlreadyActive { }; duke@1: duke@1: /** duke@1: * This is raised when an attempt is made to access a duke@1: * servant that is not active or is not registered in duke@1: * the Active Object Map. duke@1: */ duke@1: exception ServantNotActive { }; duke@1: duke@1: /** duke@1: * This is raised if the reference was not created by duke@1: * the POA duke@1: * specified in the reference. duke@1: */ duke@1: exception WrongAdapter { }; duke@1: duke@1: /** duke@1: * WrongPolicy is specified when the POA does not duke@1: * specify the policy appropriate for its operations. duke@1: */ duke@1: exception WrongPolicy { }; duke@1: duke@1: duke@1: //---------------------------------------- duke@1: // duke@1: // POA creation and destruction duke@1: // duke@1: //------------------------------- duke@1: duke@1: /** duke@1: * This operation creates a new POA as a child of the duke@1: * target POA. duke@1: * @param adapter_name identifies the new POA with duke@1: * respect to other POAs with the same parent POA. duke@1: * @param a_POAManager specifies the POA Manager to be duke@1: * associated with the new POA. duke@1: * @param policies specifies policy objects to be duke@1: * associated with the POA to control its behavior. duke@1: * @exception AdapterAlreadyExists specifies that the duke@1: * target POA already has a child POA with duke@1: * the specified name. duke@1: * @exception InvalidPolicy is raised if any of the duke@1: * policy objects are not valid for the ORB, duke@1: * or are in conflict, or require an duke@1: * administrative action that has not been duke@1: * performed. duke@1: */ duke@1: POA create_POA(in string adapter_name, duke@1: in POAManager a_POAManager, duke@1: in CORBA::PolicyList policies) duke@1: raises (AdapterAlreadyExists, InvalidPolicy); duke@1: duke@1: /** duke@1: * If the target POA is the parent of a child POA with duke@1: * the specified name (relative to the target POA), that duke@1: * child POA is returned. duke@1: * @param adapter_name POA name to be found. duke@1: * @param activate_it if a POA with the specified duke@1: * name does not exist and the value of duke@1: * the activate_it parameter is TRUE, the target duke@1: * POA's AdapterActivator, if one exists, duke@1: * is invoked. duke@1: * @return POA if one exists or is activated by the duke@1: * AdapterActivator. duke@1: * @return AdapterNonExistent is raised if POA with duke@1: * a specified name cannot be found or duke@1: * activated using AdapaterActivator. duke@1: */ duke@1: POA find_POA(in string adapter_name, duke@1: in boolean activate_it) duke@1: raises (AdapterNonExistent); duke@1: duke@1: /** duke@1: * This operation destroys the POA and all descendant duke@1: * POAs. All descendant POAs are destroyed (recursively) duke@1: * before the destruction of the containing POA. The POA duke@1: * so destroyed (that is, the POA with its name) may be duke@1: * re-created later in the same process. duke@1: * @param etherealize_objects flag to indicate whether duke@1: * etherealize operation on servant manager needs duke@1: * to be called. duke@1: * @param wait_for_completion flag to indicate whether duke@1: * POA and its children need to wait for active duke@1: * requests and the etherealization to complete. duke@1: * duke@1: */ duke@1: void destroy( in boolean etherealize_objects, duke@1: in boolean wait_for_completion); duke@1: duke@1: // ************************************************** duke@1: // duke@1: // Factories for Policy objects duke@1: // duke@1: // ************ duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return ThreadPolcy Object duke@1: */ duke@1: ThreadPolicy create_thread_policy( duke@1: in ThreadPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return LifespanPolicy Object. duke@1: */ duke@1: LifespanPolicy create_lifespan_policy( duke@1: in LifespanPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return IdUniquenessPolicy Object. duke@1: */ duke@1: IdUniquenessPolicy create_id_uniqueness_policy( duke@1: in IdUniquenessPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return IdAssignmentPolicy Object. duke@1: */ duke@1: IdAssignmentPolicy create_id_assignment_policy( duke@1: in IdAssignmentPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return ImplicitActivationPolicy Object. duke@1: */ duke@1: ImplicitActivationPolicy create_implicit_activation_policy( duke@1: in ImplicitActivationPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return ServantRetentionPolicy Object. duke@1: */ duke@1: ServantRetentionPolicy create_servant_retention_policy( duke@1: in ServantRetentionPolicyValue value); duke@1: /** duke@1: * These operations each return a reference to a policy duke@1: * object with the specified value. duke@1: * @param value policy type duke@1: * @return RequestProcessingPolicy Object. duke@1: */ duke@1: duke@1: RequestProcessingPolicy create_request_processing_policy( duke@1: in RequestProcessingPolicyValue value); duke@1: duke@1: //-------------------------------------------------- duke@1: // duke@1: // POA attributes duke@1: // duke@1: //----------------------------------- duke@1: /** duke@1: * This attribute identifies the POA relative to its duke@1: * parent. This name is assigned when the POA is created. duke@1: */ duke@1: readonly attribute string the_name; duke@1: /** duke@1: * This attribute identifies the parent of the POA. duke@1: * The parent of the root POA is null. duke@1: */ duke@1: readonly attribute POA the_parent; duke@1: /** duke@1: * This attribute identifies the current set of all duke@1: * child POAs of the POA. The set of child POAs duke@1: * includes only the POA's immediate children, and duke@1: * not their descendants. duke@1: */ duke@1: readonly attribute POAList the_children; duke@1: /** duke@1: * This attribute identifies the POA manager duke@1: * associated with the POA. duke@1: */ duke@1: readonly attribute POAManager the_POAManager; duke@1: duke@1: /** duke@1: * This attribute identifies the adapter activator duke@1: * associated with the POA. duke@1: */ duke@1: attribute AdapterActivator the_activator; duke@1: duke@1: //-------------------------------------------------- duke@1: // duke@1: // Servant Manager registration: duke@1: // duke@1: //-------------------------------------------------- duke@1: /** duke@1: * duke@1: * If the ServantRetentionPolicy of the POA is RETAIN, duke@1: * then the ServantManager argument (imgr) shall support duke@1: * the ServantActivator interface. For a NON_RETAIN policy, duke@1: * the ServantManager shall support the ServantLocator duke@1: * interface. If the argument is nil, or does not support duke@1: * the required interface, then the OBJ_ADAPTER duke@1: * exception is raised. duke@1: * @return ServantManager associated with a POA or null if duke@1: * none exists. duke@1: * @exception WrongPolicy raised if the duke@1: * USE_SERVANT_MANAGER policy is not specified. duke@1: */ duke@1: ServantManager get_servant_manager() duke@1: raises (WrongPolicy); duke@1: /** duke@1: * duke@1: * This operation sets the default servant manager duke@1: * associated with the POA. This operation may only be duke@1: * invoked once after a POA has been created. Attempting duke@1: * to set the servant manager after one has already duke@1: * been set will result in the BAD_INV_ORDER exception duke@1: * being raised. duke@1: * @param imgr servant manager to be used as a default. duke@1: * @exception WrongPolicy raised if the duke@1: * USE_SERVANT_MANAGER policy is not specified. duke@1: */ duke@1: void set_servant_manager( in ServantManager imgr) duke@1: raises (WrongPolicy); duke@1: duke@1: //-------------------------------------------------- duke@1: // duke@1: // operations for the USE_DEFAULT_SERVANT policy duke@1: // duke@1: //---------- duke@1: /** duke@1: * This operation returns the default servant associated duke@1: * with the POA. duke@1: * @return p_servant default servant associated with a POA. duke@1: * @exception NoServant raised if no default servant is duke@1: * associated with the POA. duke@1: * @exception WrongPolicy raised if the duke@1: * USE_DEFAULT_SERVANT policy is not specified. duke@1: */ duke@1: Servant get_servant() duke@1: raises (NoServant, WrongPolicy); duke@1: duke@1: /** duke@1: * duke@1: * This operation registers the specified servant with duke@1: * the POA as the default servant. This servant will duke@1: * be used for all requests for which no servant is duke@1: * found in the Active Object Map. duke@1: * @param p_servant servant to be used as a default. duke@1: * @exception WrongPolicy raised if the duke@1: * USE_DEFAULT_SERVANT policy is not specified. duke@1: */ duke@1: void set_servant(in Servant p_servant) duke@1: raises (WrongPolicy); duke@1: duke@1: // ************************************************** duke@1: // duke@1: // object activation and deactivation duke@1: // duke@1: // ************ duke@1: duke@1: /** duke@1: * duke@1: * This operation generates an Object Id and enters duke@1: * the Object Id and the specified servant in the duke@1: * Active Object Map. duke@1: * @param p_servant servant to be associated with an duke@1: * object to be activated. duke@1: * @return POA generated object id. duke@1: * @exception ServantAlreadyActive is raised if the duke@1: * POA has UNIQUE_ID policy and servant is duke@1: * is already in the Active Object Map. duke@1: * @exception WrongPolicy raised if the SYSTEM_ID and duke@1: * RETAIN policies are not specified. duke@1: */ duke@1: ObjectId activate_object( in Servant p_servant ) duke@1: raises (ServantAlreadyActive, WrongPolicy); duke@1: /** duke@1: * This operation enters an association between the duke@1: * specified Object Id and the specified servant in the duke@1: * Active Object Map. duke@1: * @param id object id for the object to be activated. duke@1: * @param p_servant servant to be associated with the duke@1: * object. duke@1: * @exception ServantAlreadyActive raised if the POA duke@1: * has the UNIQUE_ID policy and the servant duke@1: * is already in the Active Object Map. duke@1: * @exception ObjectAlreadyActive raised if the object is duke@1: * already active in the POA. duke@1: * @exception WrongPolicy raised if the RETAIN policy is duke@1: * is not specified. duke@1: */ duke@1: duke@1: void activate_object_with_id( in ObjectId id, duke@1: in Servant p_servant) duke@1: raises ( ServantAlreadyActive, ObjectAlreadyActive, duke@1: WrongPolicy); duke@1: /** duke@1: * duke@1: * This operation causes the ObjectId specified in the duke@1: * oid parameter to be deactivated. An ObjectId which duke@1: * has been deactivated continues to process requests duke@1: * until there are no active requests for that ObjectId. duke@1: * A deactivated ObjectId is removed from the Active duke@1: * Object Map when all requests executing for that duke@1: * ObjectId have completed. duke@1: * @param oid Object Id for the object to be deactivated. duke@1: * @exception ObjectNotActive if the object with the duke@1: * specified oid is not in the Active Object duke@1: * Map. duke@1: * @exception WrongPolicy raised if the RETAIN policy is duke@1: * is not specified. duke@1: */ duke@1: void deactivate_object(in ObjectId oid) duke@1: raises (ObjectNotActive, WrongPolicy); duke@1: duke@1: // ************************************************** duke@1: // duke@1: // reference creation operations duke@1: // duke@1: // ***************** duke@1: /** duke@1: * This operation creates an object reference that duke@1: * encapsulates a POA-generated Object Id value and duke@1: * the specified interface repository id. duke@1: * duke@1: * @param intf rep id for creating an object reference. duke@1: * @return object reference created using intf. duke@1: * @exception WrongPolicy if SYSTEM_ID policy is not duke@1: * specified. duke@1: */ duke@1: Object create_reference ( in CORBA::RepositoryId intf ) duke@1: raises (WrongPolicy); duke@1: duke@1: /** duke@1: * This operation creates an object reference that duke@1: * encapsulates the specified Object Id and interface duke@1: * repository Id values. It does not cause an activation duke@1: * to take place. The resulting reference may be passed duke@1: * to clients, so that subsequent requests on those duke@1: * references will cause the object to be activated duke@1: * if necessary, or the default servant used, depending duke@1: * on the applicable policies. duke@1: * @param oid object id for creating an objref duke@1: * @param intf rep id for creating an objref duke@1: * @return object reference created using oid and intf duke@1: * @exception BAD_PARAM is raised if the POA has the duke@1: * SYSTEM_ID policy and it detects that the duke@1: * Object Id value was not generated by the duke@1: * system or for this POA. duke@1: */ duke@1: Object create_reference_with_id ( in ObjectId oid, duke@1: in CORBA::RepositoryId intf ); duke@1: // not specified in 11.3.8.19 raises (WrongPolicy); duke@1: duke@1: //-------------------------------------------------- duke@1: // duke@1: // Identity mapping operations: duke@1: // duke@1: //-------------------------------------------------- duke@1: /** duke@1: * This operation has four possible behaviors. duke@1: * 1. If the POA has the UNIQUE_ID policy and the duke@1: * specified servant is active, the Object Id associated duke@1: * with that servant is returned. duke@1: * 2. If the POA has the IMPLICIT_ACTIVATION policy and duke@1: * either the POA has the MULTIPLE_ID policy or the duke@1: * specified servant is not active, the servant is duke@1: * activated using a POA-generated Object Id and the duke@1: * Interface Id associated with the servant, and that duke@1: * Object Id is returned. duke@1: * 3. If the POA has the USE_DEFAULT_SERVANT policy, duke@1: * the servant specified is the default servant, and the duke@1: * operation is being invoked in the context of executing duke@1: * a request on the default servant, then the ObjectId duke@1: * associated with the current invocation is returned. duke@1: * 4. Otherwise, the ServantNotActive exception is raised. duke@1: * duke@1: * @param p_servant servant for which the object disi returned. duke@1: * @return object id associated with the servant. duke@1: * @exception ServantNotActive if the above rules and duke@1: * policy combination is not met. duke@1: * @exception WrongPolicy if the USE_DEFAULT_SERVANT policy duke@1: * or a combination of the RETAIN policy and duke@1: * either the UNIQUE_ID or IMPLICIT_ACTIVATION duke@1: * policies are not present. duke@1: */ duke@1: ObjectId servant_to_id(in Servant p_servant) duke@1: raises (ServantNotActive, WrongPolicy); duke@1: duke@1: /** duke@1: * This operation requires the RETAIN policy and either duke@1: * the UNIQUE_ID or IMPLICIT_ACTIVATION policies if duke@1: * invoked outside the context of an operation dispatched duke@1: * by this POA. It has four possible behaviors. duke@1: * 1. If the POA has both the RETAIN and the duke@1: * UNIQUE_ID policy and the specified servant is active, duke@1: * an object reference encapsulating the information used duke@1: * to activate the servant is returned. duke@1: * 2. If the POA has both the RETAIN and the duke@1: * IMPLICIT_ACTIVATION policy and either the POA has the duke@1: * MULTIPLE_ID policy or the specified servant is not duke@1: * active, the servant is activated using a POA-generated duke@1: * Object Id and the Interface Id associated with the duke@1: * servant, and a corresponding object reference is duke@1: * returned. duke@1: * 3. If the operation was invoked in the context of duke@1: * executing a request on the specified servant, the duke@1: * reference associated with the current invocation duke@1: * is returned. duke@1: * 4. Otherwise, the ServantNotActive exception is raised. duke@1: * duke@1: * @param p_servant servant for which the object reference duke@1: * needs to be obtained. duke@1: * @return object reference associated with the servant. duke@1: * @exception WrongPolicy if the operation is not invoked duke@1: * in the context of executing a request on duke@1: * the specified servant and the required duke@1: * policies are not present. duke@1: * @exception ServantNotActive if the above specified duke@1: * policies and rules are not met. duke@1: */ duke@1: Object servant_to_reference(in Servant p_servant) duke@1: raises (ServantNotActive, WrongPolicy); duke@1: duke@1: /** duke@1: * If the POA has the RETAIN policy and the specified duke@1: * object is present in the Active Object Map, this duke@1: * operation returns the servant associated with that duke@1: * object in the Active Object Map. Otherwise, if the duke@1: * POA has the USE_DEFAULT_SERVANT policy and a default duke@1: * servant has been registered with the POA, this duke@1: * operation returns the default servant. If the object duke@1: * reference was not created by this POA, duke@1: * the WrongAdapter exception is raised. (OMG Issue duke@1: * on inconsistency with the POA.IDL. duke@1: * duke@1: * @param reference object reference for which the duke@1: * servant is returned. duke@1: * @return servant associated with the reference. duke@1: * @exception WrongPolicy if neither the RETAIN policy or duke@1: * the USE_DEFAULT_SERVANT policy is present. duke@1: * @exception ObjectNotActive if the servant is not duke@1: * present in the Active Object Map (for RETAIN) duke@1: * or no default servant is registered (for duke@1: * USE_DEFAULT_POLICY). duke@1: * @exception WrongAdapter if reference was not created by duke@1: * this POA instance. duke@1: */ duke@1: Servant reference_to_servant(in Object reference) duke@1: raises (ObjectNotActive, WrongPolicy, WrongAdapter); duke@1: duke@1: /** duke@1: * This operation returns the Object Id value duke@1: * encapsulated by the specified reference. This duke@1: * operation is valid only if the reference was created duke@1: * by the POA on which the operation is being performed. duke@1: * The object denoted by the reference does not have duke@1: * to be active for this operation to succeed. duke@1: * duke@1: * @param reference the object reference from which the duke@1: * object id needs to be returned. duke@1: * @return object id encapsulated in the reference. duke@1: * @exception WrongAdapter if the reference was not duke@1: * created by the POA specified in the duke@1: * reference. duke@1: * @exception WrongPolicy declared to allow future duke@1: * extensions. duke@1: * duke@1: */ duke@1: ObjectId reference_to_id(in Object reference) duke@1: raises (WrongAdapter, WrongPolicy); duke@1: duke@1: /** duke@1: * If the POA has the RETAIN policy and the specified duke@1: * ObjectId is in the Active Object Map, this operation duke@1: * returns the servant associated with that object in duke@1: * the Active Object Map. Otherwise, if the POA has duke@1: * the USE_DEFAULT_SERVANT policy and a default servant duke@1: * has been registered with the POA, this operation duke@1: * returns the default servant. duke@1: * duke@1: * @param oid object id for the which the servant is duke@1: * returned. duke@1: * @return servant associated with oid. duke@1: * @exception ObjectNotActive is raised if ObjectId is duke@1: * is not in the Active Object Map (for RETAIN duke@1: * policy), or no default servant is registered duke@1: * (for USE_DEFAULT_SERVANT policy). duke@1: * duke@1: * @exception WrongPolicy is raised if the RETAIN policy duke@1: * or the USE_DEFAULT_SERVANT duke@1: * policy is not present. duke@1: */ duke@1: Servant id_to_servant(in ObjectId oid) duke@1: raises (ObjectNotActive, WrongPolicy); duke@1: duke@1: /** duke@1: * If an object with the specified Object Id value is duke@1: * currently active, a reference encapsulating the duke@1: * information used to activate the object is returned. duke@1: * duke@1: * @param oid id of the object for which the duke@1: * reference is returned. duke@1: * @return the object reference duke@1: * duke@1: * @exception ObjectNotActive if the Object Id value duke@1: * is not active in the POA. duke@1: * @exception WrongPolicy if the RETAIN policy is not duke@1: * present. duke@1: */ duke@1: Object id_to_reference(in ObjectId oid) duke@1: raises (ObjectNotActive, WrongPolicy); duke@1: duke@1: /** duke@1: * This returns the unique id of the POA in the process in which it duke@1: * is created. It is for use by portable interceptors. duke@1: *

duke@1: * This id is guaranteed unique for the life span of the POA in the duke@1: * process. For persistent POAs, this means that if a POA is created duke@1: * in the same path with the same name as another POA, these POAs duke@1: * are identical and, therefore, have the same id. For transient duke@1: * POAs, each POA is unique. duke@1: */ duke@1: readonly attribute ::org::omg::CORBA::OctetSeq id; duke@1: duke@1: }; duke@1: duke@1: // ***************************************************** duke@1: // duke@1: // Current interface: duke@1: // duke@1: // ***************************************************** duke@1: duke@1: /** duke@1: * The PortableServer::Current interface, derived from duke@1: * CORBA::Current, provides method implementations with duke@1: * access to the identity of the object on which the duke@1: * method was invoked. The Current interface is provided duke@1: * to support servants that implement multiple objects, duke@1: * but can be used within the context of POA-dispatched duke@1: * method invocations on any servant. To provide location duke@1: * transparency, ORBs are required to support use of duke@1: * Current in the context of both locally and remotely duke@1: * invoked operations. An instance of Current can be duke@1: * obtained by the application by issuing the duke@1: * CORBA::ORB::resolve_initial_references("POACurrent") duke@1: * operation. Thereafter, it can be used within the duke@1: * context of a method dispatched by the POA to obtain duke@1: * the POA and ObjectId that identify the object on duke@1: * which that operation was invoked. duke@1: */ duke@1: interface Current : CORBA::Current { duke@1: #pragma sun_local Current "" duke@1: #pragma version Current 2.3 duke@1: /** duke@1: * The exception that is used to indicate that the duke@1: * operation is invoked outside the context of the duke@1: * POA-dispatched operation. duke@1: */ duke@1: duke@1: exception NoContext { }; duke@1: duke@1: /** duke@1: * Returns reference to the POA implementing the duke@1: * object in whose context it is called. duke@1: * duke@1: * @return The poa implementing the object duke@1: * duke@1: * @exception NoContext is raised when the operation is duke@1: * outside the context of a POA-dispatched duke@1: * operation duke@1: */ duke@1: POA get_POA() duke@1: raises (NoContext); duke@1: duke@1: /** duke@1: * Returns the ObjectId identifying the object in duke@1: * whose context it is called. duke@1: * duke@1: * @return the ObjectId of the object duke@1: * duke@1: * @exception NoContext is raised when the operation duke@1: * is called outside the context of a POA-dispatched duke@1: * operation. duke@1: */ duke@1: duke@1: ObjectId get_object_id() duke@1: raises (NoContext); duke@1: }; duke@1: };