/*

  * 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.

  */

 package org.apache.commons.scaffold.sql;

 import java.sql.Connection;

 import java.sql.SQLException;

 import javax.naming.Context;

 import javax.naming.InitialContext;

 import javax.naming.NamingException;

 import javax.sql.DataSource;

 /**

  * Base class for SQL connection adaptors. May be used as-is or subclassed.

  * <p>

  * This object does not provide any type of connection pooling.

  * It simply provides a standard means for obtaining a connection

  * whatever connection pool your application needs.

  * Scaffold classes in the SQL package call this object internally.

  * <p>

  * To use as-is, a DataSource compliant connection pool must be

  * available as "DATA_SOURCE" via JNDI. A subclass can

  * locate the pool under any name by any means necessary.

  *<p>

  * A <code>ConnectionAdaptor</code> can be instantiated once at

  * start-up, either from main() or via a servlet, like the

  * Scaffold ConnectionServlet.

  * Objects needing a connection can then call the static

  * method

  * <code>ConnectionAdaptor.getPool().getConnection()</code>.

  * <p>

  * Most implementations will expect callers to use and

  * close the connections promptly, since they would

  * usually be part of a pool.

  * <p>

  * Subclasses can provide their own resource name or

  * getConnection() method, and a new constructor to

  * set the protected pool field to their own

  * instance. See <code>PoolmanAdaptor</code> for an example.

  *

  * @see org.apache.commons.scaffold.http.ConnectionServlet

  * @see org.apache.commons.scaffold.sql.PoolmanAdaptor

  * @author Ted Husted

  * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $

  */

 public class ConnectionAdaptor {

 // ------------------------------------------------------------ message

     /**

      * A message for an exception if pool returns null.

      */

     private String message = "Connection pool " +

         "not available. Check your configuration.";

     /**

      * Return a message for an exception if pool returns null.

      *

      * @return Message for an exception if pool returns null

      */

     protected String getMessage() {

         return this.message;

     }

     /**

      * Set a message for an exception if pool returns null.

      * Adaptor subclasses can call this from their constructor.

      *

      * @param Message The message for an exception if pool returns null

      */

     protected void setMessage(String message) {

         this.message = message;

     }

 // ---------------------------------------------------------------- key

     /**

      * The default DataSource name.

      */

     public static final String DATA_SOURCE_KEY = "DATA_SOURCE";

     /**

      * The default JNDI context for applications.

      */

     public static final String JNDI_CONTEXT_KEY = "java:comp/env";

     /**

      * The attribute under which our DataSource is stored

      * [DATA_SOURCE_KEY].

      */

     private String key = DATA_SOURCE_KEY;

     /**

      * Return the attribute under which our datasource is stored.

      * Subclasses may override this method to provide a different key,

      * or set a new key at construction.

      */

     public String getKey() {

         return this.key;

     }

     /**

      * The attribute under which our datasource is stored.

      * Adaptor subclasses can call this method from a constructor

      * to change the default resource name.

      */

     public void setKey(String key) {

         this.key = key;

     }

 // --------------------------------------------------------- datasource

    /**

     * Field to store singleton reference to default datasource.

     *

     * TODO: Add Map to store reference to other datasoruces.

     */

     protected static DataSource datasource;

    /**

     * Return datasource using JNDI lookup. Subclasses may

     * override this method to provide other means of obtaining

     * a datasource reference.

     *

     * @param key The attribute name for the resource.

     * If null is passed, null is returned.

     * @return null or the datasource object related to "key"

     *

     * TODO: Add cache to store references to the datasources by key.

     */

     protected DataSource getDataSource(String key)

             throws SQLException {

         if (null==key) return null;

         try {

             Context env = (Context) new

                 InitialContext().lookup(JNDI_CONTEXT_KEY);

             return (DataSource) env.lookup(key);

         }

         catch (NamingException ne) {

             // Recast naming exception,

             // since that is what other routines only except

             // and because another implementation may not generate this.

             // Should only be an issue during initial setup

             throw new SQLException(ne.getMessage());

         }

     } // end getDataSource

 // --------------------------------------------------------- connection

     /**

      * Returns a JDBC connection from the default resource.

      * Calls <code>getDatasource</code> to return the resource

      * associated with the default attribute name [getKey()].

      * <p>

      * The default datasource object is cached and reused in subsequent

      * calls.

      *

      * @return JDBC connection from resource layer.

      * @exception SQLException on SQL or other errors. May wrap other

      * exceptions depending on implementation. Will not return null.

      */

     public Connection getConnection() throws SQLException {

         if (null==datasource) {

             datasource = getDataSource(getKey());

             if (null==datasource)

                 throw new SQLException(getMessage());

         }

         return (datasource.getConnection());

     } // end getConnection

     /**

      * Returns a JDBC connection from a connection pool or other

      * named resource, to be used and closed promptly.

      * <p>

      * Default implementation uses JNDI to lookup the resource named by

      * getResource() ["DATASOURCE"].

      * Will not return null.

      *

      * @return JDBC connection from resource layer.

      * @exception SQLException on SQL or other errors. May wrap

      * other exceptions depending on implementation.

      * @param resource An attribute name for the resource to use for

      * this connection or null to call getResource()

      * @return A working connection; will not return null

      * @exception SQLException On any SQL error or if pool returns null

      */

     public Connection getConnection(String key)

             throws SQLException {

         if (null==key) return getConnection();

         DataSource ds = getDataSource(key);

         if (null==ds)

             throw new SQLException(getMessage());

         return (ds.getConnection());

     } // end getConnection

 // --------------------------------------------------------------- pool

    /**

     * Field to store singleton reference to adaptor pool.

     * This would usually be private for a singleton,

     * but adaptor subclasses may set the pool upon initialization.

     * <p>

     * <code>if (null==pool) set pool = this</code>.

     */

     protected static ConnectionAdaptor pool;

    /**

     * Return adaptor instance to use in acquiring connection.

     * <p>

     * This is the main entry method to the object.

     * Client's should call:<br>

     * <code>Adaptor.getPool().getConnection()</code>

     * to acquire a connection from the default pool.

     */

     public static ConnectionAdaptor getPool() {

         if (null==pool) pool = new ConnectionAdaptor();

         return pool;

     } // end getPool

 } // end ConnectionAdaptor