README

Pattern Development Kit Lite - Version 3.0 (EJB Version)

System Requirements - hardware
System Requirements - software
Products Required
Information Required
How to Run PDK Lite EJB
Tips & Warnings
Known issues
Default settings and how to change them
Finding the source code
Suggested Reading

System Requirements - hardware Top

PDK Lite was developed on an IBM ThinkPad 600X with 512Mb of RAM and a 650Mhz Pentium III processor. We recommend that you have no less than 256Mb of memory and a Pentium II processor.

System Requirements - software Top

PDK Lite is designed to run on Windows NT 4.0 with Service Pack 6A. (Please note - although it is not yet a supported configuration, the PDK Lite Enterprise Application has been seen to work equally well on Windows 2000. It is hoped that in the near future this will be an officially supported platform. In the mean time, we welcome your comments and experiences in using the PDK Lite on the Windows 2000 platform. As with all feedback, please contact us, the UK Advanced Solutions Group with your comments.

Products Required Top

The following product levels were used to develop and test PDK Lite. There may well be cases where more recent releases, or different versions would work equally well. However, the configuration outlined below is the only one supported.

Install the following products at the specified version levels before attempting to install and run PDK Lite:

WebSphere Application Server Advanced Edition V4.0 for NT (including IBM HTTP Server V1.3.19 for NT) or WebSphere Application Server Single Server Edition V4.0 for NT (including IBM HTTP Server V1.3.19 for NT) (get a free trial copy)
DB2 Universal Database UDB 7.2 (get a free trial copy and the required fixpack)
Either Internet Explorer 5.0 or Netscape Navigator 4.7

Install the following products at the specified version levels before attempting to edit the source for this version of the PDK Lite:

VisualAge Java Version 4 Enterprise Edition for Windows

Information Required Top

Make sure you have the following information available when running the run_all.cmd: / run_all_singleserver.cmd

Machine name (To find your machine name, simply type "hostname" from a command prompt. Your machine name will be echoed to the screen.)
PDK Lite path (e.g. C:\PDK_Lite)
WebSphere install directory (e.g. C:\WebSphere\AppServer)
IBM HTTP Server install directory (e.g. C:\IBM HTTP Server)
DB2 install directory (e.g. C:\Program Files\SQLLIB)

How to Run PDK Lite Top

To install and configure the Pattern Development Kit Lite:

Extract the PDK files to your hard drive (e.g.C:\PDK_Lite)
WebSphere Single Server Edition Users - Run the command file run_all_singleserver.cmd in the PDK directory to which you have extracted the PDK files
WebSphere Advanced Edition Users - Run the command file run_all.cmd in the PDK directory to which you have extracted the PDK files

You will be prompted to provide information such as your machine's hostname, and the location of the requisite products. At this stage you can also specify whether or not you want the scripts to echo a more detailed description of what is going on for each step. When asked to edit the environment.cmd file, set VERBOSE=TRUE for this additional information. For simplicity, when configuring IBM HTTP Server, you are presented only with a subset of the http.conf configuration file, called changes.conf. This is merged with the rest of the file afterwards and the entire http.conf file is displayed.

The last command run by the run_all.cmd launches a browser window with the URL http://localhost. From here you can navigate through the sample web site, then click the 'Topology 1' link which starts the guild_funds web application. You will be presented with a start screen showing the Guild's coat of arms, and a button labelled 'Retrieve latest balances'. Clicking this will result in the display of 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 will be told whether it has succeeded or failed. You can then return to the balance display page to review the balances.

Tips & Warnings Top

You MUST run the run_all.cmd / run_all_singleserver.cmd script under a userid with administrative privileges (i.e. member of the NT 'Administrators' group. You must then be logged on with the same ID when you run PDK Lite. This ID must be acceptable to DB2 (e.g. must not be longer than 8 characters)
When you are prompted to hit a key to continue, it is important that you do so, as the next script will not start until the previous one has completed.
The NODENAME environment variable MUST be entered in lower case.
Single Server Users - when configuring the JDBC driver and DataSources, it is very important not to include any whitespace characters in the driver/datasource names, JNDI names etc. Doing so will prevent the application from working. Whitespace characters can appear if you copy from the instructions HTML page, and paste in to the Administrative Console. Check carefully before committing your changes.
It is assumed that your WebSphere node's name will be the same as your machine name (hostname). This is the default configuration.
When entering product paths, DO NOT add in quotes, EVEN IF the path includes spaces.
When editing configuration files, don't forget to SAVE and CLOSE the file to allow the command script to continue.
When starting the Default Server, it is vitally important that you wait for hard drive activity to stop before attempting to run the browser (see picture below). If you do not, you may not get the desired results.
When you have finished reading this document, close this window to continue with the setup. To open again, double-click the README.html file in the PDK Lite directory.

Known Issues Top

If a the PDK attempts to stop a service that has already been stopped, or vice-versa, you may see an error. You can ignore this.
The Advanced Edition version of the PDK Lite copies duplicate application JAR files in to the %WASDIR%\lib\app directory as a workaround to an unresolved CLASSPATH issue. This problem does not occur with WebSphere Single Server Edition, hence the JARs are not copied.
The Single Server Edition version of the PDK Lite copies the db2java.zip file from the %DB2DIR%\java directory, to the %WASDIR%\lib\app directory as a workaround to an unresolved issue where the Application Server fails to find the COM.ibm.db2.jdbc.DB2XADataSource class required by the Two Phase Commit enabled JDBC driver. This problem does not occur with WebSphere Advanced Edition, hence the zip file is not copied.

Default settings and how to change them Top

Once you have built 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.

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:
- Edit the DisplayFundsServlet.properties file under the guild_funds web module directory (e.g. C:\WebSphere\AppServer\installedApps\PDK_Lite_EJB.ear\PDK_Lite_EJB_WebApp.war).
- Use a '#' character to comment out the line: resultsPage=/displayFundsRichResults.jsp and remove the '#' from the start of the line #resultsPage=/displayFundsSimpleResults.jsp.
- Re-start the default server from the WebSphere Administrator's Console, and when you run the web application, a different JSP will be used (this file is read from the DisplayFundsServlet's init() method).
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 (e.g. com.ibm.pdk.command.GetAllBalancesCommand). This factory reads from the configuration file CommandFactory.properties which maps interfaces to implementing classes. If you decide to write a new implementation, say, of the GetAllBalancesCommand interface, edit this file in VisualAge for Java to specify your new class as that which the factory should return. Then export it, along with you class file in to the shared.jar file.
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. To change the default Command Target, you must also edit this file in Visual Age, 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.
You can add your own weather stations to the PDK Lite, by following these steps:
- Edit the file stations.txt under the Artifact010 directory (e.g. C:\PDK_Lite\TestDrive\Artifact010) and add in a new station name and a starting funds balance, for example: "MERCURY",575000
- Run the runImportStationsData.cmd file to import your new station data in to the database.
- In the Application Assembly Tool (type assembly from a command prompt), open the PDK_Lite_EJB.ear file found in the Artifact015 directory (e.g. C:\PDK_Lite\TestDrive\Artifact015). WebSphere Administrative console, under WebSphere Administrative Domain -> Enterprise Applications -> PDK Lite EJB:
  - Expand EJB Modules -> GuildFinanceSession -> SessionBeans -> GuildFinanceSession
  - Select Environment Entries
  - In the right hand pane, select the "stationsList" entry
  - Edit the value line "MARS:JUPITER:NEPTUNE:PLUTO", to reflect the name of your new station, as defined in the STATIONS database (e.g. MARS:JUPITER:NEPTUNE:PLUTO:MERCURY)
  - Click 'Apply'
  - Save the ear file
  - Remove the PDK_Lite_EJB application, and reinstall it (or wait until you run the PDK_Lite reset script, and re-run the build script)
  - To supply an image for your new station, you must use the file naming convention of 'STATIONNAME.GIF', and copy your file to the web\images\stations directory off the guild funds web app directory e.g. C:\WebSphere\AppServer\installedApps\PDK_Lite_EJB.ear\servlets).
  - Re-start the default server from the WebSphere Administrator's Console.
Your new weather station should appear with the others when you click the Display All Balances button. Its name will also be added to the drop-down menu for you.
You can make the guild_funds web application run faster by disabling the comments written to the default_server_stdout.log file by the Java components in the PDK (servlets, command beans etc). By default, this 'debug' mode is set to true. To set to false:
- Edit the file Logger.properties, found under the WebSphere properties directory (e.g. C:\WebSphere\AppServer\properties)
- Change the line debug=true to debug=false
- Re-start the default server from the WebSphere Administrator's Console.

Finding the source code Top

You can find the PDK Lite source code under the PDK install directory Please note that the Studio project also contains Java source code. This means that the same code can be found in more than one place TestDrive\Resources\.

Java Source

The full PDK Lite source can be found in a JAR file, under Resources\Jar, off the PDK Lite install directory, e.g.:

C:\PDK_Lite\TestDrive\Resources\Jar\pdk_ejb_project.jar

In addition, the same code is also included in a VisualAge for Java repository file located under the Resources\VAJ directory, e.g.:

C:\PDK_Lite\TestDrive\Resources\VAJ\pdk_ejb_project.dat

To edit the code in VisualAge Java, import the .dat file into the VAJ workspace. A project called PDK_EJB will be added, with the packages used by the PDK Lite. To compile the classes, you will need to do the following:

Import the PDK_EJB Project into VAJ, adding it to the WorkSpace.
File -> Quick Start -> select 'Features' in the left hand pane, then 'Add Feature' in the right hand pane. Click OK.
In the 'Selection Required' dialog, select the following:
- IBM EJB Development Environment 3.5.3
- IBM WebSphere Test Environment 3.5.3
Click 'OK'. This will also add various other projects to your Workspace if not already there (e.g. Servlet API Classes 2.2) After the classes have been added, the 'All Problems' tab should not display any problems for the PDK_EJB project.

You can now edit, compile and export the code.

JavaServer Pages, Graphics and other resources

In line with the new J2EE application model, all the PDK resources can be found in the PDK_Lite_EJB.ear and Command_Servers.ear files, found, for example:

C:\PDK_Lite\TestDrive\Artifact015\PDK_Lite_EJB.ear

and

C:\PDK_Lite\TestDrive\Artifact016\Command_Servers.ear

You can examine these archives and the files therein either via the Application Assembly Tool (type assembly from a command prompt) or via an archive tool such as WinZip.

	Patterns for e-business: User-to-Business Patterns for Topology 1 and 2 using WebSphere Advanced Edition SG24-5864
	WebSphere Studio and VisualAge for Java Servlet and JSP Programming SG24-5755
	Servlet/JSP/EJB Design and Implementation Guide for IBM WebSphere Application Servers SG24-5754
	Connecting e-business to the Enterprise by Example SG24-5514