Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
Using WebLogic Enterprise Connectivity:   Previous Topic   |   Next Topic   |   Contents

Writing WebLogic Server Clients That Invoke WLE Objects

This section contains the following topics:

• Before You Begin

• Implementation Overview

• Configuring a WLEC Connection Pool

• Accessing WLE CORBA Objects

• Accessing a WLE EJB or RMI Object

• Working with Transactions

• Security

Before You Begin

Before you implement WebLogic Server clients that invoke WebLogic Enterprise (WLE) objects, you need to:

• Configure and run WebLogic Server

• Configure and run a WLE server application

• Be familiar with the WebLogic Enterprise Connectivity (WLEC) 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.

Implementation Overview

To implement a WebLogic Server client that invokes a WLE object, write a WebLogic Server client (servlet, EJB, JSP, or RMI object) and include code for accessing existing WLE objects and operations. For more information, see the following:

• The WebLogic Programming Guides. These guides provide information about creating servlets, EJBs, JSPs, and RMI objects in the WebLogic Server environment.

• Configuring Security Context Propagation for information about configuring a WLEC connection pool.

• Accessing WLE CORBA Objects or Accessing a WLE EJB or RMI Object for information about the code you need to include in the WebLogic Server client in order to access the WLE object.

Configuring a WLEC Connection Pool

Configure a WLEC connection pool for each WLE domain that contains a WLE object you want to access from a WebLogic Server client. Because the security context established for the WebLogic Server client is propagated to the WLE domain through the WLEC connection pool, the WLEC connection pools are the basis for the security context propagation feature. For information about configuring WLEC connection pools, see Configuring Security Context Propagation.

Accessing WLE CORBA Objects

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

Step 1. Create Client Stubs

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

For more information, see Using the idltojava Command in the WLE documentation.

Make sure the WebLogic Server CLASSPATH environment variable includes the directory that contains the client stubs for the WLE 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 WLE Domain

Each WLEC connection pool has a Tobj_Bootstrap object that lets you access the associated WLE domain. The WLEC component provides an object called BootstrapFactory which provides access to the Tobj_Bootstrap object for a particular WLE domain. Include the following code in your WebLogic Server client to connect to a WLE 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 WLE domain. This WLEC connection pool needs to be defined in the Administration Console.

Step 4. Get an Object Reference for the WLE CORBA Object

Use the FactoryFinder object in your WebLogic Server client to get a reference to the WLE 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 WLE 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 WLE 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 WLE 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 WLE documentation.

Step 5. Start a Transaction (optional)

You can access WLE CORBA objects within the scope of a transaction. The following sample code uses the TransactionCurrent object to access a WLE CORBA object within a scope of a transaction. You can also use the UserTransaction object when accessing a WLE 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 WLE 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 WLE CORBA Object and Its Operations

Call methods on the WLE CORBA object in the WLE 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 WLE CORBA object within a transaction context, use one of the following TransactionCurrent methods to end the transaction:

• commit()

• rollback()

Accessing a WLE EJB or RMI Object

This section describes the steps for accessing a WLE EJB or RMI object from a WebLogic Server client.

Step 1. Create Client Stubs

Client stubs provide the programming interface for WLE EJB and RMI object operations. To create client stubs, use the weblogic.rmic command to compile the Java .class files for the WLE EJB or RMI object.

For more information, see the RMI compiler information in the WLE documentation:

Make sure the WebLogic Server CLASSPATH environment variable includes the directory that contains the client stubs for the WLE EJB or RMI object.

Step 2. Import Java Packages

Import the javax.naming.* Java package into your WebLogic Server client.

You also need to import the package for the stubs and skeletons of the WLE EJB or RMI object you access. For an example of how to import a package for stubs and skeletons, see the WebLogic Enterprise Connectivity JSP Stateless Session Bean Example in the /samples/examples/wlec directory in the WebLogic Server installation.

Step 3. Connect the WebLogic Server Client to a WLE Domain

To access a WLE domain from a WebLogic Server client, use a hash table to set environment properties for the JNDI InitialContext class. The InitialContext class implements the Context interface and provides the starting context for naming operations. The environment properties determine how the InitialContext attaches to a WLEC connection pool. Include the following code in your WebLogic Server client to connect to a WLE domain:

public Context getInitialContext() throws Exception {
    Hashtable myEnvironment = new Hashtable();
    myEnvironment.put(Context.PROVIDER_URL, "wlepool://myPool");
    myEnvironment.put(Context.INITIAL_CONTEXT_FACTORY, 
        "com.beasys.jndi.WLEInitialContextFactory");
    myEnvironment.put(Context.SECURITY_AUTHENTICATION, 
        "securityStyle");
    myEnvironment.put(Context.SECURITY_PRINCIPAL, "username");
    myEnvironment.put(Context.SECURITY_CREDENTIALS, "password");
    return new InitialContext(myEnvironment);
}
.
.
.
myContext = getInitialContext();

where

• myEnvironment is the name of the JNDI hash table that sets the environment properties.

• PROVIDER_URL, INITIAL_CONTEXT_FACTORY, SECURITY_AUTHENTICATION, SECURITY_PRINCIPAL, and SECURITY_CREDENTIALS are the JNDI environment properties. For more information, see the Javadoc for the weblogic.jndi package.

• wlepool is the constant that specifies access to a WLE domain.

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

• com.beasys.jndi.WLEInitialContextFactory is the class that provides the implementation for delegating JNDI methods to the WLE service provider.

• myContext is the result of the call to the getInitialContext() method.

Step 4. Get an Object Reference for the WLE EJB or RMI Object

To get a reference to a WLE EJB or RMI object, include perform a JNDI lookup and cast the object:

myObjectRef = (myObjectType)myContext.lookup("objectName");

where

• myObjectRef is a reference to an object of type myObjectType.

• myObjectType is the object type to which the object is being cast.

• myContext is the JNDI context that was defined in Step 4. Get an Object Reference for the WLE EJB or RMI Object.

• For an EJB, objectName is defined in the deployment descriptor. For an RMI object, an instance of the object was created and bound to objectName.

Step 5. Access the WLE EJB or RMI Object and Its Operations

Call methods the EJBs or RMI objects in the WLE domain associated with the WLEC connection pool. If desired, you can access objects and operations within the scope of a transaction. To access EJBs and RMI objects in a transaction context, you must use the UserTransaction interface.

Working with Transactions

This section includes additional information about transactions in the WLE system.

Multithreading

The WLE 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 WLE 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 WLE 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 WLEC 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 WLE 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 WLE domains. If you try to make a call for an object in a different domain, the WLE 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 WLEC component does not use this connection to send requests that are not in the transaction context. The WLEC 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 WLEC 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.

Security

The security context established in WebLogic Server is propagated to the WLE domain. Therefore, WebLogic Server clients do not have access to the WLE security API. If you try to access the security API by calling resolve_initial_reference("SecurityCurrent") on the Tobj_Bootstrap object, the WLE system throws an InvalidName exception.

For more information about propagating a WebLogic Server security context to the WLE domain, see Using WebLogic Server as a Client to WebLogic Enterprise and Configuring Security Context Propagation.