OpenSubsystems :: Documentation :: J2EE Application Server Setup

This document will help you get started with IBM WebSphere application server supported by OpenSubsystems. It will walk you through obtaining, installing and configuring the application server so that it can be used to run OpenSubsystems components and applications. It also describes how OpenSubsystems can integrate with and utilize transaction manager and connection pools provided by the application server to access your databases.

WebSphere Application Server 6

Official page | Download | Documentation | Fix packs
Tested version: WebSphere Application Server 6.0 Refresh Pack 2 Fix Pack 9 (6.0.2.9)

WebSphere Application Server 6 is a popular commercial application server developed by IBM Corp. It is J2EE 1.4 certified and used by many commercial clients.

Installation

Download the trial installation package from the WebSphere Application Server download page. Extract the content of the downloaded package and start the installation by launching the launchpad.bat file. Follow the easy to use installation wizard to install the application server on your system. We recommend to perform the complete installation to make sure all the necessary functionality is available.

After the installation of WebSphere is finished, it is recommended to install the latest refresh pack to address any functional and security issues, which were already corrected. Download the latest refresh pack, for example file 6.0-WS-WAS-WinX32-RP0000002.zip. The refresh pack needs to be extracted to the installation directory of the WebSphere Application Server so that it creates directory updateinstaller under the installation directory, e.g. the full directory path may be

C:\WebSphere6\updateinstaller

Start the refresh pack installation by launching file update.exe from this directory. Follow the easy to use installation wizard to install the refresh pack on your system. Continue relaunching the update wizard until you get message about all available updates being already installed.

After the installation of WebSphere Refresh Pack is finished, it is recommended to install the latest Fix Pack to address any additional details. Download the latest fix pack, for example file 6.0.2-WS-WAS-WinX32-FP0000009.zip. The fix pack needs to be extracted to the installation directory of the WebSphere Application Server so that it creates directory updateinstaller under the installation directory. If there already exists updateinstaller directory from the previous installation (e.g. from the Refresh Pack), rename that directory first before unpacking the fix pack. Start the fix pack installation by launching file update.exe from this directory. Follow the easy to use installation wizard to install the fix pack on your system. Continue relaunching the update wizard until you get message about all available updates being already installed.

Database Configuration

JDBC driver

Before you can use OpenSubsystems with WebSphere you will have to configure the persistence layer so that OpenSubsystems can access your database. Following steps assume that you are using the default instance (profile) of WebSphere server. Copy the JDBC driver for the database you want to use into directory

[WEBSPHERE_ROOT]/lib/ext

where WEBSPHERE_ROOT symbolizes the directory where WebSphere application server is installed. You should have this driver available if you have followed the Database Setup instructions.

OpenSubsystems

Next configure settings required to access your database. You have to include the default OpenSubsystems configuration file oss.properties in WebSphere configuration directory

[WEBSPHERE_ROOT]/profiles/[profile_name]/properties

where [profile_name] is the name of the profile you are using (the default profile name is called 'default').

Once the OpenSubsystem configuration file is setup, make sure that the uncommented database related settings in this file match the database you want to use. If you decide to use third party transaction manager or connection pool supported by OpenSubsystems, uncomment them in the configuration file as well. If all the connection pools and transaction managers supported by OpenSubsystems are commented out OpenSubsystems will detect if it is running inside of J2EE server and it will use the transaction management and connection pooling capabilities provided by WebSphere as part of the J2EE implementation.

Data source

If the WebSphere connection pool is being used you have to configure WebSphere data source that matches the database enabled in the configuration file. The entire configuration can be done from the WebSphere Administrative console, which is running on top of WebSphere application server. Start the server using shortcut in the Windows Start menu, which can be accessed by navigating folders

IBM WebSphere -> Application Server v6 -> Profiles -> [profile_name] -> Start the server

Next start the Administrative console using another Windows Start menu shortcut

IBM WebSphere -> Application Server v6 -> Profiles -> [profile_name] -> Administrative console

Once you login to the Administrative console, expand the Resources node and click on the JDBC Providers link. Click on the New button and on the Configuration tab of the dialog select database, provider and implementation types. If you are using one of the predefined database or provider types, you may need to enter additional properties below. If your database or provider (driver vendor) type is not present select User-defined database type. Click the Next button to progress to the next page. Once there, type Name and Description of your provider, for example use the database name to identify your provider. In the class path field, enter value

${WAS_LIBS_DIR}/ext/[jdbcdriver].jar

where the [jdbcdriver].jar is the driver you have previously copied to [WEBSPHERE_ROOT]/lib/ext directory. For example if you are configuring MS SQL Server using jTDS database driver the value for the class path field would be

${WAS_LIBS_DIR}/ext/jtds.jar

The ${WAS_LIBS_DIR} is variable specified in the Environment section accessible from the menu on the left under item WebSphere Variables. The last step of the JDBC provider definition is to specify the Implementation class name. Enter here the datasource name, which can be found in the OpenSubsystems configuration file (do not confuse it with the JDBC driver name, the datasource name is usually specified in the comments for a given database), e.g. for jTDS it would be

net.sourceforge.jtds.jdbcx.JtdsDataSource

Click Apply button to confirm the entered values.

The last step of the database configuration is to create the actual data source. Click on the Data Sources link, which became enabled after you clicked the Apply button. On the Data sources page click on the New button. Enter OSSDS as the data source name and in the JNDI Name field enter value

jdbc/OSSDS

This is because if no other datasource name is specified in the requestConnection or setDefaultDataSourceName methods of

org.opensubsystems.core.persist.db.DatabaseConnectionFactory

interface the default connection pool is always looked up for OSSDS JNDI datasource name. If your application sets different default datasource name, adjust this property accordingly. Uncheck the Use this Data Source in container managed persistence (CMP) checkbox and click the Apply button. Click on the Custom Properties link, which became enabled after you have clicked the Apply button. On the Custom properties dialog you have to add properties for the implementation class you have defined in the JDBC Provider part. These properties are listed in the OpenSubsystems configuration file comments, immediately following the datasource class you have used previously. For example for jTDS you have to specify properties: serverName, portNumber, databaseName, user and password. Once the last property is entered, save all the changes by clicking on the Save link in the messages area on top of the page. After the Data Source configuration is saved, you can test the connection by selecting checkbox for particular data source and then clicking on the Test connection button. This will of course succeed only if you have manually created the user you have specified earlier. If the specified user doesn't exist you may receive an error message, e.g.

   Test connection failed for data source OSSDS on server server1 
   at node ws_server with the following exception: 
   java.lang.Exception: java.sql.SQLException: Login failed for user 'basta'.DSRA0010E: 
   SQL State = 28000, Error Code = 18,456. View JVM logs for further details.

which is still a good sign, signaling that WebSphere tried to connect to the specified database and the database properly refused the connection. You may safely ignore this error since OpenSubsystems will create the configured user when it tries to access the database for the first time.

Server Configuration

It is critical that you correctly configure OpenSubsystems logging interface before you will be able to deploy OpenSubsystems-based application on WebSphere. Copy the OpenSubsystems logging configuration file osslog.properties into WebSphere configuration directory

[WEBSPHERE_ROOT]/profiles/[profile_name]/properties

mentioned earlier. Open this file in your favorite editor and modify it so that line specifying handlers looks like this:

   handlers= java.util.logging.FileHandler

It is critical that the setting specifying handlers doesn't contain the java.util.logging.ConsoleHandler since WebSphere application server will crash when deploying the application. Further, in this file you can also adjust the level of details logged by OpenSubsystems by adjusting various levels settings.

WebSphere stores all its activity in the log files, which are very handy during the troubleshooting of problems with your application or subsystems. The log files and information contained in them can be configured from the Administrative console under Troubleshooting section by clicking on the Logs and Trace link. In this section you can see the location of the files, but you cannot view their content. Here is also where you setup the level of details your application will log. Click on the name of your server in the Logging and Tracing section and on the new page click on the Change Log Details Levels link. On the Configuration and Runtime tabs set the level of details of packages you are interested in. The default packages for OpenSubsystems components are

org.opensubsystems

and

org.opensubystems.[subsystemname]

The OpenSubsystems logs are by default located in the system temporary directory and called oss_x_x.log. The WebSphere logs are by default located in directory

[WEBSPHERE_ROOT]/profiles/[profile_name]/logs/[server_name]

and

[WEBSPHERE_ROOT]/profiles/[profile_name]/logs/ffdc

where [profile_name] is the name of the profile you are using (the default profile name is called 'default') and [server_name] is the name of the server (default server name is called 'server1'). During normal activity, the SystemOut.log will not have any further information unless a significant error has occurred. If tasks are not executing as they should, this log, as well as the SystemErr.log activity.log and FFDC logs, should be consulted to determine the cause of the failure.

Ability to debug applications or subsystems running inside of WebSphere application server is essential during the development and the testing phase. To enable this capability you have to setup several properties required by WebSphere. In the Administrative console expand the Servers section in the left menu and click on the Application servers node. From the list select your servers and once the Configuration tab is displayed select the Debugging Service under the Additional Properties section. In the Debugging Service configuration dialog check the Enable service at service startup checkbox and enter your JVM debug port and JVM debug arguments. For example when using JVM port 8787, the JVM debug arguments can look like this

   -Djava.compiler=NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8787

For more information about particular options read the Java application launcher documentation. You can use Eclipse IDE to debug application running under WebSphere that was started in the debug mode. Follow the Debugging Remote Application guide for step by step instructions to configure your environment.

Deploying Application

The last step is to deploy your application to WebSphere application server. In the Administrative console expand the Application section on the left side and click on the Install New Application link. Once the Preparing for the application installation page loads, click on the Browse button and locate the war or ear file for the OpenSubsystems-based application or subsystem you want to deploy. In the Context root field enter the lowercase name of the application or subsystem you are deploying. Remember this name since once the application or subsystem is deployed it can be by default accessed using url

http://localhost:9080/[contextname]/

If you are deploying one of the default OpenSubsystem demo applications with names such as [subsystemname].ear, [subsystemname].war, [subsystemname]-app.ear or [subsystemname]-app.war, use the [subsystemname] part of the file name as the Context root. Click on the Next button twice to start the installation procedure. If you receive warning about additional settings, you can just safely continue.

Once the Install New Application page is loaded you can proceed with the installation by clicking on the Next button. The next page asks to map modules to servers. Check all checkboxes and click the Next button. The process will slightly differ depending on if you are installing application from .ear of from .war file.

For .ear application the next page asks you to map modules to servers. Check all checkboxes and click the Next button. Continue clicking the Next button until you get to Map virtual hosts for Web modules page leaving all the default options on the ejb deploy pages including the default (preconfigured by OpenSubsystems) JNDI names for EJB beans and resource references. Once you are on the Map virtual hosts for Web modules page check all checkboxes for each web module and click the Next button. The last page asks you to specify protection for all unprotected methods. Check the chekboxes for each EJB module and click the Next button. On the Summary page click the Finish button to start the deployment process.

For .war application your next step is to the Map virtual hosts for Web modules page. Once there, check all checkboxes for each web module and click the Next button. On the Summary page click the Finish button to start the deployment process.

After sucessfull deployment and installation click the Save to Master Configuration link and then the Save button. At this point the application has been installed. You can verify it by clicking on the Enterprise Applications link under the Applications section. If the application is not started, select the particular checkbox and click the Start button.

Once the application is started, you can access it by copying the URL http://localhost:9080/[contextname]/ to your browser address bar and modify it to reference your application.

Defects

WebSphere 6.0.2.7 is affected by following defects in WebSphere code:

ID	Description	Workaround
1487677	WebSphere incorrectly detects transaction in progress.	IBM concluded "it is highly likely this is a WebSphere defect" for which a fix is not available. We recommend to do not use the J2EE transaction manager and connection pool provided by WebSphere and instead use one of the transaction managers and connection pools bundled with OpenSubsystems.
1487670	WebSphere incorrectly manages autocommit state of connection.	IBM concluded as well "it is highly likely this is a WebSphere defect" for which a fix is not available. We recommend to do not use the J2EE transaction manager and connection pool provided by WebSphere and instead use one of the transaction managers and connection pools bundled with OpenSubsystems.

OpenSubsystems

Business Components for Java Applications

WebSphere