Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

Implementing Applications That Use WebLogic Enterprise Connectivity

  Prerequisites
  Implementation Overview
  Configuring an IIOP Connection Pool
    Configuring Security Context Propagation
    Configuring an IIOP Connection Pool for SSL
    Monitoring an IIOP Connection Pool
    Reinitializing an IIOP Connection Pool
  Accessing a CORBA Object
    Step 1. Create Client Stubs
    Step 2. Import Java Packages
    Step 3. Connect the Application to a WLE Domain
    Step 4. Get an Object Reference
    Step 5. Start a Transaction (optional)
    Step 6. Access Objects and Operations
    Step 7. End the Transaction (optional)
  Accessing an EJB or an RMI Object
    Step 1. Create Client Stubs
    Step 2. Import Java Packages
    Step 3. Connect the Application to a WLE Domain
    Step 4. Get an Object Reference
    Step 5. Access Objects and Operations
    For More Information About EJBs and RMI Objects
  Modifying a WebLogic Enterprise Application
  Working with Transactions
    Multithreading
    Multiple Active IIOP Connection Pools
    Relationship Between Active Transactions and Connections
    Transaction Management
  Security

  Related Documents
    Using WebLogic Enterprise Connectivity

Prerequisites

Before you implement applications that use WebLogic Enterprise Connectivity (WLEC), you need to:

- Configure and run BEA WebLogic ServerTM (WLS):

  - Setting WebLogic Properties
  - WebLogic Server Documentation Center

- Configure and run a BEA WebLogic EnterpriseTM (WLE) system:

  - What Is the WebLogic Enterprise System?
  - WLE documentation on the Web

- Be familiar with the WLEC architecture as described in System Architecture.

- Run the WebLogic Enterprise Connectivity examples.

Implementation Overview

To implement an application that uses WLEC, do one of the following:

- Create a WLS application

  Create a WLS application (servlet, EJB, JSP, or RMI object) and include code for accessing existing WLE objects and operations:

  - See the WebLogic Developer Guides. These guides provide information about creating servlets, EJBs, JSPs, and RMI objects for WLS.
  - Configure an IIOP connection pool.
  - Access a CORBA object or access an EJB or RMI object.

- Modify an existing WLS application

  Add code for accessing existing WLE objects and operations to an already-existing WLS client (servlet, EJB, JSP, or RMI object):

  - Configure an IIOP connection pool.
  - Access a CORBA object or access an EJB or RMI object.

- Modify an existing WLE client application

  Modify a WLE client application into a WLS application (servlet, EJB, JSP, or RMI object) and add code for accessing WLE objects and operations:

  - See the WebLogic Developer Guides. These guides provide information about creating servlets, EJBs, JSPs, and RMI objects for WLS.
  - Configure an IIOP connection pool.
  - Access a CORBA object or access an EJB or RMI object.
  - Modify a WebLogic Enterprise application.

Configuring an IIOP Connection Pool

Configure an IIOP connection pool for each WLE domain that you want to access from a WLS application. To do this, modify the weblogic.properties file as described in Setting Up WebLogic Enterprise Connectivity.

The rest of this section describes optional procedures for configuring and monitoring an IIOP connection pool:

  Configuring Security Context Propagation
  Configuring an IIOP Connection Pool for SSL
  Monitoring an IIOP Connection Pool
  Reinitializing an IIOP Connection Pool

Configuring Security Context Propagation

To configure an IIOP connection pool to use security context propagation:

1. To configure a trusted IIOP connection pool, which is required for security context propagation, add the -E option to the ISL command. The parameter for the -E option must match the username that is specified for the connection pool in the weblogic.properties file. For details about the username parameter, see Setting Up WebLogic Enterprise Connectivity.

   For information about the ISL command, see the WebLogic Enterprise Reference:

   1. Go to Reference Topics on the Web.
   2. Click WebLogic Enterprise Reference.

2. To enable security context propagation, set the securitycontext parameter for the IIOP connection pool to YES in the weblogic.properties file. For example:

       securitycontext=YES,\

   For details about this parameter, see Setting Up WebLogic Enterprise Connectivity.

3. Register the username in WLS, WLE, and WLEC:

   - To register a username in WLS, see Setting WebLogic Properties.

   - For information about registering a username in WLE, see Defining Authorized Users in the WLE documentation:

     1. Go to Security Topics on the Web.
     2. Click Defining Security for a WLE Application.
     3. Click Defining Authorized Users.

   - To register a username for WLEC, set the username parameter for the IIOP connection pool in the weblogic.properties file. For example:

         username=myself,\

     For details about this parameter, see Setting Up WebLogic Enterprise Connectivity.

If the username that WLS sends does not match a WLE username, WLE returns a CORBA.NO_PERMISSION exception to WLS. If WLS does not send a username, WLE uses the username that was used to establish the trusted connection pool.

Configuring an IIOP Connection Pool for SSL

To configure an IIOP connection pool to use SSL:

1. Install the WLE 5.1 CORBA Java client software.

   This step is necessary because you cannot install the WLE Encryption Package kit unless the WLE core bits are installed. Installing the WLE client installs the WLE core bits.

   For the WLE CORBA Java client installation procedure, see WebLogic Enterprise Installation on Windows Systems in the WLE documentation:

   1. Go to Installation Topics on the Web.
   2. Click WebLogic Enterprise Installation on Windows Systems.

2. Set the TUXDIR environment variable.

   The TUXDIR environment variable is necessary for the WLE Java client. Set TUXDIR to the directory in which you installed the WLE Java client software.

3. Install the WLE 5.1 56-bit or 128-bit Encryption Package kit.

   The Encryption Package kit provides the SSL functionality.

   For the Encryption Package installation procedure, see WLE Encryption Package Installation on Windows Systems in the WLE documentation:

   1. Go to Installation Topics on the Web.
   2. Click WLE Encryption Package Installation on Windows Systems.

4. Configure WLE for SSL.

   See Configuring the WLE Environment for the SSL Protocol in the WLE documentation:

   1. Go to Security Topics on the Web.
   2. Click Configuring the WLE Environment for the SSL Protocol.

5. Use the corbalocs protocol in the URLs for the appaddrlist and failoverlist parameters for the IIOP connection pool in the weblogic.properties file. For example:

       appaddrlist=corbalocs://555main.com:1024;corbalocs://main.com:1024,\
       failoverlist=corbalocs://555failover.com:1024,\

   For details about these parameters, see Setting Up WebLogic Enterprise Connectivity.

6. If you are using certificate-based authentication, set the certificatebasedauth, minencryptionlevel, and maxencryptionlevel parameters for the IIOP connection pool in the weblogic.properties file. For example:

       certificatebasedauth=YES,\
       minencryptionlevel=56,\
       maxencryptionlevel=128,\

   For details about these parameters, see Setting Up WebLogic Enterprise Connectivity.

If an IIOP connection pool is configured for SSL and a WLS application sends a request that does not contain the correct security information, WLEC returns an error.

Monitoring an IIOP Connection Pool

To monitor IIOP connection pools, use the WebLogic Console as described in Running the WebLogic Console.

Reinitializing an IIOP Connection Pool

You can use the Commands tab in the WebLogic Console to reinitialize WLEC IIOP connection pools without stopping WLS. See Running the WebLogic Console for information about reinitializing an IIOP connection pool.

Accessing a CORBA Object

This section describes the steps for accessing a WLE CORBA object from a WLS client.

  Step 1. Create Client Stubs
  Step 2. Import Java Packages
  Step 3. Connect the Application to a WLE Domain
  Step 4. Get an Object Reference
  Step 5. Start a Transaction (optional)
  Step 6. Access Objects and Operations
  Step 7. End the Transaction (optional)

Step 1. Create Client Stubs

Client stubs provide the programming interface for CORBA object operations. To create client stubs:

1. Compile the Object Management Group Interface Definition Language (OMG IDL) file. For a Java CORBA object, use the idltojava compiler that is included in the WLE software.

   See Using the idltojava Command in the WLE documentation:

   1. Go to idltojava Topics on the Web.
   2. Click Using the idltojava Command.

2. Make sure the CLASSPATH environment variable includes the directory that contains the client stubs.

Step 2. Import Java Packages

Import the following Java packages:

    import org.omg.CORBA.*;
    import com.beasys.Tobj.*;
    import com.beasys.*;

Step 3. Connect the Application to a WLE Domain

Each IIOP connection pool has a Tobj_Bootstrap object that lets you access the pool. WLEC provides an object called BootstrapFactory, which provides access to the Tobj_Bootstrap object. To connect the application to a WLE domain:

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

About this code:

- myPool is the name of an IIOP connection pool that is defined in the weblogic.properties file.

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

See the WebLogic Enterprise Connectivity API Reference for information about Tobj_Bootstrap.

Step 4. Get an Object Reference

Use the FactoryFinder to get a reference to a CORBA object:

1. Get the FactoryFinder object:

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

About this code:

- myBootstrap is the Tobj_Bootstrap object for an IIOP connection pool.

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

- FactoryFinderHelper provides auxiliary functionality for FactoryFinder, notably the narrow() method.

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

- Get the factory:

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

  About this code:

  - myFactFinder is the FactoryFinder object that was obtained in the previous step.

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

  - myFactoryHelper provides auxiliary functionality for myFactory, notably the narrow() method.

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

- Find the object:

  Call the object's "find" method. For example, if you are accessing an object named Simple, this line of code could be:

      Simple mySimple = mySimpleFactory.find_simple();

  About this code:

  - The factory provides the method (find_simple()) for finding the object.

  For information about the FactoryFinder interface, see FactoryFinder Interface in the WLE documentation:

  1. Go to CORBA Topics on the Web.
  2. Scroll down and click CORBA C++ Programming Reference.
  3. Scroll down and click FactoryFinder Interface.

  Step 5. Start a Transaction (optional)

  You can access WLE objects within transactions. This sample code uses TransactionCurrent. You can also use UserTransaction when accessing a CORBA object. To start a transaction:

  1. Get the TransactionCurrent object:

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

     About this code:

     - myBootstrap is the Bootstrap object for an IIOP connection pool.

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

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

     - CurrentHelper provides auxiliary functionality for Current, notably the narrow() method.

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

  2. Begin a transaction:

         myTransaction.begin();

     About this code:

     - The begin() method creates a transaction context and associates it with myTCObject. Because myTCObject is associated with myBootstrap and myBootstrap is associated with a specific connection pool, myTransaction is associated with a specific IIOP connection pool.

  See Transactions Topics in the WLE documentation on the Web.

  Step 6. Access Objects and Operations

  Call methods on objects that belong to the WLE domain associated with the IIOP connection pool.

  If you are accessing objects within a transaction context, you can also 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 objects within a transaction context, use one of the following TransactionCurrent methods to end the transaction:

  - commit()
  - rollback()

  Accessing an EJB or an RMI Object

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

    Step 1. Create Client Stubs
    Step 2. Import Java Packages
    Step 3. Connect the Application to a WLE Domain
    Step 4. Get an Object Reference
    Step 5. Access Objects and Operations
    For More Information About EJBs and RMI Objects

  Step 1. Create Client Stubs

  Client stubs provide the programming interface for EJB and RMI object operations. To create client stubs:

  1. Use the weblogic.rmic command to compile the Java .class files.

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

     1. Go to J2EE Topics on the Web.
     2. Scroll down and click Using RMI in a WebLogic Enterprise Environment.
     3. Scroll down and click Developing RMI Applications in WLE.
     4. Click Developing New RMI Classes for a WLE Application.
     5. Click Step 6. Run the WebLogic RMI compiler on the implementation class to generate stubs and skeletons.

  2. Make sure the CLASSPATH environment variable includes the directory that contains the client stubs.

  Step 2. Import Java Packages

  Import the following Java package:

      import javax.naming.*;

  You also need to import a package for the stubs and skeletons of the 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.

  Step 3. Connect the Application to a WLE Domain

  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 an IIOP connection pool. To connect the application 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();

  About this code:

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

  - PROVIDER_URL, INITIAL_CONTEXT_FACTORY, SECURITY_AUTHENTICATION, SECURITY_PRINCIPAL, and SECURITY_CREDENTIALS are environment properties.

    These properties are described in the Javadoc API reference for the Context interface:

    1. Go to J2EE Topics on the Web.
    2. Scroll down and click javax.naming (in the gold column).
    3. Click javax.naming again.
    4. Click Context.
    5. Scroll down to Field Detail.

    Some of these properties are also described in Using the WLE SPI Implementations for JNDI:

    1. Go to J2EE Programming Topics on the Web.
    2. Click Using the WLE SPI Implementations for JNDI.
    3. Click Step 1: Set Up JNDI Environment Properties for the Initial Context.

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

  - myPool is the name of an IIOP connection pool that is defined in the weblogic.properties file.

  - 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 getInitialContext.

  Step 4. Get an Object Reference

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

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

  About this code:

  - 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 context that was defined in the previous step.

  - 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 Objects and Operations

  Call methods on objects that belong to the WLE domain associated with the IIOP connection pool. If desired, you can access objects and operations within a transaction context. To access EJBs and RMI objects in a transaction context, you must use UserTransaction.

  For More Information About EJBs and RMI Objects

  See the following topics in the WLE documentation:

  - J2EE Topics (on the Web.

  - Transactions Topics (on the Web)

  - Using the WLE SPI Implementations for JNDI. To get to this document:

    1. Go to J2EE Topics on the Web.
    2. Click Using the WLE SPI Implementations for JNDI.
    3. Click Step 1: Set Up JNDI Environment Properties for the Initial Context.

  Modifying a WebLogic Enterprise Application

  To change a WLE application into a WLS application:

  1. If the application accesses a CORBA object:

     - Remove the call to ORB.init(). WLS initializes the ORB automatically at startup.

     - Replace the code that creates the Tobj_Bootstrap object with code that uses the BootstrapFactory to obtain the Tobj_Bootstrap object. WLS creates the Tobj_Bootstrap object at startup. See Step 3. Connect the Application to a WLE Domain.

  2. Remove code that accesses the WLE security API. WLS uses the security attributes in the weblogic.properties file when it creates IIOP connection pools.

  3. Remove code that accesses the InterfaceRepository object. WLEC does not support the InterfaceRepository.

  4. Configure an IIOP connection pool.

  5. Access a CORBA object or access an EJB or RMI object.

  Working with Transactions

  This section covers the following topics:

    Multithreading
    Multiple Active IIOP Connection Pools
    Relationship Between Active Transactions and Connections
    Transaction Management

  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 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 InvalidControl exception.

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

  Multiple Active IIOP Connection Pools

  WLEC supports multiple simultaneously active IIOP connection pools in a single WLS. When you call CosTransactions.Current.begin() or UserTransaction.begin() to create a transaction context, the WLE system associates the transaction with an IIOP 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 IIOP 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 WLEC client starts or resumes a transaction, the IIOP connection pool infrastructure reserves a connection for requests that are sent in the context of the transaction. WLEC does not use this connection to send requests that are not in the transaction context. WLEC reserves the connection until the transaction is committed, rolled back, or suspended.

  Note: 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, WLEC 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 WLS 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 WLS client invocation.

  Note: Suspend and resume are available only for CosTransactions.

  If necessary, you use a transaction in multiple WLS 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 WLS client invocation.

  Security

  WLS uses the security attributes in the weblogic.properties file when it creates connections in pools. Therefore, applications on WLS 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.

  Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher. Last updated 4/25/00