PDK Lite V 4.1 setup

Before you start

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

• System requirements
• Products required
• Information required

Information required

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

• PDK Lite installation directory. If you plan to extract the PDK sample to C:\, for example, then the PDK Lite installation directory will be C:\PDK_Lite.
• IBM WebSphere Application Server installation directory, for example, C:\WebSphere\AppServer.
• IBM HTTP Server installation directory, for example, C:\IBM HTTP Server.
• IBM DB2 installation directory, for example, C:\Program Files\SQLLIB.
• IBM MQSeries installation directory, for example, C:\Program Files\IBM\MQSeries.
• JCA resource adapter archive file name and path, for example, C:\Program Files\IBM\IBM CICS Transaction Gateway\deployable\cicseci.rar.
• Machine or node name. To check your machine name, open a command window and run the hostname command. Note that the WebSphere node name is case sensitive.
• IBM DB2 userid and password for database access, for example, db2admin on Windows, or db2inst1 on AIX or Linux.

Selecting different topologies

The Finance Session controls which topology will be used for each planet in order to retrieve the exchange rate during a funds transfer. By default, the topologies which are executed are:

• MARS - back-end integration using JMS and MQSeries
• JUPITER - back-end integration using JCA and CICS
• NEPTUNE - no back-end integration
• PLUTO - back-end integration using Web services

To change the topology, edit the properties file packaged with the Finance session EJB. After installation of the PDK this file can be found in the <WAS_HOME>/installedApps/PDK_Lite.ear/FinanceEJB.jar file, and is named FinanceTopology.properties. Edit this file, select the desired topology and save it before restarting the PDK Server in WebSphere Application Server. After the FundsTransfer command completes successfully you will be reminded of the topology used.

Configuring access to a CICS server

The PDK sample application can be configured to access a CICS server using the following options:

• JCA option
• • Use the WebSphere administrative console to set the ECICICS JCA adapter properties.
• JCAEIS option
• • Edit the com/ibm/pdk/eis/exchangeCICSECI/ExchangeRateCICSECI.wsdl file in ExchangeRateEIS.jar to set the ExchangeRateCICSECIService properties.

Source code for our CICS application is available in com/ibm/pdk/eis/exchangeCICSECI/calcrate.c included in ExchangeRateEIS.jar.

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 as follows:

1. Deploy PDK WebServices.ear on the remote application server.
2. On the local PDK Server, edit the ExchangeRateWSBean.properties file in ExchangeRateWSEJB.jar and change the hostname entry from localhost to the remote server's hostname.
3. Restart the local PDK 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:

1. Edit the DisplayFundsServlet.properties file under the guild_funds Web module directory <WAS_HOME>\installedApps\PDK_Lite.ear\PDKLiteWeb.war.
2. Use a '#' character to comment out the line:
3. • resultsPage=/displayFundsRichResults.jsp
   • and remove the '#' from the start of the line:
   • #resultsPage=/displayFundsSimpleResults.jsp
4. Re-start the default server from the WebSphere administrative console, and when you run the Web application, a different JSP will be used (this file is read from the DisplayFundsServlet's init() method).

Using the Command Factory

Servlets in the Web application determine which type of Command to use by making a call to the CommandFactory singleton class's getCommand(String type) method, passing the fully qualified class name of the interface the command must implement (for example, com.ibm.pdk.command.GetAllBalancesCommand). This factory reads from the configuration file CommandFactory.properties, which is part of the commandUtil.jar archive stored at the top level of the PDK EAR file (<WAS_HOME>\installedApps\PDK_Lite.ear\commandUtil.jar). This maps interfaces to implementing classes. If you decide to write a new implementation, say, of the GetAllBalancesCommand interface, edit this file to specify your new class as that which the factory should return. Then export it, along with you class file in to the commandUtil.jar file.

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 listed in the CommandTargetFactory.properties file, which is part of the commandTargetUtil.jar archive. To change the default Command Target, you must also edit this file, thus:

• Disable any command target classes you do not want to use. For example, remove or comment out (using '#') the lines:
• • commandTargetClass1=com.ibm.pdk.commandUtil.HttpServletCommandManagerTarget
  • and:
  • commandTargetClass2=com.ibm.websphere.commandUtil.EJBCommandManagerTarget
  • to leave only the com.ibm.pdk.commandUtil.LocalCommandTarget class. This will ensure that all servlets use the command targeting policy best suited to running your servlet engine and your EJB container on the same machine.

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\10ImportStationData 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 FinanceEJB.jar, for example, MARS:JUPITER:NEPTUNE:PLUTO:MERCURY.
4. • You can set the environment entry in the FinanceEJB deployment descriptor, meta-inf\ejb-jar.xml, included in the JAR file. You can also use the Application Assembly Tool (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 <WAS_HOME>\installedApps\PDK_Lite.ear\PDKLiteWeb.war\images\stations directory.
6. Re-start the PDK Server from the WebSphere administrative console.
7. Your new weather station should appear with the others when you click the link to get the latest balances. Its name will also be added to the drop-down menu for you.

Improving performance

You can make the guild_funds Web application run faster by disabling the comments written to the <WAS_HOME>/logs/PDK/stdout.txt file by the Java components in the PDK (servlets, command beans, and so on). By default, 'debug' mode is set to true. To set to false:

1. Edit the file Logger.properties, found in the utility.jar file which is included in each of the PDK enterprise applications (PDK_Lite.ear, PDK_WebServices.ear, PDK_CommandServer.ear).
2. Change the line debug=true to debug=false.
3. Re-start the PDK Server from the WebSphere administrative console.

To install the PDK sample application in the IBM WebSphere Studio Application Developer Integration Edition V4.1.1 for Windows workspace:

1. Download the PDK sample.
2. Extract the PDK sample to the required location, for example: C:\.
3. Check that system library path is correctly set up for MQSeries JMS support:
4. • In Windows, the system PATH environment variable should include <MQ_HOME>\Java\lib. For example, C:\MQSeries\Java\lib;...
5. Start Application Developer using the -data option to specify the PDK workspace folder, for example:
6. • wsappdev.exe -data C:\PDK_Lite\TestDrive\Resources\workspacePDK
7. Check the MQ_HOME workspace classpath variable:
8. • In Application Developer, select Window -> Preferences -> Java -> Classpath Variables from the main menu.
9. Check the enterprise application paths:
10. 1. Open the Server perspective.
    2. In the Navigator view, open PDKLite -> META-INF -> application.xml .
    3. If you get a message about auto-correcting the absolute path, click Yes then save application.xml.
    4. Close application.xml.
    5. Repeat 1 to 4 for the PDK CommandServer and ExchangeRateWSServerEAR enterprise applications.
11. Install the JCA adapter in the workspace:
12. 1. Open the Enterprise Services perspective.
    2. Select Resource Adapters , then right-click and select New -> Add Resource Adapter in the pop-up menu.
    3. In the RAR Import window, select to the required RAR file, set the resource adapter name to "CICS ECI", and click Finish .
    4. • You can find the CICS ECI RAR file in com.ibm.wsadie.a.Cab in the IBM WebSphere Studio Application Developer Integration Edition CD-ROM/install package. Use WinZip to extract the RAR file.
13. Check the server instance paths, JDBC settings, and JCA adapter:
14. 1. In the Server perspective, Navigator view, open PDKServer -> PDK Server Conf.wsc -> server-cfg.xml .
    2. If you get a message about auto-correcting the paths, click Yes .
    3. In the server-cfg.xml Data source view, select the XADb2Driver JDBC driver and check the Default user id and password settings for the Guild and Stations Data sources.
    4. Install the J2C resource adapter in the test server:
    5. 1. In the J2C view, click the J2C Resource Adapters Add... button, then click OK to create the resource adapter.
       2. Click the J2C Connection Factories Add... button, set the Name and the JNDI name to ECICICS, then click OK to create the connection factory.
       3. Set the resource properties required for your environment, for example: ServerName, ConnectionURL, PortNumber, UserName, Password.
    6. Save server-cfg.xml if required then close server-cfg.xml.
15. Check the MQ_HOME server path mapping:
16. 1. Start the PDK Test Domain server instance from the Server perspective, Servers view. (If the server instance isn't there, right-click the PDKServer project and select Refresh From Local .)
    2. Right-click the PDK Test Domain server instance and select Run administrative client from the pop-up menu.
    3. Login to the administrative client, then navigate to Nodes -> localhost -> Path Map -> Entries .
    4. Click the MQ_HOME symbolic name and check its path setting.
    5. Save the server configuration if required.
    6. Exit from the administrative client.
    7. Stop then restart the PDK Test Domain server instance.
17. Add the required MQ JNDI names to the test server JNDI namespace and start the back-end MQSeries application:

18.  

    Note: This step must be carried out every time you restart the PDK Test Domain server instance

    1. Make sure the required variables in the PDK environment setup script, PDK_Lite\environment.cmd, are correctly set for your environment.
    2. Open a command window.
    3. Change to the PDK_Lite\TestDrive\Install\17MQSetup folder
    4. To add the JNDI names, run the WSAD_JMSsetup script.
    5. Make sure the PDK queue manager is started, for example:
    6. • strmqm PDK.QUEUE.MANAGER
    7. To start the MQSeries back-end application, run the PDKServerStart script.
19. Open the PDK home page:
20. • In the Navigator view, select PDKLiteWeb , then right-click and select Run on Server from the pop-up menu.
21. Try a funds transfer using Web services:
22. 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 PLUTO (Pluto 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.
23. Repeat for the other back-end connection technologies that are available in your environment. The default technologies for each planet are:
24. • MARS uses JMS and MQSeries.
    • JUPITER uses JCA and CICS.
    • NEPTUNE uses Enterprise Services, JCA and CICS.
    • PLUTO uses Web services.

To install the PDK sample application in the IBM WebSphere Studio Application Developer V4.0.2 for Windows workspace:

1. Download the PDK sample.
2. Extract the PDK sample to the required location, for example: C:\.
3. Check that system library path is correctly set up for MQSeries JMS support:
4. • In Windows, the system PATH environment variable should include <MQ_HOME>\Java\lib. For example, C:\MQSeries\Java\lib;...
5. Install the Application Developer zip creation plug-in:
6. 1. Open PDK_Lite\TestDrive\Resources\std\zipCreation.zip.
   2. Extract zipCreation.zip into the Application Developer installation/plugins folder, for example C:\Program Files\IBM\Application Developer\plugins.
   3. Verify that a new Application Developer installation/plugins/com.ibm.sample.zip.creation folder has been created.

    

   Note: You can find details on this plug-in in WebSphere Developer Domain article, Developing J2EE utility JARs in WebSphere Studio Application Developer , at: http://www7b.boulder.ibm.com/wsdd/library/techarticles/0112_deboer/deboer2.html

7. Update PDK project files to use the Application Developer zip creation plug-in:
8. 1. Open PDK_Lite\TestDrive\Resources\std\zipConfig.zip.
   2. Extract zipConfig.zip into the same locate as the PDK sample, for example: C:\.
   3. You should be prompted to confirm overwrite of four .prj files and four .vcm_meta files. Click Yes to confirm each file overwrite.
9. Start Application Developer using the -data option to specify the PDK workspace folder, for example:
10. • wsappdev.exe -data C:\PDK_Lite\TestDrive\Resources\workspacePDK
11. Check the MQ_HOME workspace classpath variable:
12. • In Application Developer, select Window -> Preferences -> Java -> Classpath Variables from the main menu.
13. Check the enterprise application paths:
14. 1. Open the Server perspective.
    2. In the Navigator view, open PDKLite -> META-INF -> application.xml .
    3. If you get a message about auto-correcting the absolute path, click Yes then save application.xml.
    4. Close application.xml.
    5. Repeat 1 to 4 for the PDK CommandServer and ExchangeRateWSServerEAR enterprise applications.
15. Check the server instance paths and JDBC settings:
16. 1. In the Navigator view, open PDKServer -> PDK Server Conf.wsc -> server-cfg.xml .
    2. If you get a message about auto-correcting the paths, click Yes .
    3. In the server-cfg.xml Data source view, select the XADb2Driver JDBC driver and check the Default user id and password settings for the Guild and Stations Data sources.
    4. Save server-cfg.xml if required then close server-cfg.xml.
17. Rebuild all projects in the correct order by right-clicking on each an selecting Rebuild Project from the pop-up menu. The required order is:
18. 1. PDKSupport
    2. PDKCommandUtil
    3. PDKCommandTargetUtil
    4. ExchangeRateEIS
    5. All remaining ExchangeRateXXX projects
    6. GuildEJB and StationsEJB
    7. FinanceEJB
    8. All PDK CommandServerXXX
    9. PDKLite and PDKLiteWeb
19. Check the MQ_HOME server path mapping and add connector.jar to JMS provider:
20. 1. Start the PDK Test Domain server instance from the Server perspective, Servers view. (If the server instance isn't there, right-click the PDKServer project and select Refresh From Local .)
    2. Right-click the PDK Test Domain server instance and select Run administrative client from the pop-up menu.
    3. Login to the administrative client, then navigate to Nodes -> localhost -> Path Map -> Entries .
    4. Click the MQ_HOME symbolic name and check its path setting.
    5. Navigate to Resources -> JMS Providers .
    6. Select the IBM MQSeries JMS Provider.
    7. Add connector.jar to the start of the Server Class Path property:
    8. • ${MQ_HOME}/java/lib/connector.jar; ${MQ_HOME}/java...
    9. Click OK .
    10. Save the server configuration.
    11. Exit from the administrative client.
    12. Stop then restart the PDK Test Domain server instance.
21. Add the required MQ JNDI names to the test server JNDI namespace and start the back-end MQSeries application:

22.  

    Note: This step must be carried out every time you restart the PDK Test Domain server instance

    1. Make sure the required variables in the PDK environment setup script, PDK_Lite\environment.cmd, are correctly set for your environment.
    2. Open a command window.
    3. Change to the PDK_Lite\TestDrive\Install\17MQSetup folder.
    4. To add the JNDI names, run the WSAD_JMSsetup script.
    5. Make sure the PDK queue manager is started, for example:
    6. • strmqm PDK.QUEUE.MANAGER
    7. To start the MQSeries back-end application, run the PDKServerStart script.
23. Open the PDK home page:
24. • In the Navigator view, select PDKLiteWeb , then right-click and select Run on Server from the pop-up menu.
25. Try a funds transfer using Web services:
26. 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 PLUTO (Pluto 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.
27. Repeat for the other back-end connection technologies that are available in your environment. The default technologies for each planet are:
28. • MARS uses JMS and MQSeries.
    • JUPITER uses JCA and CICS (not available).
    • NEPTUNE uses Enterprise Services, JCA and CICS (not available).
    • PLUTO uses Web services.