PDK sample setup

In this readme we explain in detail how to set up the PDK Lite V5 sample in the following environments:

We also describe how to change the default PDK Lite V5 application settings.

IBM WebSphere Application Server base V5.0

This section provides details on installing and running the PDK Lite V5.0 sample application in IBM WebSphere Application Server base V5.0.

Before you start

Before you start installing PDK Lite, check the following prerequisites:

System requirements

PDK Lite has the following system requirements:

Products required

The following product levels were used to develop and test PDK Lite. Please install these products at the specified version levels before attempting to install and run PDK Lite:

Information required

Before starting the PDK installation, make sure you have the following information available:

Installing the PDK sample

To install the PDK sample application in IBM WebSphere Application Server base V5.0:

  1. Download the PDK sample.
  2. Extract the PDK sample to the required location, for example: C:\ or /usr.
  3. Make sure you are logged in as a user with administrative privileges:
  5. On AIX or Linux, make sure DB2 has a TCP/IP node entry in the node directory for accessing the database node:
    1. At the command line:
      • su - db2inst1
      • db2 list node directory
    3. If the local node does not appear, use the following command to add it:
      • db2 catalog tcpip node <nodename> remote <hostname> server 50000
      • Set <nodename> to the host name of your machine, provided it conforms to DB2 naming conventions (starts with a letter, no dashes, up to 8 characters, etc.).
      • Set <hostname> to the host name of your machine.
      • Use the hostname command to find out the host name of your machine.
    5. Exit the db2inst1 shell back to your root login.
  7. Open a command window and change to the PDK_Lite folder:
  9. Edit the PDK environment variables setup script to match your environment:
  11. Set the script file permissions on AIX and Linux systems, from the PDK_Lite folder:
    • chmod 755 *.sh
    • chmod 755 TestDrive/Install/*/*.sh
  13. Start the run_all script, from the PDK_Lite folder:

When the script starts, you'll get another chance to confirm your environment variables settings. On Windows, close Notepad to return to the script, after you have re-checked the environment variables. The script will pause at each stage so you can review what's happening before continuing. On Windows, you'll see the DB2 command window open several times. Make sure you wait for the DB2 command window to finish before continuing the main script.

Running the PDK sample

When the run_all script completes, you should be able to access the sample Web site with the URL http://localhost/selfservice/index.html . Click Continue to enter the site. You can then start the PDK application by clicking Run Application in the side menu.

You are presented with a start window showing the Guild's coat of arms. Clicking Click here to get the latest balances displays the balances for all weather stations and the Guild of Weather Masters. From there, you can then enter an amount to transfer from the Guild to one of the stations using a text entry field and a drop-down menu. Once you have submitted your transfer request, you are told whether it has succeeded or failed. You can then return to the balance display page to review the balances.

IBM WebSphere Studio Application Developer

You can set up the PDK sample in IBM WebSphere Studio Application Developer. WebSphere Studio can be used to view or modify the application source code, and to run the application in the Studio test environment.

 

Note: This procedure assumes that you have already set up the required application databases. These are set up during the procedure described in IBM WebSphere Application Server base V5.0.

To install the PDK sample application in the IBM WebSphere Studio Application Developer V5.0 for Windows/Linux workspace:

  1. Log in as a user with database and JMS server access:
    • On Windows, the user should be a member of the Administrators and mqm groups.
    • On Linux, the user should be a member of the mqm and mqbrkrs groups. Also run the db2profile script to allow DB2 database access. For example, add the following to your ~/.bashrc script:
      • if [ -f /home/db2inst1/sqllib/db2profile ]; then
      • . /home/db2inst1/sqllib/db2profile
      • fi
  3. Download the PDK sample.
  4. Extract the PDK sample to the required location, for example:
    • C:\ on Windows
    • Your home directory (~) on Linux
  6. Stop WebSphere Application Server if it is running locally.
  7. Start Application Developer using the -data option to specify the PDK workspace folder, for example:
    • On Windows:
      • wsappdev -data C:\PDK_Lite\TestDrive\Resources\workspacePDK
    • On Linux:
      • wsappdev50 -data ~/PDK_Lite/TestDrive/Resources/workspacePDK
  9. Import the CICS J2C resource adapter into your WebSphere Studio workspace (Skip this step if you don't have access to the CICS J2C resource adapter. You'll need to remove the ExchangeRateJ2C EJB later.):
    1. Open the Server perspective.
    2. Select File -> Import... from the Studio main menu.
    3. In the Import window, select RAR file as the import source and click Next .
    4. In the next window, click Browse... , navigate to the RAR file to import, cicseci.rar for example, and click OK . Set the New project name to PDKConnector , and click Finish to import the J2C resource adapter.
  11. Import the PDK projects into your WebSphere Studio workspace:
    1. Select File -> Import... from the Studio main menu.
    2. In the Import window, select Existing Project into Workspace as the import source and click Next .
    3. In the next window, click Browse... , then navigate to the Build project folder, for example:
      • On Windows:
        • C:\PDK_Lite\TestDrive\Resources\workspacePDK\Build
      • On Linux:
        • ~/PDK_Lite/TestDrive/Resources/workspacePDK/Build
      • Click OK , then click Finish to import the project.
    5. Repeat steps 1 to 3 for each of the remaining PDK projects:
      • PDKSupport
      • PDKMessageUtil
      • PDKFinanceUtil
      • PDKFinanceEJB
      • CommandUtil
      • ExchangeRateServerEJB
      • ExchangeRateServerWeb
      • ExchangeRateServer
      • PDKLiteEJB
      • PDKLiteWeb
      • PDKLite
      • PDKCommandUtil
      • CommandServerEJB
      • CommandServerWeb
      • CommandServer
      • Servers
    7. Now that you have imported all of the PDK projects, open the Tasks view.
      • There may be 3 warnings for the CommandServerEJB project that can be ignored. If you have any errors, check that you imported all projects, including the CICS RAR file.
      • If you don't have access to the CICS RAR file, it is probably easiest just to disable the ExchangeRateJ2C EJB as follows:
      • Navigate to PDKLiteEJB -> ejbModule -> ejb-jar.xml in the Navigator view.
      • Open ejb-jar.xml in the EJB Deployment Descriptor editor and select the Source view.
      • Comment out the ExchangeRateJ2C session bean, for example:
        • <!-- <session id="ExchangeRateJ2C">
        • ...
        • </session>-->
      • Save your changes.
      • Select PDKLiteEJB -> Properties -> Java Build Path -> Projects in the Navigator view. Deselect the PDKConnector project and click OK .
      • You will still have a number of Connector related errors appearing in the Task view, but the application will run (without CICS integration).
  13. Next, we need to generate the EJB deployment code:
    1. Select then right-click the PDKLiteEJB project, and select Generate -> Deploy and RMIC Code... from the pop-up menu.
    2. In the Generate Deploy and RMIC Code window, click Select all to select all the EJBs, then click Finish .
    3. Repeat for the ExchangeRateServerEJB project.

    Note: Don't generate EJB deployment code for the CommandServerEJB project. The CommandServerSession EJB is implemented in the WebSphere command package, provided in the WebSphere runtime.

  15. Copy the Finance EJB remote classes to the PDKFinanceEJB project:
    1. Switch to the J2EE perspective.
    2. Select the J2EE Navigator view.
    3. Copy the remote classes from PDKLiteEJB -> ejbModule -> com.ibm.pdk.ejb.finance to PDKFinanceEJB -> com.ibm.pdk.ejb.finance :
      • Finance.java
      • _Finance_Stub.java
      • FinanceHome.java
      • EJSStatelessFinanceHomeBean_xxxxxx.java
      • EJSRemoteStatelessFinanceHome_xxxxxx.java
      • _FinanceHome_Stub.java
      • _EJSRemoteStatelessFinanceHome_xxxxxx_Tie.java
      • You should overwrite any existing files in PDKFinanceEJB.
  17. Next, we need to update the test server configuration:
    1. Open the test server configuration in the editor. In the J2EE Hierarchy view, right-click WebSphere v5.0 Test Environment under the Servers folder, and select Open .
    2. Install the J2C resource adapter in the test server (Skip this step if you don't have access to the CICS J2C resource adapter):
      1. Click the J2C tab, then click the Add... button on the right of the J2C Resource Adapters list under Node Settings.
      2. In the Create Resource Adapter window, select PDKConnector in the Resource Adapter Name field, then click OK .
      3. Select the new PDKConnector in the J2C Resource Adapters list, then click the Add... button on the right of the J2C Connection Factories.
      4. In the Create Connection Factory window, set Name to ECICICS , set JNDI name to eis/ECICICS , then click OK .
      5. In the Resource Properties list, set the properties required for your environment, for example ServerName, ConnectionURL, PortNumber, UserName, Password.
    4. Check that the PDK database authentication alias is correct. Click the Security tab and set your database access userid and password in the PdkDbAuthAlias JAAS Authentication Entry. We used db2admin on Windows, or db2inst1 on Linux.
    5. Check that the JMS variables are for correct for your JMS provider:
      1. Click the Variables tab and check the MQ_INSTALL_ROOT and WAS_PUBSUB_ROOT variables.
      2. Also make sure the com.ibm.ws.messaging.JMSProvider entry in the <STUDIO_INSTALL>/runtimes/base_v5/properties/implfactories.properties file is pointing to the correct class.

      For the WebSphere Application Server embedded JMS provider (with WebSphere Application Server installed locally), we used:

      • MQ_INSTALL_ROOT to C:/WebSphere MQ on Windows, or /opt/mqm on Linux.
      • WAS_PUBSUB_ROOT to C:/WebSphere MQ/WEMPS on Windows, or /opt/wemps on Linux.
      • In the implfactories.properties file, set com.ibm.ws.messaging.JMSProvider to com.ibm.ws.messaging.JMSEmbeddedProviderImpl

      For the WebSphere Studio unit test JMS provider (with WebSphere Application Server not installed locally):

      • MQ_INSTALL_ROOT to ${WAS_INSTALL_ROOT}/mqjms.
      • WAS_PUBSUB_ROOT is left blank.
      • In the implfactories.properties file, set com.ibm.ws.messaging.JMSProvider to com.ibm.ws.messaging.JMSMQJDProviderImpl
    7. Save server configuration if required, then close the editor.
  19. Start the test server.
  20. Open the PDK home page:
    • In the Navigator view, select PDKLiteWeb , then right-click and select Run on Server from the pop-up menu.
  22. Try a funds transfer using Web services:
    1. Click the link to get the latest balances. Balances for each planet should be displayed.
    2. Enter an amount greater than zero, select To JUPITER (Jupiter is configured to use Web services by default), and click Transfer .
    3. You should get a message that funds have been transferred to the designated weather station.
  24. Repeat for the other back-end connection technologies that are available in your environment. The default technologies for each planet are:
    • MARS uses no back-end (Stand-Alone Single Channel application pattern).
    • JUPITER uses Web services.
    • NEPTUNE uses the J2EE Connector and CICS.
    • PLUTO uses JMS and WebSphere MQ.

Changing the default settings

Once you have installed the PDK, it is ready to run without any alteration. However, there are options you can specify to produce different effects, or to change the underlying technologies used, without having to change any source code.

Selecting different topologies

The ExchangeRate session bean controls which topology is used for each planet in order to retrieve the exchange rate during a funds transfer. By default, the topologies that are executed are:

To change the topology, edit the backendList environment entry defined in the PDKLiteEJB module deployment descriptor for the ExchangeRate session EJB.

You can edit the deployment descriptor in IBM WebSphere Studio Application Developer V5.0, or in the Application Assembly Tool provided with WebSphere Application Server (type assembly from a command prompt).

Configuring access to a CICS server

The PDK sample application can be configured to access a CICS server using the WebSphere Administrative Console to set the ECICICS J2EE Connector adapter properties.

Source code for our CICS application is available in com/ibm/pdk/ejb/exchangeJ2C/cics/calcrate.c included in the PDKLiteEJB module.

Configuring access to a remote Web services server

The PDK sample application can be configured to access the back-end Web service running in a remote application server.

To access a remote server, edit the exchRateServerUrl environment entry defined in the PDKLiteEJB module deployment descriptor for the ExchangeRateWS session EJB.

You can edit the deployment descriptor in IBM WebSphere Studio Application Developer V5.0, or in the Application Assembly Tool provided with WebSphere Application Server (type assembly from a command prompt).

Deploy the updated PDK applications on the front-end application server as normal. Then deploy just ExchangeRateServer.ear on the remote application server.

Changing the results page

By default, the weather stations are displayed in a rich graphical page, using special view bean methods to calculate the number of different pieces of weather reading equipment a station can afford.

If you would like to use a simpler (and faster) display, you can change the Struts action mapping for the display funds action in the WEB-INF/struts-config.xml file.

Change the "success" forward for the /displayFunds action path from:

to:

Using the command factory

Servlets in the Web application determine which type of command to use by making a call to the command factory Singleton class's getCommand(String type) method, passing the class name of the interface the command must implement (for example, GetAllBalancesCommand). This factory reads from the environment entries defined in the PDKLiteWeb module deployment desciptor. These environment entries map interfaces to implementing classes.

If you decide to write a new implementation, say of the GetAllBalancesCommand interface, edit the GetAllBalancesCommand environment entry to specify your new class as that which the factory should return.

You can edit the deployment descriptor in IBM WebSphere Studio Application Developer V5.0, or in the Application Assembly Tool provided with WebSphere Application Server (type assembly from a command prompt).

Using the command target factory

Similarly the type of Command Target to use is determined by making a call to the CommandTargetFactory class's getTarget() method. This returns an instance of the first valid class found using the commandTargetList environment entry defined in the PDKLiteWeb module deployment desciptor. To change the default Command Target, you must edit this environment entry. The PDKLiteWeb module also has an environment entry for each of the three provided Command Targets:

List only the command targets you want to use in the commandTargetList environment entry, colon (:) separated.

For example, listing only "commandTargetLocal" in commandTargetList will leave only the com.ibm.pdk.commandTargetUtil.LocalCommandTarget class. This ensures that all servlets use the command targeting policy best suited to running your Web and EJB containers on the same machine.

You can edit the deployment descriptor in IBM WebSphere Studio Application Developer V5.0, or in the Application Assembly Tool provided with WebSphere Application Server (type assembly from a command prompt).

Adding new weather stations

You can add your own weather stations to the PDK Lite, by following these steps:

  1. Edit the file stations.txt under the PDK_Lite\TestDrive\Install\07ImportStationData directory and add in a new station name and a starting funds balance, for example: "MERCURY",575000
  2. Run the runImportStationsData script to import your new station data into the database.
  3. Add your new weather station to the stationsList environment entry in the PDKLiteEJB module, for example:
    • MARS:JUPITER:NEPTUNE:PLUTO:MERCURY.
    • You can edit the deployment descriptor in IBM WebSphere Studio Application Developer V5.0, or in the Application Assembly Tool provided with WebSphere Application Server (type assembly from a command prompt).
  5. To supply an image for your new station, you must use the file-naming convention of <STATION_NAME>.gif, and copy your file to the images/stations folder in the PDKLiteWeb module.
  6. Re-deploy the PDKLite.ear application and your new weather station should appear with the others when you click the link to get the latest balances. Its name is also added to the drop-down menu for you.

Improving performance

You can make the PDK Lite application run faster by disabling the comments written to the <WAS_HOME>/logs/server1/SystemOut.log file by the Java components in the PDK (servlets, command beans, and so on).

By default, debug mode is set to true. To set it to false, edit the file Logger.properties, found in the PDKSupport module that is packaged in each of the PDK enterprise applications (PDKLite.ear, ExchangeRateServer.ear, and CommandServer.ear). Change the line debug=true to debug=false .