This User Guide is intended to help those who want to incorporate Torque into their project to provide a means of persistence for application objects.
Torque consists of two main components:
If you have not already done so, download and install Maven. You then need to obtain the Torque maven plugin. The Maven Howto includes details of how to build the maven plugin from source, but you can easily install a binary distribution thus:
maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=torque -Dversion=3.2
If you prefer to use Ant you need access to the Torque generator distribution and associated libraries - these are available from the Downloads page (the file to download is torque-gen-3.2.tar.gz or torque-gen-3.2.zip, depending on your development platform). Unpack the archive to reveal the following directory structure:
torque-gen-3.2/ docs/ <--- Contains a copy of the Torque documentation, including the API JavaDocs. lib/ <--- Contains the jar files required by the Torque generator, including the torque-gen-templates jar containing the templates. If you want to modify the templates, you can unpack the templates jar, set the <code>torque.useClasspath</code> to <code>false</code> and the <code>torque.schema.dir</code> to the correct directory in the <code>build.properties</code> src/schema/ <--- Contains the schema for the table used by Torque's IDBroker. build.properties <--- The various properties that you use to configure the Torque generator. build-torque.xml <--- The Ant build file containing the various torque goals. default.properties <--- The default property values that are used to configure the Torque generator. LICENSE.txt <--- The License for the Torque generator. torque-gen-3.2.jar <--- The generator jar.
The instructions below are targeted towards using the Torque maven-plugin.
If you are using Ant the instructions are basically the same, but instead of
using project.properties
you use build.properties
and instead of using maven torque:${goal-name}
you use
ant -f build-torque.xml ${target-name}
.
At runtime the generated object model classes need access to the Torque runtime distribution and associated libraries - these are available from the Downloads page (the file to download is torque-3.1.1.tar.gz or torque-3.1.1.zip, depending on your development platform). We will cover what to do with this file in a later step.
For those who just want to see Torque here we will race our way through all that needs to be done to define, generate and use a Torque object model.
For a complete list of generator properties, please refer to the properties reference. Below is a short list of the primary properties you should be interested in.
torque.project |
torque.database |
torque.targetPackage |
torque.database.createUrl |
torque.database.buildUrl |
torque.database.url |
torque.database.driver |
torque.database.user |
torque.database.password |
torque.database.host |
This is an example of what the XML database schema might look like. This particular example is a snippet of the database used for role-based user system of Turbine.
<database name="my_project"> <table name="ID_TABLE"> <column name="ID_TABLE_ID" required="true" primaryKey="true" type="INTEGER"/> <column name="TABLE_NAME" required="true" size="255" type="VARCHAR"/> <column name="NEXT_ID" type="INTEGER"/> <column name="QUANTITY" type="INTEGER"/> <unique> <unique-column name="TABLE_NAME"/> </unique> </table> <table name="TURBINE_PERMISSION" idMethod="idbroker"> <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER"/> <column name="PERMISSION_NAME" required="true" size="99" type="VARCHAR" javaName="Name"/> <unique> <unique-column name="PERMISSION_NAME"/> </unique> </table> <table name="TURBINE_ROLE_PERMISSION"> <column name="ROLE_ID" required="true" primaryKey="true" type="INTEGER"/> <column name="PERMISSION_ID" required="true" primaryKey="true" type="INTEGER"/> <foreign-key foreignTable="TURBINE_ROLE"> <reference local="ROLE_ID" foreign="ROLE_ID"/> </foreign-key> <foreign-key foreignTable="TURBINE_PERMISSION"> <reference local="PERMISSION_ID" foreign="PERMISSION_ID"/> </foreign-key> </table> </database>
Please refer to Torque Schema Reference to find out more about the the different elements and attributes.
The runtime distribution archive includes an Ant build file that can be used to generate your Torque runtime configuration - see the Torque tutSorial for details.
torque.database.default = my_project torque.database.my_project.adapter = mysql # Using commons-dbcp torque.dsfactory.my_project.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory torque.dsfactory.my_project.connection.driver = org.gjt.mm.mysql.Driver torque.dsfactory.my_project.connection.url = jdbc:mysql://localhost:3306/my_project torque.dsfactory.my_project.connection.user = user torque.dsfactory.my_project.connection.password = password
The above example uses the commons-dbcp connection pool - see
Pool-config Howto
details of the available DataSource
factories.
In order to be able to compile and use the generated class files it is
necessary to include the Torque runtime jar file and jar files for all of
the necessary dependencies in the classpath of your project. The necessary
jars are included in the torque/lib
directory of the Torque
runtime. If you are using Maven to build your project it may be easiest to
copy the necessary dependencies from the
Torque
runtime POM.
Generate the object model and associated SQL:
maven torque
Note: Torque will drop the database and tables that it is about to create if they exist! You should skip the next two steps if you are working with an existing database full of data.
To creating the database:
maven torque:create-db
To create the tables:
maven torque:id-table-init-sql maven torque:insert-sql
The following is an example of using the Torque object model classes - it is adapted from the Torque tutorial.
import java.util.*; import ...om.*; import org.apache.torque.Torque; import org.apache.torque.util.Criteria; public class Bookstore { public static void main(String[] args) { try { /* Initialize Torque */ Torque.init("Torque.properties"); /* Creating new objects */ Publisher addison = new Publisher(); addison.setName("Addison Wesley Professional"); addison.save(); Author bloch = new Author(); bloch.setFirstName("Joshua"); bloch.setLastName("Bloch"); bloch.save(); /* Foreign keys provided using convenience methods and manually. */ Book tcpip = new Book(); tcpip.setTitle("TCP/IP Illustrated, Volume 1"); tcpip.setISBN("0-201-63346-9"); effective.setPublisher(addison); tcpip.setAuthorId(stevens.getAuthorId()); tcpip.save(); /* Selecting all books */ List booklist = BookPeer.doSelectAll(); // iterate over booklist, casting the items to Book /* Selecting specific objects */ Criteria crit = new Criteria(); crit.add(BookPeer.ISBN, "0-201-63346-9"); booklist = BookPeer.doSelect(crit); // iterate over booklist, casting the items to Book /* Updating data */ effective.setAuthor(stevens); effective.save(); tcpip.setAuthor(bloch); BookPeer.doUpdate(tcpip); /* Deleting data */ crit = new Criteria(); crit.add(BookPeer.ISBN, "0-618-12902-2"); BookPeer.doDelete(crit); crit = new Criteria(); crit.add(BookPeer.ISBN, "0-201-63346-9"); crit.add(BookPeer.TITLE, "TCP/IP Illustrated, Volume 1"); BookPeer.doDelete(crit); AuthorPeer.doDelete(bloch); AuthorPeer.doDelete(stevens); PublisherPeer.doDelete(addison); } catch (Exception e) { e.printStackTrace(); } } }