Integrating NonStop JDBC Type 4 Driver with IBM
WebSphere applications
Introduction......................................................................................................................................... 2
Products and components ..................................................................................................................... 2
Setup ................................................................................................................................................. 2
WebSphere Application Server ......................................................................................................... 2
The J2EE Tutorial—Duke Bank’s Application ........................................................................................ 3
What’s different ........................................................................................................................... 3
Extract the Type 4 files .................................................................................................................. 3
Extract Duke’s Bank files................................................................................................................ 3
Configuring the application for the WebSphere Application Server environment ..................................... 3
Preparing the files......................................................................................................................... 3
Compiling the Java source............................................................................................................. 4
Setting up the database .................................................................................................................... 4
Populating the NonStop SQL/MX Database .................................................................................... 4
Starting the NonStop ODBC/MX Service ........................................................................................ 5
Copying the t4sqlmx.jar file........................................................................................................... 5
Starting the default WebSphere Application Server .......................................................................... 5
Configuring JDBC Type 4 Data Source for WebSphere Application Server.......................................... 5
Adding a new JDBC provider ........................................................................................................ 5
Configuring a data source for the new JDBC provider....................................................................... 6
Specifying custom properties for the data source.............................................................................. 6
Saving the configuration changes................................................................................................... 7
Testing the DukesDatabase data source .......................................................................................... 7
Enabling security.............................................................................................................................. 8
Deploying and running the sample ...................................................................................................... 12
Conclusion........................................................................................................................................ 16
Ordering information ......................................................................................................................... 17
For more information.......................................................................................................................... 18
Introduction
The HP NonStop JDBC Type 4 Driver (hereafter referred to as Type 4 Driver) is a high-performing
standard compliant driver providing remote access from Java™ clients to HP NonStop SQL/MX
Release 2.0 Database MP and MX tables. Type 4 Driver is integrated with the features of the
NonStop SQL/MX Database server and provides a highly available and scalable connectivity
solution to the HP NonStop platform.
The purpose of this document is to provide a step-by-step guide to integrating the Type 4 Driver in the
Java 2 Platform, Enterprise Edition (J2EE) compliant IBM WebSphere Application Server. This guide
uses the popular “Duke’s Bank” provided by Sun Microsystems in the J2EE tutorial. Further details
about the application can be found in “The J2EE Tutorial—Duke Bank’s Application” section.
Products and components
This section describes the various products and components needed in order to successfully run the
Duke’s Bank sample.
Table 1. Products and components needed for Duke’s Bank sample.
Product/Component
Where to obtain
Special notes
NonStop JDBC Type 4 Driver
Ordering information
Auxilary files for sample
Same location as this document (named
NonStopFiles_WebSphere.zip)
Download here
IBM WebSphere Application Server
http://www-106.ibm.com/developerworks/
websphere/downloads/
Download trial
Version 5.1 or later
Duke’s Bank Application
http://java.sun.com/j2ee/1.3/download.html#tutorial
Download the 1.3
tutorial files (and not
the 1.4 ones)*
Jakarta Struts
http://jakarta.apache.org/struts
Apache Ant
http://ant.apache.org
Version 1.5.4 or later
Note: *The 1.4 version of the files have a different directory layout.
Setup
This section provides documentation to configure the IBM WebSphere Application Server environment
to run the Duke’s Bank Application. Please follow the order for the installation process as described
below.
WebSphere Application Server
Install the WebSphere Application Server by following the instructions provided as part of the
download. If installation is successful, then the administration console can be located at
http://localhost:9090/admin.
2
The J2EE Tutorial—Duke Bank’s Application
As mentioned earlier, we will make use of the example applications provided by Sun in the J2EE
tutorial, and, in particular, the “Duke’s Bank” Application. You can find the tutorial online at
http://java.sun.com/j2ee/tutorial/1_3-fcs/index.html.
Duke’s Bank is an online banking application. It has two clients: an application client, used by
administrators to manage customers and accounts, and a Web client, used by customers to access
account histories and perform transactions. The clients access the customer, account, and transaction
information maintained in a database through Enterprise JavaBeans (EJB). The Duke’s Bank
Application demonstrates the way that many of the component technologies—EJB, application clients,
and Web components—are applied to provide a simple but functional application.
What’s different
J2EE technologies are designed so that the client code is independent of the server in which the
application is deployed. The deployment descriptors for EJB and Web applications (ejb-jar.xml and
web.xml, respectively) are also standard and do not change between different J2EE containers.
However, there are a few things that need to be done in order to move the application to WebSphere
Application Server. In particular, we have to configure WebSphere Application Server and ensure
that the database scripts will work.
Extract the Type 4 files
Install the NonStop JDBC Type 4 Driver using the installation instructions provided in the product’s
README.txt file. The installation directory will hereafter be referred to as TYPE4_HOME.
Extract Duke’s Bank files
Unpack the downloaded archive file containing the Duke’s Bank files. This will create a directory
named j2eetutorial containing all the necessary source and configuration files.
Configuring the application for the WebSphere Application Server
environment
Preparing the files
1. Unpack the contents of the NonStopFiles_WebSphere.zip archive file to the location where you
have installed WebSphere Application Server. This will create a directory named nonstop
containing all the necessary NonStop related files. For example, if you have installed
WebSphere Application Server to the C:\Program Files\WebSphere\Appserver directory on a
Microsoft® Windows® system–based machine, unpacking the NonStopFiles_WebSphere.zip
should create the C:\Program Files\WebSphere\AppServer\nonstop directory with four files in
it.
The WebSphere Application Server installation location will be referred to as WSAS_HOME.
2. The entire sample code is in the bank subdirectory. You should copy the wsas-build.xml file
from the WSAS_HOME/nonstop directory to the j2eetutorial/bank directory. The wsasbuild.xml is the Ant build script for the WebSphere Application Server version of the
application.
3. Edit the j2eetutorial/bank/wsas-build.xml file and set the wsas_home property to the full path
to your WebSphere Application Server installation. The build process makes use of the jar files
and utilities that come with WebSphere Application Server, so it needs to know where to find
them.
3
For example,
<property name="wsas_home"
value="C:\Program Files\WebSphere\AppServer"/>
4. Download the struts distribution and copy the struts.jar, struts-logic.tld and the supporting
jakarta-commons jars (all those prefixed with “commons-”) to bank/jar.
Compiling the Java source
At the command line, change to the j2eetutorial/bank directory. All the build commands will be run
from here. Compilation should be fairly straightforward—just type the following command:
ant -f wsas-build.xml all
This compiles the source code and creates the necessary .jar, .war, and .ear files. If there aren’t any
errors, you should find a newly created build directory with the class files in it. Also in the jar
directory, you should see the DukesBank.ear file.
Setting up the database
Before you can deploy the application, you need a viable database for it to run against. If you are
writing an application that uses container-managed EJB persistence, you can configure the engine to
create the tables for you at deployment; otherwise, you must have a set of scripts to do the job. This is
also a convenient way of pre-populating the database with data.
The J2EE Software Development Kit (SDK) comes with the Cloudscape database, which is used
throughout the tutorials. You will be using the NonStop SQL/MX Database, which is running on the
HP NonStop Operating System.
You must therefore accomplish a few tasks before you can successfully test your application:
• Create and populate the NonStop SQL/MX Database with the appropriate tables and values
• Start the HP NonStop ODBC/MX Service on the NonStop system
• Make the Type 4 Driver jar file available in the WebSphere Application Server environment
• Start and Configure WebSphere Application Server to use the NonStop JDBC Type 4 Driver to
connect to NonStop SQL/MX Database
Populating the NonStop SQL/MX Database
Supplementing this document is a zip file named NonStopFiles_WebSphere.zip. One of the files in this
archive, named dukesDB.sh, contains the script file to create and populate the necessary database on
NonStop SQL/MX Database. Unpack the archive file and transfer dukesDB.sh (in ASCII mode) to the
HP NonStop Open System Services (OSS) environment.
To set up the NonStop SQL/MX Database, change to the directory on OSS where the dukesDB.sh is
located and run the following command:
OSS>
./dukesDB.sh
This creates the database in the schema DUKECAT.DUKESCHEMA.
4
Starting the NonStop ODBC/MX Service
The NonStop ODBC/MX Service must be installed and running on the NonStop system. Check the
NonStop ODBC/MX Service, also known as NonStop SQL/MX Connectivity Services (MXCS;
T7969G10), manual documentation on how to start the MXCS Association Server.
The following is a quick reference to start the MXCS Association Server from the TACL command
prompt as a super.super user:
<volume>.<subvolume>.mxoas /name $<process name>,
nowait, term $zhome/ -pn <port>
Example:
$data08.A2040209.mxoas /name $vn, nowait, term $zhome/ -pn 6100
Note: The above TACL command must be issued from an audited disk volume.
Copying the t4sqlmx.jar file
This Type 4 Driver class is part of the t4sqlmx.jar file and has to be made available to the
WebSphere Application Server environment at runtime.
To do this,
• Create a new directory named “nonstop” in the WSAS_HOME folder, if required.
• Copy the TYPE4_HOME/lib/t4sqlmx.jar file to the WSAS_HOME/nonstop directory.
Starting the default WebSphere Application Server
Start the default WebSphere Application Server by executing the startServer script located in the
WSAS_HOME/bin directory. Because the default server is “server1”, you should execute the following
on the command prompt:
C:\>
{WSAS_HOME}/bin/startServer server1
Configuring JDBC Type 4 Data Source for WebSphere Application Server
In order to use the JDBC Type 4 Driver in the WebSphere Application Server environment, the
following configurations need to be made using the WebSphere Application Server administration
Web console (http://localhost:9090/admin).
Adding a new JDBC provider
On the left panel, select the Resources Æ JDBC Providers option. On the screen in the right panel,
select the Server radio button and click the Apply button. Doing so will display all the currently
configured JDBC providers on the sample server (server1).
Click the New button. A new screen will appear on the right panel. Select “User-defined JDBC
Provider” from the drop-down list and click OK. In the screen that follows, configure the Type 4 Driver
by entering the details shown in table 2.
5
Table 2. Details for configuring the NonStop JDBC Type 4 Driver.
Property
Value
Name
SQLMX Type 4 JDBC Provider
Description
SQL/MX JDBC 3.0-compliant provider configuration
Classpath
${USER_INSTALL_ROOT}/nonstop/t4sqlmx.jar
Implementation classname
com.tandem.t4jdbc.SQLMXConnectionPoolDataSource
Click the Apply button. The same screen will reappear.
Configuring a data source for the new JDBC provider
On the same screen, scroll to the bottom and click on Data Sources in the Additional Properties
section. This will bring you to the screen where you can provide the configuration details for the data
source you want to add. Enter the information shown in table 3.
Table 3. Details for configuring the data source.
Property
Value
Name
$ DukesDatabase
JNDI name
jdbc/DukesDB
Container managed persistence
Select the checkbox
Statement cache size
10
Datasource helper classname
com.ibm.websphere.rsadapter.GenericDataStoreHelper
Component-managed authentication alias
None
Container-managed authentication alias
None
Mapping-configuration alias
DefaultPrincipalMapping
Click the Apply button. The same screen will reappear.
Specifying custom properties for the data source
On the same screen, scroll to the bottom and click on Custom Properties in the Additional Properties
section. Clicking the New button will cause a configuration screen to appear. From here you can
enter a new name/value pair. Create the following name/value pairs by entering the information
shown in table 4 on the screen (one name/value pair at a time) and clicking OK.
6
Table 4. Choosing custom properties for the data source.
Name
Value
Type
URL
Location where the MXCS’s Association Server is running, in the form:
‘jdbc:t4sqlmx://<nsk host dns or IP address>:<MXCS server port>/:’
java.lang.String
User
Valid username on the NonStop system that has sufficient privileges to
access the Duke’s Bank sample database
java.lang.String
Password
Password for the user
java.lang.String
Catalog
DUKECAT
java.lang.String
Schema
DUKESCHEMA
java.lang.String
Saving the configuration changes
Now that all the necessary changes have been made, you will need to persist your changes by saving
the configuration. Click on Save on the top menu, as shown in figure 1.
Figure 1
In the screen that follows, press the Save button to finalize the changes to the Master configuration.
Testing the DukesDatabase data source
To test the newly created data source, click on the Resources Æ JDBC Providers link on the left panel.
Then on the right panel, click on the SQLMX Type 4 JDBC Provider. Scroll down to the bottom and
click on the Data Sources link.
Select the checkbox next to the DukesDatabase and click the Test Connection button. If the
configuration values were correctly provided, you will see a message similar to that shown in figure
2.
7
Figure 2
Enabling security
In the Duke’s Bank Application, most of the URLs are restricted to the security role BankCustomer. The
application requires users to identify themselves via the form-based login mechanism. When a
customer tries to access a Web client URL, and has not been authenticated, the Web container
displays the form-based login URL/logon mapped to the logon.jsp page. This page contains a form
that requires a customer to enter an identifier and password. The Web container retrieves this
information, maps it to a security role, and verifies that the role matches that specified in the security
constraint. You will thus need to configure the WebSphere Application Server environment to provide
authentication for your application.
To keep things simple, you will implement a file-based security system to work with the Duke’s Bank
Application. The following subsections provide detailed information on how to enable security in the
WebSphere Application Server environment:
1. Because security is not enabled, you will be prompted for only a user ID (see figure 3). Once
you enable your security to use the custom registry, you will need to use one of the user IDs
defined in the users file. In the meantime, keep the user ID blank and select OK.
Figure 3
8
2. Next, from the Navigation menu of the administration console, expand Security ÆUser
Registries Æ Custom. This will take you to the User Registry screen (see figure 4).
Figure 4
3. In the User Registry window (above right), you need to enter data that implements the user
registry interface you are using, in this case the FileRegistrySample. Because you are using the
FileRegistrySample, you need to make sure you enter a valid user ID from the users.prop file;
you will use User1. The server will need this ID as well. Because this is being used as a
development aid, you need not worry about protecting the administration console; however,
you can assign one of the administrative roles if you desire. Enter the following information:
a. Server User ID: user1
b. Server User Password: password
c. Custom Registry Classname: com.ibm.websphere.security.FileRegistrySample
4. Select Apply and click on Custom Properties.
5. Because FileRegistrySample uses two property files, users.prop and groups.prop, you need to
tell it where these files are located. Before you populate these entries, create two new
properties on the Custom Properties window by clicking New (once for each property), then
enter the data shown in table 5.
9
Table 5. Entering new custom properties.
Name
Value
usersFile
<WSAS_HOME>/nonstop/users.prop
groupsFile
<WSAS_HOME>/nonstop/groups.prop
6. With the custom registry successfully configured, you now need to enable your Global Security.
From the navigation menu bar, select Security Æ Global Security (see figure 5).
Figure 5
7. In the Global Security window (see figure 6), check the Enabled box to enable Global Security.
De-select Enforce Java 2 Security; Java 2 Security enforces policy files to protect different
resources, but such strict requirements are not necessary for your development implementation.
For Active User Registry, select Custom from the list. Leave the default values for the remaining
fields and press OK.
10
Figure 6
8. Now that all the necessary changes have been made, you will need to persist your changes by
saving the configuration. Click on Save on the top menu. Click the Save in the new Save
window to make the configuration change final (see figures 7 and 8).
11
Figure 7
Figure 8
9. Stop the default WebSphere Application Server by executing the stopServer script located in
the WSAS_HOME/bin directory. Because the default server is “server1”, you should execute the
following on the command prompt:
C:\>
{WSAS_HOME}/bin/stopServer server1
10. Restart the server by executing the following command:
C:\>
{WSAS_HOME}/bin/startServer server1
Deploying and running the sample
Deployment in WebSphere Application Server can be done using the browser-based graphical user
interface (GUI) administration tool. Using ‘200’ and ‘j2ee’ as the user name and password,
respectively, log in to the Administration Console located at http://localhost:9090/admin. Use the
following steps to install the Duke’s Bank Application in the WebSphere Application Server
environment:
12
Figure 9
1. On the left panel expand the Applications group and click on the Install New Application link.
2. Click on the Browse button and navigate to the j2eetutorial/bank/jar directory. Select the
DukesBank.ear. Then click Next.
3. In the next screen (see figure 9), check to select the Generate Default Bindings box and press
Next.
4. The next screen represents Step 1. Without changing any values, press Next to go to the next
step.
5. In Step 2, select SQL92 as the database type and DUKECAT.DUKESCHEMA as the database
schema for the EJB. Do not change the other fields, and press Next to move to the next step.
6. Because you selected the Generate Default Bindings box in Step 3, JNDI names are autogenerated for you. Accept these values and press Next.
7. In Step 4 some of the JNDI, names for the bindings are also auto-generated. However, for the
BankWAR module, you will have to manually add the entries shown in table 6, as well as
displayed in figure 10, and click Next.
13
Table 6. Entering the JNDI names for the BankWAR module.
Referrence Binding
JNDI name
ejb/accountController
ejb/AccountControllerEJB
ejb/customerController
ejb/CustomerControllerEJB
ejb/txController
ejb/TxControllerEJB
Figure 10
8. In Step 5 you are required to map resource references in the EJB to a SQL data source. Here,
because you intend to use NonStop SQL/MX Database on NonStop systems as your database,
you change the JNDI Name values of all the entries to jdbc/DukesDB (see “Configuring a data
source for the new JDBC provider” section). Once this is done, click Next to proceed to Step 6.
9. Select the default values in Step 6 and proceed to the next step by clicking the Next button.
Select the default values in Step 7 and proceed to the next step by clicking the Next button.
10. In Step 8 you will map security roles defined in the Duke’s Bank Application to users/groups in
the WebSphere Application Server environment. To do this, you will rely on the file-based
security that you enabled in the “Enabling security” section. As a result, you should select both
the checkboxes in the All Authenticated? column and press Next.
11. Step 9 provides a summary of the installation options. Pressing Finish begins the deployment of
the Duke’s Bank Application.
12. The WebSphere Application Server workbench starts the deployment process and displays the
status in the browser. This process may last for a few minutes, depending on the system
resources present in the target machine. At the end of the deployment, you should see a screen
similar to figure 11.
14
Figure 11
13. Before you start the application, you must save the changes to the Master Configuration. This
can be done by clicking the Save to Master Configuration link, as shown in figure 11.
Once the changes are saved, expand the Applications group and click on Enterprise
Applications. Select the checkbox next to DukesBank and click on the Start button (see figure
12). Duke’s Bank is now functional at http://localhost:9080/bank/main.
15
Figure 12
You should be forwarded to the application login page when you first access the Duke’s Bank at
http://localhost:9080/bank/main. As explained in the tutorial, you can log in with a customer ID of
“200” and the password “j2ee”. If you receive an error at this point, check again to ensure that you
have set up the database correctly, as described in the “Setting up the database” section. Also,
ensure that you have populated the database with data.
Note: In order to stop the server, you now need to supply the stop script with authentication
parameters. For example, you would need to run the stopServer.bat as follows:
WSAS_HOME\bin\stopServer.bat server1 –user user1 –password password
Conclusion
The Type 4 Driver supports the portability goal of fast ROI with absolute minimum application change.
This sample indicates how applications written for a third-party JDBC driver can be executed on the
Type 4 Driver with just runtime configuration changes. It highlights that the Type 4 Driver’s JDBC
standards compliance helps you port existing applications or write new ones to use the NonStop
SQL/MX or SQL/MP Databases via any platform.1
1
The platform used must have Java 1.4.1 or later running on it.
16
The example here is only intended to get you up and running with integrating NonStop SQL/MX
Database and the Type 4 Driver with the WebSphere Application Server. The applications are not
intended to reflect how you should go about writing production J2EE software, as there are great
differences of opinion on this subject.
Ordering information
The NonStop JDBC Type 4 Driver is an Independent product that can be ordered using the part
number SJ82V1.
17
For more information
www.hp.com/go/nonstop
© 2005 Hewlett-Packard Development Company, L.P. The information contained
herein is subject to change without notice. The only warranties for HP products and
services are set forth in the express warranty statements accompanying such
products and services. Nothing herein should be construed as constituting an
additional warranty. HP shall not be liable for technical or editorial errors or
omissions contained herein.
Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation.
Java is a US trademark of Sun Microsystems, Inc.
04/2005
18