<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 -->

<document>

 <properties>
  <title>Migrating from 2.1 to 2.2</title>
 </properties>

<body>

<section name="Important note">
<p>
    The information in this HOWTO pertains to Turbine 2.2.  Please refer 
    to the <a href="migrate-from-2_2-howto.html">Migrating from 
    2.2 to 2.3</a> page for information on migating to Turbine 2.3.
</p>
</section>

<section name="Introduction">
<p>
    This document describes the basic steps needed to migrate an
    application written for Turbine 2.1 to Turbine 2.2 using the
    decoupled Torque.
</p>
<p>
    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.
</p>
</section>

<section name="Cleanup">
<p>
    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.
</p>
</section>

<section name="Build and Properties Files">
<p>
    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.
</p>
<p>
    From the demo application you should:
    <ul>
    <li>Merge <code>tdk-2.2/webapps/newapp/WEB-INF/conf/build.properties</code>
        with your existing properties file.</li>
    <li>Copy <code>build-torque.xml</code> from the demo application
        to your build directory.</li>
    <li>Copy <code>project-build.xml</code> from the demo application
        to your build directory.</li>
    <li>Merge <code>build.xml</code> 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).</li>
    <li>Copy <code>WEB-INF/conf/TurbineResources.template</code> and 
        <code>WEB-INF/conf/Torque.template</code>) 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
        <code>build.properties</code> or the other property files).</li>
    </ul>
</p>
<p>
    See the Torque 
  <a href="http://jakarta.apache.org/turbine/torque/properties-reference.html">
    Properties Reference</a> for full details of the available properties.
</p>
</section>

<section name="Libraries">
<p>
    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.
</p>
<p>
    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).
</p>
<p>
    By default Torque will utilize a set of  Velocity templates that
    you need to extract from the Torque jar file (see the 
    <code>torque.templatePath</code> 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 
    <code>torque.useClasspath</code> property to <code>true</code> in
    <code>build.peoperties</code>.  In any case, you should either 
    replace or delete the old versions of these templates from your
    existing project.
</p>
</section>

<section name="Import Statements">
<p>
    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.
</p>
<p>
    <a href="http://jakarta.apache.org/turbine/torque/changes.html#Torque%203.0-b3">
    [Here]</a> is list of the most common import changes.
</p>
</section>

<section name="Transactions and obtaining database connections">
<p>
    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.
</p>
<p>
    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.
</p>
<p>
    Below is an example of how you might have been obtaining database
    connections in version 2.1.
</p>

<source>
<![CDATA[
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.
    }
}
]]>
</source>
<p>
    Using the new version of Torque this would be rewritten as follows.
</p>
<source>
<![CDATA[
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);
}
]]>
</source>
<p>
    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.
</p>
<source>
<![CDATA[
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);
}
]]>
</source>
<p>
    This would now be written as shown below.
</p>
<source>
<![CDATA[
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);
}
]]>
</source>
</section>

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

<section name="Exception becomes TorqueException">
<p>
    Methods generated by Torque now throw <code>TorqueException</code>
    rather than <code>Exception</code>.  You might like to update
    your code to match.
</p>
<p>
    Note that the exception thrown by <code>save()</code> methods is 
    determined by the Torque property <code>torque.saveException</code>
    which defaults to <code>Exception</code>.
</p>
</section>

<section name="Extending Turbine User">
<p>
    See
    <a href="http://jakarta.apache.org/turbine/turbine-2/howto/extend-user-howto.html">
    Extending Turbine User How-To</a> for this information.
</p>
</section>

<section name="Changes to the OM classes">
<p>
    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).
</p>
<p>
    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.
</p>
<source>
<![CDATA[
public <base class> copy() throws TorqueException
{
    return copyInto(new <sub class>());
}
]]>
</source>
<p>
    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).
</p>
<p>
    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.
</p>
</section>

<section name="XML-RPC service">
<p>
    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.
</p>
<p>
    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.
</p>
</section>

<section name="Other services">
<p>
    Intake, Security, and Scheduler all work without a problem
    after migrating to T2.2.
</p>
</section>

<section name="Maven">
<p>
    You may like to consider using 
    <a href="http://jakarta.apache.org/turbine/maven/">Maven</a> to
    build your project.  The  document 
    <a href="http://nagoya.apache.org/wiki/apachewiki.cgi?JakartaTDK/Starting_Project_With_TDK2.2_And_Maven">
    Starting your project and database with TDK2.2 and Maven</a> 
    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).
</p>
</section>

<section name="Updates to this document">
<p>
    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.
</p>
</section>

</body>
</document>