Install and setup the TestDataCaptureJ tool in the Eclipse IDE as per the setup instructions.

Install and setup Tomcat 6.x as the app server, in the tutorial instructions {TOMCAT_HOME} will refer to the location where Tomcat is installed. It is assumed that you will already have a compatible version of Java installed on your server machine and have the appropriate environment setup for it, e.g. JAVA_HOME.

Get a copy of the Spring JPetStore sample application, it should be included in the Spring Framework 2.x download http://www.springsource.org/download.

Alternatively if you have a version of the Spring Framework that does not include the JPetStore sample, you can use Subversion to export a copy from the Spring Framework version control repository. Note that you have to put the JPetStore folder under the samples folder of a Spring Framework 2.x distribution for the build files to work.

https://src.springframework.org/svn/spring-maintenance/trunk/samples/jpetstore/

D:\>svn export https://src.springframework.org/svn/spring-maintenance/trunk/samples/jpetstore/ D:\tutorial\spring-framework-2.5.6.SEC01\samples\jpetstore
A    D:\tutorial\jpetstore
A    D:\tutorial\jpetstore\build.bat
.
.
.
A    D:\tutorial\jpetstore\warfile.bat
Exported revision 17168.

Install whatever build tools are required to build the JPetStore application war file, e.g. Ant. Follow the instructions in the readme.txt file for the JPetStore project as they may vary depending on the version of the JPetStore sample that was downloaded.

Build the JPetStore application war file, following the instructions in the readme.txt file for the JPetStore project.

Deploy the JPetStore to the Tomcat server, just need to copy the war file in the target directory to the webapps directory in Tomcat. Before deploying the war file, rename it to 'jpetstore.war' to make it easier to manage if it is called something more complicated.

Setup and start the JPetStore database of your choice in the db directory, the HSQLDB instance is probably the easiest one to use. Once again follow the instructions in the readme.txt file for the JPetStore project.

D:\tutorial\spring-framework-2.5.6.SEC01\samples\jpetstore\db\hsqldb>server.bat
.
.
.
[Server@54c4ad]: Database [index=0, id=0, db=file:D:\tutorial\jpetstore\db
\hsqldb\jpetstore, alias=] opened sucessfully in 2438 ms.
[Server@54c4ad]: Startup sequence completed in 4047 ms.
[Server@54c4ad]: 2010-08-12 09:45:54.250 HSQLDB server 1.8.0 is online
[Server@54c4ad]: To close normally, connect and execute SHUTDOWN SQL
[Server@54c4ad]: From command line, use [Ctrl]+[C] to abort abruptly

Start the Tomcat server and check the console log to ensure that it starts up successfully.

Run the JPetStore app, go through the process of buying some pets and going through the checkout process to make sure it runs successfully.http://localhost:8080/jpetstore/ (replace localhost with your server name if you are not running Tomcat on your local machine)

Stop the Tomcat server.

In the file org.springframework.samples.jpetstore.domain.Order.java there is a method that creates an order from the contents of the shopping cart. The initOrder() method has the cart as one of its parameters, and this would be a good place to capture the cart data as it should contain all the necessary information that we need as this stage of the checkout process.

Edit conf/META-INF/aop.xml in the TestDataCaptureJ project in Eclipse to setup the AspectJ pointcut to intercept the parameters of initOrder() method.

Fragment of 'conf/META-INF/aop.xml':

<aspectj>
<aspects>
	<aspect name="au.dom.dw.testdatacapturej.aspect.Trace"/>
	<aspect name="au.dom.dw.testdatacapturej.aspect.TraceAdaptor"/>
.	
.
.
    <!-- For use in the JPetStore tutorial -->
	<concrete-aspect name="au.dom.dw.testdatacapturej.aspect.TestSpringPetStoreTrace"
                            extends="au.dom.dw.testdatacapturej.aspect.TraceAdaptor">
             <pointcut name="loggedParamOperations" expression="execution(* org.springframework.samples.jpetstore.*.Order.initOrder(..))"/>
             <pointcut name="loggedReturnOperations" expression="if(false)"/>
    </concrete-aspect>
    
</aspects>
.
.
.
</aspectj>

The changes involve adding a <concrete-aspect> tag to the xml file nested inside the <aspects> tag.

An example of an edited file can be found in the TestDataCaptureJ project at tutorial/conf/META-INF/aop.xml.

Configure the conf/logback.groovy file for the location (and possibly the name) of the generated file(s) that we want. This configuration file is setup with 2 appenders, the default is the 'SIFT' appender which allows each intercepted object to be logged to a separate file. If instead you want all the logging to go to a single file, then just configure the logger 'au.com.dw.testdatacapturej-trace' to use the 'FILE' appender instead, i.e. 'logger("au.com.dw.testdatacapturej-trace", INFO, ["FILE"], false)'.

The log file locations are also currently setup for use with Tomcat as the app server, by using

Fragment of 'conf/logback.groovy':

.
.
.
appender("FILE", FileAppender) {
  file = "${CATALINA_HOME}/logs/Test-${bySecond}.java"
  encoder(PatternLayoutEncoder) {
    pattern = "// Generated %d%n%m%n"
  }
}
.
.
.
appender("SIFT", GSiftingAppender) {
  discriminator(MDCBasedDiscriminator) {
    key="traceClass"
    defaultValue = "unknownValue"
  }
  sift {
    appender("FILE-${traceClass}", FileAppender) {
      file = "${CATALINA_HOME}/logs/${traceClass}.java"
      encoder(PatternLayoutEncoder) {
        pattern = "// Generated %d%n%m%n"
      }
    }
  }
}
.
.
.
// logger for the code generation logging
logger("au.com.dw.testdatacapturej-trace", INFO, ["SIFT"], false)
.
.
.

Changing the location for the log files generated by the 'SIFT' appender means editing the 'file' variable to a valid path on your local machine, e.g. 'file = [Your location]/${traceClass}.java'. In this example it has been set so that the generated files will appear in the 'logs' directory in your Tomcat installation. Note that the '${traceClass}' expression must be kept since it is used in the MDC (Mapped Diagnostic Context) for the logging framework and will also contain the file name of the log file which is generated in the code.

Changing the location and/or name of the log file generated by the 'FILE' appender' also means editing the 'file' variable to a valid path and file name on your local machine.

Copy the AspectJ runtime jars needed for load time weaving to {TOMCAT_HOME}/lib. These are aspectjrt.jar and aspectjweaver.jar.

Decide where to put the TestDataCaptureJ and dependency jar files so that they are included in the classpath of the JPetStore web application,. Two possible choices are directly into the web app or setting up a Tomcat shared library directory.

Copy the dependency jars to the location to be included in the web application classpath. These are:

Copy the logging framework jars to the location to be included in the web application classpath. These are:

Make the changes to catalina.bat in {TOMCAT_HOME}/bin so that the AspectJ load-time weaving will be done.

It is a good idea to make a backup of catalina.bat in your Tomcat installation before making changes to it.

Fragment of 'bin/catalina.bat' :

.
.
.
set ASPECTJ_WEAVING=-javaagent:%CATALINA_BASE%\lib\aspectjweaver.jar -Xmx1024m
set JAVA_OPTS=%JAVA_OPTS% %ASPECTJ_WEAVING%
.
.
.

The changes involve adding the ASPECTJ_WEAVING variable to the file, and then adding that variable to be included in the JAVA_OPTS variable. There is a section in 'bin/catalina.bat' where the JAVA_OPTS variable is set, so a good place to add our changes is at the end of this section. Note that the ASPECTJ_WEAVING variable must point to the location where you have copied aspectjweaver.jar to your Tomcat installation.

An example of an edited file can be found in the TestDataCaptureJ project at tutorial/tomcat/bin/catalina.bat, n. Note this this example file is from an installation of Tomcat 6.0.26, so may vary slightly from your copy of catalina.bat if you have installed a different version of Tomcat.

Edit the configuration file 'conf/configuration.properties' so that there are no custom configuration files used:

As an example see 'tutorial/conf/step.1.configuration.properties' :

# config files for constructor configuration

constructor.config.files=

# config files for setter method configuration

setter.config.files=

# config files for collection adder configuration

collection.config.files=

This ensures that the TestDataCaptureJ tool will run without any custom configurations for the generated logs.

See the customization page for details of the custom configurations that are available.

Export the project as a jar with AspectJ support to the location to be included in the web application classpath.

See the setup page for details on doing this step.

Import the JPetStore project as an existing java project into Eclipse.

Configure the build path for the project so that

Create a directory to store the unit test files, and configure the build path for the JPetStore project to include the test directory as a source folder.

Create a class file, containing an empty class, under the test directory. Let's name the class 'CreateTestObject'.

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/CreateTestCart_Empty.java' :

package au.com.dw.testdatacapturej.tutorial;

public class CreateTestCart {
	
	// copy and paste generated method here
	
}

Copy and paste the contents of the log file, containing the generated code for the Cart object, into the empty class - this is the class that will (eventually) be used to create the test object. For the tutorial we are copying the contents of the log file containing the generated code for re-creating the Cart object, e.g. 'org.springframework.samples.jpetstore.domain.Order.initOrder-Parameter2-org.springframework.samples.jpetstore.domain.Cart-xxx.java',into the empty class.

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/CreateTestCart_Step1.java' :

package au.com.dw.testdatacapturej.tutorial;

public class CreateTestCart {
	
public org.springframework.samples.jpetstore.domain.Cart createParam2Cart_org_springframework_samples_jpetstore_domain_Order_initOrder() {

org.springframework.samples.jpetstore.domain.Cart cart0 = new org.springframework.samples.jpetstore.domain.Cart();

java.util.Collections$SynchronizedMap collections$SynchronizedMap0 = new java.util.Collections$SynchronizedMap();
// Default constructor for java.util.Collections$SynchronizedMap does not exist.

org.springframework.samples.jpetstore.domain.CartItem cartItem1 = new org.springframework.samples.jpetstore.domain.CartItem();

org.springframework.samples.jpetstore.domain.Item item2 = new org.springframework.samples.jpetstore.domain.Item();
item2.setItemId("EST-14");
item2.setProductId("FL-DSH-01");
item2.setListPrice(58.5d);
.
.
.
pagedListHolder4.setPage(0);
pagedListHolder4.setNewPageSet(false);
pagedListHolder4.setMaxLinkedPages(10);
cart0.setItemList(pagedListHolder4);

return cart0;
}

}

When Eclipse tries to build the code for the class file (or if you have autobuild configured for the project) after the log contents have been pasted in, then you will see that it will not compile and has some errors.

Figure 4. tutorial_eclipse-compile2.jpg

The first error that stops the file compiling will occur at this line:

.
.
.
java.util.Collections$SynchronizedMap collections$SynchronizedMap0 = new java.util.Collections$SynchronizedMap();
// Default constructor for java.util.Collections$SynchronizedMap does not exist.
.
.
.

If we look at the JPetStore source, we can see the problem in org.springframework.samples.jpetstore.domain.Cart.java in the itemMap field is created using a java.util.Collections wrapper method instead of new() operator to create the field.

package org.springframework.samples.jpetstore.domain;

import java.io.Serializable;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;

import org.springframework.beans.support.PagedListHolder;

public class Cart implements Serializable {

  /* Private Fields */

  private final Map itemMap = Collections.synchronizedMap(new HashMap());

.
.
.

This is one of the limitations of the TestDataCaptureJ tool, currently there is no way around this yet. For the purposes of this tutorial, we will ignore this for now.

The second error is at this line that is trying to create a Date object:

.
.
.
java.util.Date date8 = new java.util.Date();
date8.setFastTime(1279213622453L);
date8.setCdate(null);
.
.
.

The last error occurs near the end of the class:

.
.
.
pagedListHolder4.setSort(mutableSortDefinition9);
pagedListHolder4.setSortUsed(null);
pagedListHolder4.setPageSize(4);
pagedListHolder4.setPage(0);
pagedListHolder4.setNewPageSet(false);
pagedListHolder4.setMaxLinkedPages(10);
cart0.setItemList(pagedListHolder4);

return cart0;
}

}

Since the 'CreateTestCart' class won't compile, for this tutorial make some manual edits to it so that it will compile. This involves commenting out some of the lines that are causing errors and inserting a line to create the field 'collections$SynchronizedMap0' based on the Cart class source (TestDataCaptureJ cannot handle generating code for non-standard object creation, such as the 'java.util.Collections' wrapper methods).

package au.com.dw.testdatacapturej.tutorial;

public class CreateTestCart {
.
.
.
//java.util.Collections$SynchronizedMap collections$SynchronizedMap0 = new java.util.Collections$SynchronizedMap();
java.util.Map collections$SynchronizedMap0 = java.util.Collections.synchronizedMap(new java.util.HashMap());
.
.
.
//cart0.setItemMap(collections$SynchronizedMap0);
.
.
.
//date8.setFastTime(1279213622453L);
//date8.setCdate(null);
//pagedListHolder4.setRefreshDate(date8);
.
.
.
//pagedListHolder4.setSortUsed(null);
.
.
.
//pagedListHolder4.setNewPageSet(false);
.
.
.
//cart0.setItemList(pagedListHolder4);
.
.
.
}

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/CreateTestCart_Step1_Edited.java' :

Create a unit test case that uses the 'CreateTestCart' class to test the data that was generated.

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/TutorialTest.java' :

.
.
.
public class TutorialTest {

	@Test
	public void testInitOrderCart()
	{
		// Create the object that contains the pasted generated code for the Cart
		CreateTestCart createTestCart = new CreateTestCart();
		
		// invoke the generated method
		Cart cart = createTestCart.createParam2Cart_org_springframework_samples_jpetstore_domain_Order_initOrder();
		
		// test the generated data
		assertNotNull("cart exists", cart);
		
		assertTrue("cart has corrent number of items" + cart.getNumberOfItems(), cart.getNumberOfItems() == 3);
		
		assertTrue("cart contains specific item id", cart.containsItemId("FL-DSH-01"));
		
	}
}

We are using JUnit 4.x for the unit testing as that comes with Eclipse, but you can also use TestNG if you have the TestNG plugin installed in the Eclipse IDE.

Run the unit test 'testInitOrderCart()'.

Although the test case should run using the generated code, we have had to comment out some lines that did not compile for various reasons and so the test should fail. Now we can try to fix some of these issues.

The fields 'fastTime' and 'cDate' do not have setter methods, and the 'cDate' field is actually meant to be transient. Therefore the generated setter methods for these fields do not actually exist.

The no-argument constructor for 'java.util.Date' will actually set the internal state to the current date and time at which the object was created, instead of the time in the 'fastTime' field.

Stop the Tomcat server if it is still running, but make sure the JPetStore database server is still running.

Edit the configuration file 'conf/configuration.properties' so that the customization files 'conf/setter-config.xml' and 'conf/constructor-config.xml' will be used:

As an example see 'tutorial/conf/step.2.configuration.properties' :

# config files for constructor configuration

constructor.config.files=constructor-config.xml

# config files for setter method configuration

setter.config.files=setter-config.xml

# config files for collection adder configuration

collection.config.files=

This ensures that the TestDataCaptureJ tool will run with the configuration in the files 'setter-config.xml' and 'constructor-config.xml' for the generated logs.

See the customization page for an explanation of customization for constructors and setter methods..

Export the TestDataCaptureJ project as a jar with AspectJ support to the location to be included in the web application classpath, over-writing the jar exported before from the previous run (or if you export with a different file name for the jar, then the jar from the previous run will have to be deleted)

Start the Tomcat server.

Run the JPetStore as before, buying some pets and then going through the checkout process. Check that the generated code has been created in the log file.

As before, either create another empty class file for 'CreateTestCart' and paste the contents of the new log file, containing the generated code for the Cart object into it OR just paste over the generated log in the 'CreateTestCart' class from the previous tutorial run.

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/CreateTestCart_Step2.java' .

Once again this file will not compile properly due to errors that we found in the first run of the tutorial.

However notice that there are fewer errors now because the previous error we had with the java.util.Date field doesn't exist any more. The configuration for TestDataCaptureJ has fixed this problem so that the java.util.Date object is created properly now:

.
.
.
java.util.Date date20 = new java.util.Date(1279454122375L);
.
.
.

instead of the error generated from the previous tutorial run:

.
.
.
java.util.Date date8 = new java.util.Date();
date8.setFastTime(1279213622453L);
date8.setCdate(null);
.
.
.

If we look at the xml configuration in the file 'conf/constructor-config.xml', we find that the configuration for the class 'java.util.Date' is specifying that we want to set the value of the field 'fastTime' from a constructor instead of a setter method. That is, when an object of the class 'java.util.Date' is to be created in the generated log, instead of using the default no-argument constructor [new java.util.Date()], it will instead generate a constructor line that will use the value of the field 'fastTime' as a parameter, e.g. [new java.util.Date(1279454122375L)]. In addition, it will not generate a setter method line for the field 'fastTime'.

Fragment of 'conf/constructor-config.xml':

.
.
.
	<constructor class="java.util.Date">
		<argument>
			<field-name>fastTime</field-name>
		</argument>
	</constructor>.
.
.
.

In the xml configuration in the file 'conf/setter-config.xml', we find that the configuration for the class 'java.util.Date' is specifying that we want to ignore the field 'cdate' when it comes to generating setter methods for that class (i.e. no setter method will be generated for that particular field).

Fragment of 'conf/setter-config.xml':

.
.
.
	<setter class="java.util.Date">
		<field>
			<field-name>cdate</field-name>
			<alternative>ignore</alternative>
		</field>
	</setter>.
.
.
.

Of course while we've fixed one of the errors, the other errors will still stop the 'CreateTestCart' class from compiling. If you like you can do another manual edit of the 'CreateTestCart' class to make it compile and then re-run the test case again. Once again the test should fail when run.

As an example see 'tutorial/sample/au/com/dw/testdatacapturej/tutorial/CreateTestCart_Step2_Edited.java' .

Now we can try to fix some of the other errors.

Stop the Tomcat server if it is still running, but make sure the JPetStore database server is still running.

Edit the configuration file 'conf/configuration.properties' so that in addition to the customization files that we used in the previous run, it will also include 'conf/jpetstore-test-setter-config.xml' .

As an example see 'tutorial/conf/step.3.configuration.properties' :

# config files for constructor configuration

constructor.config.files=constructor-config.xml

# config files for setter method configuration

setter.config.files=setter-config.xml, jpetstore-test-setter-config.xml

# config files for collection adder configuration

collection.config.files=

This ensures that the TestDataCaptureJ tool will run with all 3 configuration files for the generated logs.

Export the TestDataCaptureJ project as a jar with AspectJ support to the location to be included in the web application classpath. Once again if you are not over-writing the jar exported from the previous run, then the jar from the previous run will have to be deleted.

Start the Tomcat server.

Run the JPetStore as before, buying some pets and then going through the checkout process. Check that the generated code has been created in the log file.

As before, either create another empty class file for 'CreateTestCart' and paste the contents of the new log file, containing the generated code for the Cart object into it OR just paste over the generated log in the 'CreateTestCart' class from the previous tutorial run.

For the tutorial, as an example look at 'TutorialTest3.java', your log should look similar to this.

Once again the 'CreateTestObject' class file will not compile properly, but also notice that the number of errors has been reduced again. Have a look at the configuration file 'jpetstore-test-setter-config.xml' to see what has changed.

Fragment of 'conf/jpetstore-test-setter-config.xml':

.
.
.
	<setter class="org.springframework.beans.support.PagedListHolder">
		<field>
			<field-name>refreshDate</field-name>
			<alternative>ignore</alternative>
		</field>
		<field>
			<field-name>newPageSet</field-name>
			<alternative>ignore</alternative>
		</field>
		<field>
			<field-name>sortUsed</field-name>
			<alternative>ignore</alternative>
		</field>
	</setter>
.
.
.

Since we have decided that the class 'org.springframework.beans.support.PagedListHolder' is not relevant to our testing, the additional custom configuration has removed the errors associated with this class from the generated log.

There is no setter method in the 'org.springframework.samples.jpetstore.domain.Cart' class for the field 'itemMap', i.e. no 'setItemMap()' method.

Similarly there is no setter for the field 'itemList', i.e. no 'setItemList()' method.

The only way to add the items to the 'itemMap' collection is through the 'addItem()' method. Unfortunately this is not a straightforward adder method and has side effects.