PoemDatabaseFactory

/*
 * $Source$
 * $Revision$
 *
 * Copyright (C) 2007 Tim Pizey
 *
 * Part of Melati (http://melati.org), a framework for the rapid
 * development of clean, maintainable web applications.
 *
 * Melati is free software; Permission is granted to copy, distribute
 * and/or modify this software under the terms either:
 *
 * a) the GNU General Public License as published by the Free Software
 *    Foundation; either version 2 of the License, or (at your option)
 *    any later version,
 *
 *    or
 *
 * b) any version of the Melati Software License, as published
 *    at http://melati.org
 *
 * You should have received a copy of the GNU General Public License and
 * the Melati Software License along with this program;
 * if not, write to the Free Software Foundation, Inc.,
 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
 * GNU General Public License and visit http://melati.org to obtain the
 * Melati Software License.
 *
 * Feel free to contact the Developers of Melati (http://melati.org),
 * if you would like to work out a different arrangement than the options
 * outlined here.  It is our intention to allow Melati to be used by as
 * wide an audience as possible.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * Contact details for copyright holder:
 *
 *     Tim Pizey <timp At paneris.org>
 *     http://paneris.org/~timp
 */
package org.melati.poem;

import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Vector;

/**
 * @author timp
 * @since 2 Feb 2007
 *
 */
public final class PoemDatabaseFactory {

  private static final Hashtable<String,Database> databases = new Hashtable<String,Database>();

  private static PoemShutdownThread poemShutdownThread = new PoemShutdownThread();

  /**
   * Disallow instantiation.
   */
  private PoemDatabaseFactory() {
  }

  /**
   * Retrieve the databases which have completed initialisation.
   *
   * @return a <code>Vector</code> of the initialised databases
   */
  public static Vector<Database> initialisedDatabases() {
    Vector<Database> dbs = new Vector<Database>();
    Enumeration<String> e = null;
    synchronized (databases) {
      e = databases.keys();
      while (e.hasMoreElements()) {
        Database dbOrPending = databases.get(e.nextElement());
        if (dbOrPending != pending)
          dbs.addElement(dbOrPending);
      }
    }
    return dbs;
  }

  /**
   * Retrieve the names of the databases which have completed initialisation.
   * Note that a database which has not been used will not have been initialised.
   *
   * @return a <code>Vector</code> of the initialised database names
   */
  public static Vector<String> getInitialisedDatabaseNames() {
    Vector<String> dbs = new Vector<String>();
    Enumeration<String> e = null;
    synchronized (databases) {
      e = databases.keys();
      while (e.hasMoreElements()) {
        String key = (String)e.nextElement();
        Object dbOrPending = databases.get(key);
        if (dbOrPending != pending)
          dbs.addElement(key);
      }
    }
    return dbs;
  }

  private static final Database pending = new PoemDatabase();

  /**
   * Retrieve a database by name.
   *
   * @param name
   *          the name of the database
   * @throws DatabaseInitialisationPoemException
   *           if any Exception is trapped
   * @return a <code>Database</code> with the name specified
   */
  public static Database getDatabase(String name)
          throws DatabaseInitialisationPoemException {
    if (name == null)
      throw new NullPointerException();

    Object dbOrPending;

    synchronized (databases) {
      dbOrPending = databases.get(name);
    }
    if (dbOrPending == pending)
      throw new ConnectionPendingException(name);
    return (Database)dbOrPending;
  }

  /**
   * Return a database from the cache or create it. NOTE The first sucessful
   * invocation will determine databases settings.
   *
   * @param name
   *          a short name of the db
   * @param url
   *          a JDBC url
   * @param user
   *          user authorised to access the databse through JDBC
   * @param password
   *          password for the user
   * @param clazz
   *          the name of the (POEM) database class
   * @param dbmsClass
   *          the name of the (POEM) dbms class
   * @param addConstraints
   *          whether to add constraints to the databases JDBC meta data
   * @param logSQL
   *          whether SQL statements should be logged
   * @param logCommits
   *          whether commits should be logged
   * @param maxTransactions
   *          the number of transactions (one less than the number of
   *          connections)
   * @return a new or existing database
   */
  public static Database getDatabase(String name, String url, String user,
          String password, String clazz, String dbmsClass,
          boolean addConstraints, boolean logSQL, boolean logCommits,
          int maxTransactions) {

    Database dbOrPending;

    synchronized (databases) {
      dbOrPending = databases.get(name);
    }
    if (dbOrPending == pending)
      throw new ConnectionPendingException(name);
    if (dbOrPending != null)
      return (Database)dbOrPending;

    // Set an entry whilst we load
    databases.put(name, pending);

    Database database = null;
    try {

      try {
        Object databaseObject = null;

        try {
          databaseObject = Thread.currentThread().getContextClassLoader()
                  .loadClass(clazz).newInstance();
        } catch (Exception e) {
          databaseObject = Class.forName(clazz).newInstance();
        }

        if (!(databaseObject instanceof Database))
          throw new ClassCastException("The .class=" + clazz
                  + " entry named a class of type " + databaseObject.getClass()
                  + ", " + "which is not an org.melati.poem.Database");

        database = (Database)databaseObject;

        // Set properties
        database.setLogSQL(logSQL);
        database.setLogCommits(logCommits);

        database.connect(name, dbmsClass, url, user, password, maxTransactions);

        if (addConstraints)
          database.addConstraints();
      } finally {
        // get it removed from the "initialising" state even if an Error, such
        // as no class found, occurs
        databases.remove(name);
      }

      databases.put(name, database);
    } catch (Exception e) {
      throw new DatabaseInitialisationPoemException(name, e);
    }
    return database;
  }

  /**
   * Enable a database to be reinitialised, without
   * incurring the full overhead of restarting hsqldb,
   * used in tests.
   *
   * @param name
   *          name of db to remove
   */
  public static void removeDatabase(String name) {
    databases.remove(name);
  }

  /**
   * Disconnect and disconnect from a known database.
   *
   * @param name
   *          name of db to remove
   */
  public static void disconnectDatabase(String name) {
    Database db = (Database)databases.get(name);
    if(db != null && db.getCommittedConnection() != null) {
      db.disconnect();
      databases.remove(name);
    }
  }

  /**
   * Disconnect from all initialised databases.
   */
  public static void disconnectFromDatabases() {
    Vector<String> dbs = PoemDatabaseFactory.getInitialisedDatabaseNames();
    Enumeration<String> them = dbs.elements();
    while (them.hasMoreElements()) {
      disconnectDatabase((String)them.nextElement());
    }
  }
  /**
   * Shutdown databases cleanly when JVM exits.
   *
   * This method is called in one of two ways: when the jvm exits or when a
   * ServletContext is detroyed.
   * Jetty, and presumably other servlet containers, registers its listeners as
   * shutdown hooks too, so there is no way of determining which is to be executed first.
   *
   * If PoemDatabaseFactory has not been initialised before the ContextListener is
   * activated then this thread will be created but will fail to register.
   * It will then be run by the ContextListener.
   *
   * It may well be that the registered thread will be run before the ContextListener thread,
   * or visa versa, so there is a synchronised variable to ensure it actually does something
   * only the first time.
   *
   * @author timp
   * @since 23 May 2007
   * See org.melati.servlet.PoemServletContextListener
   *
   */
  public static class PoemShutdownThread extends Thread {
    /** Constructor. */
    public PoemShutdownThread() {
      super();
      setName("PoemShutdownThread");
      try {
        Runtime.getRuntime().addShutdownHook(this);
        System.err.println("\n*** PoemShutdownThread registered. ***\n");
      } catch (IllegalStateException e) {
        System.err.println("\n*** PoemShutdownThread tried to register during shutdown. ***\n");

        // Happens when the PoemServletContextListener
        // tries to shutdown databases when none have yet been
        // initialised.
        e = null;
      }
    }
    private static Boolean haveRun = Boolean.FALSE;
    /**
     * {@inheritDoc}
     *
     * @see java.lang.Thread#run()
     */
    public void run() {
      synchronized(haveRun) {
        if (!haveRun.booleanValue()) {
          haveRun = Boolean.TRUE;
          try {
            boolean removed = Runtime.getRuntime().removeShutdownHook(this);
            System.err.println("\n*** PoemShutdownThread removed: " + removed + " ***\n");
          } catch (IllegalStateException e) {
            System.err.println("\n*** PoemShutdownThread cannot be removed at this stage. ***\n");
            // I think this happens during normal termination,
            // you cannot remove a hook during shutdown,
            // but if we are run when not in shutdown
            // we do want to be removed.
            e = null;
          }
          System.err.println("*** PoemShutdownThread starting to shutdown dbs. ***");
          disconnectFromDatabases();
          System.err.println("*** PoemShutdownThread has shutdown dbs. ***");
        } else
          System.err.println("*** PoemShutdownThread has already run. ***");
      }
    }
  }
  /**
   * @return the poemShutdownThread
   */
  public static PoemShutdownThread getPoemShutdownThread() {
    return poemShutdownThread;
  }

}