jdk8-mips64-public/corba: src/share/classes/org/omg/PortableServer/poa.idl@95db968660e7 (annotated)

src/share/classes/org/omg/PortableServer/poa.idl@95db968660e7 (annotated)

src/share/classes/org/omg/PortableServer/poa.idl

Thu, 17 Jun 2010 16:27:56 -0700

author: mikejwre
date: Thu, 17 Jun 2010 16:27:56 -0700
changeset 171: 95db968660e7
parent 158: 91006f157c46
child 748: 6845b95cba6b
permissions: -rw-r--r--

Added tag jdk7-b98 for changeset 3b99409057e4

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

Mercurial > jdk8-mips64-public > corba / annotate

src/share/classes/org/omg/PortableServer/poa.idl@95db968660e7 (annotated)

src/share/classes/org/omg/PortableServer/poa.idl