×
2007/10/18
18 Oct, 2007

Running WSO2 WSAS on an IBM WebSphere Application Server

  • Upul G
  • - WSO2

Applies to

WSO2 WSAS 2.1

Table of Contents

Introduction

WSO2 Web Services Application Server (WSAS) is an open-source application server for Web services, supporting a whole array of open Web services standards and protocols. It is built on top of Apache Axis2 Web services framework and integrates several other open-source components and tools.

WSO2 WSAS can be run as a standalone server out of the box. Also, it can be integrated with J2EE compliant Servlet containers such as Apache Tomcat, Apache Geronimo, Redhat JBoss, BEA WebLogic, IBM WebSphere application servers, etc., to get the best of both industry-strength J2EE application server features and the full stack of open-standard Web services functionality.

We will be using the Microsoft Windows platform for the installation. For Linux and other platforms, substitute the associated shell scripts and directory locations as required. Note that the Unix operating systems use / (slash) directory separator instead of \ (backslash). This tutorial has used \ compatible with the Windows platform for consistency. Curly-bracket enclosed names in this article represent special directory locations. For example {WSAS_HOME} is the WSAS home directory and {WEBSPHERE_HOME} is the IBM WebSphere application server home directory.

Preparing the Environment

  1. Install a Java runtime environment if you haven't already done so.
  2. Set the JAVA_HOME environment variable to the Java home directory. WSAS installer uses the given Java environment when integrating WSO2 WSAS with an application server.
    e.g. C:\>set JAVA_HOME=C:\apps\jdk1.5

    We will assume that Java was installed at C:\apps\jdk1.5 directory.

    Tip: It is always easier to work with short file and directory names and to use directory and file names without spaces or non-alphanumeric characters.

  3. Install the IBM WebSphere application server if you haven't already done so. We will be using IBM WebSphere application server V6.1 on a Microsoft Windows XP machine.

    We will assume that it was installed at C:\apps\was directory.

Preparing the WSO2 WSAS Distribution

  1. Download WSO2 WSAS distribution from https://wso2.org/wsas
  2. Unzip the distribution into a temporary directory.
    e.g. C:\install\wso2wsas-SNAPSHOT
  3. Open a command prompt and go to the WSAS distribution bin directory
    e.g. C:\>cd C:\install\wso2wsas-SNAPSHOT\bin
  4. Run install.bat batch file.
    e.g. C:\install\wso2wsas-SNAPSHOT\bin>install.bat

    This will start the WSO2 WSAS installer program.

###########################################################
#                                                         #
#               WSO2 WSAS vSNAPSHOT Installation          #
#                                                         #
###########################################################

Using Java Home : C:\apps\jdk1.5


Please select your installation mode : [1/2]
1) WSO2 WSAS Servlet Container Installation
2) WSO2 WSAS Eclipse WTP Plugins Installation
:1

We will be installing WSO2 WSAS Servlet Container Installation. Type 1 and press Enter.

Selection: WSO2 WSAS Servlet Container Installation
WSO2 WSAS Home directory is where the WSO2 WSAS database, conf files, logs, and
module & service repository will reside.
Please enter the WSO2 WSAS Home directory [C:\Documents and Settings\Upul Godage\.wso2wsas]: C:\apps\wso2wsas

Installer asks for the WSO2 WSAS home directory. You can either accept the default location in your home directory or select another location. Installer will create the directory if it does not exist.
e.g. C:\apps\wso2wsas

Please select your application server:
1. Tomcat Server
2. JBoss Server
3. Geronimo Server
4. Generic Server
:4

Installer asks for the type of application server that we are going to use to run WSO2 WSAS. For the given application servers, the installer will do the necessary changes automatically without any user involvement. We will select 4. Generic Server for the IBM WebSphere application server.

Installing on Generic Server...
Starting Generic installation...
Please enter your Application Server's WAR file deployment directory : C:\apps\wso2wsas\war

Installer asks for the directory to create the web application archive or WAR file. Installer will prompt and create the directory if it does not exist.
e.g. C:\apps\wso2wsas\war

C:\apps\wso2wsas\war does not exist. Create new directory? (y/n)
Serializing wso2wsas.properties file ...
Creating wso2wsas.properties file...
OK
Creating Web Archive...
OK
Copying "wso2wsas.war" to "C:\apps\wso2wsas\war"
OK

WSO2 WSAS Servlet Edition installation was successful.
Please configure your J2EE app-server configuration files as described in the README.txt file.

clean:
   [delete] Deleting directory C:\install\wso2wsas-SNAPSHOT\wso2wsastmp

BUILD SUCCESSFUL
Total time: 0 seconds
Press any key to continue . . .

This will finish preparing the WSO2 WSAS distribution for integrating with the application server.

Creating an IBM WebSphere Application Server Profile

We will create a new profile for the WSO2 WSAS distribution using the profile management tool.

  1. Run, Start -> All Programs -> IBM WebSphere -> Application Server V6.1 -> Profile Management Tool

    A welcome message is displayed. Click Next.

  2. In the Environment Selection step, in Environments, select Application server and click Next.
  3. In the Profile Creation Options step, click Advanced profile creation and click Next.
  4. In the Optional Application Deployment step, clear the Deploy the default application check box. Leave the Deploy administrative console check box selected, and click Next.
  5. In the Profile Name and Location step, enter the profile name and profile directory location.
    e.g. Profile name: prof2
    Profile directory: C:\apps\was\profiles\prof2
  6. In the Node and Host Names step, enter the node name and host name.
    e.g. Node name: node2
    Host name: localhost
  7. In the Administrative Security step, select the Enable administrative security and enter username and passwords.
    e.g. User name: admin
    Password: admin
    Confirm password: admin

    8.  
     


    Figure 1: Ports
  8. In the Port Values Assignment step, the profile management tool displays all the ports used by this application server instance when it is running. Note down the HTTP and HTTPS transport port numbers. We will need those port numbers later when using WSAS.
  9. In the Windows Service Definitions step, clear the Run the application server as a Windows service check box and click Next. We will be using the start, stop application server shortcuts instead.
  10. In the Web Server Definition step, keep the default values and click Next. We will be using the built-in web server.
  11. In the Profile Creation Summary step, the profile management tool shows the summary of the profile settings we selected. Click Create.

    12. The profile management tool will create the new profile in a few minutes.

  12. In the Profile Creation Complete step, clear the launch first steps check box and then click Finish.

Application Server Profile Shortcuts

The profile management tool has created a set of shortcuts for each profile.
e.g. Start -> All Programs -> IBM WebSphere -> Application Server V6.1 -> prof2

The shortcuts are explained below. We will use all of them later while completing the installation.

Start the Application Server

Wait until the opened console window automatically closes.

Administrative Console

This will open up a web browser. Enter the username and password, we gave in the Administrative Security step when creating the profile, and click Log in.
e.g. User ID: admin
Password: admin

Stop the Application Server

Enter the username and password in the dialog box that appears.
e.g. User ID: admin
Password: admin
Wait until the opened console window closes automatically.

Starting the IBM WebSphere Application Server

  1. Start the application server instance using the shortcut. Wait until the opened console window closes automatically.
  2. Open the administrative console using the shortcut and log in.

 


Figure 2: Save configuration

When we make changes to the application server configuration later in this article, it will display the above message on top of the console page every time. Then click Save to save changes to the master configuration and proceed to the next step.

Creating the Data Source

Now we will create the data source required for WSO2 WSAS.

This is a summary of the data source settings.

JNDI name: jdbc/wso2wsas_db
Database Driver : org.apache.derby.jdbc.EmbeddedDriver
Database URL : e.g. jdbc:derby:{WSAS_HOME}\database\WSO2WSAS_DB
({WSAS_HOME} is the directory where WSO2 WSAS was installed by
the installer.)
Database Username : wso2wsas
Database Password : wso2wsas

The IBM WebSphere application server V6.1 comes with Derby jars.

 

  1. On the left pane, select Resources -> JDBC -> Data sources.
  2. In the JDBC sources panel, select the last option, the entry with Node=node2, Server=server1 for Scope and click New. The scope entries will reflect the names you have chosen earlier for node etc.
  3. Enter the following details in the Enter basic data source information panel and click Next.
    4. Data source name: wso2wsas_db
    JNDI name: jdbc/wso2wsas_db
  4. In the Select JDBC Provider panel, select Create new JDBC provider and click Next.
  5. Enter the following details in the Create new JDBC provider panel and click Next.
    6. Database type: Derby
    Provider type: Derby JDBC Provider
    Implementation type: Connection pool data source
    Name: WSO2 WSAS Derby JDBC Provider
  6. Click Finish in the Summary box.
  7. Enter the following details in the Enter database specific properties for the data source panel, clear the Use this data source in container managed persistence (CMP) check box and click Next.
    8. Database name: {WSAS_HOME}\database\WSO2WSAS_DB
    e.g. C:\apps\wso2wsas\database\WSO2WSAS_DB
  8. Click Finish in the Summary panel.
  9. When the message 'Changes have been made to your local configuration' appears, click Save in the Messages box.
  10. Now we will add the username and password for the data source.

    On the left pane, select Resources -> JDBC -> Data sources. Click on the wso2wsas_db data source.

    11.  


    Figure 3: Data source authentication data
  11. On the right side of the Configuration panel, click on JAAS - J2C authentication data under the heading Related Items.
  12. In the Data sources > wso2wsas_db > JAAS - J2C authentication data panel click New.
  13. Enter the following details in the Configuration panel and click OK.
    14. Alias: wso2wsas_db_id
    User ID: wso2wsas
    Password: wso2wsas
  14. When the message 'Changes have been made to your local configuration' appears, click Save in the Messages box.

Adding the keystore

We are going to add the keystore that comes with the distribution to the application server. Otherwise we can add our own keystore and specify it in {WSAS_HOME}\conf\server.xml file.

  1. On the left pane, select Security -> SSL certificate and key management.
  2. On the right side of the Configuration panel, click on Key stores and certificates under the heading Related Items.
  3. In the SSL certificate and key management -> Key stores and certificates panel click New.
  4. Enter the following details in the Configuration page and click OK.
    5. Name: wso2wsas_ks
    Path: {WSAS_HOME}\conf\wso2wsas.jks
    e.g. C:\apps\wso2wsas\conf\wso2wsas.jks
    Password: wso2wsas
    Confirm password: wso2wsas
    Type: JKS
  5. When the message 'Changes have been made to your local configuration' appears, click Save in the Messages box.

Adding WSO2 WSAS to IBM WebSphere Application Server

  1. On the left pane, select Applications -> Install New Application.
  2. Enter the following details in the Preparing for the application installation panel and click Next.
  3. Select the Local file system option.
    Full path: Select {WAR_DIR}\wso2wsas.war
    e.g. C:\apps\wso2wsas\war\wso2wsas.war
    {WAR_DIR} is the directory where we gave the installer as the WAR directory. You can select the wso2wsas.war by clicking on Browse.
    Context root: wso2wsas
    Select the Prompt me only when additional information is required option.
  4. In the Select installation options page, make sure the Distribute application check box is selected and click Next.
  5. In the Map modules to servers page click Next.

    6.  


    Figure 4: Data source mapping
  6. In the Map resource references to resources page, click Browse under Target Resource JNDI Name for Resource Reference value jdbc/wso2wsas_db.
  7. Select the entry wso2wsas_db and click Apply. This is the name we gave for the data source earlier.
  8. In the Map resource references to resources page, select the check box corresponding to the Resource Reference value jdbc/wso2wsas_db. Select the specify authentication method: value Use default method (many-to-one mapping) above. Select node2/wso2wsas_db_id from the Authentication data entry list and click Apply. Name wso2wsas_db_id is the name we gave for the authentication entry earlier.
  9. We have mapped the application server jdbc/wso2wsas_db resource to web application resource jdbc/wso2wsas_db with the authentication data wso2wsas_db_id. Click Next.
  10. In the Map virtual hosts for Web modules page, click Next.
  11. In the Summary page, click Finish.

    12. Now wso2wsas.war will be installed as a web application. Click Save at the end of the next page. But before we start the web application we need to do some changes to the installed web application.

Configuring IBM WebSphere Application Server

We need to set the class loaders to load the application classes first.

  1. On the left pane, click Enterprise Applications.
    Click wso2wsas_war entry and click Class loading and update detection.
    Enter the following values and click OK.
    Polling interval for updated files: 60 Seconds
    Class loader order: Classes loaded with application class loader first
    WAR class loader policy: Class loader for each WAR file in application
  2. When the message 'Changes have been made to your local configuration' appears, click Save in the Messages box.
  3. On the left pane, click Enterprise Applications.
    Click entry wso2wsas_war ; click Manage Modules and then click entry wso2wsas.war.
    In the Class loader order select Classes loaded with application class loader first.
    Click OK.
  4. When the message 'Changes have been made to your local configuration' appears, click Save in the Messages box.
  5. On the left pane, click Servers -> Enterprise servers
    Click entry server1. This should be the server instance that the web application was installed. In this case server1.

    6.  


    Figure 5:Web container settings
  6. Expand Web Container settings under the heading Container settings on the right, and click Web container.
    In the configuration page, click Custom properties under the heading Additional properties.
  7. In the Application servers > server1 > Web container > Custom Properties page, click New.
    Enter the following details and click OK.
    8. Name: directoryBrowsingEnabled
    Value: true
  8. Again, in the Application servers > server1 > Web container > Custom Properties page, click New.
    Enter the following details and click OK.
    9. Name: fileServingEnabled
    Value: true

Adding JAR libraries to the Installed Web Application

We can find the installed web application at,

{WEBSPHERE_HOME}\profiles\{PROFILE_NAME}\installedApps\{CELL_NAME}\wso2wsas_war.ear\wso2wsas.war
e.g. C:\apps\was\profiles\prof2\installedApps\localhostNode02Cell\wso2wsas_war.ear\wso2wsas.war

We need to copy some jars from the {WSAS_HOME} directory to the expanded installed web application's lib directory manually.

  1. Open a file browser window and go to {WSAS_HOME}\lib\endorsed
    e.g. C:\apps\wso2wsas\lib\endorsed.
  2. Copy three jars (resolver-2.8.0.jar, xercesImpl-2.8.0.jar, xml-apis-2.8.0.jar) to the installed web application's lib directory at, {WEBSPHERE_HOME}\profiles\{PROFILE_NAME}\installedApps\{CELL_NAME}\wso2wsas.war\WEB-INF\lib.
    e.g. C:\apps\was\profiles\prof1\installedApps\localhostNode02Cell\wso2wsas_war.ear\wso2wsas.war\WEB-INF\lib
  3. Also copy {WSAS_HOME}\lib\log4j-1.2.13.jar to the installed web application s lib directory above.

Configuring WSO2 WSAS

  1. Open server.xml at {WSAS_HOME}\conf in a text editor.
    e.g. C:\apps\wso2wsas\conf
  2. Uncomment the <Ports> section and replace the HTTP, HTTPS transport port numbers with the respective numbers that was shown in the profile management tool.
    3. <!--
    Uncomment this section and provide the correct HTTP port
    in the case of a generic server installation
    -->
    <Ports>
    <HTTP>9081</HTTP>
    <HTTPS>9444</HTTPS>
    </Ports>

Restarting the IBM WebSphere Application Server

Now, we will restart the application server instance. Stop the application server using the shortcut. Wait until the opened console window closes automatically. Then start the application server using the shortcut.

  1. Log in to Administrative console using the shortcut.
  2. On the left pane, click Applications -> Enterprise Applications.
  3. Select the check box corresponding to the entry wso2wsas_war and click Start.
  4. Open a web browser and go to https://localhost:9444/wso2wsas
  5. The port number should be replaced with the one shown for the HTTPS transport port in the profile creation tool.
  6. Now we can log in with the default administrator account.
    7. username: admin
    password: admin

INSTCONFSUCCESS. WSO2 WSAS in IBM WebSphere application server is open for business.

Summary

In brief, to integrate WSO2 WSAS on an IBM WebSphere application server we did the following steps.

  • Set up the Java Environment.
  • Installed WSO2 WSAS Distribution as a generic server.
  • Created an IBM WebSphere application server profile.
  • Created the data source.
  • Added the keystore.
  • Added WSO2 WSAS to the IBM WebSphere application server.
  • Configured the IBM WebSphere application server class loader and web container settings.
  • Added JAR libraries to the installed web application from the WSO2 WSAS distribution.
  • Configured the WSO2 WSAS transport port settings.

References

WSO2 WSAS How To Series

Author

Upul Godage, Senior Software Engineer, WSO2 Inc. upul AT wso2 DOT com

 

About Author

  • Upul G
  • IT

API Management
Integration
IAM
Internal Developer Platform
Solutions
Resources
Support
Company
Sign Up For Our Newsletter

Follow us

Learn About Security At WSO2 →