Metacat

/**

 *  '$RCSfile$'

 *    Purpose: A Class that implements utility methods for a metadata catalog

 *  Copyright: 2000 Regents of the University of California and the

 *             National Center for Ecological Analysis and Synthesis

 *    Authors: Matt Jones, Jivka Bojilova

 *    Release: @release@

 * 

 *   '$Author: bojilova $'

 *     '$Date: 2000-09-26 13:03:30 -0700 (Tue, 26 Sep 2000) $'

 * '$Revision: 464 $'

 */

package edu.ucsb.nceas.metacat;

import java.io.File;

import java.net.URL;

import java.net.MalformedURLException;

import java.sql.Connection;

import java.sql.DriverManager;

import java.sql.SQLException;

import java.util.PropertyResourceBundle;

import java.util.Hashtable;

import java.util.Enumeration;

/**

 * A suite of utility classes for the metadata catalog server

 */

public class MetaCatUtil {

  private PropertyResourceBundle options = null;

  private String propertiesFile = "edu.ucsb.nceas.metacat.metacat";

  private Hashtable connectionPool = new Hashtable();

  private static boolean debug = false;

  /**

   * Construct an instance of the utility class

   */

  public MetaCatUtil() {

    options = (PropertyResourceBundle)

          PropertyResourceBundle.getBundle(propertiesFile);

  }

  /**

   * This constructor allows the usage of a different properties file

   * @param propFile the properties file that you wish to use.

   */

  public MetaCatUtil(String propFile)

  {

    propertiesFile = propFile;

  }

  /** 

   * Utility method to establish a JDBC database connection using connection

   * info from the properties file

   */

  public Connection openDBConnection()

                throws SQLException, ClassNotFoundException {

    return openDBConnection(getOption("dbDriver"), getOption("defaultDB"),

                     getOption("user"), getOption("password"));

  }

  /** 

   * Utility method to establish a JDBC database connection 

   *

   * @param dbDriver the string representing the database driver

   * @param connection the string representing the database connectin parameters

   * @param user name of the user to use for database connection

   * @param password password for the user to use for database connection

   */

  public static Connection openDBConnection(String dbDriver, String connection,

                String user, String password)

                throws SQLException, ClassNotFoundException {

     // Load the Oracle JDBC driver

     Class.forName (dbDriver);

     debugMessage("Opening connection: " + connection);

     // Connect to the database

     Connection conn = DriverManager.getConnection( connection, user, password);

     return conn;

  }

  /** 

   * Utility method to get an option value from the properties file

   *

   * @param option_name the name of the option requested

   */

  public String getOption(String option_name) {

      // Get the configuration file information

      if (options == null) {

        options = (PropertyResourceBundle)

          PropertyResourceBundle.getBundle(propertiesFile);

      }

      String value = (String)options.handleGetObject(option_name);

      return value;

  }

  /* Utility method to create and return a pool of Connection objects */

  public Hashtable getConnectionPool()

                throws SQLException, ClassNotFoundException {

    int initConn = (new Integer(getOption("initialConnections"))).intValue();

    for ( int i = 0; i < initConn; i++ ) {

        connectionPool.put( openDBConnection(), Boolean.FALSE );

    }    

    return connectionPool;

  }

  /* Utility method to get a unused Connection object from the pool */

  public Connection getConnection()

                throws SQLException, ClassNotFoundException, Exception {

    Connection conn = null;

    Enumeration connections = connectionPool.keys();

    synchronized (connectionPool) {

      while (connections.hasMoreElements()) {

        conn = (Connection)connections.nextElement();

        Boolean b = (Boolean)connectionPool.get(conn);

        if (conn == null) {

            // closed connection; replace it

            conn = openDBConnection();

            // update the pool to show this one taken

            connectionPool.put(conn, Boolean.TRUE);  

            return conn;

        } else if (b == Boolean.FALSE) {

            // unused connection; test if it works and get it

            try {

                conn.setAutoCommit(true);

            } catch (SQLException e) {

                // problem with the connection, replace it

                conn = openDBConnection();

            }    

            // update the pool to show this one taken

            connectionPool.put(conn, Boolean.TRUE);    

            return conn;

        }    

      }  

    }   

    // If we get here, there no free connections;

    // we need to make more

    int incConn = (new Integer(getOption("incrementConnections"))).intValue();

    int maxConn = (new Integer(getOption("maximumConnections"))).intValue();

    int k = connectionPool.size();

    if ( k >= maxConn ) {

        throw new Exception("The maximum of " + maxConn + 

                            " open db connections is reached." +

                            " New db connection to MetaCat" +

                            " cannot be established.");

    }    

    // decide how many new connections to open; no more than the maximum

    if ( incConn > maxConn - k ) { incConn = maxConn - k; }

    // get them

    for ( int i = 0; i < incConn; i++ ) {

        connectionPool.put( openDBConnection(), Boolean.FALSE );

    }

    // Recurse to get one of the new connections

    return getConnection();

  }

  /* Utility method to give the connection back to the pool */

  public void returnConnection (Connection returned) {

    Connection conn;

    Enumeration connections = connectionPool.keys();

    if (returned != null) {

      while (connections.hasMoreElements()) {

        conn = (Connection)connections.nextElement();

        if ( conn == returned ) {

            connectionPool.put( conn, Boolean.FALSE );

            break;

        }    

      }    

    }

  }

  /* Return the size of the pool */

  public int getPoolSize() {

    return connectionPool.size();

  }

  /* Utility method to close all the connection from the pool */

  public void closeConnections() {

    Connection conn;

    Enumeration connections = connectionPool.keys();

    while (connections.hasMoreElements()) {

        conn = (Connection)connections.nextElement();

        if ( conn != null ) {

            try {

                conn.close();

            } catch (SQLException e) {}    

        }    

    }

  }

  /** Utility method to convert a file handle into a URL */

  public static URL fileToURL(File file)

  {

     String path = file.getAbsolutePath();

     String fSep = System.getProperty("file.separator");

     if (fSep != null && fSep.length() == 1)

       path = path.replace(fSep.charAt(0), '/');

     if (path.length() > 0 && path.charAt(0) != '/')

       path = '/' + path;

     try {

       return new URL("file", null, path);

     }

     catch (java.net.MalformedURLException e) {

       /* According to the spec this could only happen if the file

          protocol were not recognized. */

       throw new Error("unexpected MalformedURLException");

     }

  }

  /** 

   * Utility method to print debugging messages

   *

   * @param flag an integer indicating the message number

   */

  public static void debugMessage(int flag) {

    if (debug) {

      System.err.println("DEBUG FLAG: " + flag);

    }

  }

  /** 

   * Utility method to print debugging messages

   *

   * @param flag an integer indicating the message number

   */

  public static void debugMessage(String msg) {

    if (debug) {

      System.err.println(msg);

    }

  }

}

/**

 * '$Log$

 * 'Revision 1.15  2000/08/14 22:31:13  berkley

 * 'added new constructor to allow the creation of a metacatutil object that uses a properties file other than edu.ucsb.nceas.metacat.metacat.

 * '

 * 'Revision 1.14  2000/08/14 20:53:34  jones

 * 'Added "release" keyword to all metacat source files so that the release

 * 'number will be evident in software distributions.

 * '

 * 'Revision 1.13  2000/08/09 00:39:47  jones

 * '-Reorganized xmltodb module to support new install process for the new

 * 'linux server (dev.nceas.ucsb.edu).  Added "build.sh" shell script that

 * 'calls ant withthe proper umask set for installation.  Use:

 * '

 * '  ./build.sh install

 * '

 * 'to post a new copy of the servlet and its supporting files to the install

 * 'directory defined in build.xml.

 * '

 * '-Updated the servlet to use a new servlet prefix that we'll use with the

 * 'Tomcat servlet engine.

 * '

 * '-Update bin dir shell scripts to reflect new locations of relevant jar files.

 * '

 * 'Revision 1.12  2000/08/04 23:34:10  bojilova

 * 'more precise handling of the Connection Pool

 * '

 * 'Revision 1.11  2000/08/01 18:26:50  bojilova

 * 'added Pool of Connections

 * 'DBQuery, DBReader, DBTransform, DBUtil are created on every request and use the connections from the Pool

 * 'same with DBWriter and DBValidate

 * '

 * 'Revision 1.10  2000/06/26 10:35:05  jones

 * 'Merged in substantial changes to DBWriter and associated classes and to

 * 'the MetaCatServlet in order to accomodate the new UPDATE and DELETE

 * 'functions.  The command line tools and the parameters for the

 * 'servlet have changed substantially.

 * '

 * 'Revision 1.9.2.4  2000/06/26 00:51:06  jones

 * 'If docid passed to DBWriter.write() is not unique, classes now generate

 * 'an AccessionNumberException containing the new docid generated as a

 * 'replacement.  The docid is then extracted from the exception and

 * 'returned to the calling application for user feedback or client processing.

 * '

 * 'Revision 1.9.2.3  2000/06/25 23:38:17  jones

 * 'Added RCSfile keyword

 * '

 * 'Revision 1.9.2.2  2000/06/25 23:34:18  jones

 * 'Changed documentation formatting, added log entries at bottom of source files

 * ''

 */