umontreal.iro.lecuyer.util
Class JDBCManager

java.lang.Object
  umontreal.iro.lecuyer.util.JDBCManager

public class JDBCManager
extends Object

This class provides some facilities to connect to a SQL database and to retrieve data stored in it. JDBC provides a standardized interface for accessing a database independently of a specific database management system (DBMS). The user of JDBC must create a Connection object used to send SQL queries to the underlying DBMS, but the creation of the connection adds a DBMS-specific portion in the application. This class helps the developer in moving the DBMS-specific information out of the source code by storing it in a properties file. The methods in this class can read such a properties file and establish the JDBC connection. The connection can be made by using a DataSource obtained through a JNDI server, or by a JDBC URI associated with a driver class. Therefore, the properties used to connect to the database must be a JNDI name (jdbc.jndi-name), or a driver to load (jdbc.driver) with the URI of a database (jdbc.uri).

jdbc.driver=com.mysql.jdbc.Driver

jdbc.uri=jdbc:mysql://mysql.iro.umontreal.ca/database?user=foo&password=bar

The connection is established using the connectToDatabase method. Shortcut methods are also available to read the properties from a file or a resource before establishing the connection. This class also provides shortcut methods to read data from a database and to copy the data into Java arrays.

Constructor Summary

JDBCManager()

Method Summary

static Connection	connectToDatabase(File file) Equivalent to connectToDatabase (new FileInputStream (file)).
static Connection	connectToDatabase(InputStream is) Returns a connection to the database using the properties read from stream is.
static Connection	connectToDatabase(Properties prop) Connects to the database using the properties prop and returns the an object representing the connection.
static Connection	connectToDatabase(String fileName) Equivalent to connectToDatabase (new FileInputStream (fileName)).
static Connection	connectToDatabase(URL url) Equivalent to connectToDatabase (url.openStream()).
static Connection	connectToDatabaseFromResource(String resource) Uses connectToDatabase with the stream obtained from the resource resource.
static double[]	readDoubleData(Connection connection, String query) Copies the result of the SQL query query into an array of double-precision values.
static double[]	readDoubleData(Connection connection, String table, String column) Returns the values of the column column of the table table.
static double[]	readDoubleData(Statement stmt, String query) Copies the result of the SQL query query into an array of double-precision values.
static double[]	readDoubleData(Statement stmt, String table, String column) Returns the values of the column column of the table table.
static double[][]	readDoubleData2D(Connection connection, String query) Copies the result of the SQL query query into a rectangular 2D array of double-precision values.
static double[][]	readDoubleData2D(Statement stmt, String query) Copies the result of the SQL query query into a rectangular 2D array of double-precision values.
static double[][]	readDoubleData2DTable(Connection connection, String table) Returns the values of the columns of the table table.
static double[][]	readDoubleData2DTable(Statement stmt, String table) Returns the values of the columns of the table table.
static int[]	readIntData(Connection connection, String query) Copies the result of the SQL query query into an array of integers.
static int[]	readIntData(Connection connection, String table, String column) Returns the values of the column column of the table table.
static int[]	readIntData(Statement stmt, String query) Copies the result of the SQL query query into an array of integers.
static int[]	readIntData(Statement stmt, String table, String column) Returns the values of the column column of the table table.
static int[][]	readIntData2D(Connection connection, String query) Copies the result of the SQL query query into a rectangular 2D array of integers.
static int[][]	readIntData2D(Statement stmt, String query) Copies the result of the SQL query query into a rectangular 2D array of integers.
static int[][]	readIntData2DTable(Connection connection, String table) Returns the values of the columns of the table table.
static int[][]	readIntData2DTable(Statement stmt, String table) Returns the values of the columns of the table table.
static Object[]	readObjectData(Connection connection, String query) Copies the result of the SQL query query into an array of objects.
static Object[]	readObjectData(Connection connection, String table, String column) Returns the values of the column column of the table table.
static Object[]	readObjectData(Statement stmt, String query) Copies the result of the SQL query query into an array of objects.
static Object[]	readObjectData(Statement stmt, String table, String column) Returns the values of the column column of the table table.
static Object[][]	readObjectData2D(Connection connection, String query) Copies the result of the SQL query query into a rectangular 2D array of integers.
static Object[][]	readObjectData2D(Statement stmt, String query) Copies the result of the SQL query query into a rectangular 2D array of objects.
static Object[][]	readObjectData2DTable(Connection connection, String table) Returns the values of the columns of the table table.
static Object[][]	readObjectData2DTable(Statement stmt, String table) Returns the values of the columns of the table table.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JDBCManager

public JDBCManager()

Method Detail

connectToDatabase

public static Connection connectToDatabase(Properties prop)
                                    throws SQLException

Connects to the database using the properties prop and returns the an object representing the connection. The properties stored in prop must be a JNDI name (jdbc.jndi-name), or the name of a driver (jdbc.driver) to load and the URI of the database (jdbc.uri). When a JNDI name is given, this method constructs a context using the nullary constructor of InitialContext, uses the context to get a DataSource object, and uses the data source to obtain a connection. This method assumes that JNDI is configured correctly; see the class InitialContext for more information about configuring JNDI. If no JNDI name is specified, the method looks for a JDBC URI. If a driver class name is specified along with the URI, the corresponding driver is loaded and registered with the JDBC DriverManager. The driver manager is then used to obtain the connection using the URI. This method throws an SQLException if the connection failed and an IllegalArgumentException if the properties do not contain the required values.

Parameters:

prop - the properties to connect to the database.

Returns:

the connection to the database.

Throws:

SQLException - if the connection failed.

IllegalArgumentException - if the properties do not contain the require values.

connectToDatabase

public static Connection connectToDatabase(InputStream is)
                                    throws IOException,
                                           SQLException

Returns a connection to the database using the properties read from stream is. This method loads the properties from the given stream, and calls connectToDatabase to establish the connection.

Parameters:

is - the stream to read for the properties.

Returns:

the connection to the database.

Throws:

SQLException - if the connection failed.

IOException - if the stream can not be read correctly.

IllegalArgumentException - if the properties do not contain the require values.

connectToDatabase

public static Connection connectToDatabase(URL url)
                                    throws IOException,
                                           SQLException

Equivalent to connectToDatabase (url.openStream()).

Throws:

IOException

SQLException

connectToDatabase

public static Connection connectToDatabase(File file)
                                    throws IOException,
                                           SQLException

Equivalent to connectToDatabase (new FileInputStream (file)).

Throws:

IOException

SQLException

connectToDatabase

public static Connection connectToDatabase(String fileName)
                                    throws IOException,
                                           SQLException

Equivalent to connectToDatabase (new FileInputStream (fileName)).

Throws:

IOException

SQLException

connectToDatabaseFromResource

public static Connection connectToDatabaseFromResource(String resource)
                                                throws IOException,
                                                       SQLException

Uses connectToDatabase with the stream obtained from the resource resource. This method searches the file resource on the class path, opens the first resource found, and extracts properties from it. It then uses connectToDatabase to establish the connection.

Throws:

IOException

SQLException

readDoubleData

public static double[] readDoubleData(Statement stmt,
                                      String query)
                               throws SQLException

Copies the result of the SQL query query into an array of double-precision values. This method uses the statement stmt to execute the given query, and assumes that the first column of the result set contains double-precision values. Each row of the result set then becomes an element of an array of double-precision values which is returned by this method. This method throws an SQLException if the query is not valid.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readDoubleData

public static double[] readDoubleData(Connection connection,
                                      String query)
                               throws SQLException

Copies the result of the SQL query query into an array of double-precision values. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readDoubleData, which returns an array of double-precision values.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readDoubleData

public static double[] readDoubleData(Statement stmt,
                                      String table,
                                      String column)
                               throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readDoubleData (stmt, "SELECT column FROM table").

Throws:

SQLException

readDoubleData

public static double[] readDoubleData(Connection connection,
                                      String table,
                                      String column)
                               throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readDoubleData (connection, "SELECT column FROM table").

Throws:

SQLException

readIntData

public static int[] readIntData(Statement stmt,
                                String query)
                         throws SQLException

Copies the result of the SQL query query into an array of integers. This method uses the statement stmt to execute the given query, and assumes that the first column of the result set contains integer values. Each row of the result set then becomes an element of an array of integers which is returned by this method. This method throws an SQLException if the query is not valid. The given statement stmt must not be set up to produce forward-only result sets.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readIntData

public static int[] readIntData(Connection connection,
                                String query)
                         throws SQLException

Copies the result of the SQL query query into an array of integers. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readIntData, which returns an array of integers.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readIntData

public static int[] readIntData(Statement stmt,
                                String table,
                                String column)
                         throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readIntData (stmt, "SELECT column FROM table").

Throws:

SQLException

readIntData

public static int[] readIntData(Connection connection,
                                String table,
                                String column)
                         throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readIntData (connection, "SELECT column FROM table").

Throws:

SQLException

readObjectData

public static Object[] readObjectData(Statement stmt,
                                      String query)
                               throws SQLException

Copies the result of the SQL query query into an array of objects. This method uses the statement stmt to execute the given query, and extracts values from the first column of the obtained result set by using the getObject method. Each row of the result set then becomes an element of an array of objects which is returned by this method. The type of the objects in the array depends on the column type of the result set, which depends on the database and query. This method throws an SQLException if the query is not valid. The given statement stmt must not be set up to produce forward-only result sets.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readObjectData

public static Object[] readObjectData(Connection connection,
                                      String query)
                               throws SQLException

Copies the result of the SQL query query into an array of objects. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readObjectData, which returns an array of integers.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the first column of the result set.

Throws:

SQLException - if the query is not valid.

readObjectData

public static Object[] readObjectData(Statement stmt,
                                      String table,
                                      String column)
                               throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readObjectData (stmt, "SELECT column FROM table").

Throws:

SQLException

readObjectData

public static Object[] readObjectData(Connection connection,
                                      String table,
                                      String column)
                               throws SQLException

Returns the values of the column column of the table table. This method is equivalent to readObjectData (connection, "SELECT column FROM table").

Throws:

SQLException

readDoubleData2D

public static double[][] readDoubleData2D(Statement stmt,
                                          String query)
                                   throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of double-precision values. This method uses the statement stmt to execute the given query, and assumes that the columns of the result set contain double-precision values. Each row of the result set then becomes a row of a 2D array of double-precision values which is returned by this method. This method throws an SQLException if the query is not valid. The given statement stmt must not be set up to produce forward-only result sets.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readDoubleData2D

public static double[][] readDoubleData2D(Connection connection,
                                          String query)
                                   throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of double-precision values. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readDoubleData2D, which returns a 2D array of double-precision values.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readDoubleData2DTable

public static double[][] readDoubleData2DTable(Statement stmt,
                                               String table)
                                        throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readDoubleData2D (stmt, "SELECT * FROM table").

Throws:

SQLException

readDoubleData2DTable

public static double[][] readDoubleData2DTable(Connection connection,
                                               String table)
                                        throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readDoubleData2D (connection, "SELECT * FROM table").

Throws:

SQLException

readIntData2D

public static int[][] readIntData2D(Statement stmt,
                                    String query)
                             throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of integers. This method uses the statement stmt to execute the given query, and assumes that the columns of the result set contain integers. Each row of the result set then becomes a row of a 2D array of integers which is returned by this method. This method throws an SQLException if the query is not valid. The given statement stmt must not be set up to produce forward-only result sets.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readIntData2D

public static int[][] readIntData2D(Connection connection,
                                    String query)
                             throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of integers. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readIntData2D, which returns a 2D array of integers.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readIntData2DTable

public static int[][] readIntData2DTable(Statement stmt,
                                         String table)
                                  throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readIntData2D (stmt, "SELECT * FROM table").

Throws:

SQLException

readIntData2DTable

public static int[][] readIntData2DTable(Connection connection,
                                         String table)
                                  throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readIntData2D (connection, "SELECT * FROM table").

Throws:

SQLException

readObjectData2D

public static Object[][] readObjectData2D(Statement stmt,
                                          String query)
                                   throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of objects. This method uses the statement stmt to execute the given query, and extracts values from the obtained result set by using the getObject method. Each row of the result set then becomes a row of a 2D array of objects which is returned by this method. The type of the objects in the 2D array depends on the column types of the result set, which depend on the database and query. This method throws an SQLException if the query is not valid. The given statement stmt must not be set up to produce forward-only result sets.

Parameters:

stmt - the statement used to make the query.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readObjectData2D

public static Object[][] readObjectData2D(Connection connection,
                                          String query)
                                   throws SQLException

Copies the result of the SQL query query into a rectangular 2D array of integers. This method uses the active connection connection to create a statement, and passes this statement, with the query, to readObjectData2D, which returns a 2D array of integers.

Parameters:

connection - the active connection to the database.

query - the SQL query to execute.

Returns:

the columns of the result set.

Throws:

SQLException - if the query is not valid.

readObjectData2DTable

public static Object[][] readObjectData2DTable(Statement stmt,
                                               String table)
                                        throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readObjectData2D (stmt, "SELECT * FROM table").

Throws:

SQLException

readObjectData2DTable

public static Object[][] readObjectData2DTable(Connection connection,
                                               String table)
                                        throws SQLException

Returns the values of the columns of the table table. This method is equivalent to readObjectData2D (connection, "SELECT * FROM table").

Throws:

SQLException