Getting Started

This section provides a step-by-step guide to getting the code and building the first five JDO Learning Tools.

Step One: Download Open Source JDO Learning Tools

Download the zip file containing the JDO Learning Tools from SourceForge.net by going to the following URL:

http://sourceforge.net/projects/jdo-tools

You can also obtain this code from the Apress Web site at http://www.apress.com. After the download, unzip the files to a directory of your choice. For simplicity, the instructions here will refer to the directory that you choose as the bookcode-home directory. Unless otherwise specified, all directory paths mentioned in this chapter are relative to your bookcode-home directory.

Estimated time excluding download: 5 minutes

Step Two: Download Java SDK If Necessary

The examples in this book were tested with the Java Software Development Kit (SDK, also known as JDK) version 1.3.1. The various implementations and the examples will likely work with a later version of the JDK, but this has not been tested. If you do not already have JDK 1.3.1, go to the following URL:

http://java.sun.com/j2se/1.3

Follow the instructions that come with the JDK to set up the Java development and runtime environments and verify that they are working.

Estimated time excluding the download: 20 minutes

Step Three: Download Ant If Necessary

If you do not already have Ant version 1.4.1, or a later 1.x version, go to the following URL:

http://ant.apache.org

Follow the links to download a binary version of Ant. Follow Ant's instructions to set up Ant and verify that it is working.

Estimated time excluding download: 45 minutes

Step Four: Download J2EE Jar If Necessary

You need access to the j2ee.jar file that contains the public interfaces of J2EE. This file, which can be found in the J2EE SDK, is available at the following Web location:

http://java.sun.com/j2ee/download.html

Download it, and follow the directions to install it. This file is needed for all build targets because some of the common files use the J2EE framework to report messages.

Estimated time excluding download: 10 minutes

Step Five: Download JDO Implementation

The next step is to pick the JDO implementation that you want to use. The build scripts in this book work with any of the four JDO implementations mentioned earlier. The examples should work with any implementation, but you will have to create or find the tool script for implementations that are not on this list. It is possible that some vendors who are not on the list will provide a tool script for their implementation. Building a new tool script is not difficult, but you may want to start your exploration of JDO with the reference implementation. The reference implementation does have one serious drawback: the 1.0 version does not work well with EJB containers. As a result, the EJB examples in this book do not have build targets for the reference implementation.

To get the reference implementation, go to the Java Community Process page at the following URL:

http://jcp.org/aboutJava/communityprocess/final/jsr012/index.html

or go to the public access page maintained by the specification lead at the following URL:

http://access1.sun.com/jdo

Download the reference implementation and unzip to a directory of your choice.

To download one of the commercial implementations, go to the associated vendor's Web site and follow the directions. The home page for each is listed here.

http://www.solarmetric.com

http://www.libelis.com

http://www.signsoft.com

Estimated time for the reference implementation excluding download: 5 minutes. It will take longer for the commercial implementations because of the need to set up a license key and configure the JDBC settings.

Step Six: Configure Build Properties

In this step, you configure the property files. The properties in the global.properties file, found in the bookants directory, should not require changes, unless there are some operating system issues that need to be addressed.

The four tool property files provided are found in the bookants directory. Edit the property file that goes with the implementation that you have selected. For the reference implementation, that would be the jdori.properties file. This file has two properties. The jdo.home property should be set to the root directory where the implementation is installed. The second property, jdo.tool, is the name used to find the tool's build script. It should not be changed, unless you are writing a new tool script. After configuring the tool's properties file, make a copy named custom.properties in the bookants directory.

Next, edit the default.properties file. This file contains the following properties:

• java.home

• jdbc.jar

• j2ee.home

• tomcat.home

• jboss.home

Of these, the last two will be addressed in Chapters 10 and 11. The jdbc.jar property is required only if a relational implementation of JDO is used. These include the Kodo, Lido, and IntelliBO implementations. The java.home property provides the file path to the root directory where you installed the Java SDK. Set the j2ee.home property to point to the root directory where you installed the J2EE SDK.

Estimated time for this step: 10 minutes

Step Seven: Test the Build Environment

You are now ready to test the build environment. To begin, go to the bookants directory and type ant. You should see console output similar to the output in the following lines:

 E:\Bookcode\bookants>ant Buildfile: build.xml Help:      [echo] Please specify a particular build target, such as testfactory      [echo]    or, enter the command: ant -projecthelp      [echo]    for a list of targets BUILD SUCCESSFUL 

By typing ant -projecthelp, you will see a list of targets for the build. The expected output will look similar to the output in Listing 8-1. You will see quite a few more main targets than the ones listed here. The additional targets that are not shown in Listing 8-1 are used in later chapters.

Listing 8-1: Expected Output from Running ant -projecthelp at the Command Line

 E:\Bookcode\bookants>ant -projecthelp Buildfile: build.xml Default target:  Help                   The default target for this build script Main targets:  Help                   The default target for this build script  clean-out              removes all files in output directories  megacups               build MegaCups example  testfactory            build TestFactory example  testjdohelper          build TestJDOHelper example  learning-programs      Builds all learning-programs  library                build Library example  statetracker           build Statetracker example Subtargets:  are-we-ready  help  verify BUILD SUCCESSFUL 

If everything is working as expected at this point, then you are ready to try the most dangerous target in the build, the clean-out target. This target deletes all files in the build directory, enhanced directory, and warfiles directory under the bookcode-home directory. The expected output, since you have not yet built any files to delete, will look like the following:

 E:\Bookcode\bookants>ant clean-out Buildfile: build.xml are-we-ready: verify: clean-out:      [echo] Deleting files in build, enhanced, and warfiles BUILD SUCCESSFUL 

Use the clean-out target whenever you want the subsequent build to proceed from scratch.

The testjdohelper, testfactory, megacups, library, and statetracker targets are described in the following sections of this chapter. They can be built individually, or you can build them all at once by going to the bookants directory and typing ant learning-programs. The build should take a minute or so.

Estimated time for this step: 10 minutes