Synopsis

Creates new instances of policy objects of a specific type with specified initial state.

C++ Binding

void CORBA::ORB::create_policy (
                       in PolicyType type,
                        in any val);

Arguments

Exceptions

Description

This operation can be invoked to create new instances of policy objects of a specific type with specified initial state. If create_policy fails to instantiate a new Policy object due to its inability to interpret the requested type and content of the policy, it raises the Policy Error exception with the appropriate reason. (See Exceptions below.)

The BidirectionalPolicy argument is provided for remote clients using callbacks because remote clients use IIOP. It is not used for native clients using callbacks or for BEA Tuxedo servers because machines inside a BEA Tuxedo domain communicate differently.

Before GIOP 1.2, bidirectional policy was not available as a choice in IIOP (which uses TCP/IP). Connections in GIOP 1.0 and 1.1 were one way (that is, a request flowed from a client to a server); only responses flowed from the server back to the client. If the server wanted to make a request back to the client machine (say for a callback), the server machine had to establish another one-way connection. (Be advised that "connections" in this sense mean operating system resources, not physically different wires or communication paths. A connection uses resources, so minimizing connections is desirable.)

Since this release of the BEA Tuxedo C++ software supports GIOP 1.2, it supports reuse of the TCP/IP connection for both incoming and outgoing requests. Reusing connections saves resources when a remote client sends callback references to a BEA Tuxedo domain. The joint client/server uses a connection to send a request to a BEA Tuxedo domain; that connection can be reused for the callback request. If the connection is not reused, the callback request must establish another connection.

Allowing reuse of a connection is a choice of the ORB/POA that creates callback object references. The server for those object references (usually the creator of the references, especially in the callback case) might choose not to allow reuse for security considerations (that is, the outgoing connection [a client request from this machine to a remote server] may not need security because the remote server does not require it, but the callback server on this machine might require security). Since security is established partly on a connection basis, the incoming security can be established only if a separate connection is used. If the remote server requires security, and if that security involves a mutual authentication, the local server usually feels safe in allowing reuse of the connection.

Since the choice of connection reuse is at the server end, whenever a process acts as a server—in this case a joint client/server—and creates object references, it must inform the ORB that it is willing to reuse connections. The process does this by setting a policy on the POA that creates the object references. The default policy is to not allow reuse (that is, if you do not supply a policy object for reuse, the POA does not allow reuse).

This default allows for backward compatibility with code written before CORBA version 2.3. Such code did not know that reuse was possible so it did not have to take into consideration the security implications of reuse. Thus, that unchanged code should continue to disallow reuse until the user considers security and explicitly makes a decision to the contrary.

To allow reuse, you use the create_policy operation to create a policy object that allows reuse, and use that policy object as part of the list of policies for POA creation.

Return Values

None.

Example

#include <BiDirPolicy_c.h>
BiDirPolicy::BidirectionalPolicy_var bd_policy;
CORBA::Any allow_reuse;

allow_reuse <<= BiDirPolicy::BOTH;

CORBA::Policy_var generic_policy =
      orb->create_policy( BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE,
                          allow_reuse );
bd_policy = BiDirPolicy::BidirectionalPolicy::_narrow(
                                                 generic_policy );

In the above example, the bd_policy would then be placed in the PolicyList passed to the create_poa operation.