IBM WebSphere Developer Technical Journal: Leverage IBM Express Runtime to develop and deploy complete software solutions

IBM® Express Runtime offers a cohesive set of middleware components and a single environment that enables ISVs to create and deploy middleware components along with their own applications as a single package across multiple platforms. This article demonstrates the entire process.

Share:

Lim Sham Sham (limss@my.ibm.com), IT Specialist, IBM

Lim Sham Sham works as a technical support representative with Virtual Innovation Center supporting DB2 and Express Runtime. She is an IBM Certified Database Administrator and Application Developer for DB2 UDB V8. She is also an IBM Certified Application Developer for WebSphere Studio Application Developer.



Tan Eng Kian (tanek@my.ibm.com), Advisory IT Specialist, IBM

Tan Eng Kian works as a technical support representative with the ISVs and Developer Relations unit supporting WebSphere and Rational Software. He is an IBM Certified System Administrator and Application Developer for WebSphere Application Server and WebSphere Studio Application Developer



18 January 2006

From the IBM WebSphere Developer Technical Journal.

Introduction

For independent software vendors (ISVs) and their customers, there is more to a solution than just the application. A complete solution includes an application, but it's an application that is integrated with the middleware components that enable the application to work in the customer's environment. To turn their applications into solutions, it is common for an ISV to have to navigate through the complex process of obtaining, installing, configuring, and supporting many different middleware components from multiple suppliers with different terms and conditions, different licensing structures, and so on. From there, the process of integrating an application with all the different supporting components -- and deploying them all together for the customer -- is often equally complex.

IBM Express Runtime changes all that. IBM Express Runtime offers a cohesive set of middleware components and a single environment that enables ISVs to create and deploy middleware along with their own applications as a single package across multiple platforms quickly and effectively. This article explains what you need to know to begin developing and deploying complete solutions for mid-sized businesses using IBM Express Runtime V2.1.1, including:

  • Assembling a Web-based Enterprise JavaBeans™ (EJB) application.
  • Using three of IBM’s main middleware components -- IBM WebSphere® Application Server - Express V6.0.2, IBM DB2® Universal Database Express Edition V8.2 Fixpack 3, and IBM HTTP Server V6.0.2 -- all of which are included with IBM Express Runtime V2.1.1.
  • Using the Express Runtime Developer.
  • Deploying the integrated solution using the deployment wizard.

We will look at IBM Express Runtime and walk through the development and deployment process in these sections:

  1. IBM Express Runtime product and process overview
  2. Develop a Web-based EJB application
  3. Create application wrapper and package with the required middleware components
  4. Test the solution wrapper

This article assumes a working knowledge of J2EE application development. To follow the steps in this article, you will need to have IBM Express Runtime V2.1.1 properly installed in your environment.

Visit the IBM PartnerWorld Web site for details on obtaining an evaluation copy of IBM Express Runtime.


IBM Express Runtime product and process overview

Let's take a quick look at what IBM Express Runtime is and what you can do with it.

IBM Express Runtime V2.1.1 (hereafter called Express Runtime) is made up of the following main components:

  • Fully functional IBM middleware components that you need to run applications for mid-sized businesses:

    • IBM WebSphere Application Server - Express V6.0.2
    • IBM DB2 Universal Database (UDB) Express Edition V8.2, Fixpack 3
    • IBM Informix® Dynamic Server Express V10.0 TC3E/UC3E
    • IBM HTTP Server V6.0.2
    • Web server plug-in for WebSphere Application Server - Express 6.0.2
  • Solution assembly toolkit consisting of:

    • Express Runtime Developer that helps you assemble your application, along with IBM middleware components.
    • Deployment wizard to quickly and effectively deploy your solution to a target system.
  • IBM Rational® Web Developer V6.0 application development tool
  • Express Runtime console provides a single, Web-based utility for managing IBM middleware components.

In general, there are five steps involved in developing-to-deploying a solution in the Express Runtime environment, as shown in Figure 1.

Figure 1. Express Runtime architecture
Express Runtime architecture

Step 1: Use IBM Rational Web Developer V6.0, or equivalent application development tools, to develop your own J2EE applications.

Step 2: Install Express Runtime on an internal development machine. The following artifacts are included with the Express Runtime installation:

  • Solution Assembly Toolkit, which consists of Express Runtime Developer and Deployment Wizard
  • IBM middleware images
  • IBM Rational Web Developer V6.0
  • Express Runtime console
  • Documentations and samples.

Step 3 consists of two activities:

  • Integrate your applications with the required IBM middleware components using the Express Runtime Developer tool. A solution that consists of your application and all the required middleware components will be created.
  • The solution is then stored (on CD, DVD, or on a staging server) for later deployment to customer environment.

Step 4: Use the Deployment Wizard to deploy the stored solution.

Step 5: Manage IBM middleware components through the Express Runtime console, a Web-based console that provides consolidated administration of WebSphere Application Server - Express and DB2 UDB Express, or Informix Dynamic Server and HTTP Server.


Develop a Web-based EJB application

The goal is to create not just a valuable application, but a complete packaged solution that, upon installation, is already integrated with the components it needs.

We will walk through the process, beginning with a completed EJB application. For the purpose of this article, we will use a Personal Budget Analysis (PBA) EJB application as an example. (This application is provided in PersonalBudget.ear, included in the download ZIP file; steps on creating this application is beyond the scope of this article.)

To create a packaged solution with this application:

  • We will use three middleware components to run the application: WebSphere Application Server - Express, DB2 UDB Express, and HTTP Server.
  • We will use Express Runtime Developer to package the PBA application together with these middleware components into a solution.
  • We will deploy the solution to a customer environment using the Deployment Wizard.

About the sample application

Here is some background on the sample application we will be working with.

From a business function standpoint, the PBA application captures income and expense data and generates an income-and-expense ratio graph. The application was developed using IBM Rational Application Developer V6.0 with the UML editor as the development tool, along with JSPs, servlets, container-managed persistence (CMP) entity beans, session facade, and Service Data Objects.

Figure 2 shows you the relationship diagram for CMP entity beans used in our application.

Figure 2. Relationship diagram for CMP entity beans
Relationship diagram for CMP entity beans

Every individual user obtains income and incurs expenses:

  • Income consists of salary income and non-salary income.
  • Expense consists of household expenses, repayment for loan borrowing, and payment for insurance premium.

In this model, we use an entity bean named PBUser which represents a user in the Personal Budget database. PBUser has one-to-one relationship reference with the following entity beans:

  • Income
  • HouseholdExpense
  • BorrowingAndLoan
  • InsurancePayment.

Figure 3 shows a class diagram depicting the entities and their relationships. (This class diagram was created using the UML visual editor in Rational Application Developer.)

Figure 3. Class diagram for PBA application
Class diagram for PBA application

The class diagram shows the attributes for each entity bean. You will also notice a session facade bean named PBUserFacade, which contains the create, update and delete (CRUD) APIs to manage the instances of the PBUser SDO, which was added to the facade using the value-objects attribute. The methods it creates (shown in Figure 3) are getAllPBUserObjects, getPBUserByKey, createPBUser, updatePBUser, and deletePBUser. This session bean will be used by an ActionServlet in PBudgetWeb module to interact with PBUser entity bean to manage the user instance and its related entity bean instances.

The typical process flow for the PBA application is:

  1. New user signs up as a user by completing the user registration page.
  2. Registered user logs on to the PBA system using their user ID and password.
  3. Registered user performs one of the available personal budget functions:
    • View the Income and Expenditure Budgeting summary page (Figure 4).
    • View or enter details of personal monthly income (Figure 5).
    • View or enter details of monthly household expenses (Figure 6).
    • View or enter details of monthly loan repayment expenses (Figure 7).
    • View or enter details of monthly insurance premium payment (Figure 8).
Figure 4. Summary page for Personal Income and Expenditure Budgeting
Summary page for Personal Income and Expenditure Budgeting
Figure 5. Details for household income
Details for household income
Figure 6. Details for monthly household expenses
Details for monthly household expenses
Figure 7. Details for any monthly loan repayment expenses
Details for any monthly loan repayment expenses
Figure 8. Details for any monthly payment for insurance premium
Details for any monthly payment for insurance premium

Create PBA application wrapper and package with the required middleware components

Before assembling the application, we need to understand some key terminology as it is used within the Express Runtime context:

  • Wrappers can be thought of as the "workflow" or "controller" elements that are responsible for controlling the flow of execution for deploying a component. There are two types of wrappers available:

    • Application Wrapper
    • Solution Wrapper.
  • An application is a component of an overall solution; it can be a middleware component or an actual application. For example, our PBA application is considered an application wrapper in the context of Express Runtime; DB2 UDB Express -- which is one of the components required to support the PBA application -- is also an application wrapper.

    There are some ready-to-use sample application wrappers provided in the Express Runtime Developer tool that you can use as templates for your own application wrappers. Each application wrapper contains information specific to the application, such as name and version of the application, user programs to be used by the application, and so on. Application wrapper information is kept in a XML file called application.axml, which can be found in the src folder in the Express Runtime Developer tool, as shown in Figure 9.

    Figure 9. Application wrapper file application.axml is placed in the src folder
    Application wrapper file application.axml is placed in the src folder
  • When your application wrapper development is complete, you can then package all the required application wrappers into a single solution wrapper; a solution wrapper consists of one or more application wrappers.

    The Express Runtime Developer tool provides some ready-to-use sample solution wrappers, each of which contains information specific to the solution, including the ID, version, supported language of the solution, and so on. Solution wrapper information is kept in a XML file called solution.sxml, located in the src folder in the Express Runtime Developer tool, as shown in Figure 10.

    Figure 10. Solution wrapper solution.sxml is located in the src folder
    Solution wrapper solution.sxml is located in the src folder

The solution we will be developing, PBASolution, is made up of five application wrappers:

  • PBA
  • WebSphere Application Server - Express
  • DB2 UDB Express
  • HTTP Server
  • Web server plug-in.

Since WebSphere Application Server - Express, DB2 UDB Express, HTTP Server, and the Web server plug-in are part of the sample application wrappers provided in the Express Runtime tool, we only need to develop the application wrapper for PBA. Subsequently, all of these application wrappers will together be packaged into a solution wrapper, as shown in Figure 11.

Figure 11. Conceptual view of PBASolution
Conceptual view of PBASolution

With an understanding of wrappers and how they are structured, we will move on to the next level of PBA application wrapper development. More terminology will be introduced along the way.

To develop our PBA application wrapper, we will perform these general tasks, each of which is explained in detail in the following sections:

  1. Create PBA application project
  2. Edit Application Wrapper
  3. Create Budget.prop response file
  4. Create PBA user programs
  5. Add wsadmin and DB2 scripts
  6. Complete PBA application project
  7. Create PBASolution solution project
  8. Edit Solution Wrapper Editor
  9. Complete PBASolution solution project

A. Create PBA application project

  1. Start Express Runtime Developer by selecting Start => Programs => IBM Express Runtime 2.1 => Express Runtime Developer. You should now be in the Express Runtime Developer perspective.

  2. Create a new application project by selecting File => New => Express Runtime Application Project.

  3. On the next dialog, enter PBA for the Project name and select Next.

  4. Next, enter or select the following values use the following values:

    • Application ID: PBA
    • Version: 1.0
    • Installation time (minutes): 30
    • Operating system: Windows
    • Default language: English
    • Wrapper file name: application.axml

    Select Finish to complete the creation of PBA application project.

  5. From the Package Explorer panel, you will see that the PBA application project has been created and that the Application Wrapper Editor Welcome page is displayed in the right pane (Figure 12).

Figure 12. Application Wrapper Editor Welcome page
Application Wrapper Editor Welcome page

B. Edit Application Wrapper

Next, we will use the Application Wrapper Editor to edit the PBA application wrapper.

The General tab shows the details you specified above, which includes the general information of the application project. You can use this page to select the appropriate options; since our sample application only runs on Windows® and the only supported language we selected is English, these are the only options you will see selected.

The Programs tab gives you the information about any custom user programs, which can be used to:

  • Perform pre-installation, installation, or post-installation of IBM middleware components and ISV applications.
  • Execute wsadmin scripts written in Jython or JACL to configure the WebSphere Application Server environment.
  • Execute DB2 scripts to create databases or tables, and populate tables with data.

(Rational Web Developer, which is included with Express Runtime, can be used to develop Java-based user programs.)

There are four types of user programs that can be developed for use with Express Runtime, differentiated by the point during the deployment process in which the program runs:

  • A predeployment checker is run prior to the entry, main, or exit programs, and is used to examine whether target computer meets certain criteria, such as having adequate disk space, any conflicting software, a previous version of the application, and so on.

  • An entry program is typically used to perform any pre-configuration or setup required before the main installation program runs.

  • The main program is the installation program that performs the installation of your application(s) on target computer.

  • An exit program is typically used for any post-configuration required following the product installation, and can be used to determine if the installation of the solution is successful.

Our sample application project will use two user programs: a predeployment checker and a main program. The predeployment checker will be used to determine whether the target computer has all necessary prerequisites in place, and the main program will perform the actual installation of our PBA application, which will include executing DB2 scripts, creating a DB2 database and tables, installing the PBA application on WebSphere Application Server - Express, and invoking wsadmin scripts to configure WebSphere Application Server - Express environment resources.

You may notice at this point that there is an error in the PBA application project. This is because a main program is required for every application project, but, by default, no program is initially associated with it. This error will disappear after the main program has been defined.

To define both of the user programs we need:

  1. Select the Programs tab to be taken to the Main Program page.

  2. In the Basic Program Configuration section, make sure that the Program type field is set to Java program.

  3. In the Program field, type in com.budget.PBAWinMain. This will associate the PBAWinMain class as the Main Program.

  4. In the Program Arguments section, enter Budget.prop into the Response file field, and PBAWinMain.log into the Log file name field.

  5. In the Arguments field, select Add, from the Add Argument window, select Response file name, and then click Next.

  6. Make sure the Response file name field is set to Budget.prop and then Finish. The PBAWinMain program will take Budget.prop as an input argument.

    We have completed the definition of the Main Program, as shown in Figure 13. Next, we will define the predeployment checker user program.

    Figure 13. Completed definitions of the main program
    Completed definitions of the main program
  7. Change to the Predeployment Checker page and check Enable predeployment.

  8. Make sure Java program is selected as the Program type in the Set Program window and click Next.

  9. In the Specify the main class window, enter com.budget.PBAWinPDC in the Main class field and click Finish.

  10. In the Program Arguments section of the User Programs Information window, enter Budget.prop in the Response file field and PBAWinPDC.log in the Log file name field.

  11. In the Arguments field, click Add.

  12. From the Add Argument window, select Response file name and click Next.

  13. Make sure the Response file name field is set to Budget.prop and click Finish.

  14. Save the changes we have made so far by selecting File => Save from the main menu.

    We have completed the definition of our predeployment checker, our second user program, as shown in Figure 14.

    Figure 14. Completed definitions of the predeployment checker
    Completed definitions of the predeployment checker

The Variables tab enables you to configure the variables you need in deploying applications. For our sample application project, two variables, DB2UserId and DB2UserPassword, are required. We will first add the variables and then set the following validation rules for these two variables (you can always add more, if necessary):

  • Valid characters: @#$_abcdefghijklmnopqrstuvwxyz0123456789
  • Invalid values: ADMINS, USERS
  • Invalid prefixes: SQL, _, IBM

To configure these variables:

  1. In the Application Variables section, select Add.

  2. Select String Variable as the Variable type. Enter DB2UserId into the Variable name field and DB2 Administrator User ID into the Variable description field. Click Finish.

  3. You should now see a string variable called DB2UserId added in the Application Variables list.

  4. In the Variable Validation Configuration section at the bottom of the window, define the following:

    • Default value: db2admin
    • Minimum length: 2
    • Maximum length: 30
  5. Click Add next to the Validation rules field to add each of the validation rules listed above. To define the first validation rule, select Specify a valid value in the Add a variable validation rule window, then Next.

  6. Make sure you select the Specific characters option and then Next.

  7. In the next window, enter the following in the Valid string field: @#$_abcdefghijklmnopqrstuvwxyz0123456789 and then Finish.

  8. Select Add next to the Validation rules field again to define the second validation rule.

  9. In the Add a variable validation rule window, select Specify an invalid value and click Next. In the next window, keep the Complete String default option and then Next.

  10. Enter the following in the Invalid string field: ADMINS and click Finish.

  11. Repeat steps 22 through 24 to add an invalid string for USERS.

  12. To define an invalid prefix, click Add next to the Validation rules field again.

  13. In the Add a variable validation rule window, select Specify an invalid value, then Next.

  14. In the next window, make sure you select the Prefix option and then Next.

  15. Enter SQL in the Invalid prefix field and click Finish.

  16. Repeat steps 27 through 29 to add an invalid prefix for "_" and "IBM".

You may notice a section called Variable Associations Configuration. This option is used to perform variable associations, making variable values available to user programs by including the values in the response file (properties file). We will perform variable associations for DB2UserId in the next set of steps, making the value of DB2UserId available to user programs through the Budget.prop properties file.

There are few different types of associations available. We will be using Properties association in our example. All Java-based user programs can access the variable values through this type of association.

  1. Click Add to the Variable Associations Configuration section.

  2. In the Add Association window, select Properties association and then Next.

  3. Enter DB2UserId in the Keyword field and click Finish.

  4. You should now have DB2UserId in the Variable Associations Configuration list.

  5. Save the changes by selecting File => Save from the main menu.

    We have completed defining our first variable, DB2UserId, as shown in Figure 15. Next, we will define our other variable.

    Figure 15. Completed definitions for variable DB2UserId
    Completed definitions for variable DB2UserId

The second variable we will add is DB2UserPassword, which has the following validation rules:

  • Valid characters: @#$_abcdefghijklmnopqrstuvwxyz0123456789
  • Invalid values: ADMINS, USERS
  • Invalid prefixes: SQL, _, IBM

To add the DB2UserPassword variable:

  1. In the Application Variables section, click Add.

  2. Select Password Variable as the Variable type. Enter DB2UserPassword for the Variable name, and DB2 Administrator User Password as the Variable description, then Finish.

  3. DB2UserPassword is now added in the Application Variables list.

  4. In the Variable Validation Configuration section, define the following values:

    • Minimum length: 2
    • Maximum length: 30
  5. Follow the same steps for DB2UserId to add the validation rules for DB2UserPassword.

  6. Click Add next to define the Variable Associations Configuration for DB2UserPassword.

  7. In the Add Association window, select Properties association, then Next.

  8. Enter DB2UserPassword in the Keyword field and click Finish.

  9. DB2UserPassword should now appear in the Variable Associations Configuration list.

  10. Save the changes by selecting File => Save from the main menu.

The completed variable definition for DB2UserPassword as shown in Figure 16.

Figure 16. Completed definitions for variable DB2UserPassword
Completed definitions for variable DB2UserPassword

The Files tab enables you to define all the files needed for installing your application. We will come update this tab later, after we have created all the required files (next).

C. Create Budget.prop response file

At this point, you may notice an error in the PBA application project. This is because the properties file we specified above has not yet been created. A properties file contains parameters that will be shared and used by user programs at run time. The Budget.prop properties file used in our exercise will contain all the parameters that are required by both the predeployment and main program user programs.

To create the Budget.prop properties file:

  1. From the Package Explorer panel, expand the src folder.

  2. Right-click on the PBA folder and select New => File.

  3. Enter Budget.prop in the File name field and click Finish.

  4. You will see that Budget.prop file is now created. Copy and paste the contents of the Budget.prop file, available in the download zip file included with this article.

  5. Save your changes by pressing Ctrl-S.

Our Budget.prop properties file (also referred to as a response file) is created, as shown in Figure 17.

Some of the parameters in the Budget.prop file, such as DB2.UserID and DB2.UserPW, do not have values defined; the variable associations we did in Step 2 for both DB2UserId and DB2UserPassword enable us to provide values for these variables at run time. For example, if a user enters db2admin as the DB2 User ID and db2admin as the DB2 User Password, these values will be included in the response file and be made available to both the predeployment and main program user programs.

Figure 17. Budget.prop response file
Budget.prop response file

D. Create PBA user programs

Above, we specified the following to be used as user programs in our exercise:

  • Predeployment checker: PBAWinPDC
  • Main program: PBAWinMain

PBAWinPDC.java will:

  • Verify whether DB2 Express and WebSphere Application Server - Express are installed on the target machine.
  • If they are installed, the checker will then determine whether the PBA application is already installed on WebSphere Application Server - Express.
  • If the application is not already installed, then PBAWinMain.java will be invoked; if the application is already installed, then the main program will not be invoked.

In addition to these two user programs, the following Java files are also part of our PBA application:

  • PBAWinCommon.java contains the constants and methods referenced by both PBAWinPDC.java and PBAWinMain.java.
  • PBAMessagesNLS.java is used to define the messages for exception handling during deployment.
  • PBANLSKeys.java contains the static keys for the resource bundles used by both PBAWinPDC.java and PBAWinMain.java. The static keys defined here will be used to look up the message in PBAMessagesNLS.java for exception handling during the deployment.

To simplify the creation of user programs, customize the sample wrappers that are provided in the Express Runtime Developer tool according to customer requirements.

To create the predeployment program:

  1. From Package Explorer, right click on the src/PBA/userPrograms folder and select New => Class.

  2. On the New Java Class panel, enter or select the following values:

    • Package: com.budget
    • Name: PBAWinPDC
    • Superclass: com.ibm.jsdt.support.SupportWindowsBase

    In the Superclass Selection window, enter SupportWindowsBase in the Choose a type field, and select public static void main(String[] args) for the Which method stubs would you like to create field.

  3. PBAWinPDC.java file is now created. Replace the contents of the PBAWinPDC.java file with the source code from the PBAWinPBC.java, included in the download ZIP file. Save the changes by pressing Ctrl-S.

  4. Repeat these steps to create the following Java files, using the values specified and the associated source code from the download ZIP file:

    PBAWinMain.java file:

    • Package: com.budget
    • Name: PBAWinMain
    • Superclass: com.ibm.jsdt.support.SupportWindowsBase

    PBAWinCommon.java:

    • Package: com.budget
    • Name: PBAWinCommon
    • Superclass: com.ibm.jsdt.support.SupportWindowsBase

    PBAMessagesNLS.java:

    • Package: com.budget
    • Name: PBAMessagesNLS
    • Superclass: com.ibm.jsdt.support.SupportWindowsBase

    PBANLSKeys.java:

    • Package: com.budget
    • Name: PBANLSKeys
    • Superclass: com.ibm.jsdt.support.SupportWindowsBase

You should now have five Java programs in the src/PBA/userPrograms folder under the com.budget package, as shown in Figure 18.

Figure 18. Five user programs in src/PBA/userPrograms folder
Five user programs in src/PBA/userPrograms folder

Some APIs in the SupportFramework package are used extensively in our Java programs. For example, as you can see from the code snippets below from PBAWinMain.java:

import com.ibm.jsdt.support.SupportWindowsBase;
.....
private SupportWindowsHelper ivHelper = null;
.....
private int runWebSphereScript() {
int rc = SUCCESS;
// Get the WAS script to be run
// The script name is specified in the application properties file – PBA.WASscript
.....
String unpackedDir = ivHelper.getUnpackedDir(this);
.....
String shortWasProfileBinDir = ivHelper.getWindowsShortPath(this)) {
.....

The ivHelper object is a type of SupportWindowsHelper, which is part of the SupportFramework API. The invocation of the getUnpackedDir method returns the directory where the PBA application is unpacked. Another method, called getWindowsShortPath, retrieves the Windows short name path for a given path. Documentation on SupportFramework can be found in the following path in the Express Runtime documentation: <ER_install_dir>\Runtime21\SolutionEnabler\Support_Framework\index.html.

By default, all the Java programs will be compiled automatically. Class files are generated after successful compilation. Problems detected by the compiler are reported as warnings or errors in the Express Runtime Developer tool.

Since we have five Java programs, the default build path for all the five class files can be found in <ER_install_dir>\Runtime21\SolutionEnabler\workspace\PBA\bin\com\budget directory. Alternatively, those files can also be found using the Navigator panel, in the bin\com\budget directory, as shown in Figure 19.

Figure 19. The class files are located in bin\com\budget folder from the Navigator panel
The class files are located in bin\com\budget folder from the Navigator panel

E. Add wsadmin and DB2 scripts

We will complete our user programs by adding wsadmin scripts written in JACL, and DB2 scripts that will be used by the user programs. The JACL scripts will be used to configure the WebSphere Application Server - Express environment, including setting up a JDBC connection to the database, creating a data source, and so on. DB2 scripts are used to create the databases and tables required to support PBA application.

Scripts required by our PBA sample application:

  • JACL scripts:
    • CheckAppInstall.jacl

      This script is called by PBAWinPDC.java to check if the PBA application is already installed on the system.

    • EditMap.jacl
      ViewApp.jacl

      In WebSphere Application Server - Express, each module of an application can be mapped to one or more target servers. The target server can be an application server, cluster of application servers, or a Web server. Modules can be installed on the same application server or dispersed among several application servers. The selected Web server will serve as routers for requests to your application.

      Our PBA application has two modules, PBudgetEJB and PBudgetWeb. EditMap.jacl and ViewApp.jacl are used to map both modules to the following server:

      WebSphere:cell=<Computer_Name>Node01Cell, node=webserver1_node, server=webserver1
      WebSphere:cell=<Computer_Name>Node01Cell, node=<Computer_Name>Node01, server=server1

      <Computer_Name> is the target computer name you enter during the deployment of the PBA application.

    • WebSphereScript.jacl
      WebSphereConfigProcs.jacl
      SetupProcs.jacl

      WebSphereScript.jacl invokes both WebSphereConfigProcs.jacl and SetupProcs.jacl to accomplish the following:

      • Install the PBA application.
      • Create JDBC Provider.
      • Create DB2 Data Source.
      • Create JAAS authorization alias for database authentication at run time.

      SetupProcs.jacl is used to set values for all the required variables and WebSphereConfigProcs.jacl contains the actual implementation of the above tasks.

  • DB2 scripts:
    • DB2Script.bat
    • CreateTables.ddl

      These scripts are used to create the DB2 database and tables.

All these scripts are taken from IRU2_1_1SampleWin application project and are customized for our PBA application. The customized version of the scripts can be downloaded from the download ZIP file.

Figure 20 shows you all the required components to set up the PBA application.

Figure 20. Complete picture of all the required components to set up PBA application
Complete picture of all the required components to set up PBA application

We will now create a folder in the PBA application project in which to keep all the files required for setting up the PBA application:

  1. Copy PersonalBudget.ear and all the scripts from the download file to a newly created folder called PBA in the C: directory.

  2. From the Package Explorer panel, expand the PBA folder. Right click on src/PBA/userPrograms and select New => Folder.

  3. Enter PBA_ScriptsDir for the Folder name field and click Finish.

  4. Copy all the scripts shown in Figure 21 (without the PersonalBudget.ear) to the PBA_ScriptsDir folder. One way to do this is to drag the files in Windows Explorer to the newly created PBA_ScriptsDir folder in Developer's Package Explorer. The PBA_ScriptsDir should looks like Figure 21.

    Figure 21. Script files required by predeployment checker and main program
    Script files required by predeployment checker and main program

    Next, we will go back to the Application Wrapper Editor to add all the files needed by the PBA application.

  5. Switch to the Files tab and click on the Add button under the Software Image Files section. Select Yes if you get a pop-up window that says the software image root is not set. Browse to C:\PBA directory and click OK.

  6. In the Add Files window, select PersonalBudget.ear from the list and click Finish. C:\PBA is now set as the Source directory and PersonalBudget.ear is added to the Files list.

  7. Save the changes by pressing Ctrl-S.

    Figure 22. PersonalBudget.ear which is required to run the main installation is added to the Software Image Files section
    PersonalBudget.ear which is required to run the main installation is added to the Software Image Files section

F. Complete PBA application project

The last step is to perform the task of building the PBA application wrapper:

  1. From Express Runtime Explorer, right click on the PBA folder and select Generate Application.

  2. Once the application is generated successfully, the Application Generation Successful message will appears. Click OK. (The message will also appear in the console window.) The binary file PBA_win.ser is created in the <ER_workspace_dir>\SolutionEnabler\workspace\PBA\bin\PBA folder.

  3. Next, we will generate the deployment package for PBA. Right click on the PBA folder and select Generate Deployment Packages. A pop-up window appears stating the package has been generated successfully. Click OK. This creates the JAR file pba.xx.jar in the <ER_workspace_dir>\SolutionEnabler\workspace\IRU_common_resources\mediaJars> folder. The application PersonalBudget.ear is packaged into this JAR file.

The creation of the PBA application wrapper is now completed. Since the rest of the application wrappers come with the Express Runtime installation, our next step is to create a solution wrapper to package all the required application wrappers together.

G. Create PBASolution solution project

  1. From the Express Runtime Developer, create a new solution project by selecting File => New => Solution Project.

  2. Enter PBASolution as the Project name and click Next.

  3. In the next dialog, enter the following values and click Finish to complete the creation of PBASolution solution project:

    • Solution ID: PBASolution
    • Solution Title: Personal Budget Analysis Solution
    • Default Language: English
    • Wrapper file name: solution.sxml

From the Express Runtime Explorer panel, you will now see that the PBASolution solution project is created and the Solution Wrapper Editor Welcome page is displayed in the right pane, as shown in Figure 23.

Figure 23. Solution Wrapper Editor Welcome page
Solution Wrapper Editor Welcome page

H. Edit Solution Wrapper Editor

In this step, we will use the Solution Wrapper Editor to edit the PBASolution solution wrapper:

  1. The General tab provides the details you specified above, including the general information of the solution project. Click on the General tab and enter the following values in the Basic Solution Configuration section:

    • ID: PBASolution
    • Title: Personal Budget Analysis Solution
    • Version: 1.0
  2. Enter the following values in the Welcome Screen Configuration section:

    • Welcome screen title: Personal Budget Analysis (PBA) V1.0
    • Welcome screen text: This solution will deploy Personal Budget Analysis (PBA) V1.0 and three IBM middleware components which consist of: <br>- WebSphere Application Server - Express Edition V6.0 <br>- DB2 Universal Database Express Edition V8.2 <br>- IBM HTTP Server V6.0.
    • Version: 1.0

The Tasks tab lets you define the applications needed to install a solution. In our case, the solution consists of the following application wrappers:

  • PBA
  • WebSphere Application Server - Express
  • DB2 Express
  • HTTP Server
  • Web server plug-in.

To add the above tasks into the PBASolution:

  1. From the Solution Tasks, select Add.

  2. In the Add window, select Create an empty task group and click Next.

  3. Enter Personal Budget Analysis in the Task group title field and enter Select the platform where Personal Budget Analysis application and middleware should be installed in the Task group prompt. Click Finish.

  4. Right click on the Task Group you have just created and select Add applications.

  5. In the Add Applications window, set the following values:

    • Parent task group: Personal Budget Analysis
    • Task description: PBA and Middleware for Windows
    • Operating System: Windows
  6. Select all applications needed by PBA, as shown in Figure 24, then click Finish.

    Figure 24. List of applications to be added to the Install Task
    List of applications to be added to the Install Task
  7. You should now have five applications in Personal Budget Analysis Task Group. Use the Up and Down button to re-order the tasks to have the following sequence:

    1. Application: IRU2_1_1DB2Express8_2Win
    2. Application: IRU2_1_1IHS6_0Win
    3. Application: IRU2_1_1WASExpress6_0Win
    4. Application: IRU2_1_1WebServerPluginForWAS6_0Win
    5. Application: PBA

    If you would like to use the Express Runtime console to administer the middleware, the management extension component for each middleware component needs to be added to your Install Task. The management extension components for all the three IBM middleware components are supplied with Express Runtime installation. (We will not use the Express Runtime Console for this exercise.)

  8. There is more than one application in PBASolution that uses DB2 User ID and password variables. To avoid users from providing the same information multiple times during deployment, we can make these variables shareable among the applications:
    1. Select Application: IRU2_1_1DB2Express8_2Win from the Solution Tasks list, then select the Add button in the Overridden application variables section.

    2. In the Override Application Variables window, select username from the Variables list and click Next. Set these values:

      • Appearance: Editable (default)
      • Behavior: Share the value of username with other variables
      • Shared as: DB2AdminUsernameWin
    3. Under the Shared Variable Value Configuration section, add validation requirements to username by following the steps outlined above, as shown in Figure 25.

      Figure 25. Specify validation requirements for username
      Specify validation requirements for username
    4. Select Application: IRU2_1_1DB2Express8_2Win from the Solution Tasks list, and click on the Add button in the Overridden application variables section.

    5. In the Override Application Variables window, select password from the Variables list and click Next. Set these values:

      • Appearance: Editable (default)
      • Behavior: Share the value of password with other variables
      • Shared as: DB2AdminPasswordWin
    6. Under the Shared Variable Value Configuration section, add validation requirements to password by following the same steps outlined above for username.

    7. Select Application: PBA from the Solution Tasks list, click the Add button in the Overridden application variables section.

    8. In the Override Application Variable window, select DB2UserId from the Variables list and click Next. Set these values:

      • Appearance: Editable (default)
      • Behavior: Share the value of DB2UserId with other variables
      • Shared as: DB2AdminUsernameWin
    9. In the Override Application Variable window, select DB2UserPassword from the Variables list and click Next. Set these values:

      • Appearance: Editable (default)
      • Behavior: Share the value of DB2UserPassword with other variables
      • Shared as: DB2AdminPasswordWin
  9. Save the changes by pressing Ctrl-S.

I. Complete PBASolution solution project

The last step is to perform the task of building the PBASolution solution wrapper:

  1. From Express Runtime Explorer, right click on the PBASolution folder and select Generate Solution.

  2. When the solution has generated successfully, a Solution Generation Successful message will display. Click OK. (The message will also appear in the Console window.)

The binary file PBASolution.ser is created in the <ER_workspace_dir>\SolutionEnabler\workspace\PBASolution\bin folder.

We have now completed the creation of the PBASolution solution wrapper, which consists of the PBA application and all the required middleware components.


Test the solution wrapper

PBASolution is now ready for testing. From the Package Explorer, right click on PBASolution and select Test in Deployment Wizard. (Alternatively, you can use the Deployment Wizard to deploy PBASolution. Start the Deployment Wizard by selecting Start => Programs => IBM Express Runtime 2.1 => Deployment Wizard.)

  1. In the Deployment Wizard, select File => Open, and locate PBASolution.ser file.

  2. You will be prompted to select the task you want to deploy. Select Personal Budget Analysis (PBA) and then Next.

  3. On the next screen, select Personal Budget Analysis and Middleware for Windows and then Next.

  4. You are required to provide the hostname or IP address of the target server where PBASolution and middleware components will be deployed. In our case, we will be deploying the PBA solution on the same computer on which we built it, so get the hostname of your machine by typing hostname in a Windows command prompt.

  5. Use the Add button to add the hostname or IP address to the Selected target computers list. Click on the Test connections button to see if the Deployment Wizard can connect to the target machine.

  6. On the next screen, you will be prompted to configure parameters for DB2 Express. You are required to enter the DB2 Administrator user ID and password (you can use db2admin for both ID and password for this exercise). By default, the installation directory for DB2 Express will be at C:\Program Files\IBM\SQLLIB. You can leave the remaining parameters as is.

  7. The subsequent pages will prompt you to provide configuration parameters information for HTTP Server, WebSphere Application Server - Express, and the Web server plug-in. You can leave all the default values.

    (You will notice that DB2 Administrator ID and password fields for Configure Parameters - PBA page are pre-filled with the values you entered in the Configure Parameters - DB2 Universal Database Express Edition page. This is because we overrode these variables earlier on. As a result, the user does not need to enter the variables multiple times in the Deployment Wizard.)

  8. The Summary panel provides information on the task that will be deployed, hostname or IP address of the target machine, as well as the estimated time needed to deploy all tasks. Press the Deploy All button to start the deployment of our PBA solution.

  9. When asked for the location files, select C:\PBA. The status bar on the last page will show you the progress of the deployment of PBASolution, as shown in Figure 26.

    Figure 26. Deployment of PBASolution is in progress
    Deployment of PBASolution is in progress
  10. You can check the messages generated by the Deployment Wizard from time to time to see if the installation of each component is successful by clicking on the Master log button. Alternatively, you can view the same file at: <ER_install_dir>\SolutionEnabler\logs\IRU_DeploymentWizard.log.

  11. A screen similar to Figure 27 will display when the deployment of PBA and the middleware finishes without any errors.

    Figure 27. PBA application and three middleware components have been deployed successfully
    PBA application and three middleware components have been deployed successfully

    You should also find the following messages in IRU_DeploymentWizard.log file:

    Click to see code listing

    ....
    IRU03000: The deployment was successful for IBM DB2 Universal Database Express Edition for 8.2.3
    ....
    IRU03000: The deployment was successful for IBM HTTP Server for Windows 6.0.2.0.
    ....
    IRU03000: The deployment was successful for IBM WebSphere Application Server - Express 6.0.2.
    ....
    IRU03000: The deployment was successful for  IBM Web server plug-ins for IBM WebSphere Application Server 
    for Windows 6.0.2.0.
    ....
    IRU03000: The deployment was successful for PBA 1.0.
    ....
    IRU06172: Task1 in solution <ER_install_dir>\...\PBASolution.ser deployed successfully
  12. Launch the WebSphere Application Server administrative console by selecting Start => Programs => IBM WebSphere => Application Server - Express v6 => Profiles => default => Administrative console.

  13. Log in to the administrative console with any user ID.

  14. From the left navigation bar, select Servers => Application servers. You will see that, currently, there is one application server called server1. You will also see that the definition for webserver1 is added in the administrative console by clicking on Servers => web servers, as shown in Figure 28.

    Figure 28. Definition for webserver1 is added in Administrative console
    Definition for webserver1 is added in Administrative console
  15. Within the console, you can generate a plug-in to update the plugin-cfg.xml file for webserver1, and propagating a plug-in button would let you propagate plug-in configuration information to webserver1.

  16. To check if the PBA application is installed, select Applications => Enterprise Applications. You should see PersonalBudget is listed as one of the applications installed on server1.

  17. The Resources => JDBC Providers link gives you information on the JDBC provider, PBADB2Provider, that was configured in WebSphere Application Server - Express through the JACL scripts we supplied in the PBA application wrapper. Clicking on PBADB2Provider will enable you to see its configuration.

    Besides the JDBC provider, data source and JAAS authentication have also been configured through JACL scripts. Information on data sources can be found by clicking on Data sources under the Additional Properties link. You will see that a data source called PBudget with jdbc/PBudget as the JNDI name has already been created. From the properties list, you will find that the Component-managed authentication alias is set to DB2AuthAlias, PBUDGET is set as the database name, and so on.

  18. The JAAS Authentication Configuration can be viewed from Security => Global security link. Under the Authentication section, click on JAAS Configuration => J2C Authentication data. You will find DB2AuthAlias is in the list with db2admin as the User ID. The ID and password are taken when the Deployment Wizard prompts the user for the DB2 User ID and password during the PBA solution deployment, as shown in Figure 29.

    Figure 29. User ID and password are set in the JAAS Authentication configuration that will be used to connect to DB2 Express
    User ID and password are set in the JAAS Authentication configuration that will be used to connect to DB2 Express
  19. To test the PBA application, open a browser and navigate to this URL http://localhost:9080/PBA. The application should execute, as shown in Figure 30.

    Figure 30. Main page for Personal Budget Analysis application
    Main page for Personal Budget Analysis application

    If you wish to further explore the sample application, more information on the business functions of the PBA application can be found above.

Congratulations! You have successfully packaged and deployed a complete solution, made up of WebSphere Application Server - Express, HTTP Server, DB2 Express and an EJB application.

Now that we have a packaged a working solution, we can distribute the solution to a customer environment using several methods: We can create installation CDs or DVDs for the entire solution, or we could place the solution on a staging server. Both methods enable you to deploy a solution either locally or remotely. Local deployment means the solution will be deployed on the same machine where the PBASolution and all the necessary files are kept, whereas remote deployment refers to the installation of solution on a remote computer.

Express Runtime also provides you with a tool called Express Runtime console, a single, Web-based user interface that enables you to perform administrative tasks on WebSphere Application Server - Express and DB2 UDB Express, or on Informix Dynamic Server and IBM HTTP Server.

For more information on packaging and deploying your solution, as well as using the Express Runtime console to manage the middleware components, see Resources.


Conclusion

Prior to IBM Express Runtime, ISVs needed to go through the complex process of obtaining, installing, configuring, and supporting middleware components from multiple suppliers that had multiple terms and conditions, different licensing structures, and so on. IBM Express Runtime offers a cohesive set of middleware components and a single environment that enables ISVs to create and deploy this middleware along with their own applications as a single package across multiple platforms more quickly and effectively than ever before.


Download

DescriptionNameSize
Code sampleIER_sampleapp.zip  ( HTTP | FTP )2.4 MB

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Rational, Information Management
ArticleID=102155
ArticleTitle=IBM WebSphere Developer Technical Journal: Leverage IBM Express Runtime to develop and deploy complete software solutions
publish-date=01182006