Apache Derby is an open-source, standards-based database written purely in Java. Its diminutive footprint makes it especially attractive for development testing. The database system is based on technology donated to the Apache Software Foundation by IBM. The database is released under the Apache Derby project.

Apache Derby traces its roots back to 1996, when Cloudscape, Inc. embarked on the task to build a database server written in the Java language. As history would have it, a year later, Cloudscape, Inc. produced its first database release, called JBMS. Shortly after, that database was named Cloudscape^®. In 1999, Cloudscape, Inc. was acquired by Informix^® Software Inc. IBM bought Informix in 2001, and the IBM Cloudscape found its way into a number of IBM middleware products as an embedded database engine. IBM donated the Cloudscape database to the Apache Software Foundation in April 2004. That event marked the birth of the Apache Derby project. In July 2005, the Derby project hatched from the Apache incubator and is now a subproject of the “DB” top-level project at Apache. Sun Microsystems joined the Derby project right before Derby graduated from incubation. In December 2006, with the release of Java 6, Sun started packaging Derby in the JDK as Java DB.

Apache Derby is ideal for development and proof of concept efforts. Apache Derby’s ease of use and small footprint were some of the key motivators for using it as the testbed of examples in this book.

Eclipse is an extensible open-source IDE (Integrated Development Environment). The Eclipse Project was launched in November 2001, when IBM donated $40 million worth of source code derived from its WebSphere Studio Workbench. The tandem combination of the Eclipse platform combined with the Java Development Tools (JDT) produced by the Eclipse Project yields an IDE that has gained great respect throughout the Java development community. Most of IBM’s modern suite of application development tools, including Rational Application Developer, Rational Software Architect, and the WebSphere Application Server Toolkit, are built on top of the Eclipse Platform.

For this book, the familiarity of much of the Java development community with Eclipse was our motivator for choosing it as the IDE for development. Of course, there is nothing binding you to use a particular IDE (or any at all, for that matter). You could opt to be a purist and stick to the command line. Of course, you can also mow your lawn with a pair of scissors. We just don’t find it to be very efficient.

JUnit [Junit] is a unit-testing framework for the Java programming language that we explained briefly in Chapter 3, “Designing Persistent Object Services.” Because JUnit and DbUnit are so important to the setup, we feel the information is worth repeating.

Created by Kent Beck and Erich Gamma, JUnit is one of, and arguably the most successful of, the xUnit family of frameworks that originated with Kent Beck’s SUnit. JUnit has spawned its own ecosystem of JUnit extensions. “JUnit” is also a synonym for unit tests in general, as in, “Did you run the junits before you checked in?”

Experience gained with JUnit has been important in the development of test-driven development, and as a result, some knowledge of JUnit is often presumed in discussions of agile test-first approaches—for example, in the book Test-Driven Development: By Example [Beck].

One extension of JUnit is DbUnit [DbUnit]. DbUnit is a JUnit extension targeted for database-driven projects that, among other things, puts your database into a known state between test runs. This is an excellent way to avoid the myriad of problems that can occur when one test case corrupts the database and causes subsequent tests to fail or exacerbate the damage. DbUnit is an open-source framework created by Manuel Laflamme.

DbUnit has the capability to export and import your database data to and from XML datasets. Since version 2.0, DbUnit can work with very large datasets when used in streaming mode. DbUnit can also help you verify that your database data matches the expected set of values.

In our common example, we use JUnit and DbUnit to test our Service Interface.

Download PWTE.zip from the book website, ibmpressbooks.com/title/9780131587564.

Once unpacked, the zip file includes the directory structure shown in Figure A.1.

Figure A.1. Download Directory Structure

The examples require a Java 5.0 development environment. A Java 5.0 development kit can be acquired from the following online resources:

Acquire Eclipse 3.2.2 or later from the following website:

Acquire and install the Apache Derby Core and UI plug-ins for Derby 10.2 or later from the following website:

This section walks you through importing the code for the various technologies that run in a Java SE application. From your Eclipse workspace you will import the JDBC Project into your Eclipse workspace. You can right-click from the Project or Package Explorer and select Import, as shown in Figure A.2.

Figure A.2. Import menu option.

Select Existing Projects into Workspace, as shown in Figure A.3, and then click Next.

Figure A.3. Existing Projects into Workspace folder.

Inside the Import Projects screen, the root directory should be <Location to where you extracted the Zip>/PWTE, as shown in Figure A.4. Select all the projects under Projects. Ensure that the Copy Projects into Workspace option is selected. Click Finish.

Figure A.4. Import Projects screen.

The Test Projects depend on DbUnit. All Test Projects except for Project Zero (we will configure that one later) have an Eclipse User Library configured for DbUnit. Right-click on the DbUnit folder and select Configure, as shown in Figure A.5, for the JDBC-Test, iBatis-Test, Hibernate-Test, and JPA-Test.

Figure A.5. Configure the DbUnit Library.

Click the User Libraries button. Then select DbUnit and click Add Library, as shown in Figure A.6. There you can add the dbunit-2.2.jar file that you downloaded from the DbUnit site discussed in the section “Setting Up the Prerequisites.”

Figure A.6. Add dbunit-2.2jar to the Library.

Next, right-click on JDBC-Test (or any Test Project) project and select Apache Derby, Add Apache Derby Nature, as shown in Figure A.7.

Figure A.7. Add Apache Derby Nature.

Right-click the project again and select Apache Derby, Start Derby Network Server, as shown in Figure A.8.

Figure A.8. Start the Network Server.

The Console should display the Apache Derby Network Server with a status showing it as started.

Under the JDBC-Test Project, expand the dbscript folder and right-click on schema-1.4.sql. Select Apache Derby, Run SQL Script Using “ij”. As a brief explanation, ij is the command-line tool for Derby that runs the SQL scripts. The step shown in Figure A.9 will create the necessary tables for the common example applications.

Figure A.9. Run the SQL Script using ij.

The console should display the result of the table it creates. There will likely be some errors the first time you run a script because the script will attempt to delete the tables in case they existed already. Do not worry too much about any delete errors you see. This extra delete step makes the script more robust so that it can be run in any state to initialize the database tables.

From the Package Explorer, in the Java Perspective, expand the src folder. Expand the Java package com.pwte.example.jdbc.test. Right-click on CustomerOrderServices Test.java and select Run As, then JUnit Test, as shown in Figure A.10.

Figure A.10. Run the JUnit test.

The JUnit View should open and display six successful JUnit results, as shown in Figure A.11.

Figure A.11. JDBC Unit test results.

This section walks you through running the application for the iBATIS application shown in Chapter 6, “Apache iBATIS.” You need to download version 2.3 of iBATIS from here: ibatis.apache.org/javadownloads.cgi.

You need to add your dependency to iBATIS. Expand the iBATIS Project. From the Project Explorer, right-click IBATIS_LIBRARY and select Configure, as shown in Figure A.12.

Figure A.12. Configure the iBATIS library.

Click the User Libraries button. Then select the DbUnit and click Add JARs, as shown in Figure A.13. There you can add the ibatis-2.3.0.xxx.jar and log4j-1.2.15.jar files that you downloaded from the ibatis site shown in the beginning of this section.

Figure A.13. iBATIS user libraries.

From the Package Explorer, in the Java Perspective, expand the src folder. Expand the Java package com.pwte.example.ibatisc.test. Right-click on CustomerOrderServices Test.java and select Run As, then JUnit Test, as shown in Figure A.14.

Figure A.14. Run iBATIS.

The JUnit View should open and display six successful JUnit results, as shown in Figure A.15.

Figure A.15. iBATIS JUnit result.

This section walks you through setting up the code and application for the JDBC application shown in Chapter 7, “Hibernate Core.” You need to download Hibernate 3.2 from here: sourceforge.net/project/showfiles.php?group_id=40712&package_id=127784&release_id=529023.

You need to add your dependency to Hibernate. Expand the Hibernate Project. From the Project Explorer, right-click HIBERNATE_JARS and select Configure, as shown in Figure A.16.

Figure A.16. Hibernate Library.

Click the User Libraries button. Then select HIBERNATE_JARS and click Add JARs, as shown in Figure A.17. Add the following JARs (available as part of the Hibernate distribution):

Figure A.17. Hibernate dependencies.

From the Package Explorer, in the Java Perspective, expand the src folder. Expand the Java package com.pwte.example.hibernate.test. Right-click on CustomerOrderServices Test.java and select Run As, then JUnit Test, as shown in Figure A.18.

Figure A.18. Run the JUnit test.

The JUnit View should open and display six successful JUnit results, as shown in Figure A.19.

Figure A.19. Hibernate JUnit result.

This section walks you through setting up the code and running the application for the OpenJPA application in Chapter 8, “Apache OpenJPA.” This is the Java SE version. The next section shows you how to run the Java EE version. To do this, you first need to download version 1.0.1 of OpenJPA from here:

You need to add your dependencies to OPEN_JPA. Expand the OpenJPA Project. From the Project Explorer, right-click OPEN_JPA and select Configure, as shown in Figure A.20.

Figure A.20. Configure the OPEN_JPA Library.

Click the User Libraries button. Then select OPEN_JPA and click Add JARs, as shown in Figure A.21. Add the following JARs (available as part of the Open distribution):

Figure A.21. Add OPEN_JPA JARs.

OpenJPA needs bytecode enhancement of the persistent classes, as described in Chapter 8, to the persistent classes. We provided a build script that runs the enhancer. Right-click the build.xml file, as shown in Figure A.22, and select Run As, then Ant Build (the second option with the 3).

Figure A.22. Open Ant Build.

Click on the Classpath tab and add the OpenJPA JARs included in the distribution, as shown in Figure A.23.

Figure A.23. Ant dependencies.

Under the Targets tab, select Enhance. Then click Run, as shown in Figure A.24.

Figure A.24. Run Enhance.

The console should display the results, as shown in Figure A.25.

Figure A.25. Open JPA Bytecode Enhancement Results screen.

From the Package Explorer, in the Java Perspective, expand the src folder. Expand the Java package com.pwte.example.jdbc.test. Right-click on CustomerOrderServices Test.java and select Run As, then JUnit Test, as shown in Figure A.26.

Figure A.26. Run SQL Script.

The JUnit View should open and display six successful JUnit results, as shown in Figure A.27.

Figure A.27. JUnit result.

This section walks you through setting up the code and running the application for the Project Zero application shown in Chapter 9, “pureQuery and Project Zero,” utilizing the pureQuery technology.

Install the M1 release to work with the sample, right-click the PWTEZero-Test application, and select Run As, then Project Zero Application, as shown in Figure A.28.

Figure A.28. Run the Project Zero application.

Enter the following address into a browser:

The result should be a page that successfully runs the unit tests, as shown in Figure A.29.

Figure A.29. Run Project Zero tests.

Stop the database.

This section walks you through setting up the code and running the application for the OpenJPA application, shown in Chapter 8, inside a Java EE. Unlike in the preceding section, we will use Rational Application Developer version 7.5, which is in beta. You can download the Open Beta for Rational Application Developer here:

Rational Application Developer comes with WebSphere Application Server 6.1 with the EJB 3 Feature Pack preconfigured. (The installation instructions are available on the site.) After you have it installed, follow the directions that follow.

You can right-click from the Project or Package Explorer and select Import.

Select Project Interchange under the Other folder, as shown in Figure A.30.

Figure A.30. Project Interchange.

Enter <place where you unzipped download>/PWTE/EJB3-App/JPA-EJB3_PI.zip and select the four projects, as shown in Figure A.31.

Figure A.31. Project Interchange.

Next, right-click on the JPA-Code project and select Apache Derby, Add Apache Derby Nature, as shown in Figure A.32.

Figure A.32. Apache Nature.

Right-click the Project again and select Apache Derby, then Start Derby Network Server, as shown in Figure A.33.

Figure A.33. Start Derby Server.

Under the JPA-Code Project, expand the dbscript folder and right-click on schema-1.4.sql. Select Apache Derby, then Run SQL Script Using “ij”. (As noted previously, ij is the command-line tool for Derby that runs the SQL scripts. This will create the necessary tables for creating the example.) Figure A.34 shows the example.

Figure A.34. Run dbscript.

The unit tests run inside of a Java EE Container. To run the tests, copy the dependencies shown in Figure A.35 into the directories shown (JUnit 3.8, JUnit EE, Derby client and tools, and DbUnit).

Figure A.35. Dependencies.

Next, you will run the application in the Server. You can do this by expanding the JPA-Web project from the Project Explorer as shown in Figure A.36. Right-click on the JUnitEEServlet and select Run As, then Run on Server.

Figure A.36. Run on Server.

From within the Run on Server Wizard, shown in Figure A.37, check the Always Use This Server When Running This Project option (this will keep you from repeating this test on subsequent runs).

Figure A.37. Run on Server Wizard.

The Servers View should show a State of Starting, as shown in Figure A.38.

Figure A.38. Server starting.

Examine the console to ensure that the Server starts and the application is started, as shown in Figure A.39.

Figure A.39. Application started.

RAD 7.5 should load a browser with the JUnit EE Servlet to run the test case from within the container. Enter the test class (org.pwte.example.jpa.test.CustomerOrderServices Test) in the Test Suite section, as shown in Figure A.40.

Figure A.40. Run the test case.

The test cases should run and the results displayed as shown in Figure A.41.

Figure A.41. Test case result.

If the unit test cases fail due to a violation, it is most likely because of a previous failure in running the test cases causing the data to be in an inconsistent state. If you rerun the database script to drop and re-create the tables, it should remove this issue and bring you back to a consistent state. Figure A.42 shows an example.

Figure A.42. Example of a common error you may get when running these steps.