Thomas,

Although I'm +1 on the solution for customizable adapters, the 
implementation could be slightly improved in my eyes. The method 
DBFactory.create(String) throws an exception in the case where a custom DB 
adapter is used. I am in favour of not throwing exceptions if a legal 
condition occurs, so I'd rather return null in the method. I can do it if 
you do not mind.

Would you also mind to add some documentation to the 
initialisation-configuration.xml in the runtime reference ? This is where 
(hopefully) all runtime configuration settings should be explained.

     Thomas

On Sun, 23 Jul 2006, tv@apache.org wrote:

> Author: tv
> Date: Sun Jul 23 13:05:14 2006
> New Revision: 424794
>
> URL: http://svn.apache.org/viewvc?rev=424794&view=rev
> Log:
> - Provide support for user loadable DB adapters
> - Extend TorqueInstanceTest and configuration
> - Adjust documentation
>
> Modified:
>    db/torque/runtime/trunk/src/java/org/apache/torque/TorqueInstance.java
>    db/torque/runtime/trunk/src/java/org/apache/torque/adapter/DBFactory.java
>    db/torque/runtime/trunk/src/test/TurbineResources.properties
>    db/torque/runtime/trunk/src/test/org/apache/torque/TorqueInstanceTest.java
>    db/torque/runtime/trunk/xdocs/reference/new-database-support.xml
>
> Modified: db/torque/runtime/trunk/src/java/org/apache/torque/TorqueInstance.java
> URL: http://svn.apache.org/viewvc/db/torque/runtime/trunk/src/java/org/apache/torque/TorqueInstance.java?rev=424794&r1=424793&r2=424794&view=diff
> ==============================================================================
> --- db/torque/runtime/trunk/src/java/org/apache/torque/TorqueInstance.java (original)
> +++ db/torque/runtime/trunk/src/java/org/apache/torque/TorqueInstance.java Sun Jul 23 13:05:14 2006
> @@ -53,6 +53,7 @@
>  * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
>  * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
>  * @author <a href="mailto:kschrader@karmalab.org">Kurt Schrader</a>
> + * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
>  * @version $Id$
>  */
> public class TorqueInstance
> @@ -238,7 +239,25 @@
>                 {
>                     String adapter = c.getString(key);
>                     String handle = key.substring(0, key.indexOf('.'));
> -                    DB db = DBFactory.create(adapter);
> +
> +                    DB db;
> +
> +                    try
> +                    {
> +                        db = DBFactory.create(adapter);
> +                    }
> +                    catch (InstantiationException e)
> +                    {
> +                        db = null;
> +                    }
> +
> +                    // Not supported, try manually defined adapter class
> +                    if (db == null)
> +                    {
> +                        String adapterClassName = c.getString(key + "." + adapter + ".className", null);
> +                        db = DBFactory.create(adapter, adapterClassName);
> +                    }
> +
>                     Database database = getOrCreateDatabase(handle);
>
>                     // register the adapter for this name
>
> Modified: db/torque/runtime/trunk/src/java/org/apache/torque/adapter/DBFactory.java
> URL: http://svn.apache.org/viewvc/db/torque/runtime/trunk/src/java/org/apache/torque/adapter/DBFactory.java?rev=424794&r1=424793&r2=424794&view=diff
> ==============================================================================
> --- db/torque/runtime/trunk/src/java/org/apache/torque/adapter/DBFactory.java (original)
> +++ db/torque/runtime/trunk/src/java/org/apache/torque/adapter/DBFactory.java Sun Jul 23 13:05:14 2006
> @@ -135,4 +135,50 @@
>                 + ": Check your configuration file");
>         }
>     }
> +
> +    /**
> +     * Creates a new instance of the Torque database adapter associated
> +     * with the specified JDBC driver or adapter key and the class defined.
> +     *
> +     * @param driver The fully-qualified name of the JDBC driver to
> +     * create a new adapter instance for or a shorter form adapter key.
> +     * @param className The fully qualified name of the adapter class
> +     * @return An instance of a Torque database adapter.
> +     * @throws InstantiationException throws if the JDBC driver could not be
> +     *      instantiated
> +     */
> +    public static DB create(String driver, String className)
> +        throws InstantiationException
> +    {
> +        Class adapterClass;
> +
> +        try
> +        {
> +            adapterClass = (Class) Class.forName(className);
> +        }
> +        catch (ClassNotFoundException e)
> +        {
> +            throw new InstantiationException(
> +                    "Could not find adapter "
> +                    + className
> +                    + " for driver "
> +                    + driver
> +                    + ": Check your configuration file");
> +        }
> +
> +        try
> +        {
> +            DB adapter = (DB) adapterClass.newInstance();
> +            adapters.put(driver, adapterClass);
> +            // adapter.setJDBCDriver(driver);
> +            return adapter;
> +        }
> +        catch (IllegalAccessException e)
> +        {
> +            throw new InstantiationException(
> +                "Could not instantiate adapter for JDBC driver: "
> +                + driver
> +                + ": Assure that adapter bytecodes are in your classpath");
> +        }
> +    }
> }
>
> Modified: db/torque/runtime/trunk/src/test/TurbineResources.properties
> URL: http://svn.apache.org/viewvc/db/torque/runtime/trunk/src/test/TurbineResources.properties?rev=424794&r1=424793&r2=424794&view=diff
> ==============================================================================
> --- db/torque/runtime/trunk/src/test/TurbineResources.properties (original)
> +++ db/torque/runtime/trunk/src/test/TurbineResources.properties Sun Jul 23 13:05:14 2006
> @@ -70,7 +70,8 @@
> # -------------------------------------------------------------------
>
> torque.database.default = turbine
> -torque.database.turbine.adapter=mysql
> +torque.database.turbine.adapter=mymysql
> +torque.database.turbine.adapter.mymysql.className=org.apache.torque.adapter.DBMM
> torque.dsfactory.turbine.factory= org.apache.torque.dsfactory.SharedPoolDataSourceFactory
> torque.idbroker.prefetch=false
>
>
> Modified: db/torque/runtime/trunk/src/test/org/apache/torque/TorqueInstanceTest.java
> URL: http://svn.apache.org/viewvc/db/torque/runtime/trunk/src/test/org/apache/torque/TorqueInstanceTest.java?rev=424794&r1=424793&r2=424794&view=diff
> ==============================================================================
> --- db/torque/runtime/trunk/src/test/org/apache/torque/TorqueInstanceTest.java (original)
> +++ db/torque/runtime/trunk/src/test/org/apache/torque/TorqueInstanceTest.java Sun Jul 23 13:05:14 2006
> @@ -7,6 +7,7 @@
> import org.apache.commons.configuration.Configuration;
> import org.apache.commons.configuration.ConfigurationException;
> import org.apache.commons.configuration.PropertiesConfiguration;
> +import org.apache.torque.adapter.DB;
> import org.apache.torque.dsfactory.DataSourceFactory;
> import org.apache.torque.map.DatabaseMap;
> import org.apache.torque.map.MapBuilder;
> @@ -73,6 +74,16 @@
>     }
>
>     /**
> +     * Tests whether an external adapter is loaded correctly.
> +     * @throws Exception if an error occurs during the Test.
> +     */
> +    public void testExternalAdapter() throws Exception
> +    {
> +        DB adapter = Torque.getDatabase(TURBINE_NAME).getAdapter();
> +        assertNotNull(adapter);
> +    }
> +
> +    /**
>      * Checks whether a DataSourceFactory with the name
>      * <code>DEFAULT_NAME</code> is defined. (TRQS 322)
>      * @throws Exception if an error occurs during the Test.
> @@ -120,7 +131,7 @@
>                     defaultDatabase,
>                     turbineDatabase);
>     }
> -
> +
>     public void testShutdown() throws Exception
>     {
>         // because we have not properly initialized the DataSourceFactory,
>
> Modified: db/torque/runtime/trunk/xdocs/reference/new-database-support.xml
> URL: http://svn.apache.org/viewvc/db/torque/runtime/trunk/xdocs/reference/new-database-support.xml?rev=424794&r1=424793&r2=424794&view=diff
> ==============================================================================
> --- db/torque/runtime/trunk/xdocs/reference/new-database-support.xml (original)
> +++ db/torque/runtime/trunk/xdocs/reference/new-database-support.xml Sun Jul 23 13:05:14 2006
> @@ -21,6 +21,7 @@
>   <title>Torque Runtime Reference - Support for new Databases</title>
>   <author email="jon@latchkey.com">Jon S. Stevens</author>
>   <author email="fischer@seitenbau.de">Thomas Fischer</author>
> +  <author email="tv@apache.org">Thomas Vandahl</author>
>  </properties>
>
>  <body>
> @@ -41,7 +42,7 @@
>       by Torque to generate a SQL schema for your RDBMS--in the templates
>       component. The recommend method for doing this is to copy an existing set
>       of templates and adapt them to your RDBMS as needed.  This is not
> -      elaborated forther here.
> +      elaborated further here.
>     </p>
>
>   </section>
> @@ -49,7 +50,7 @@
>   <section name="Database Adapters">
>
>     <p>
> -      A database adapter class is a class that extends
> +      A database adapter class is a class that implements
>       <code>org.apache.torque.adapter.DB</code> and encapsulates access
>       to a specific RDBMS implementation. Database adapter classes already
>       found in Torque include DBOracle, DBMM, DBSybase, etc.
> @@ -75,10 +76,12 @@
>     <p>
>       <ul>
>         <li>
> -          Create a new class DB&lt;dbname> that extends
> +          Create a new class DB&lt;dbname> that implements
>           <code>org.apache.torque.adapter.DB</code> (where dbname is the name of
> -          the database or database driver you wish to add to Torque). DB is an
> -          abstract class, so you need to implement a number of methods.
> +          the database or database driver you wish to add to Torque). An abstract
> +          implementation, <code>org.apache.torque.adapter.AbstractDBAdapter</code> is
> +          provided which sets some defaults so that you only need to implement a
> +          number of methods.
>         </li>
>
>         <li>
> @@ -89,6 +92,13 @@
>         </li>
>
>         <li>
> +          Implement generateLimits(). This method has to provide the special
> +          SQL expressions to limit the number of records returned and/or the
> +          offset into the result set. This is only needed if supportsNativeLimit()
> +          or supportsNativeOffset() return true.
> +        </li>
> +
> +        <li>
>           Implement getIdMethodType(). This method should return the method
>           the database uses to generates unique Ids.  Valid return values are
>           <code>org.apache.torque.adapter.IDMethod.AUTO_INCREMENT</code>,
> @@ -141,6 +151,19 @@
>       </ul>
>     </p>
>
> +  </section>
> +
> +  <section name="Configuring Torque to use the new adapter">
> +    <p>
> +      The adapter you wrote does not need to be compiled into Torque but
> +      it can be referenced in the configuration. Just use a new short name for
> +      the adapter and provide the class name in the configuration file. See the
> +      following example:
> +    </p>
> +    <source>
> +torque.database.mydatabase.adapter=myadapter
> +torque.database.mydatabase.adapter.myadapter.className=com.acme.DBMyAdapter
> +    </source>
>   </section>
>
>  </body>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
> For additional commands, e-mail: torque-dev-help@db.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org