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: 2001-05-08 14:40:46 -0700 (Tue, 08 May 2001) $'

 * '$Revision: 739 $'

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of 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.

 *

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

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

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 || conn.isClosed()) {

            // 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();

    try {

      if ( (returned != null) && !(returned.isClosed()) ) {

        while (connections.hasMoreElements()) {

          conn = (Connection)connections.nextElement();

          if ( conn == returned ) {

            connectionPool.put( conn, Boolean.FALSE );

            break;

          }    

        }    

      }

    } catch (SQLException e) {}    

  }

  /* 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();

        try {

            if ( (conn != null) && !(conn.isClosed()) ) {

              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 parse the query part of a URL into parameters. This

   * method assumes the format of the query par tof the url is an 

   * ampersand separated list of name/value pairs, with equal signs separating

   * the name from the value (e.g., name=tom&zip=99801 ). Returns a

   * has of the name value pairs, hashed on name.

   */

  public static Hashtable parseQuery(String query) throws MalformedURLException

  {

    String[][] params = new String[200][2];

    Hashtable parameters = new Hashtable();

    String temp = "";

    boolean ampflag = true;

    boolean poundflag = false;

    int arrcount = 0;

    if ( query != null ) {

      for (int i=0; i < query.length(); i++) { 

        // go throught the remainder of the query one character at a time.

        if (query.charAt(i) == '=') { 

          // if the current char is a # then the preceding should be a name

          if (!poundflag && ampflag) {

            params[arrcount][0] = temp.trim();

            temp = "";

          } else { 

            //if there are two #s or &s in a row throw an exception.

            throw new MalformedURLException("metacatURL: Two parameter names "+

                                            "not allowed in sequence");

          }

          poundflag = true;

          ampflag = false;

        } else if (query.charAt(i) == '&' || i == query.length()-1) { 

          //the text preceding the & should be the param value.

          if (i == query.length() - 1) { 

            //if at the end of the string grab the last value and append it.

            if (query.charAt(i) != '=') { 

            //ignore an extra & on the end of the string

              temp += query.charAt(i);

            }

          }

          if (!ampflag && poundflag) {

            params[arrcount][1] = temp.trim();

            parameters.put(params[arrcount][0], params[arrcount][1]);

            temp = "";

            arrcount++; //increment the array to the next row.

          } else { 

            //if there are two =s or &s in a row through an exception

            throw new MalformedURLException("metacatURL: Two parameter values "+

                                            "not allowed in sequence");

          }

          poundflag = false;

          ampflag = true;

        } else { 

          //get the next character in the string

          temp += query.charAt(i);

        }

      }

    }

    return parameters;

  }

  /** 

   * 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);

    }

  }

}