BEA Logo BEA WebLogic Server Release 5.0

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

Using WebLogic Enterprise Connectivity

I. Introduction
What is the WebLogic Enterprise system?
About CORBA, objects, factories, and ORBs
About domains, transactions, and transaction contexts
About environmental objects
About IIOP, ISLs, and ISHs
What is WebLogic Enterprise Connectivity?
About the system architecture
What are the clients and servers in the system?
What is connection pooling?
What kind of failure handling is provided?
What happens at server startup?

II. WebLogic Enterprise Connectivity API

III. Implementing with WebLogic Enterprise Connectivity
What you need to know
What you need to do
Adding WebLogic Enterprise access to an EJB or servlet
Step 1. Create client stubs
Step 2. Configure a connection pool
Step 3. Import Java packages
Step 4. Connect to a domain
Step 5. Use the FactoryFinder to get an object reference
Step 6. Start a transaction (optional)
Step 7. Access objects and operations
Step 8. End the transaction (optional)
Working with transactions
Multithreading
Multiple active connection pools
Relationship between active transactions and connections
Transaction management
Security
Modifying a WebLogic Enterprise application

Related documents
Setting up WebLogic Enterprise Connectivity
WebLogic Enterprise Connectivity examples
WebLogic Enterprise Connectivity API Reference

Top

I. Introducing WebLogic Enterprise Connectivity

This document describes how to use WebLogic Enterprise Connectivity to connect from a WebLogic Server to a WebLogic Enterprise system (formerly M3). This section covers the following topics:

What is the WebLogic Enterprise system?
What is WebLogic Enterprise Connectivity?

For more information about the WebLogic Server, see the WebLogic Developer Center.

Top

What is the WebLogic Enterprise system?

The WebLogic Enterprise system combines Common Object Request Broker Architecture (CORBA) with the BEA Engine. The WebLogic Enterprise system uses CORBA distributed object technology to provide a standard programming model. The BEA Engine provides online transaction processing (OLTP) technology as well as transaction management, security, message transport, administration and manageability, and XA-compliant database support. The combination of CORBA and the BEA Engine provides a high performance platform for enterprise distributed object applications using transactions. The WebLogic Enterprise system provides a robust solution for complex procedures such as state management, object activation and deactivation, and security.

For more information about the WebLogic Enterprise system, see the WebLogic Enterprise documentation. If you are new to the WebLogic Enterprise system, we recommend that you look at Getting Started.

The following diagram provides an overview of the WebLogic Enterprise system:

WebLogic Enterprise Architecture

The rest of this section introduces some of the WebLogic Enterprise system terminology:

About CORBA, objects, factories, and ORBs
About domains, transactions, and transaction contexts
About environmental objects
About IIOP, ISLs, and ISHs

About CORBA, objects, factories, and ORBs

Common Object Request Broker Architecture (CORBA) is a language-independent specification that promotes an object-oriented approach to building and integrating distributed software applications. You can implement your business logic as CORBA objects in different languages. WebLogic Enterprise supports C++ and Java language bindings, as well as ActiveX clients. For example, a banking application could have objects for customer accounts. These customer account objects could have operations for depositing, withdrawing, and viewing the account balances.

A CORBA factory provides an operation to create an object reference to another CORBA object. A server application uses CORBA factories to let client applications access CORBA objects that are implemented in the server application. When a client application needs to get a reference to a CORBA object that is managed by a server application, it typically gets that object reference from a CORBA factory.

An Object Request Broker (ORB) is a communications bus that lets client applications communicate with distributed objects that are managed by server applications. In a CORBA environment, applications do not need to include network and operating system information to communicate. Instead, heterogeneous client and server applications communicate with the ORB. The ORB delivers client requests to the appropriate server applications and returns the server responses to the requesting client application.

About domains, transactions, and transaction contexts

A WebLogic Enterprise domain is a group of objects, services, machines, and resources that you administer as a unit. You can set up domains based on characteristics such as application functions, security needs, or geographical locations. For example, a domain might consist of the objects, services, machines, and resources for a bank's customer accounts. The bank might have a separate domain for its employee and payroll resources.

A transaction is a set of operations based on business rules. The operations act as one logical unit, even if they are distributed geographically. By acting as one unit, either all the transaction's operations complete successfully (if the transaction completes successfully) or all the operations roll back (if the transaction fails). For example, a transaction might withdraw money from one customer's account and deposit it into another customer's account. This transaction would consist of two operations. Both operations must succeed in order for the transactions to succeed.

A transaction context defines the scope of a transaction, and is shared by the objects that are participating in the transaction. A transaction context can consist of various types of data, such as local variables, locks, cursor positions, and file control blocks.

About environmental objects

The WebLogic Enterprise system provides environmental objects that let client applications use the WebLogic Enterprise system's services. When used with WebLogic Enterprise Connectivity, the WebLogic Enterprise system provides the following environmental objects.

Tobj_Bootstrap
A Tobj_Bootstrap object establishes communication between a client application and a WebLogic Enterprise domain. It also obtains object references for the other environmental objects in the WebLogic Enterprise domain.

FactoryFinder
The FactoryFinder lets a client application find CORBA factories. A CORBA factory can create object references for CORBA objects. The factories available to client applications are those that register with the FactoryFinder at startup.

TransactionCurrent
TransactionCurrent lets a client application manage a WebLogic Enterprise transaction. TransactionCurrent is the WebLogic Enterprise implementation of the CORBA Object Transaction Service (OTS), which supports multiple transaction models. Some of the operations that TransactionCurrent provides are begin(), commit(), rollback(), suspend(), resume(), and get_status().

UserTransaction
UserTransaction lets a client application participate in a transaction. This environmental object is an implementation of the Sun Microsystems, Inc. Java Transaction Application Programming Interface (JTA).

About IIOP, ISLs, and ISHs

Internet Inter-ORB Protocol (IIOP) is the standard protocol defined by the CORBA specification for interoperation between ORBs. A WebLogic Enterprise IIOP listener (ISL) manages incoming communications for remote CORBA clients. Each ISL has one or more IIOP handlers (ISH) associated with it. An ISL assigns client applications to ISHs and balances the incoming client loads across the ISHs. An ISH is a communications link between a client application and a WebLogic Enterprise object. Each WebLogic Enterprise domain that supports remote clients has at least one ISL.

Top

What is WebLogic Enterprise Connectivity?

WebLogic Enterprise Connectivity lets you call WebLogic Enterprise CORBA objects from servlets and EJBs that run on a WebLogic Server. WebLogic Enterprise Connectivity uses IIOP connection pooling to provide a scalable and robust solution.

The key features of WebLogic Enterprise Connectivity are:

  • Pooled IIOP connections to the WebLogic Enterprise system

  • Multiple active WebLogic Enterprise client transactions from a single WebLogic Server process

  • Configuration of connection pools via the weblogic.properties file

  • Monitoring of connection pools via the WebLogic Console

The rest of this section covers the following topics:

About the system architecture
What are the clients and servers in the system?
What is connection pooling?
What kind of failure handling is provided?
What happens at server startup?

About the system architecture

The following diagram provides an overview of the system architecture:

WebLogic
Enterprise Connectivity Architecture

The diagram shows three ways to access a WebLogic Enterprise object:

  1. HTML client servlet connection pool CORBA object

  2. HTML client servlet EJB connection pool CORBA object

  3. Java client EJB connection pool CORBA object

For each WebLogic Enterprise domain, the WebLogic Server creates a connection pool if the connection pool is configured in the weblogic.properties file. Servlets and EJBs use the connection pool to access CORBA objects in the domain, which can be on a remote machine and/or behind a firewall.

What are the clients and servers in the system?

HTML clients and Java clients are served by servlets and EJBs on the WebLogic Server. The servlets and EJBs act as clients to WebLogic Enterprise domains, which provide the requested CORBA objects and send results back to the servlets and EJBs. The servlets and EJBs can then compile the results, do some other work, and send the results to the HTML clients and Java clients.

What is connection pooling?

WebLogic Enterprise Connectivity uses connection pooling to let WebLogic Server servlets and EJBs connect to WebLogic Enterprise domains. A connection pool is a set of IIOP connections to a WebLogic Enterprise domain. The WebLogic Server creates the connection pools at startup and hands out connections to servlets and EJBs as needed. Connection pools are efficient because they let a limited number of connections serve many users. Since the overhead for creating connections is performed at startup, WebLogic Enterprise operations can occur quickly.

WebLogic Enterprise Connectivity connection pooling has the following features:

  • Uses IIOP.

  • Supports one connection pool for each WebLogic Enterprise domain.

  • Allows a WebLogic Server to have multiple simultaneous active WebLogic Enterprise transaction contexts. However, a thread in the WebLogic Server can have only one active WebLogic Enterprise client transaction context at a time. In particular, WebLogic Enterprise Connectivity does not support nested transactions.

What kind of failure handling is provided?

WebLogic Enterprise Connectivity provides failure handling by using two lists of ISL addresses for each connection pool: a primary and a failover. WebLogic Enterprise Connectivity provides failure handling in the following cases:

  • When the WebLogic Server is booted.

    If none of the ISLs defined in the primary list are accessible at server startup, WebLogic Enterprise Connectivity uses ISL addresses from the failover list.

  • When a connection pool loses an active connection.

    When the pool loses a connection, WebLogic Server tries to reconnect using other addresses from the primary list. If all addresses in the primary list fail, it tries to reconnect using addresses from the failover list. Lost connections are restarted only when they are needed. If the current load on the connection pool does not require a lost connection to be reopened, it stays disconnected and other active connections are used instead.

What happens at server startup?

At startup, the WebLogic Server:

  • Initializes the WebLogic Enterprise system's ORB.

  • Creates IIOP connection pools. For each configured connection pool, the WebLogic Server creates a Tobj_Bootstrap object.

Top

II. WebLogic Enterprise Connectivity API

WebLogic Enterprise Connectivity API Reference

Top

III. Implementing with WebLogic Enterprise Connectivity

This section covers the following topics:

What you need to know
What you need to do
Adding WebLogic Enterprise access to an EJB or servlet
Working with transactions
Security
Modifying a WebLogic Enterprise application

Top

What you need to know

Before you implement applications that use WebLogic Enterprise Connectivity, you should:

  1. Know how to configure and run a WebLogic Server. See the following:

  2. Know how to configure and run a WebLogic Enterprise system. See the following:

  3. Be familiar with the WebLogic Enterprise Connectivity architecture. See About the system architecture.

  4. Run the WebLogic Enterprise Connectivity examples.

Top

What you need to do

To use WebLogic Enterprise Connectivity, you do one of the following:

For details about the WebLogic Enterprise Connectivity API, see the WebLogic Enterprise Connectivity API Reference Manual.

Top

Adding WebLogic Enterprise access to an EJB or servlet

This section describes the steps for accessing WebLogic Enterprise from an EJB or servlet. The steps are:

Step 1. Create client stubs
Step 2. Configure a connection pool
Step 3. Import Java packages
Step 4. Connect to a domain
Step 5. Use the FactoryFinder to get an object reference
Step 6. Start a transaction (optional)
Step 7. Access objects and operations
Step 8. 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 OMG IDL (Object Management Group Interface Definition Language) file. For a Java CORBA object, use the idltojava or m3idltojava command. For more information, see Creating CORBA Client Applications.

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

Step 2. Configure a connection pool

Configure an IIOP connection pool for each WebLogic Enterprise domain that you want to access. To configure an IIOP connection pool, modify the weblogic.properties file, which is described in Setting up WebLogic Enterprise Connectivity and Setting WebLogic properties.

To monitor the IIOP connection pools, use the WebLogic Console. For information about the WebLogic Console, see Running the WebLogic Console.

Step 3. Import Java packages

Import the following CORBA and BEA Systems Java packages:

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

Step 4. Connect to a domain

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

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

myPool is the name of a 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.

Step 5. Use the FactoryFinder to 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);

    myBootstrap is the Tobj_Bootstrap object for a 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.

  2. Get the factory:
      org.omg.CORBA.Object myFactoryRef = myFactFinder.
          find_one_factory_by_id(myFactoryHelper.id());
      myFactory = myFactoryHelper.narrow(myFactoryRef);

    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.

  3. 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();

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

Step 6. Start a transaction (optional)

You can access WebLogic Enterprise objects within transactions. 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);
    myBootstrap is the Bootstrap object for a 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. Create a transaction:
      myTransaction.begin();

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

Step 7. Access objects and operations

Call methods on objects that belong to the WebLogic Enterprise domain that is associated with the connection pool.

If you are accessing objects within a transaction, you can also use the following TransactionCurrent methods to manipulate the transaction and to get information about the transaction:

  • suspend()
  • resume()
  • rollback_only()
  • get_status()
  • get_transaction_name()
  • set_timeout()
  • get_control()

For more information about these methods, see Using Transactions.

Step 8. End the transaction (optional)

If you accessed objects within a transaction, use one of the following TransactionCurrent methods to end the transaction:

  • commit()
  • rollback()

For more information about these methods, see Using Transactions.

Top

Working with transactions

This section covers the following topics:

Multithreading
Multiple active connection pools
Relationship between active transactions and connections
Transaction management

Multithreading

The Transaction Service in the WebLogic Enterprise system lets multiple threads of a single application process start separate transactions simultaneously. For example, if two threads simultaneously call CosTransactions.Current.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. To use a 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.

If a thread tries to resume a transaction that has not been suspended, the WebLogic Enterprise system throws an InvalidControl exception.

Multiple active connection pools

WebLogic Enterprise Connectivity supports multiple simultaneously active connection pools in a single WebLogic Server. When you call CosTransactions.Current.begin() to create a transaction context, the WebLogic Enterprise system associates the transaction with a connection pool based on the Tobj_Bootstrap object from which Current was obtained. All calls made inside the scope of the transaction must be for objects that reside in the domain associated with the transaction's connection pool.

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

Relationship between active transactions and connections

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

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, WebLogic Enterprise Connectivity 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 servlet or EJB get executed in the same thread. Therefore, it is important for a thread to commit, roll back, or suspend a transaction before ending a servlet or EJB invocation.

If necessary, you can use the following solution to use a transaction in multiple servlet or EJB invocations:

  1. At the end of each invocation, suspend the transaction and store the Control object.

  2. In the next invocation, resume the transaction.

Be careful when using this solution, because a transaction can time out if you do not make the next servlet or EJB invocation.

Top

Security

The WebLogic Server uses the security attributes in the weblogic.properties file when it creates connections in pools. Therefore, applications on WebLogic Servers do not have access to the WebLogic Enterprise security API. If you try to access the security API by calling resolve_initial_reference("SecurityCurrent") on the Tobj_Bootstrap object, the WebLogic Enterprise system throws an InvalidName exception.

Top

Modifying a WebLogic Enterprise application

If you are modifying a WebLogic Enterprise application:

  1. Remove the call to ORB.init(). The WebLogic Server initializes the ORB at startup.

  2. Replace the code that creates the Tobj_Bootstrap object with code that uses the BootstrapFactory to obtain the Tobj_Bootstrap object. The WebLogic Server creates the Tobj_Bootstrap object at startup. See Step 4. Connect to a domain.

  3. Remove code that accesses the WebLogic Enterprise security API. The WebLogic Server uses the security attributes in the weblogic.properties file when it creates connection pools.

  4. Remove code that accesses the InterfaceRepository object. WebLogic Enterprise Connectivity does not support the InterfaceRepository.

Top

 

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 12/21/1999