Using WebLogic Enterprise Connectivity
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:
For more information about the WebLogic Server, see the WebLogic Developer Center.
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.
The following diagram provides an overview of the WebLogic Enterprise system:
The rest of this section introduces some of the WebLogic Enterprise system terminology:
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.
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.
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:
The rest of this section covers the following topics:
About the system architecture
The following diagram provides an overview of the system architecture:
The diagram shows three ways to access a WebLogic Enterprise 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:
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:
What happens at server startup?
At startup, the WebLogic Server:
II. WebLogic Enterprise Connectivity API
III. Implementing with WebLogic Enterprise Connectivity
This section covers the following topics:
What you need to know
Before you implement applications that use WebLogic Enterprise Connectivity, you should:
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.
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
Client stubs provide the programming interface for CORBA object operations. To create 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:
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.
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.
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:
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:
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:
For more information about these methods, see Using Transactions.
Working with transactions
This section covers the following topics:
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:
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.
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:
Be careful when using this solution, because a transaction can time out if you do not make the next servlet or EJB invocation.
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.
Modifying a WebLogic Enterprise application
If you are modifying a WebLogic Enterprise application:
Copyright © 2000 BEA Systems, Inc. All rights reserved.