About this task
Setting up the remote CHA involves setting up the CHA server and
configuring the application to use the CHA. Setting up the CHA server is to
create the CHAInstance, and CHAControl tables used by the server and deploy
the server in WebSphere® Application
Server. CHA server can work with any one of the three famous Database: DB2® v7.2
or v8.1.4 or above, Oracle 8i, 9i, or 10g, and SQLServer2000 and SQLServer2005.
To
set up the CHA server, do the following:
Procedure
- Locate the createCHATable.ddl script file for the operating system
and database management system you are using for the database. You
can find the scripts under the Bank Transformation Toolkit installation directory
in the following path:
\dbtools\<op_system>\<DBMS>\tableDefinition\cha
For
<op_system>, look in the directory that matches the operating
system category on which the database is installed. The directories are:
- Unix (for AIX®, Linux on Intel,
and Sun Solaris)
- Windows (for Windows XP
and Microsoft Windows 2003)
For
<DBMS>, look in the directory that
matches the database management system that is operating the database. The
directories are :
- Edit the createCHATables.ddl file and customize the size of the
CONTEXT field in the CHAInstance table as needed. For Oracle and
SQLServer 2000, there is no need to adjust the size of CONTEXT field.
- Create the database tables for the CHA.
- For DB2:
- From a DB2 command
line prompt, create database called SAMPLE in DB2 Command Window using the following command:
DB2 CREATE DATABASE SAMPLE
.
- Use the CD command to go to the directory containing the createCHATables.ddl
file you just edited.
- Connect to the database in which you want to create CHA tables. For example,
suppose the user/password for database SAMPLE is db2admin/admin, use the
following command to create the tables in the SAMPLE database:
DB2 CONNECT TO SAMPLE USER db2admin USING admin
- Create the tables using the following command:
DB2 -tvf createCHATables.ddl
.
- For Oracle:
- In a sqlplus_command_line, use the cd command to go
to the directory containing the createCHATables.ddl file you edited.
- Connect to the database in which you want to create CHA tables. For example,
if you want to create the tables in the sample database, use the following
command:
sqlplus> connect userid/password@sample
- Create the tables using the following command:
sqlplus> start createCHATables.ddl
- For SQL Server:
- Open the SQL Server Enterprise Manager.
- In the Enterprise Manager, select .
- In the toolbar, select the database in which you want to create the CHA
tables.
- Open the createCHATables.ddl file you edited.
- Copy the contents of the createCHATables.ddl file into the Query window.
- In the toolbar, click Execute Query.
- Generate EJB to RDB mapping
- For DB2:
- In J2EE perspective of Rational® Application Developer, right click the BTTCHAEJB project,
then select .
- In the dialog box that pops up, select Create a new backend
folder and then click Next.
- Select Top-Down and then click Next.
- In the dialog box that pops up, complete the Target Database, Database
name, and Schema name fields. Clear the Generate
DDL checkbox, and then click Finish.
- For Oracle:
- Import BTTCHAEAR.ear file into your Rational Application Developer.
- Right-click the BTTCHAEJB EJB project, and select . When a dialog box
pops up, click next.
- In the next dialog box, select Meet in The Middle and
click Next.
- Fill in the information needed to establish a JDBC connection, and click Next
- Select the table for import, and click Next.
- Select the Match By Name, and Type option and click Finish.
- The Rational Application
Developer workspace will look like the following screen capture:
- From the workspace, drag CHAInstance from Tables View to CHAInstanceForRoot
in Enterprise Beans View.
- From the workspace, drag CHAInstance from Tables View to CHAInstanceForSession
in Enterprise Beans View.
- From the workspace, double-click the MYDB1_SCOTT_CHAINSTANCE.tblxmi file
to open it. Change the data type of ISROOT column from NUMBER to SAMLLINT.
- Likewise, double-click the MYDB1_SCOTT_CHACONTROL.tblxmi file to open
it. Change the data type of HASCTXTREEcolumn from NUMBER to SAMLLINT.
- Save all the modifications.
- Export the workspace as BTTCHAEAR.ear.
- Prepare deployment. In the J2EE perspective
of Rational Application
Developer, right click the BTTCHAEJB project, and then
select Prepare for Deployment.
- Deploy the BTTCHA.ear into WebSphere Application Server. The deployment settings vary according to the different databases.
- For DB2:
- From the WebSphere Application Server Administration Console,
select to configure the variables for DB2.
- From the WebSphere Application Server Administration Console,
select , then select , and create a new entry.
- Fill in the username and password for accessing DB2. This creates the J2C Authentication
Data Entry for DB2.
- From the WebSphere Application
Server Administration Console, select to create a new a new
user-defined JDBC provider using the following parameters:
- Classpath: ${DB2_JDBC_DRIVER_PATH}/db2java.zip
- Implementation Class:COM.ibm.db2.jdbc.DB2XADataSource
- The environment variable DB2_JDBC_DRIVER_PATH must have a correct value.
- Restart the WebSphere Application
Server.
- Create a Data Source for the JDBC provider and fill in the following properties:
- JNDI Name: the default value is jdbc/CHADataSource
- Container managed persistence: select the check box
- Component-managed Authentication Alias: choose the Authentication Alias
created in step 6.b.
- Container-managed Authentication Alias: choose the Authentication Alias
created in step 6.b.
- Specify databaseName for the Data Source. Use default values for other
properties.
- From the WebSphere Application
Server Administration Console, install BTTCHAEAR.ear.
Note: Select DB2UDBNT
V8.1 as the database type and fill in JDNI Name field with
jdbc/CHADataSource.
- From the WebSphere Application
Server Administration Console, start the CHA server. If the WebSphere log
file, SystemOut.log, has no any error message, the CHA server starts successfully.
- For Oracle:
- From the WebSphere Application Server Administration
Console, select , and then click , and create a new entry.
- Fill in the username and password for accessing the Oracle database. This
creates the J2C Authentication Data Entry for Oracle databases.
- From the WebSphere Application
Server Administration Console, select to create a new JDBC provider
by selecting Oracle JDBC Driver (XA).
- Create a Data Source for the JDBC provider and fill in the following properties:
- JNDI Name: the default value is jdbc/CHADataSource
- Container managed persistence: select the check box
- Component-managed Authentication Alias: choose the
Authentication Alias created in step 6.a
- Container-managed Authentication Alias: choose the
Authentication Alias created in step 6.a
- Specify URL for the Custom Properties for the Data Source. Use default
values for other properties.
- From the WebSphere Application
Server Administration Console, install BTTCHAEAR.ear.
Note: Select ORACLE
10g as the database type and fill in JDNI Name field with
jdbc/CHADataSource and choose to use default bindings.
- From the WebSphere Application
Server Administration Console, start the CHA server. If the WebSphere log
file, SystemOut.log, has no any error message, the CHA server starts successfully.
- For SQL Server:
- Visit ftp://ftp.software.ibm.com/software/websphere/info/tools/DataDirect/datadirect.htm to
download a Connect 3.3 driver. Do the following to install the driver:
- Open the ConnectJDBC33-JTA.zip file, which is part of the JDBC driver
you downloaded.
- Copy the sqljdbc.dll file from the zip file to the <SQL Server root>/binn
directory. For example, C:\Program Files\Microsoft SQL Server\MSSQL\Binn
- Use the ISQL utility to run the instjdbc.sql script from the zip file.
The DOS prompt syntax for doing so is:
>ISQL -U sa -P sa_password -S server_name -i location\instjdbc.sql
. sa is
the SQL Server system administrator user ID,
sa_password is
the password for the system administrator,
server_name is
the name of the server on which the SQL Server is running, and
location is
the full path to the instjdbc.sql script. For example,
>ISQL -U sa -P mypasswd -S Ojai -i c:\instjdbc.sql
Note: The
instjdbc.sql script generates many messages. These messages should be benign
and can be ignored in most cases, but you should review the output for any
messages that indicate an installation/execution error. The last message should
indicate that instjdbc.sql ran successfully.
- Start the SQL Server Distributed Transaction Coordinator. After you start
the Distributed Transaction Coordinator you'll see the
icon in front of the Distributed Transaction Coordinator in the SQL
Server Enterprise Server Manager.
- From the WebSphere Application Server Administration
Console, select .
- Fill in the username and password for accessing the SQL database. This
creates the J2C Authentication Data Entry for SQL databases.
- From the WebSphere Application
Server Administration Console, select to create a new JDBC provider
by selecting WebSphere embedded ConnectJDBC driver for MS SQL Server
(XA).
- Create a Data Source for the JDBC provider and fill in the following properties:
- JNDI Name: the default value is jdbc/CHADataSourc
- Container managed persistence: select the check box
- Component-managed Authentication Alias: choose the
Authentication Alias created in step 6.c.
- Container-managed Authentication Alias: choose the
Authentication Alias created in step 6.c
- Specify the following Custom Properties for the Data Source:
- databaseName
- serverName
- portNumber
Use default values for other
properties.
- From the WebSphere Application
Server Administration Console, install BTTCHAEAR.ear.
Note: Select MSSQLSERVER_2000 as
the database type and fill in JDNI Name field with jdbc/CHADataSource.
- From the WebSphere Application
Server Administration Console, start the CHA server. If the WebSphere log
file, SystemOut.log, has no any error message, the CHA server starts successfully.
Results
An application must contain the CHA facade and other related classes
contained in the BTTBase.jar and be configured so that the CHA facade can
find the CHA server before it can use the CHA.
To set up an application
to use the CHA, edit the system configuration files (btt.xml) for the client
and server side of the CHA to configure the following settings:
- ejbInitialContextFactory - provides the value for the InitialContextFactory
parameter when creating the javax.naming.InitialContext for JNDI lookup. The
default value is com.ibm.websphere.naming.WsnInitialContextFactory, which
is the value for Rational Application Server.
- CHASessionHome - provides the JNDI name of CHASession Session
Bean. The default value is ejb/com/ibm/btt/cha/ejb/CHASessionHome. This value
must be the same as the JNDI name used to deploy the CHASession.
- EJBProviderURL - specify the CHA server location: iiop://hostname:2809.
The user can change 2809 to other RMI port numbers.
- CHASessionLocalHome - provides the local reference for the CHASession
entity bean. The default value is java:comp/env/ejb/CHASession. Except for
the prefix of java:comp/env/, the setting value must be the same as the EJB
local reference for the deployed CHASession (ejb/CHASession) bean.
- CHAInstanceHome - provides the JNDI name of the CHAInstance CMP.
The default value is ejb/com/ibm/btt/cha/ejb/CHAInstanceHome. This value must
be the same as the JNDI name used to deploy the CHAInstance.
- CHAInstanceLocalHome - provides the EJB local reference of the
CHAInstance CMP. The default value is java:comp/env/ejb/CHAInstance. Except
for the prefix of java:comp/env/, the setting value must be the same as the
EJB local reference for the deployed CHAInstance (ejb/CHAInstance) bean.
- CHAControlLocalHome - provides the EJB local reference of the
CHAControl CMP. The default value is java:comp/env/ejb/CHAControl. Except
for the prefix of java:comp/env/, the setting value must be the same as the
EJB local reference for the deployed CHAControl bean.
- initTailContextName - identifies the root context when initializing
a context tree. The default value is "", which means the initialization is
not performed. If the setting contains a valid value, the startup bean initializes
the context and its children. If the setting value is not valid, an error
occurs and the CHA server does not start. The server side only must have this
setting.
- isLocalCall - indicates whether the CHA façade (EJB client) accesses
the CHA Server (EJB container) using the EJB local reference. The default
value is false. If set to true, the values of the CHASessionLocalHome and
CHAInstanceLocalHome settings set for the CHA facade must be the same as the
EJB local references for the CHASession and CHAInstance.
- CleanupCHAServer - cleans up the CHAInstance table, CHAChildren
table, and CHAControl table when the value is set to true.
- startMode - identifies the start mode of CHA. "PersistenceShared"
means using remote EJB and database persistence. "MemoryShared" means using
only remote EJB without database persistence.
<kColl id="settings">
...
<kColl id="cha-server">
<field id="ejbInitialContextFactory" value="com.ibm.websphere.naming.WsnInitialContextFactory"/>
<field id="CHASessionHome" value="ejb/com/ibm/btt/cha/ejb/CHASessionHome"/>
<field id="EJBProviderURL" value="iiop://localhost:2809"/>
<field id="CHASessionLocalHome" value="java:comp/env/ejb/CHASession"/>
<field id="CHAInstanceHome" value="ejb/com/ibm/btt/cha/ejb/CHAInstanceHome"/>
<field id="CHAInstanceLocalHome" value="java:comp/env/ejb/CHAInstance"/>
<field id="CHAControlLocalHome" value="java:comp/env/ejb/CHAControl"/>
<field id="initTailContextName" value="branchServer"/>
<field id="cleanupCHAServer" value="true"/>
<field id="isLocalCall" value="false"/>
<field id="startMode" value="PersistenceShared"/>
</kColl>
...
</kColl>
If a servlet or EJB calls the CHA facade and
they are in the same EAR file as the CHA server, the facade can use the local
EJB interface. To set up the CHA facade to use the local interface to access
the CHA EJBs:
- In the btt.xml file, set the value of isLocalCall to true.
- In the servlet or EJB that calls the CHA, establish the EJB local reference
for the CHAInstance and CHASession EJBs.
If the servlet or EJB are not in the same EAR file as the CHA server,
the facade must use the remote EJB interface. To set up the CHA facade to
use the remote interface, set the value of is LocalCall to false in the client
side btt.xml file.