Fork me on GitHub
Built by Maven

Important note

The information in this HOWTO pertains to Turbine 2.2. Please refer to the Migrating from 2.2 to 2.3 page for information on migating to Turbine 2.3.

Introduction

This document describes the basic steps needed to migrate an application written for Turbine 2.1 to Turbine 2.2 using the decoupled Torque.

You may find that migrating to 2.2 is not all that difficult. Of course, this depends quite a bit on how much of Turbine your application actually uses. You may find migrating to 2.2 to be quite a chore, but it is well worth the effort. Most of the pain in figuring out this migration process has been documented in the mailing list archives, but is summarized here for your convenience.

Cleanup

Start off with deleting all of the objects that Torque generated for you. I am talking about om.map.* and om.Base*. You will be able to regenerate them later during the migration process.

Build and Properties Files

The structure of the build files used by Turbine has changed quite a bit with the 2.2 release. The easiest way of obtaining a reference set of property (and build files) is to install version 2.2 of the TDK and generate the demo application.

From the demo application you should:

  • Merge tdk-2.2/webapps/newapp/WEB-INF/conf/build.properties with your existing properties file.
  • Copy build-torque.xml from the demo application to your build directory.
  • Copy project-build.xml from the demo application to your build directory.
  • Merge build.xml from the demo application to your existing build file (if you have only ever used the default build file supplied with the tdk then I assume you can just replace your file with the new one).
  • Copy WEB-INF/conf/TurbineResources.template and WEB-INF/conf/Torque.template) to your application and apply changes as needed (it is up to you as to how much you hard code into your application template and how much you allow to be processed into the resulting properties files by way of build.properties or the other property files).

See the Torque Properties Reference for full details of the available properties.

Libraries

Turbine and Torque use updated versions of a number of libraries (jar files). Take a look at the WEB-INF/lib directory of the TDK sample application to see which libraries have been updated and replace the files in the lib directory of your application as needed.

Note that if you have applied local changes to Turbine itself then you should ensure that your changes have made it into the Turbine 2.2 and Torque 3.0 releases. If any of your changes have not made it then you will need to port these changes forward and build your own versions of the Turbine and Torque jar files (while you are there you may as well create patches and submit them to the relevant modules in Scarab so that they can be included in future releases).

By default Torque will utilize a set of Velocity templates that you need to extract from the Torque jar file (see the torque.templatePath property). Unless you have a need to alter these templates you may prefer to use these directly from the jar file. To do this you need to set the torque.useClasspath property to true in build.peoperties. In any case, you should either replace or delete the old versions of these templates from your existing project.

Import Statements

Many of your import statements will need to be changed. This is due to the decoupled version of Torque. This will take care of most of the changes due to refactoring. There will still be a few cases (discussed later) where the methods have been changed and/or moved to different classes.

[Here] is list of the most common import changes.

Transactions and obtaining database connections

org.apache.turbine.util.db.DBConnection is gone. The replacement is java.sql.Connection. This was a wrapper class from the Connection object. It was returned when you asked for a database connection. The new version of Torque will simply return a Connection object.

org.apache.turbine.services.db.TurbineDB is gone. The replacement is org.apache.torque.Torque. This was mainly used to obtain database connections and the name of the default database. All of this functionality is in the new class.

Below is an example of how you might have been obtaining database connections in version 2.1. 


DBConnection dbConn = null;
try
{
    dbConn = TurbineDB.getConnection();
    // Do something with the connection here...
}
catch (Exception e)
{
    // Either from obtaining the connection or from your application code.
}
finally
{
    try
    {
        TurbineDB.releaseConnection(dbConn);
    }
    catch (Exception e)
    {
        // Error releasing database connection back to pool.
    }
}

Using the new version of Torque this would be rewritten as follows. 


Connection conn = null;
try
{
    conn = Torque.getConnection();
    // Do something with the connection here...
}
catch (TorqueException ex)
{
    // Either from obtaining the connection or from your application code.
	Log.error(ex);
}
finally
{
    Torque.closeConnection(conn);
}

Support for transactions has been moved from org.apache.turbine.om.BasePeer into org.apache.torque.util.Transaction. The method names have changed slightly as well. Here is an example of using transactions in 2.1. 


DBConnection dbConn = null;
try
{
    dbConn = BasePeer.beginTrasaction(TurbineDB.getDefaultDB?());
    someObject.save(dbConn);
    someOtherObject.save(dbConn);
    BasePeer.commitTransaction(dbConn);
}
catch (Exception e)
{
    // Either from obtaining the connection or from your application code.
    BasePeer?.rollbackTransaction(dbConn);
}

This would now be written as shown below. 


Connection conn = null;
try
{
    conn = Transaction.begin(Torque.getDefaultDB());
    someObject.save(conn);
    someOtherObject.save(conn);
    Transaction.commit(conn);
}
catch (TorqueException ex)
{
    try
    {
        Transaction.rollback(conn);
    }
    catch (TorqueException ex2)
    {
        Log.error(ex2);
    }
    Log.error(ex);
}

Vector becomes List

Methods generated by Torque that previously had a return type of Vector now have a return type of List. If you have not already been doing so you should switch to retrieving the results of these methods into variables declared as List. While you are at it you might like to update any of your own code to use ArrayList in preference to Vector.

Exception becomes TorqueException

Methods generated by Torque now throw TorqueException rather than Exception. You might like to update your code to match.

Note that the exception thrown by save() methods is determined by the Torque property torque.saveException which defaults to Exception.

Extending Turbine User

See Extending Turbine User How-To for this information.

Changes to the OM classes

Read over the Torque Schema Reference to find out what to change in your project-schema.xml file. The main changes are the deprecation of sequence and autoIncrement idMethods and the addition of the javaType attribute to column elements (Torque can now work with object types).

If you used inheritance, you will run need to specify abstract="true" for the tables which have abstract base classes. When you do this, you will need to implement the copy() method in your subclasses. An example is provided below. 


public <base class> copy() throws TorqueException
{
    return copyInto(new <sub class>());
}

Atributes defined as primary keys are no longer generated as NumberKey objects. They are now Integer or int (depending on the javaType specified in project-schema.xml).

If you have a turbine-schema.xml file in your WEB-INF/conf directory, the project-om ant task will generate all of the Turbine*, BaseTurbine*, and map.Turbine* objects for you. These will not be used by Turbine. They will only confuse you. The best thing to do for this is to rename your turbine-schema.xml file to something like turbine-schema.nogenerate.

XML-RPC service

My TurbineResources.properties did not have settings to configure the secure options. This caused initialization of the service to fail. To fix this, I simply obtained all of the configuration settings from the TurbineResources.properties included with the source version.

The service does not listen on the loopback interface by default any longer. There were no other changes that are required to get this service up and running under T2.2.

Other services

Intake, Security, and Scheduler all work without a problem after migrating to T2.2.

Maven

You may like to consider using Maven to build your project. The document Starting your project and database with TDK2.2 and Maven provides some information that can be adapted for this purpose (jump down to the "Moving The Sample" heading for the documentation relevant to an existing project).

Updates to this document

This document is by no means complete or totally accurate. We welcome suggestions as to how it might be improved, particularly if you have just completed migrating an application by following this howto.