Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.base.database
Class ConnectionManager

java.lang.Object
  extended by com.jivesoftware.base.database.ConnectionManager

public class ConnectionManager
extends java.lang.Object

Central manager of database connections. All methods are static so that they can be easily accessed throughout the classes in the database package.

This class also provides a set of utility methods that abstract out operations that may not work on all databases such as setting the max number or rows that a query should return.

In most cases, Jive is able to determine appropriate meta-data about what features the database and JDBC driver support. However, certain meta-data can be manually set by editing Jive properties. Generally, these values should only be set manually if you are running into specific problems with them:

See Also:
ConnectionProvider

Nested Class Summary
static class ConnectionManager.DatabaseType
          A class that identifies the type of the database that Jive is connected to.
 
Method Summary
static void batchDeleteWithoutSubqueries(java.sql.Connection con, java.lang.String sql, long[] objectIDs)
          Batch deletes a set of objects for the case when sub-selects are not supported (MySQL versions earlier than 4.1).
static void close(java.sql.Statement stmt)
          Closes a prepared statement.
static void closeConnection(java.sql.Connection con)
          Closes a database connection (returning the connection to the connection pool).
static void closeConnection(java.sql.PreparedStatement pstmt, java.sql.Connection con)
          Closes a prepared statement and database connection (returning the connection to the connection pool).
static void closeConnection(java.sql.ResultSet rs, java.sql.Statement stmt, java.sql.Connection con)
          Closes a result set, prepared statement and database connection (returning the connection to the connection pool).
static void closeConnection(java.sql.Statement stmt, java.sql.Connection con)
          Closes a statement and database connection (returning the connection to the connection pool).
static void closeResultSet(java.sql.ResultSet rs)
          Closes a result set.
static void closeStatement(java.sql.Statement stmt)
          Closes a prepared statement.
static void closeTransactionConnection(java.sql.Connection con, boolean abortTransaction)
          Closes a transactional connection.
static void closeTransactionConnection(java.sql.PreparedStatement pstmt, java.sql.Connection con, boolean abortTransaction)
          Closes a prepated statement and transactional connection.
static void closeTransactionConnection(java.sql.ResultSet rs, java.sql.PreparedStatement pstmt, java.sql.Connection con, boolean abortTransaction)
           
static void closeTransactionConnection(java.sql.Statement stmt, java.sql.Connection con, boolean abortTransaction)
          Closes a prepared statement and transactional connection.
static java.sql.PreparedStatement createScrollablePreparedStatement(java.sql.Connection con, java.lang.String sql)
          Creates a scrollable PreparedStatement if the JDBC driver supports it, or a normal PreparedStatement otherwise.
static java.sql.Statement createScrollableStatement(java.sql.Connection con)
          Creates a scrollable Statement if the JDBC driver supports it, or a normal Statement otherwise.
static void disablePostgresTablescan(java.sql.Connection con)
          Disables table scanning in Postgres for the connection.
static void enablePostgresTablescan(java.sql.Connection con)
          Enables table scanning in Postgres for the connection.
static java.lang.String getAltSyntaxName(java.lang.String originalName)
          Returns the alternate syntax name for the given schema resource (db name, column, etc).
static java.lang.String getAltSyntaxName(java.lang.String originalName, boolean showTableName)
          Returns the alternate syntax name for the given schema resource (db name, column, etc).
static java.io.InputStream getBlob(java.sql.ResultSet rs, int columnIndex)
          Retrives a binary column from a result set, automatically performing streaming if the JDBC driver requires it.
static java.sql.Connection getConnection()
          Returns a database connection from the currently active connection provider.
static ConnectionProvider getConnectionProvider()
          Returns the current connection provider.
static ConnectionManager.DatabaseType getDatabaseType()
          Returns the database type.
static java.util.Date getDateField(java.sql.ResultSet rs, int columnIndex)
          Deprecated. Use rs.setLong(long)
static int getDateType()
          Returns the SQL type from Types that Date information is stored in.
static java.lang.String getLargeTextField(java.sql.ResultSet rs, int columnIndex)
          Retrives a large text column from a result set, automatically performing streaming if the JDBC driver requires it.
static java.sql.Connection getTransactionConnection()
          Returns a Connection from the currently active connection provider that is ready to participate in transactions (auto commit is set to false).
static boolean isBatchUpdatesSupported()
           
static boolean isDeleteSubqueriesSupported()
           
static boolean isFetchSizeSupported()
           
static boolean isMaxRowsSupported()
           
static boolean isProfilingEnabled()
          Returns true if connection profiling is turned on.
static boolean isScrollResultsSupported()
           
static boolean isStreamBlobRequired()
           
static boolean isStreamTextRequired()
           
static boolean isSubqueriesSupported()
           
static boolean isTransactionsSupported()
           
static boolean isUseAltSyntaxForLongSchemaNames()
          Returns true if we're using the alternate syntax for longer schema names in the database scripts (names longer than 18 characters), false otehrwise.
static void scrollResultSet(java.sql.ResultSet rs, int rowNumber)
          Scrolls forward in a result set to the specified row number.
static void setConnectionProvider(ConnectionProvider provider)
          Sets the connection provider.
static void setDateField(java.sql.PreparedStatement pstmt, int parameterIndex, java.util.Date value)
          Deprecated. User rs.setLong(long)
static void setFetchSize(java.sql.ResultSet rs, int fetchSize)
          Sets the number of rows that the JDBC driver should buffer at a time.
static void setLargeTextField(java.sql.PreparedStatement pstmt, int parameterIndex, java.lang.String value)
          Sets a large text column in a result set, automatically performing streaming if the JDBC driver requires it.
static void setMaxRows(java.sql.Statement stmt, int maxRows)
          Sets the max number of rows that should be returned from executing a statement.
static void setProfilingEnabled(boolean enable)
          Turns connection profiling on or off.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getConnection

public static java.sql.Connection getConnection()
                                         throws java.sql.SQLException
Returns a database connection from the currently active connection provider. (auto commit is set to true).

Throws:
java.sql.SQLException

closeConnection

public static void closeConnection(java.sql.Statement stmt,
                                   java.sql.Connection con)
Closes a statement and database connection (returning the connection to the connection pool). This method should be called within the finally section of your database logic, as in the following example:

 Connection con = null;
 Statment stmt = null;
 try {
     con = ConnectionManager.getConnection();
     stmt = con.createStatement("select * from blah");
     ....
 }
 catch (SQLException sqle) {
     Log.error(sqle);
 }
 finally {
     ConnectionManager.closeConnection(stmt, con);
 }

Parameters:
stmt - the statement.
con - the connection.

closeConnection

public static void closeConnection(java.sql.PreparedStatement pstmt,
                                   java.sql.Connection con)
Closes a prepared statement and database connection (returning the connection to the connection pool). This method should be called within the finally section of your database logic, as in the following example:

 Connection con = null;
 PrepatedStatment pstmt = null;
 try {
     con = ConnectionManager.getConnection();
     pstmt = con.prepareStatement("select * from blah");
     ....
 }
 catch (SQLException sqle) {
     Log.error(sqle);
 }
 finally {
     ConnectionManager.closeConnection(pstmt, con);
 }

Parameters:
pstmt - the prepared statement.
con - the connection.

closeConnection

public static void closeConnection(java.sql.ResultSet rs,
                                   java.sql.Statement stmt,
                                   java.sql.Connection con)
Closes a result set, prepared statement and database connection (returning the connection to the connection pool). This method should be called within the finally section of your database logic, as in the following example:

 Connection con = null;
 PrepatedStatment stmt = null;
 ResultSet rs = null;
 try {
     con = ConnectionManager.getConnection();
     stmt = con.prepareStatement("select * from blah");
     rs = psmt.executeQuery();
     ....
 }
 catch (SQLException sqle) {
     Log.error(sqle);
 }
 finally {
     ConnectionManager.closeConnection(rs, stmt, con);
 }

Parameters:
rs - the result set.
stmt - the statement.
con - the connection.

closeConnection

public static void closeConnection(java.sql.Connection con)
Closes a database connection (returning the connection to the connection pool). Any statements associated with the connection should be closed before calling this method. This method should be called within the finally section of your database logic, as in the following example:

 Connection con = null;
 try {
     con = ConnectionManager.getConnection();
     ....
 }
 catch (SQLException sqle) {
     Log.error(sqle);
 }
 finally {
     ConnectionManager.closeConnection(con);
 }

Parameters:
con - the connection.

close

public static void close(java.sql.Statement stmt)
Closes a prepared statement. This method should be called within the finally section of your database logic, as in the following example:

  public void doSomething(Connection con) {
      PreparedStatement stmt = null;
      try {
          stmt = con.prepareStatement("select * from blah");
          ....
      }
      catch (SQLException sqle) {
          Log.error(sqle);
      }
      finally {
          ConnectionManager.close(stmt);
      }
 } 

Parameters:
stmt - the statement.

closeStatement

public static void closeStatement(java.sql.Statement stmt)
Closes a prepared statement. This method should be called within the finally section of your database logic, as in the following example:

  public void doSomething(Connection con) {
      PreparedStatement stmt = null;
      try {
          stmt = con.prepareStatement("select * from blah");
          ....
      }
      catch (SQLException sqle) {
          Log.error(sqle);
      }
      finally {
          ConnectionManager.closeStatement(stmt);
      }
 } 

Parameters:
stmt - the statement.

closeResultSet

public static void closeResultSet(java.sql.ResultSet rs)
Closes a result set. This method should be called within the finally section of your database logic, as in the following example:

  public void doSomething(Connection con) {
      ResultSet rs = null;
      PreparedStatement pstmt = null;
      try {
          pstmt = con.prepareStatement("select * from blah");
          rs = pstmt.executeQuery();
          ....
      }
      catch (SQLException sqle) {
          Log.error(sqle);
      }
      finally {
          ConnectionManager.closeResultSet(rs);
          ConnectionManager.closeStatement(pstmt);
      }
 } 


getTransactionConnection

public static java.sql.Connection getTransactionConnection()
                                                    throws java.sql.SQLException
Returns a Connection from the currently active connection provider that is ready to participate in transactions (auto commit is set to false).

Throws:
java.sql.SQLException

closeTransactionConnection

public static void closeTransactionConnection(java.sql.Statement stmt,
                                              java.sql.Connection con,
                                              boolean abortTransaction)
Closes a prepared statement and transactional connection. The transaction will be committed or rolled back depending on the value of abortTransaction.

Parameters:
stmt - the statement to close
con - the connection to close
abortTransaction - whether or not to abort the transaction

closeTransactionConnection

public static void closeTransactionConnection(java.sql.PreparedStatement pstmt,
                                              java.sql.Connection con,
                                              boolean abortTransaction)
Closes a prepated statement and transactional connection. The transaction will be committed or rolled back depending on the value of abortTransaction.


closeTransactionConnection

public static void closeTransactionConnection(java.sql.ResultSet rs,
                                              java.sql.PreparedStatement pstmt,
                                              java.sql.Connection con,
                                              boolean abortTransaction)

closeTransactionConnection

public static void closeTransactionConnection(java.sql.Connection con,
                                              boolean abortTransaction)
Closes a transactional connection. The transaction will be committed or rolled back depending on the value of abortTransaction.


createScrollableStatement

public static java.sql.Statement createScrollableStatement(java.sql.Connection con)
                                                    throws java.sql.SQLException
Creates a scrollable Statement if the JDBC driver supports it, or a normal Statement otherwise.

Parameters:
con - the database connection.
Returns:
a forward-scrollable Statement.
Throws:
java.sql.SQLException - if an error occurs.

createScrollablePreparedStatement

public static java.sql.PreparedStatement createScrollablePreparedStatement(java.sql.Connection con,
                                                                           java.lang.String sql)
                                                                    throws java.sql.SQLException
Creates a scrollable PreparedStatement if the JDBC driver supports it, or a normal PreparedStatement otherwise.

Parameters:
con - the database connection.
sql - the SQL to create the PreparedStatement with.
Returns:
a forward-scrollable PreparedStatement.
Throws:
java.sql.SQLException - if an error occurs.

disablePostgresTablescan

public static void disablePostgresTablescan(java.sql.Connection con)
                                     throws java.sql.SQLException
Disables table scanning in Postgres for the connection. If the database is not Postgres, this method is a no-op. Disabling table scanning is necessary in cases to force Postgres to use an index when it's query planner says otherwise. The enablePostgresTablescan(java.sql.Connection) method mus be called before the connection is returned to the pool. Typical code block:

 Connection con = null;
 Pstmt pstmt = null;
 try {
     con = ConnectionManager.getConnection();
     ConnectionManager.disablePostgresTablescan(con);
     ...
 }
 finally {
     ConnectionManager.enablePostgresTablescan(con);
     ConnectionManager.closeConnection(pstmt, con);
 }

Parameters:
con - the connection.
Throws:
java.sql.SQLException - if an exception occurs.

enablePostgresTablescan

public static void enablePostgresTablescan(java.sql.Connection con)
Enables table scanning in Postgres for the connection. If the database is not Postgres, this method is a no-op. This method is typically called to compliment a call to disable table scanning. Disabling table scanning is necessary in cases to force Postgres to use an index when it's query planner says otherwise. Typical code block:

 Connection con = null;
 Pstmt pstmt = null;
 try {
     con = ConnectionManager.getConnection();
     ConnectionManager.disablePostgresTablescan(con);
     ...
 }
 finally {
     ConnectionManager.enablePostgresTablescan(con);
     ConnectionManager.closeConnection(pstmt, con);
 }

Parameters:
con - the connection.

scrollResultSet

public static void scrollResultSet(java.sql.ResultSet rs,
                                   int rowNumber)
                            throws java.sql.SQLException
Scrolls forward in a result set to the specified row number. If the JDBC driver supports the feature, the cursor will be moved directly. Otherwise, we scroll through results one by one manually by calling rs.next().

Parameters:
rs - the ResultSet object to scroll.
rowNumber - the row number to scroll forward to.
Throws:
java.sql.SQLException - if an error occurs.

getConnectionProvider

public static ConnectionProvider getConnectionProvider()
Returns the current connection provider. The only case in which this method should be called is if more information about the current connection provider is needed. Database connections should always be obtained by calling the getConnection method of this class.


setConnectionProvider

public static void setConnectionProvider(ConnectionProvider provider)
Sets the connection provider. The old provider (if it exists) is shut down before the new one is started. A connection provider should not be started before being passed to the connection manager because the manager will call the start() method automatically.

Parameters:
provider - the ConnectionProvider that the manager should obtain connections from.

getLargeTextField

public static java.lang.String getLargeTextField(java.sql.ResultSet rs,
                                                 int columnIndex)
                                          throws java.sql.SQLException
Retrives a large text column from a result set, automatically performing streaming if the JDBC driver requires it. This is necessary because different JDBC drivers have different capabilities and methods for retrieving large text values.

Parameters:
rs - the ResultSet to retrieve the text field from.
columnIndex - the column in the ResultSet of the text field.
Returns:
the String value of the text field.
Throws:
java.sql.SQLException

getBlob

public static java.io.InputStream getBlob(java.sql.ResultSet rs,
                                          int columnIndex)
                                   throws java.sql.SQLException
Retrives a binary column from a result set, automatically performing streaming if the JDBC driver requires it. This is necessary because different JDBC drivers have different capabilities and methods for retrieving blob values.

Parameters:
rs - the ResultSet to retrieve the blob field from.
columnIndex - the column in the ResultSet of the blob field.
Returns:
an InputStream of the binary data
Throws:
java.sql.SQLException

setLargeTextField

public static void setLargeTextField(java.sql.PreparedStatement pstmt,
                                     int parameterIndex,
                                     java.lang.String value)
                              throws java.sql.SQLException
Sets a large text column in a result set, automatically performing streaming if the JDBC driver requires it. This is necessary because different JDBC drivers have different capabilities and methods for setting large text values.

Parameters:
pstmt - the PreparedStatement to set the text field in.
parameterIndex - the index corresponding to the text field.
value - the String to set.
Throws:
java.sql.SQLException

getDateField

public static java.util.Date getDateField(java.sql.ResultSet rs,
                                          int columnIndex)
                                   throws java.sql.SQLException
Deprecated. Use rs.setLong(long)

Returns a date/time field as a Date.

Parameters:
rs - the ResultSet.
columnIndex - the column index that contains date information.
Returns:
the Date.
Throws:
java.sql.SQLException - if an error occurs.

setDateField

public static void setDateField(java.sql.PreparedStatement pstmt,
                                int parameterIndex,
                                java.util.Date value)
                         throws java.sql.SQLException
Deprecated. User rs.setLong(long)

Sets a date/time field using a Date.

Parameters:
pstmt - the PreparedStatement.
parameterIndex - the index of the parameter that will be set with date information.
value - the Date.
Throws:
java.sql.SQLException - if an error occurs.

getDateType

public static int getDateType()
Returns the SQL type from Types that Date information is stored in.

Returns:
the date field type.

setMaxRows

public static void setMaxRows(java.sql.Statement stmt,
                              int maxRows)
Sets the max number of rows that should be returned from executing a statement. The operation is automatically bypassed if Jive knows that the the JDBC driver or database doesn't support it.

Parameters:
stmt - the Statement to set the max number of rows for.
maxRows - the max number of rows to return.

setFetchSize

public static void setFetchSize(java.sql.ResultSet rs,
                                int fetchSize)
Sets the number of rows that the JDBC driver should buffer at a time. The operation is automatically bypassed if Jive knows that the the JDBC driver or database doesn't support it.

Parameters:
rs - the ResultSet to set the fetch size for.
fetchSize - the fetchSize.

batchDeleteWithoutSubqueries

public static void batchDeleteWithoutSubqueries(java.sql.Connection con,
                                                java.lang.String sql,
                                                long[] objectIDs)
                                         throws java.sql.SQLException
Batch deletes a set of objects for the case when sub-selects are not supported (MySQL versions earlier than 4.1). When batch deletes are not supported, the records to delete must first be selected into a long array and then passed into this method along with a SQL framgement that can be used to delete the records. The SQL fragment must be in the form "DELETE FROM [table] WHERE [column] IN". This method will then use that SQL fragment to build a SQL query to delete multiple records at once (which should be significantly faster than looping through and deleting individual records.

Parameters:
con - the connection to use.
sql - the SQL fragment used to delete the records. It must be in the form "DELETE FROM [table] WHERE [column] IN".
objectIDs - an array of long values to delete.
Throws:
java.sql.SQLException - if an exception occurs.

getDatabaseType

public static ConnectionManager.DatabaseType getDatabaseType()
Returns the database type. The possible types are constants of the DatabaseType class. Any database that doesn't have its own constant falls into the "Other" category.

Returns:
the database type.

isProfilingEnabled

public static boolean isProfilingEnabled()
Returns true if connection profiling is turned on. You can collect profiling statistics by using the static methods of the ProfiledConnection class.

Returns:
true if connection profiling is enabled.

setProfilingEnabled

public static void setProfilingEnabled(boolean enable)
Turns connection profiling on or off. You can collect profiling statistics by using the static methods of the ProfiledConnection class.

Parameters:
enable - true to enable profiling; false to disable.

isTransactionsSupported

public static boolean isTransactionsSupported()

isStreamTextRequired

public static boolean isStreamTextRequired()

isStreamBlobRequired

public static boolean isStreamBlobRequired()

isMaxRowsSupported

public static boolean isMaxRowsSupported()

isFetchSizeSupported

public static boolean isFetchSizeSupported()

isSubqueriesSupported

public static boolean isSubqueriesSupported()

isDeleteSubqueriesSupported

public static boolean isDeleteSubqueriesSupported()

isScrollResultsSupported

public static boolean isScrollResultsSupported()

isBatchUpdatesSupported

public static boolean isBatchUpdatesSupported()

isUseAltSyntaxForLongSchemaNames

public static boolean isUseAltSyntaxForLongSchemaNames()
Returns true if we're using the alternate syntax for longer schema names in the database scripts (names longer than 18 characters), false otehrwise. By default, this method will return false which means we use the normal, longer names for schema names (for backwards compatibility).

Returns:
true if the short syntax for schema names should be used false otherwise.

getAltSyntaxName

public static java.lang.String getAltSyntaxName(java.lang.String originalName)
Returns the alternate syntax name for the given schema resource (db name, column, etc). If the alt syntax is not being used then this method no-ops and the given name parameter is returned.

Parameters:
originalName - the original name of the table/method, etc.
Returns:
the alternate (usually shorter) name of the resource or the name itself if we're not in alt synatx mode. This method will also return the original name if no alternate syntax was found.

getAltSyntaxName

public static java.lang.String getAltSyntaxName(java.lang.String originalName,
                                                boolean showTableName)
Returns the alternate syntax name for the given schema resource (db name, column, etc). If the alt syntax is not being used then this method no-ops and the given name parameter is returned.

Pass in "false" as a second parameter to hide the table part of a column reference (ie, in "jiveForum.foo", the "jiveForum." part would be hidden). Often, it's not necessary to explicitly reference the table name.

Parameters:
originalName - the original name of the table/method, etc.
showTableName - true to show the table name for a column reference, false to hide it. This is useful when doing some SQL queries that only deal with a single table.
Returns:
the alternate (usually shorter) name of the resource or the name itself if we're not in alt synatx mode. This method will also return the original name if no alternate syntax was found.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.