Writing WebLogic Server Clients That Invoke CORBA Objects

The following sections describe the requirements to access BEA Tuxedo CORBA objects from WebLogic Server including:

• Before You Begin

• Configuring a WLEC Connection Pool

• Accessing BEA Tuxedo CORBA Objects

• More Information About Transactions

 

---

Before You Begin

Before you implement WebLogic Server clients that invoke BEA Tuxedo CORBA objects, you need to:

• Configure and run WebLogic Server

• Configure and run a BEA Tuxedo CORBA server application

• Be familiar with the WebLogic Enterprise Connectivity architecture as described in Introducing WebLogic Enterprise Connectivity.

• Run the WebLogic Enterprise Connectivity examples in the /samples/examples/wlec directory in the WebLogic Server installation.

 

---

Configuring a WLEC Connection Pool

Configure a WLEC connection pool for each BEA Tuxedo domain that contains a BEA Tuxedo CORBA object you want to access from a WebLogic Server client. Because the security context established for the WebLogic Server client is propagated to the BEA Tuxedo domain through the WLEC connection pool, the WLEC connection pools are the basis for the security context propagation feature.

Before using WLEC connection pools, add WL_HOME/lib/wleorb.jar, WL_HOME/lib/wlepool.jar, and TUXDIR/udataobj/java/jdk/wleclient.jar to the CLASSPATH variable in the startAdminWebLogic.sh or startAdminWebLogic.cmd file. If you are using a JSP that requests an EJB served by WLE 5.1, add the location of the WLE 5.1 wlej2eecl.jar file to the CLASSPATH variable in the startAdminWebLogic.sh or startAdminWebLogic.cmd file.

Create a new WLEC connection pool for the purpose of security context propagation. To create a WLEC connection pool:

1. Go to the Services—>WLEC node in the left pane of the Administration Console. In the right pane of the Administration Console, click the Create a new WLEC Connection Pool link. Define the attributes listed in the following table.

   Table 2-1 WLEC Connection Pool Attributes on the General Tab 

   Attribute	Description
   Name	The name of the WLEC connection pool. The name must be unique for each WLEC connection pool.
   Primary Addresses	A list of addresses for IIOP Listener/Handlers that can be used to establish a connection between the WLEC connection pool and the BEA Tuxedo domain. The format of each address is //hostname:port. The addresses must match the ISL addresses defined in the UBBCONFIG file. Multiple addresses are separated by commas. For example: //main1.com:1024, //main2.com:1044. To configure the WLEC connection pool to use the SSL protocol, use the corbalocs prefix with the address of the IIOP Listener/Handler. For example: corbalocs://hostname:port.
   Failover Addresses	A list of addresses for IIOP Listener/Handlers that are used if connections cannot be established with the addresses defined in the Primary Addresses attribute. Multiple addresses are separated by commas. This attribute is optional.
   Domain	The name of the BEA Tuxedo domain to which this WLEC connection pool connects. You can have only one WLEC connection pool per BEA Tuxedo domain. The domain name must match the domainid parameter in the RESOURCES section of the UBBCONFIG file for the BEA Tuxedo domain.
   Minimum Pool Size	The number of IIOP connections to be added to the WLEC connection pool when WebLogic Server starts. The default is 1.
   Maximum Pool Size	The maximum number of IIOP connections that can be made from the WLEC connection pool. The default is 1.

   
    

2. Click the Create button.

3. Propagate the security context for a User in a WebLogic Server security realm to a BEA Tuxedo domain. To do so, define the attributes on the Security tab in the Connection Pool Configuration window. The following table describes these attributes.

   Table 2-2 WLEC Connection Pool Attributes on the Security Tab 

   Attribute	Description
   User Name	A BEA Tuxedo user name. This attribute is required only when the security level in the BEA Tuxedo domain is USER_AUTH, ACL or MANDATORY_ACL.
   User Password	The password for the User defined in the User Name attribute. This attribute is required only when you define the User Name attribute.
   User Role	The BEA Tuxedo user role. This attribute is required when the security level in the BEA Tuxedo is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Application Password	The password for the BEA Tuxedo CORBA application. This attribute is required when the security level in the BEA Tuxedo domain is APP_PW, USER_AUTH, ACL, or MANDATORY_ACL.
   Minimum Encryption Level	The minimum SSL encryption level used between the BEA Tuxedo domain and WebLogic Server. The possible values are 0, 40, 56, and 128. The default is 40. Zero (0) indicates that the data is signed but not sealed. 40, 56, and 128 specify the length, in bits, of the encryption key. If this minimum level of encryption is not met, the SSL connection between the BEA Tuxedo domain and WebLogic Server fails.
   Maximum Encryption Level	The maximum SSL encryption level used between the BEA Tuxedo domain and WebLogic Server. The possible values are 0, 40, 56, and 128. The default is the maximum level allowed by the Encryption Package kit license. Zero (0) indicates that the data is signed but not sealed. 40, 56, and 128 specify the length, in bits, of the encryption key. If this minimum level of encryption is not met, the SSL connection between the BEA Tuxedo domain and WebLogic Server fails.
   Enable Certificate Authentication	Checkbox that enables the use of certificate authentication. By default, certificate authentication is disabled.
   Enable Security Context	Check this check box to pass the security context of the WebLogic Server User passed to the BEA Tuxedo domain. By default, security context is disabled.

   
    

4. To save your changes, click the Apply button.

5. Click the Targets tab and select a server. Click Apply.

6. Reboot your WebLogic Server.

7. Run the tpusradd command to define the WebLogic Server User as an authorized User in the BEA Tuxedo domain.

8. Set the -E option of the ISL command to configure the IIOP Listener/Handler to detect and utilize the propagated security context from the WebLogic Server realm. The -E option of the ISL command requires you to specify a principal name. The principal name defines the principal used by the WLEC connection pool to log in to the BEA Tuxedo domain. The principal name should match the name defined in the User Name attribute when creating a WLEC connection pool.

Using certificate authentication between the WebLogic Server environment and the BEA Tuxedo CORBA environment implies performing a new SSL handshake when establishing a connection from the WebLogic Server environment to a CORBA object. To support multiple client requests over the same SSL network connection, you must set up certificate authentication so that it operates as follows:

1. Obtain a digital certificate for the principal and put the private key in the TUXDIR/udataobj/security/keys directory of BEA Tuxedo.

2. Use the tpusradd command to define the principal as a BEA Tuxedo user.

3. Define the IIOP Listener/Handler in the UBBCONFIG file with the -E option to indicate the principal is to be used for authentication.

4. Define the principal name in the User Name attribute when creating a WLEC Connection pool in the Administration Console of WebLogic Server.

5. Obtain a digital certificate for the IIOP Listener/Handler.

6. Specify the digital certificate in the SEC_PRINCIPAL_NAME option of the ISL command and use the -S option to indicate that a secure port should be used for communication between the BEA Tuxedo domain and the WebLogic Server security realm.

For more information about configuring security in BEA Tuxedo CORBA applications, see Using Security in CORBA Applications.

 

---

Accessing BEA Tuxedo CORBA Objects

This section describes accessing a BEA Tuxedo CORBA object from a WebLogic Server client.

Step 1. Create Client Stubs

Client stubs provide the programming interface for operations of a BEA Tuxedo CORBA object. To create client stubs, compile the Object Management Group (OMG) Interface Definition Language (IDL) file for the BEA Tuxedo CORBA object you want to access from the WebLogic Server client. To create client stubs for a BEA Tuxedo CORBA object, use the idl compiler that is included in the BEA Tuxedo software.

Make sure the WebLogic Server CLASSPATH environment variable includes the directory that contains the client stubs for the BEA Tuxedo CORBA object.

Step 2. Import Java Packages

Import the following Java packages into your WebLogic Server client:

• org.omg.CORBA.*

• com.beasys.Tobj.*

• com.beasys.*

Step 3. Connect the WebLogic Server Client to a BEA Tuxedo Domain

Each WLEC connection pool has a Tobj_Bootstrap object that lets you access the associated BEA Tuxedo domain. The WebLogic Enterprise Connectivity component provides an object called BootstrapFactory which provides access to the Tobj_Bootstrap object for a particular BEA Tuxedo domain. Include the following code in your WebLogic Server client to connect to a BEA Tuxedo domain:

Tobj_Bootstrap myBootstrap = Tobj_BootstrapFactory.getClientContext("myPool");

where

• The getClientContext() method returns the Tobj_Bootstrap object that is associated with myPool. If getClientContext() cannot find a WLEC connection pool with this name, it returns null.

• myPool is the name of a WLEC connection pool for the desired BEA Tuxedo domain. This WLEC connection pool needs to be defined in the Administration Console.

Step 4. Get an Object Reference for the BEA Tuxedo CORBA Object

Use the FactoryFinder object in your WebLogic Server client to get a reference to the BEA Tuxedo CORBA object.

1. Get the FactoryFinder object as follows:

   org.omg.CORBA.Object myFFObject = 
       myBootstrap.resolve_initial_references("FactoryFinder");
   FactoryFinder myFactFinder =
       FactoryFinderHelper.narrow(myFFObject);

   where

   • myBootstrap is the Tobj_Bootstrap object for the desired BEA Tuxedo domain.

   • The resolve_initial_references() method returns the object reference for the FactoryFinder object.

   • The FactoryFinderHelper interface provides auxiliary functionality for the FactoryFinder interface, notably the narrow() method.

   • The narrow() method casts the object reference to point to a FactoryFinder object.

2. Get the factory for the desired BEA Tuxedo CORBA object as follows:

   org.omg.CORBA.Object myFactoryRef = 
       myFactFinder.find_one_factory_by_id(myFactoryHelper.id());
   myFactory = 
       myFactoryHelper.narrow(myFactoryRef);

   where

   • myFactFinder is the FactoryFinder object.

   • The find_one_factory_by_id() method finds and returns a factory object reference based on an ID number.

   • The myFactoryHelper interface provides auxiliary functionality for the myFactory interface, notably the narrow() method.

   • The narrow() method casts the object reference to point to the object factory.

3. Get the BEA Tuxedo CORBA object using the object's find() method. For example, if you are accessing an object named Simple, use the following code:

   Simple mySimple = mySimpleFactory.find_simple();

   where the factory provides the find_simple() method for finding the Simple object.

For information about the FactoryFinder object, see the CORBA C++ Programming Reference in the BEA Tuxedo documentation.

Step 5. Start a Transaction (Optional)

You can access BEA Tuxedo CORBA objects within the scope of a transaction. The following sample code uses the TransactionCurrent object to access a BEA Tuxedo CORBA object within a scope of a transaction. You can also use the UserTransaction object when accessing a BEA Tuxedo CORBA object.

To start a transaction, include the following code in your WebLogic Server client:

1. Get the TransactionCurrent object as follows:

   org.omg.CORBA.Object myTCObject = 
     myBootstrap.resolve_initial_references("TransactionCurrent");
   CosTransactions.Current myTransaction = 
       CosTransactions.CurrentHelper.narrow(myTCObject);

   where

   • myBootstrap is the Bootstrap object for the BEA Tuxedo domain associated with the WLEC connection pool.

   • The resolve_initial_references() method returns the object reference for the TransactionCurrent object.

   • The CosTransactions.Current interface defines the interface for the TransactionCurrent object. It lets you explicitly manage the associations between threads and transactions.

   • The CurrentHelper interface provides auxiliary functionality for the Current interface, notably the narrow() method.

   • The narrow() method casts the object reference to point to a CosTransactions object.

2. Begin a transaction as follows:

   myTransaction.begin();

   where the begin() method creates a transaction context and associates it with myTCObject in step 1. Because myTCObject is associated with myBootstrap and myBootstrap is associated with a specific WLEC connection pool, myTransaction is associated with a specific WLEC connection pool.

Step 6. Access the BEA Tuxedo CORBA Object and Its Operations

Call methods on the BEA Tuxedo CORBA object in the BEA Tuxedo domain associated with the WLEC connection pool.

If you are accessing objects within a transaction context, you can use the following TransactionCurrent methods to manipulate and query the transaction context:

• suspend()

• resume()

• rollback_only()

• get_status()

• get_transaction_name()

• set_timeout()

• get_control()

Step 7. End the Transaction (Optional)

If you accessed the BEA Tuxedo CORBA object within a transaction context, use one of the following TransactionCurrent methods to end the transaction:

• commit()

• rollback()

 

---

More Information About Transactions

This section includes additional information about transactions in the BEA Tuxedo environment.

Multithreading

The BEA Tuxedo CORBA Transaction service enables multiple threads of a single application process to start separate transactions simultaneously. For example, if two threads simultaneously call CosTransactions.Current.begin() or UserTransaction.begin() both threads have separate transaction contexts that correspond to separate transactions.

The CORBA Transaction Service does not let multiple threads of a single application work with the same transaction at the same time. If you use CosTransactions, you can suspend and resume a transaction in order to use the transaction in multiple threads:

1. In the first thread, call Current.suspend() to suspend the transaction and to obtain a Control object.

2. In the second thread, call Current.resume() for the Control object in order to resume the transaction.

If a thread tries to resume a transaction that has not been suspended, the BEA Tuxedo system throws an INVALID_CONTROL exception.

The UserTransaction interface does not support the suspend() and resume() methods. Therefore, you cannot use a transaction in multiple threads when you use UserTransaction.

Multiple Active WLEC Connection Pools

The WebLogic Enterprise Connectivity component supports multiple simultaneously active WLEC connection pools in a single WebLogic Server client. When you call CosTransactions.Current.begin() or UserTransaction.begin() to create a transaction context, the BEA Tuxedo system associates the transaction with a WLEC connection pool. All calls made inside the scope of the transaction must be for objects that reside in the domain associated with the transaction's WLEC connection pool.

A transaction cannot span multiple BEA Tuxedo domains. If you try to make a call for an object in a different domain, the BEA Tuxedo system throws an INVALID_TRANSACTION exception.

Relationship Between Active Transactions and Connections

When a WebLogic Server client starts or resumes a transaction, the WLEC connection pool infrastructure reserves a connection for requests that are sent in the context of the transaction. The WebLogic Enterprise Connectivity component does not use this connection to send requests that are not in the transaction context. The WebLogic Enterprise Connectivity component reserves the connection until the transaction is committed, rolled back, or suspended.

Note: The suspend() and resume() are available only for CosTransactions.

The number of concurrently active transactions is bound by the number of available connections in the pool. If a connection is not available when a thread begins or resumes a transaction, the WebLogic Enterprise Connectivity component throws a NO_RESOURCES exception.

Transaction Management

Each thread has its own transaction context. When a thread starts or resumes a transaction, the transaction is active until it is committed, rolled back, or suspended. There is no guarantee that subsequent invocations to a WebLogic Server client get executed in the same thread. Therefore, it is important for a thread to commit, roll back, or suspend a transaction before ending a WebLogic Server client invocation.

Note: The suspend() and resume() are available only for CosTransactions.

If necessary, you can use a transaction in multiple WebLogic Server client invocations as follows:

1. At the end of each invocation, suspend the transaction.

2. In the next invocation, resume the transaction.

Be careful when using this solution, because a transaction can time out before you make the next WebLogic Server client invocation.