August 25, 2004.

This directory tree contains Version 8.25.04 of the TORPEDO-2004 Reference
Implementation. 

The TORPEDO-2004 framework tests Object Relational Mapping Software's sophistication
in accessing a relational database and maintaining an object-oriented cache in
the middle tier of a J2EE application.



DOCUMENTATION
-------------
A functional specification for the TORPEDO-2004 framework is explained in great
detail in a paper:

	"TORPEDO: A Testbed of Object-Relational Products for Enterprise
	Distributed Objects"

This paper can be found in the doc subdirectory and on-line at
http://www.torpedo-group.org You should read this paper prior to working
with this software.

This distribution also contains many README files in the various
subdirectories.  The README files document the framework and it's configuration
at different levels of detail.



O/R MAPPING APIs
----------------
The TORPEDO framework currently supports four Java API's for O/R mapping,
namely EJB-CMP, JDO, Toplink and Hibernate.

The API (CMP, JDO, Toplink, Hibernate) to use is selected by modifying the
PersistenceClass EJB environment entry found in the AuctionServiceBean
deployment descriptor in the ejb-jar.xml file.  In particular,

    <env-entry>
	<description />
	<env-entry-name>PersistenceClass</env-entry-name>
	<env-entry-type>java.lang.String</env-entry-type>
	<env-entry-value>com.middleware_company.torpedo.auction.cmp.Persistence</env-entry-value>
    </env-entry>
    
The above entry indicates CMP should be used.  

To change it to use Solarmetric's Kodo JDO, change <env-entry-value> to:

	com.middleware_company.torpedo.auction.jdo.Persistence
	
To change it to use Oracle's Toplink, change <env-entry-value> to:

	com.middleware_company.torpedo.auction.toplink.untuned.Persistence
	
To change it to use Hibernate, change <env-entry-value> to:

	com.middleware_company.torpedo.auction.hibernate.Persistence


SUPPORTED PRODUCTS
------------------
The reference implementation currently runs with:

	Oracle Toplink (POJO) 9.0.4
	BEA Weblogic 8.1 CMP
	Solarmetric Kodo JDO 3.1.5 
	Hibernate 2.1.6
	
This code may also work with other versions of these products but none have
been tested.  You can run TORPEDO on some or all of these products.  They
must be installed on the machines where TORPEDO is built and run and the following files
must be modified to reflect your installations:
	build.properties
	script to start your application server

The intent is to port the reference implementation to work with lots of CMP,
JDO implementations, Toplink and Hibernate. The above list will grow.

The TORPEDO server is implemented as two stateless session beans.  One of the 
stateless session beans accesses the persistence layer.  The current code runs 
on WebLogic 8.1. Porting to non-CMP implementations does not require
changing the EJB container -- it can remain WebLogic 8.1.  However, when
porting the persistence layer to other CMP implementations, the stateless
session beans will also need to be ported. 



DIRECTORY STRUCTURE
-------------------

bin
	Contains a script to run the TORPEDO client
	
classes
	Contains compiled Java classes implementing TORPEDO
	
configuration
	Contains configuration files for each supported product.  Also contains
	any used and redistributed open-source libraries, such as Hibernate and
	p6spy.
	
doc
	Contains all documentation for TORPEDO.
	
lib
	Contains the built libraries for TORPEDO.  
	
src
	Contains Java source code implementing TORPEDO.



BUILDING TORPEDO
----------------
The reference implementation builds with Ant.  The targets in the build.xml file
are:

init
	Builds the required subdirectories, namely lib and classes.
	
compile_independent
	Compiles all of the O-R mapping product independent code.
	
compile
	Compiles all product independent code and the product dependent
	code.  The script detects which products you
	have installed and wish to build against.  See build.properties
	for more information.
	
build_weblogic
	Produces the lib/*.jar files. lib/torpedo.jar can be deployed to
	a WebLogic 8.1 server.
	
build_oc4j
	Produces the lib/*.jar files and lib/torpedo.ear.  lib/torpedo.ear
	can be deployed to Oracle Application Server.
	
clean
	Removes classes and lib subdirectories in order to start over.



RUNNING TORPEDO
---------------
The torpedo.jar/ear file is deployed to the target application server.  The
torpedo.jar file assumes that there is a DataSource named AuctionDataSource
already deployed on the application server.  All three versions of the
persistence layer (CMP, JDO, Hibernate) assume the AuctionDataSource.

The AuctionDataSource needs to be the p6spy.jar JDBC driver.  The p6spy.jar
driver wraps the JDBC driver for the database and captures the SQL sent to the
database.  The p6spy driver looks on the classpath for spy.properties, found in
the configuration/properties directory for the real JDBC connection.

Deploy torpedo.jar according to the target application server's instructions.


Run the torpedo client. There is a simple script in bin/torpedo.bat that simply
sets up the class path and executes the desired client.  There is a client named
"AllTests".  This runs all of the tests.



KNOWN LIMITATIONS
-----------------
The functional specification mentions a test that concurrently places bids and
executes list and find operations.  This test has not yet been implemented.  It
will appear in a future release of the TORPEDO reference implementation.



QUESTIONS AND CONTRIBUTIONS
---------------------------
Visit the TORPEDO web site at http://www.torpedo-group.org 
Send questions and or request changes by sending email to 
i n f o r m a t i o n@torpedo-group.org  Also, follow TORPEDO discussions on 
The Server Side at http://www.theserverside.com

Any source code and/or configuration contributions for any products supporting
these three APIs will be greatfully accepted and considered for inclusion in
the TORPEDO reference implementation.  Contact us at the above email address.