Mailing-List: contact torque-user-help@db.apache.org; run by ezmlm
Date: Sun, 16 Feb 2003 18:52:52 -0500
Mime-Version: 1.0 (Apple Message framework v551)
Content-Type: text/plain; charset=US-ASCII; format=flowed
Subject: Suggested fixes for Torque tutorial
From: Finn Smith <fcs@modcult.org>
To: torque-user@db.apache.org
Content-Transfer-Encoding: 7bit
Message-Id: <C2EA6F7C-4209-11D7-A03C-000A9576633C@modcult.org>

Hi,

I recently decided to download and play with the decoupled Torque 
(version 3.0) as it might be applicable to a project I am working on. I 
decided to build the small sample Bookstore app in the tutorial to 
reacquaint myself with how Torque worked (I used it as part of the TDK 
about a year and a half ago). In doing so, I discovered many problems 
with the current tutorial. In several places there are small and/or 
large problems which would make the tutorial hard to use for a 
beginner. I was able to resolve them all with common sense and 
knowledge gleaned from the various jakarta list archives. Here's a 
summary of the issues I came across while getting the Bookstore app to 
run correctly.

Additions that are obvious, but would be useful to beginners:
  * Mentioning that the tutorial assumes that you are using mysql 
running on the same machine as Torque, and advising that you'd have to 
adjust the variables in the properties files accordingly if you are 
using a different and/or non-local database.
  * A pointer to the web page of the mysql driver used by the tutorial, 
and a mention that the mysql-bin.jar file can simply be placed in the 
torque/lib directory and expected to work.

Errors/problems in the tutorial:
Step 1 is fine.
Step 2:
  * The files project-schema.xml and id-table-schema.xml in the 
torque/schema directory both rely on .dtd files online. If you are not 
connected to the internet, the build fails when it cannot find these 
files. Since I was doing my work offline, I had to download these files 
and adjust the paths in the xml files to point to them.
  * The file Torque.properties is in the top level torque directory, not 
in torque/schema. The tutorial should suggest editing the 
Torque.properties file that exists instead of making a new one.
  * The lines given for the database settings in the Torque.properties 
file will result in:
"java.lang.NullPointerException: There was no DataSourceFactory 
configured for the connection bookstore" when you try and run the app 
in the last step. The properties that need to be set are 
torque.dsfactory.bookstore.connection.* not 
torque.database.bookstore.*. The Torque.properties file that comes with 
the distribution is set up with the correct properties, which is why 
editing is probably a better solution than making a new file. The log4j 
properties set in the tutorial work fine. The log4j properties in 
Torque.properties can simply be commented out and replaced with the 
ones in the tutorial.
  * The table listing the various properties that are set in 
Torque.properties should also be edited to reflect the fact that 
torque.dsfactory properties need to be set, not torque.database 
properties.
Step 3:
  * There should probably be a mention that (obviously) the database 
needs to be up and running for the steps on table creation to work.
Step 4:
   * When adding the code to the BookPeer, AuthorPeer, and PublisherPeer 
classes to return all rows, the line "import java.util.*;" (or just 
java.util.List) should be added at the top of the file since 
doSelectAll() returns a List object.

As you can see, the major problems have to do with the 
Torque.properties file in Step 2. The rest are fairly minor, and 
changing them would just make the existing material more clear to a 
beginner. I have not read enough about the development of the Torque 
project to completely understand where the changes occurred in the code 
that made Torque.database properties obsolete and made Torque.dsfactory 
necessary. I'm sure those more enlightened than I on the internal 
structure of the Torque project could provide the necessary 
explanation(s).

I would be happy to rewrite some of the text of these files, but would 
feel uncomfortable trying to tackle the 	explanations of the various 
properties in the table at the end of Step 2 until I have poked around 
more with the code.

Hopefully this message will help newbies get Torque up and running 
faster and the changes suggested will be incorporated into the 
documentation eventually. If I've missed anything, or ignorance has led 
me to suggest changes to things which are better left alone, please let 
me know...

-F