|
|
|
Using Jolt for WebLogic
I. Introduction
Jolt for WebLogic is an extension to the Jolt 1.1 Java class library
that allows the Jolt client class library to be used in HTTP servlets
Key featuresKey features of this architecture include:
Note that Jolt for WebLogic does not provide access to asynchronous TUXEDO event notifications. How Jolt for WebLogic worksFirst, we shall describe the major components used for communication in Jolt. To describe how Jolt for WebLogic works, we shall then follow the journey of how the connection is initialized when the server is started, and describe the flow of information between an end-user web browser, the WebLogic Server, and the TUXEDO transaction processing system. What are the clients and servers in the system?Jolt for Weblogic allows you to access your underlying TUXEDO system from the web. This gives you the opportunity to write web-enabled applications with the functionality to interact with the other systems and databases in your TUXEDO domain. The system we shall describe here is accessed via a standard web-browser. The web-browser is served by the WebLogic Server, and uses a customized Java HTTP servlet to handle the interactive HTTP requests of the browser. The custom HTTP servlet uses the Jolt for WebLogic API to talk to a Jolt Server, which may 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 and which are not to each client. The Jolt Server invokes the requested TUXEDO service, and sends any results back to the WebLogic Server. The results may then be compiled into a servlet generated web page, and sent back to the browser. The result is a highly accessible and user friendly interface to TUXEDO services from anywhere on the internet or intranet. Essential components of the Jolt architectureBefore we follow the flow of information we should describe the fundamental object types in Jolt that maintain the communications connection from our WebLogic Servlet to the Jolt Server, through to TUXEDO.
What happens when the WebLogic Server starts up?The WebLogic Server is configured to initialize the session pools at startup via the weblogic.properties file. A special startup class called PoolManagerStartUp is invoked by the WebLogic Server with a number of parameters. This class creates a session pool manager if one does not already exist, registers it with JNDI, creates a session pool according to the given parameters, and adds the new session pool to the pool manager. Each successive call to this startup class adds another session pool to the same pool manager. Connecting to the WebLogic Server from a client browserIn 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 in the weblogic.properties file with a virtual name. A servlet may be invoked directory, 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 see Using WebLogic HTTP Servlets. The HTTP servlet's service() method (which invokes either the servlet's doPost() or doGet() methods, depending on the context), is invoked and passed an HttpServletRequest object containing the HTTP data sent from the browser. In our case, we shall use the client's query data in a transaction call to TUXEDO and build the response into the new HTML page. How a servlet connects to TUXEDOFirst, using a JNDI lookup, a servlet obtains a reference to the session pool manager that was created and initialized by the WebLogic Server when it started. The session pool manager is always registered in the WLInitialContext JNDI context under the name defined by the SessionPoolManager.POOLMANAGER_NAME final (constant) static variable. The pool manager is used to retrieve the session pool that was configured in the weblogic.properties 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. Here, the service's expected input and output parameter types are declared. A servlet must supply the expected input parameters; Jolt for WebLogic uses specialized ServletSessionPool objects that can accept their input directly from an HttpServletRequest object. The output is returned in a ServletResult object. What if the request fails?The session pool distributes the requests equally amongst the sessions in the pool. It picks the least busy session to call the TUXEDO service. If the selected session is terminated before the service is called, the session pool will redirect the service call to a different session and then establish a new session to replace the disconnected one. To establish a connection to a Jolt Server, the session pool uses round-robin algorithm to select a primary Jolt Server. If none of the primary Jolt Servers responds, the session pool will connect to one of the failover servers. 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 an transaction fails, a TransactionException is thrown, which should be caught by the servlet and handled appropriately; usually, a rollback should be performed. Responding to the client browserProvided the service call was successful, the following is performed:
A diagram of the architecture for Jolt for WebLogic is shown below.
Disconnecting from the Jolt ServerThe WebLogic Server is also configured to shut down the existing session pool connections to TUXEDO via the weblogic.properties file. Use the weblogic.system.shutdownClass property to register the class PoolManagerShutDown so that the Jolt session pool is cleaned up properly when the WebLogic Server shuts down. The PoolManagerShutDown accepts the name of the session pool to be closed as shutdownArgs parameters, also configured in the weblogic.properties file. II. The Jolt for WebLogic API
Class java.lang.Object
Class bea.jolt.pool.Connection
Class java.util.Dictionary
Class java.util.Hashtable
(implements java.lang.Cloneable,
java.io.Serializable)
Class bea.jolt.pool.DataSet
Class bea.jolt.pool.Result
Class bea.jolt.pool.servlet.ServletResult
Class bea.jolt.pool.servlet.ServletDataSet
Class bea.jolt.pool.SessionPoolManager
Class bea.jolt.pool.servlet.ServletSessionPoolManager
Class bea.jolt.pool.Factory
Class bea.jolt.pool.SessionPool
Class bea.jolt.pool.servlet.ServletSessionPool
Class java.lang.Throwable
(implements java.io.Serializable)
Class java.lang.Exception
Class java.lang.RuntimeException
Class bea.jolt.pool.ApplicationException
Class bea.jolt.pool.Transaction
Class bea.jolt.pool.UserInfo
III. Implementing with Jolt for WebLogicThis section describes the steps involved to use Jolt to connect to TUXEDO from your WebLogic application or servlet. In the last section, we provide a step-by-step description of a very simple example that establishes a connection and accesses a TUXEDO service from an HTTP servlet.
Importing packagesTo use Jolt for WebLogic, import the following into your servlet:
You must import the JNDI package to look up the SessionPoolManager. There are other classes you must import into any servlet; for more information on writing Java servlets, read the Developers Guide Using WebLogic HTTP Servlets. Configuring a session poolSession pools are created and accessed via the SessionPoolManager class. You can use the SessionPoolManager to create a session pool from within your application code, or have the WebLogic Server perform this task for you on startup, by setting a property in the weblogic.properties file. The latter is recommended since it provides a soft-coded configuration that is not part of your application logic, which means you can administer it without changing and recomping your code. That's the method we assume you are using in these instructions. The WebLogic Server uses a derivative of the SessionPool called a ServletSessionPool. The ServletSessionPool provides some extra functionality that is convenient for use inside an HTTP Servlet. A ServletSessionPool is configured in the weblogic.properties file by adding a set of properties as shown below: weblogic.system.startupClass.joltpool=\
bea.jolt.pool.servlet.weblogic.PoolManagerStartUp
weblogic.system.startupArgs.joltpool=\
poolname=joltpoolname,\
appaddrlist=//hostname:port;//hostname:port,\
failoverlist=//hostname:port,\
minpoolsize=1
maxpoolsize=3
When WebLogic is either started or restarted, it will invoke the PoolManagerStartUp class with the associated startupArgs. This association is made via a virtual name binding; in this example, we used joltpool. For more information on virtual names and the WebLogic properties file, see the Administrators Guide document, Setting WebLogic Properties. On the first invocation, the PoolManagerStartUp class creates a ServletSessionPoolManager, which contains every ServletSessionPool configured in the WebLogic properties file. Subsequent calls will add another ServletSessionPool to the same ServletSessionPoolManager. You must add registrations to the WebLogic properties file for each session pool using a unique virtual name binding for each, as shown in the properties example above. The ServletSessionPoolManager object is always bound to the name defined by SessionPoolManager.POOLMANAGER_NAME, and added to WebLogic's JNDI tree, so that it may be retrieved by your application code later. This process is described under Obtaining a ServletSessionPool, later in this document. The WebLogic Server creates a new ServletSessionPool as defined by the startupArgs you supply in the properties file. These are defined as follows:
Obtaining a ServletSessionPoolNow that you have configured the WebLogic Server to set up a Jolt SessionPool on start up, you will want to access it, and make use of it from your Java application or servlet. As we described above, in the WebLogic Server all ServletSessionPool objects are managed by the same ServletSessionPoolManager. You can look up the pool manager in the WebLogic JNDI InitialContext using the following code:
// Create the InitialContext
Context ctx =
WLInitialContextFactory.newInstance(new Environment());
// Lookup the pool manager
ServletSessionPoolManager poolMgr = (ServletSessionPoolManager)
ctx.lookup(SessionPoolManager.POOLMANAGER_NAME);
The WebLogic Server uses a ServletSessionPoolManager class, which is derived from SessionPoolManager. The ServletSessionPoolManager manages ServletSessionPool objects, which offer additional HTTP servlet methods. The SessionPoolManager provides several methods for managing the administration of a SessionPool. Here, the SessionPoolManager is used to retrieve the SessionPool that has been named joltpoolname : SessionPool sPool = poolMgr.getSessionPool("joltpoolname");
Since the WebLogic Server uses the subclass ServletSessionPoolManager, however, this in fact returns a ServletSessionPool object in the guise of a SessionPool. You must cast the SessionPool to a ServletSessionPool, as illustrated in this code example: ServletSessionPool ssPool =
(ServletSessionPool) poolMgr.getSessionPool("joltpoolname");
Since the WebLogic Server creates and configures the ServletSessionPoolManager for us, it is likely that this is the only method you shall use. Other methods of the SessionPoolManager allow you to create, suspend, stop, or shut down individual or all session pools it manages. We recommend that you leave these administrative operations to the WebLogic Server, by configure and managing your session pools via the WebLogic properties file. Using a ServletSessionPoolThe reference to the named ServletSessionPool from the pool manager represents a pool of sessions (or connections) to the Jolt Server in TUXEDO. The size of this pool and the TUXEDO system it connects to are abstracted from our application code and are defined in the WebLogic properties file. When we initiate a request, the SessionPool uses the least busy connection available. Calling a TUXEDO serviceA Jolt request usually consists of a single call to a TUXEDO service, using the call() method of the SessionPool. You supply the name of the TUXEDO service and a set of parameters to the call() method, and it returns a set of results from the TUXEDO service. It is possible to make multiple calls within a single transaction, which allows a servlet to comply with transactional demands of a TUXEDO application or preserve integrity between databases. This is described in more detail later under the section Using a Transaction. Sending a ServletDataSetThe ServletSessionPool provides overloaded call() methods for use inside an HTTP servlet. These methods accept their input parameters in terms of an HttpServletRequest object, and hence can conveniently be passed the same HttpServletRequest object that was passed into your HTTP servlet's doPost() or doGet() methods. However, in this instance, you must ensure that the names of the HTTP posted name=value pairs correspond to those expected by the TUXEDO service. The ordering is not important, since the data is ultimately converted into a Java Hashtable. Other non-related data in the HttpServletRequest will not disrupt the TUXEDO service. You invoke a TUXEDO service from within an HTTP servlet with the following method:
ssPool.call("serviceName", request);
where ssPool is a reference to a ServletSessionPool, "serviceName" is the name the TUXEDO service you wish to call, and the request argument is the HttpServletRequest object associated with the servlet. Internally, the ServletSessionPool.call() method converts the HttpServletRequest into a ServletDataSet, which may be submitted to a regular SessionPool. Adding parameters to the DataSetYou may wish to add extra data to the parameter set before calling the TUXEDO service. For example, you may need to add a parameter representing the date and time of the request. You would not expect to receive this parameter from the FORM data in the HttpServletRequest, better that you add it in the servlet, then submit the augmented data set to the TUXEDO service. The following example illustrates how to achieve this. // Create a new dataset
ServletDataSet dataset = new ServletDataSet();
// Import the HttpServletRequest into the dataset.
dataset.importRequest(request);
// Insert an extra parameter into the dataset.
dataset.setValue("REQUEST_TIME", (new Date()).toString());
// Send the dataset to the named service.
ssPool.call("service_name", dataset, null);
Here we manually convert the HttpServletRequest object into a ServletDataSet object. In this new format, we can add extra parameters, using the setValue() method. The new value is associated with a key, represented by a String. Then, we invoke the call() method that is inherited from the SessionPool. This method accepts the ServletDataSet class, but requires an extra argument for use with transactions. We supply null for this last parameter, indicating that we are not using a transaction to group multiple session calls. See Using transactions later for more details. Accessing a TUXEDO service through JoltTo access an existing TUXEDO service via Jolt, you must define and export the service in the Jolt Repository. For details on this, refer to the Jolt Repository Editor, or the Jolt Bulk Loader, in the Jolt User's Guide. The Jolt service definition defines the parameters that are expected by the TUXEDO application service. Converting Java data types to TUXEDO data typesThe following table is a mapping between Java types and TUXEDO parameter types required by a TUXEDO service. Use the appropriate Java types for the value to the DataSet or ServletDataSet. If you specify any parameter as a Java String, it is translated automatically to the appropriate type according to the service definition in the Jolt repository. This feature is also used to convert all of the data inside an HttpServletRequest object, since all parameters associated with the request are represented in string format. Otherwise, you should use the type specified in the table below. Providing the correct data-type may improve efficiency since no lookup is required to convert from a string.
A TUXEDO CARRAY is specified in a Java String by describing each byte value as a two digit hexadecimal number. You specify multiple bytes by concatenating these hexadecimal digit-pairs together. For example, the string "FF0A20" would represent the TUXEDO type CARRAY { 255, 10, 32 }. Receiving results from a serviceThe ServletSessionPool.call() method returns a ServletResult object that contains the results from the TUXEDO service. If the service call fails, an Exception is thrown. You should always attempt to catch Exceptions and handle them appropriately. Refer to the Jolt WAS Developer's Guide for details about the possible exceptions that can occur. Here is an example that retrieves a ServletResult using the ServletSessionPool.call() method in an HTTP servlet: ServletResult sResult = ssPool.call("service_name", request);
Here, ssPool is a ServletSessionPool, and request is an HttpServletRequest. The ServletSessionPool.call() method returns a Result object that you must cast as a ServletResult object. The ServletResult object provides extra methods for retrieving data as Java Strings. Using the Result.getValue() methodsProvided the call was successful, the individual parameters may be retrieved from the Result or ServletResult object using various forms of the getValue() method. The data is retrieved from a ServletResult by providing a key that corresponds to the parameter names of the TUXEDO service, as defined in the Jolt Repository. You supply the key to the appropriate getValue() method, which returns the corresponding value object. The Result.getValue() method also expects a default value object; this is returned if the key lookup fails. It is your responsibility to cast the returned object to the appropriate type, as defined by the TUXEDO service. Refer to the table above for the Java equivalents of the TUXEDO types. For example: Integer answer = (Integer) resultSet.getValue("Age", null);
This will set the Integer answer to the returned value in the ServletResult identified by the key "Age", or null if this key does not exist in the ServletResult. It is possible to have an array of values associated with a key. In that case, the simple getValue() method will return the first element of an array in this instance. Use this method signature in that case: public Object getValue(String name, int index, Object defVal)to reference a particular indexed element in an array value. Using the ServletResult.getStringValue() methodsServletResult extends Result, and provides the extra methods: public String getStringValue(String name,
int index,
String defVal)
public String getStringValue(String name,
String defVal)
These methods behave like the getValue() methods of the Result class, except that they always return a Java string equivalent of the value object expected. The CARRAY is converted into a string of two digit hexadecimal byte values as described earlier in Converting Java data types to TUXEDO data types. Using a transactionYou can use a Transaction object to group multiple service calls into an atomic action, maintaining data integrity within your application logic. You obtain a Transaction from a session pool with the method: Transaction trans = ssPool.startTransaction(timeout);where the Transaction object trans holds the reference to the transaction, ssPool is the SessionPool or ServletSessionPool object, and the timeout argument for the transaction is specified in seconds. Once a transaction has obtained a session, that session cannot be used by other transactions until the transaction is committed, aborted, or times out. The session may, however, still be used by single requests that are not part of a transaction. If a transaction fails to obtain a session from the pool, this method will throw a bea.jolt.pool.TransactionException. If the session pool is suspended, the method will throw a bea.jolt.pool.SessionPoolException. Each time your application uses the call() method, you should supply the Transaction object as the last parameter. For instance: ssPool.call("svcName", request, trans);
You can make multiple calls in the same transaction. The calls will not complete until you either commit or rollback the transaction using the methods of the Transaction object. The trans.commit() method completes the transaction. The method returns 0 if the commit was successful, or throws a TransactionException if the transaction failed to commit. If you need to abort the transaction, use the Transaction.rollback() method. This attempts to abort the transaction. It returns 0 if successful, or throws a TransactionException otherwise.
A simple exampleThis section provides step-by-step instructions on running the Jolt simpapp example, which uses a servlet to access a TUXEDO service that converts a string to uppercase. There are two parts to the simpapp example: the HTTP servlet that is shipped with the WebLogic examples, and the TUXEDO service application that is shipped with the TUXEDO examples. The TUXEDO simpapp server contains the TOUPPER service, which transposes a given string to uppercase. You can find the source code for the simpapp example in the examples/jolt/servlet/simpapp directory, included in the WebLogic distribution. Here is what you will find in the simpapp example directory:
A complete listing of the TUXEDO server-side source code of the simpapp application service is located in the TUXEDO distribution in the >$TUXDIR/apps/simpapp where $TUXDIR is the TUXEDO home directory. To run this example, you should be familiar with:
OverviewThe simpapp example is easy to follow. Just launch the simpapp.html page from the WebLogic Server. The simpapp.html page loads an HTML form which contains a text field for entering the string. Type in a string and click the Post button to submit the string as a post request. The SimpAppServlet formats the string you typed for use with the Jolt for WebLogic class libraries, and then dispatches the request to the TUXEDO TOUPPER service, which transposes the string to uppercase and returns it for display in the browser. Step 1. Getting started checklist
Step 2. Setting up the WebLogic environmentPlace a copy of the simpapp.html page in your WebLogic Server document root, then edit the weblogic.properties file to set up the WebLogic environment. You must add three registrations:
Follow these instructions to edit the WebLogic properties file.
Step 3. Starting the WebLogic ServerIf you are using a Windows system and you installed using the Install Shield, you can start the WebLogic Server from the menu item in the WebLogic Start menu. Otherwise, use the startWebLogic script on the command line, in the root directory of the WebLogic distribution. For more information on restarting the WebLogic Server, see the Administrators Guide, Setting up and starting the WebLogic Server. For more information on editing the weblogic.properties file, see Setting WebLogic properties. Step 4. Displaying the simpapp.html form
If you have problems displaying the form, check to be sure that the simpapp.html file is in the WebLogic document root. Step 5. Posting the FORM data from the browserEnter some text into the text field on the HTML page and submit it by clicking the POST button. Along with the text you entered, other parameters are submitted to the simpapp servlet class running in WebLogic. Here is the relevant section from the simpapp.html file, describing the HTML form. <form name="simpapp" action="/simpapp" method="post"> <input type="hidden" name="SVCNAME" value="TOUPPER"> <table bgcolor=#dddddd border=1> <tr> <td>Type some text here and click the Post button: <input type="text" name="string"> </td></tr> <tr> <td align=center><input type="submit" value="Post!"> </td></tr> </table> </form> This HTML form specifies two input fields: the text you enter and a hidden field. In this example, the value of the hidden field actually specifies the name of the TUXEDO service to be invoked. Although putting the name of the TUXEDO service within the HTML page is flexible and efficient, it is not recommended for production use for security reasons. In this HTML page, you can submit an HTTP request specifying a different service name as the hidden field. Note that TUXEDO service names are case-sensitive. When the WebLogic Server receives the HTTP form request, it invokes the doPost() method of the simpapp servlet and passes the form data inside an HttpServletRequest. Step 6. Processing the requestBefore the first request to the simpapp servlet, WebLogic initializes the servlet by calling its init() method. A reference to the SessionPoolManager is obtained (using a JNDI lookup) in the init() method, which is only invoked once. This reference is placed in the SessionPool Manager b_mgr variable. Here is an example: // Get the session pool manager through JNDI
Context ctx =
WLInitialContextFactory.newInstance(new Environment());
b_mgr =
(ServletSessionPoolManager)ctx
.lookup(SessionPoolManager.POOLMANAGER_NAME);
You can read more on using JNDI in the WebLogic framework. Next, the servlet's doPost() method is executed, which contains the code to get a connection from the "simpapp" session pool that was created during the startup of the WebLogic Server. The following code snippet shows the code that is used to retrieve the simpapp session pool. // Get the "simpapp" session pool
ServletSessionPool session =
(ServletSessionPool) b_mgr.getSessionPool("simpapp");
The TUXEDO service that will be called is identified in a hidden field which is retrievable from the request object. Here is how we retrieve the service name parameter: String svcnm[] = req.getParameterValues("SVCNAME");
We retrieve the value of the SVCNAME field in a string array that contains only a single value; we use only the first element of the array. The value set for the SVCNAME hidden field in the form is "TOUPPER". This is the name of the TUXEDO service that the servlet invokes, which we pass to the call() method as shown below: // Invoke a service and get the result. result = session.call(svcnm[0], req); The session object in this example is a ServletSessionPool that can accept the HttpServletRequest object directly. Internally, it converts the data into a Jolt DataSet object, which contains the parameters for the TOUPPER service. Note that the TOUPPER service expects a case-sensitive parameter called "STRING", so it is essential for the text field within the HTML form to be labeled exactly the same, i.e. "STRING". Note also that the other data fields like the SVCNAME are not relevant as parameters but do not disrupt the TUXEDO service. The form parameter is used to actually name the service, which you do not have to pass as a service parameter. It is passed automatically since it is already contained in the HttpServletRequest object. The TOUPPER service transposes the text in the "STRING" parameter to uppercase text and passes it back to the servlet in a ServletResult object that contains the results of an executed call, as well as details about exceptions if any are thrown during the service call. Step 7. Returning the results to the clientThe final step constructs and sends an HTML page containing the results of the service call back to the client via the HttpResponse output stream. The uppercase result is retrieved from the ServletResult object using the result.getValue() method. Here is a very unsophisticated example of passing this data back as HTML that the browser can display: out.println("<p><center><font size=+1><b>"+
result.getValue("STRING", "")+
"</b></font></center><p><hr
width=80%>");
The output stream produces a page that appears like this:
IV. Change history
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|
