Introduction to Oracle Jolt for Oracle WebLogic Server

With Oracle Jolt for Oracle WebLogic Server, you can enable Oracle Tuxedo services for the Web, using the Oracle WebLogic Server as the front-end HTTP and application server.

Oracle Jolt is a Java-based client API that manages requests to Oracle Tuxedo services via a Jolt Service Listener (JSL) running on the Tuxedo server. The Jolt API is embedded within the WebLogic API, and is accessible from a servlet or any other Oracle WebLogic application.

Because Oracle Jolt for Oracle WebLogic Server is an extension to the Jolt Java class library, the Jolt Java client class library can be used in HTTP servlets running in the WebLogic Server. Oracle Jolt for Oracle WebLogic Server also uses Java HTTP servlets to provide an interface between HTML browser clients and Oracle Tuxedo services.

Hereafter, Oracle Tuxedo is referred to as Tuxedo, Oracle Jolt is referred to as Jolt, and Oracle WebLogic is referred to as WebLogic for readability.

This topic includes the following sections:

•	Key Features

•	How Jolt for WebLogic Works

•	Using the Example Packages

Key Features

Key features of the Oracle Jolt for Oracle WebLogic Server architecture include:

•	Enabling the use of Java HTTP servlets to provide a dynamic HTML front-end for Tuxedo applications

•	Providing session pooling to use Tuxedo resources efficiently

•	Supporting transactions

•	Integrating session pool management into the WebLogic Console

Note:

Jolt for WebLogic does not provide access to asynchronous Tuxedo event notifications.

How Jolt for WebLogic Works

This section describes the major components used for communication in Jolt, and how Oracle Jolt for Oracle WebLogic Server works, including:

•	How the connection is initialized when the server is started

•	The flow of information through:

•	An end-user Web browser

•	The WebLogic Server

•	The Tuxedo transaction processing system

Relationship Between Jolt for WebLogic and Tuxedo

Using Oracle Jolt for Oracle WebLogic Server, you can access your underlying Tuxedo system from the Web. This access allows you to write Web-enabled applications that can interact with other systems and databases in your Tuxedo domain.

The system described here is accessed through a standard Web browser. This Web browser is served by the WebLogic Server, which uses a customized Java HTTP servlet to handle the interactive HTTP requests of the browser. (An HTTP servlet is a Java class that handles an HTTP request and delivers an HTTP response.) The custom HTTP servlet uses the Jolt for WebLogic API to talk to a Jolt Server that can be on a remote machine or behind a security firewall.

The Jolt Server lives within the Tuxedo domain and determines which Tuxedo services are accessible to each client. The Jolt Server invokes the requested Tuxedo service and sends any results back to the WebLogic Server. You can then compile the results into a servlet-generated Web page, and send them to the browser. In doing so, you create a highly accessible and user friendly interface to Tuxedo services from anywhere on the Internet or intranet.

Essential Components of the Jolt Architecture

The fundamental object types that maintain the communications connection from the WebLogic Java HTTP servlet to the Jolt Server and from the Jolt Server to Tuxedo, are as follows:

•

Session

A session object represents a physical connection with the Tuxedo system.

•	SessionPool

A session pool contains one or more sessions. The sessions in the session pool are reused for efficiency. Your WebLogic servlet uses sessions to invoke services in Tuxedo through the methods of a session pool. Session pools are initialized by the WebLogic server at startup and configured by attributes in the config.xml file.

Note:

For Oracle WebLogic Server 6.0 or later, the xml-based config.xml configuration file has replaced the weblogic.properties file. For more information about the config.xml file, refer to the Oracle WebLogic Server Administration Guide.

•	SessionPoolManager

Use the session pool manager to get a reference to a session pool and to create, administer, and remove session pools. The session pool manager is created just before the WebLogic Server initializes the first session pool.

Figure 1‑1 shows the architecture for Oracle Jolt for Oracle WebLogic Server.

Figure 1‑1 Oracle Jolt for Oracle WebLogic Server Architecture

WebLogic Server Startup

The WebLogic standards-based, pure-Java application server assembles, deploys, and manages distributed Java applications. It supports distributed component services and enterprise database access, including Enterprise JavaBeans, Remote Method Invocation (RMI), distributed JavaBeans, and Java Database Connect (JDBC).

The WebLogic Server’s Administration Server is populated with JavaBean-like objects Sun Microsystem’s Java Management Extension (JMX) standard. These objects provide management access to domain resources.

The Administration Server contains both configuration MBeans and run-time MBeans. Configuration MBeans provide both SET (write) and GET (read) access to configuration attributes. Run-time MBeans provide a snapshot of information about domain resources, such as current HTTP sessions or the load on a JDBC session pool. When a particular resource in the domain (such as a Jolt connection pool) is instantiated, an MBean is created to collect information about that resource.

Note:

For more information about configuration and run-time MBeans, refer to the Oracle WebLogic Server Administration Guide.

The WebLogic Server is configured to initialize the session pools at startup through the config.xml file. A special startup class, PoolManagerStartUp, is invoked by the WebLogic Server with a number of parameters. This class functions as follows:

•	Creates a session pool manager if one does not already exist

•	Creates a session pool according to the given parameters

•	Adds the new session pool to the pool manager

Note:

Start the Jolt servers before attempting to create a session pool; otherwise the startup classes will fail, and they will not attempt to commit again.

The number of session pools created depends on the number of JoltConnectionPools that are configured in the config.xml file.

Connecting to a WebLogic Server from a Client Browser

In addition to its other Java services, the WebLogic Server is a fully functional HTTP server that supports Java HTTP servlets. In general, each servlet must be registered with a virtual name in the config.xml file.

A servlet may be invoked directly, that is, may actually present HTML to the browser, or may be invoked indirectly from an HTML form when the user submits the form. When the WebLogic Server receives a request containing the registered virtual name of a servlet, it invokes the appropriate servlet's service() method. For more information on HTTP servlets, refer to the Programming WebLogic HTTP Servlets guide.

The HTTP servlet's service() method (which invokes either the servlet's doPost() or doGet() method, depending on the context) is invoked and passes an HttpServletRequest object containing the HTTP data sent from the browser. In the example packages described in “Using the Example Packages” on page 1‑7, the client's query data is used in a transaction call to Tuxedo, and the response is built into the new HTML page.

How a Servlet Connects to Tuxedo

A servlet obtains a reference to the session pool manager that was created and initialized by the WebLogic Server when it started. The pool manager is used to retrieve the session pool that was configured in the config.xml file. This session pool references the appropriate Jolt Server in a Tuxedo domain. A servlet uses the session pool to invoke a specific Tuxedo service.

Tuxedo services are described and exported (declared accessible) on the Jolt Server in the Jolt Repository. In the Jolt Repository, the service’s expected input and output parameter types are declared. A servlet must supply the expected input parameters; Oracle Jolt for Oracle WebLogic Server uses specialized ServletSessionPool objects that can accept their input directly from an HttpServletRequest object. The output is returned in a ServletResult object.

What Happens if the Request Fails

The session pool distributes the requests equally among the sessions in the pool. It selects the least busy session to call the Tuxedo service. If the selected session is terminated before the Tuxedo service is called, the session pool redirects the service call to a different session, then establishes a new session to replace the disconnected one. The session pool uses a round-robin algorithm to select and establish a connection to a primary Jolt Server. If no primary Jolt Servers responds, the session pool connects to a failover server.

If no sessions are available from a session pool, or the session pool is suspended, then a SessionPoolException is thrown.

Multiple requests can be grouped into a single transaction. When a transaction fails, a TransactionException is thrown. This exception should be caught by the servlet and handled appropriately. (Usually, the servlet performs a rollback.)

Responding to the Client Browser

Provided the service call was successful, the following events occur:

•	The desired results are extracted from the ServletResult object.

•	The results are processed by the servlet and incorporated into an HTML page for presentation to the user's browser. The HTML page can be built in one of two ways:

•	With WebLogic's easy-to-use Java Server Pages (JSP) service that lets you embed Java in a standard HTML page.

•	Using a more sophisticated programmatic approach with WebLogic htmlKona.

•	The WebLogic Server returns the HTML page to the client via the HttpServletResponse object.

Disconnecting from the Jolt Server

The WebLogic Server is also configured to shut down the existing session pool connections to Tuxedo through the config.xml file.

Register the class PoolManagerShutDown so that the Jolt session pool is cleaned up properly when the WebLogic Server shuts down. PoolManagerShutDown does not require an attribute in the config.xml file.

Using the Example Packages

Two example packages are included with Oracle Jolt for Oracle WebLogic Server. These packages are described in Appendix B, “Simple Servlet Example,” and Appendix C, “Servlet with Enterprise JavaBean Example.” They demonstrate how Jolt is used in WebLogic servlets to access Tuxedo services. You can build, run, and inspect these examples to help you decide how to use WebLogic to extend Tuxedo services to the Internet.

•	Simple Servlet Example

A FORM-based HTML front end that submits a string to an HTTP servlet. The servlet in turn sends this string to a Tuxedo service. The returned data is compiled into a dynamically-generated HTML file, and sent back to the client browser.

•	Servlet with Enterprise JavaBean Example

The Enterprise JavaBean (EJBean) example package contains the classes and other files necessary to set up and run an EJBean stateful session to a Tuxedo Server that is using Jolt.