Suggested fixes for Torque tutorial

[Finn Smith <fc...@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

Re: Suggested fixes for Torque tutorial

[Geoff Fortytwo <g4...@ign.com>]

>A HOWTO for creating a Torque project around an existing database would 
>probably be useful for a lot of people. You run into a different set of 
>issues than those encountered when building up an application from scratch.

http://g42.org/programming/torque/TorqueHowto.html

Re: Suggested fixes for Torque tutorial

[Finn Smith <fc...@modcult.org>]

On Sunday, February 16, 2003, at 08:22 PM, Travis Walker McCauley wrote:

>
> I am a beginner who just got Torque running last week. It took me about
> two full days and many trips to the list archives to figure stuff out
> (including running the 'jdbc' target on my existing database to 
> generate
> the schema for my data).
> ...
> The other step that's missing is how to compile the OM and where to put
> the Torque.properties file during runtime.
>

Hm... those are both in the tutorial here: 
http://db.apache.org/torque/tutorial/index.html
Which are the pages I was talking about in my post.

For where Torque.properties goes, in Step 2 it reads: "Create a new 
file called Torque.properties in the top-level torque directory."

For how to compile, in Step 4 it reads: "Now that you've generated your 
object model with Torque, and created a sample application, you are now 
ready to compile everything. Again, Ant is used to control the build 
process. To compile, type the following in the Torque top-level 
directory:
ant -f build-torque.xml compile"

A HOWTO for creating a Torque project around an existing database would 
probably be useful for a lot of people. You run into a different set of 
issues than those encountered when building up an application from 
scratch.

-F

Re: Suggested fixes for Torque tutorial

[Travis Walker McCauley <tw...@unix.mail.virginia.edu>]

I am a beginner who just got Torque running last week. It took me about
two full days and many trips to the list archives to figure stuff out
(including running the 'jdbc' target on my existing database to generate
the schema for my data).

I  agree that the DatasourceFactory issue needs addressing because that
took
me quite a while get passed and it was just luck that I found somebody's
suggested settings posted to the list. It did seem that there were a lot
of people who had posted with the same DatasourceFactory problems..

The other step that's missing is how to compile the OM and where to put
the Torque.properties file during runtime.

It might be worth suggesting to set Torque to use Objects instead of
primitives. My generated source wouldn't compile until I did that.

It was sure worth the effort though! I can't believe what Torque makes
possible. Thanks to all the people who created it.

Sincerely,
Travis McCauleyy