org.aris.hldb
Class CS

java.lang.Object
  extended by org.aris.hldb.CS

public class CS
extends java.lang.Object

The main class which provides the pooled CallableStatements. This class is THREAD SAFE. Note: when using transactions, the pool can't be used. Call CS.allocTransactionalCS() instead.

Version:
1.0
Author:
Konstantine Kougios

Constructor Summary
CS(ConnectionProviderI hl_con)
          Creates a new instance of hlCS
 
Method Summary
 void addSqlCall(java.lang.String key, java.lang.String sql, int maxInPool)
          Creates a new pooled CS which will be searchable by the "key" key.
 void addSqlCall(java.lang.String key, java.lang.String sql, int resultSetType, int resultSetConcurency, int maxInPool)
          Creates a new pooled CS which will be searchable by the "key" key.
 java.sql.CallableStatement allocCS(java.lang.String key)
          Allocates an unused CS.
 java.sql.CallableStatement allocTransactionalCS(java.sql.Connection con, java.lang.String key)
          Gets a CallableStatement for the key.
 void dumpAllocated(java.io.PrintStream out)
          This function is used for debugging reasons.
 void execCS(java.lang.String key)
          Executes a simple sql which doesn't have parameters.
 java.lang.String execCS(java.lang.String key, int parameter)
          Executes a query with 1 int parameter and returns the 1 single string result, or null if there are no results.
 int execCSID(java.sql.CallableStatement cs)
          Executes a CallableStatement that returns 1 row with an integer.
 boolean exists(java.lang.String key)
          Checks to see if a key (which links to a CS pool) exists in the CS pool tree.
 java.sql.CallableStatement freeCS(java.sql.CallableStatement cs)
          Returns an allocated CS back to it's CS pool.
 ConnectionProviderI gethlCon()
          Get the hlCon that this hlCS uses.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CS

public CS(ConnectionProviderI hl_con)
Creates a new instance of hlCS

Parameters:
hl_con - The hlCon database Connection pool. The hlCS will use that pool for new CS's.
Method Detail

gethlCon

public ConnectionProviderI gethlCon()
Get the hlCon that this hlCS uses.

Returns:
The hlCon database pool in use for this object.

exists

public boolean exists(java.lang.String key)
Checks to see if a key (which links to a CS pool) exists in the CS pool tree.

Parameters:
key - The CS pool key.
Returns:
True if the key exists.

addSqlCall

public void addSqlCall(java.lang.String key,
                       java.lang.String sql,
                       int resultSetType,
                       int resultSetConcurency,
                       int maxInPool)
                throws KeyAlreadyExistsException
Creates a new pooled CS which will be searchable by the "key" key.

Parameters:
key - The key assigned to this CS pool. It mustn't already exist in the CS pool tree.
sql - The sql command of this pool, i.e. "{call mySP(...)}".
resultSetType - The type of the ResultSets returned by this CS.
resultSetConcurency - The Concurency kind of the resultSets returned by this CS.
maxInPool - The pool tries to keep maximum CallableStatements below this figure, but if more CallableStatements are needed, they will be allocated
Throws:
KeyAlreadyExistsException

addSqlCall

public void addSqlCall(java.lang.String key,
                       java.lang.String sql,
                       int maxInPool)
                throws KeyAlreadyExistsException
Creates a new pooled CS which will be searchable by the "key" key.

Parameters:
key - The key assigned to this CS pool. It mustn't already exist in the CS pool tree.
sql - The sql command of this pool, i.e. "{call mySP(...)}".
maxInPool - The pool tries to keep maximum CallableStatements below this figure, but if more CallableStatements are needed, they will be allocated.
Throws:
KeyAlreadyExistsException

allocCS

public java.sql.CallableStatement allocCS(java.lang.String key)
                                   throws java.sql.SQLException
Allocates an unused CS. This function searches in the CS tree for the key and it's associated CS pool. If the pool is found, it asks for a free CS. If no free CS is found, then a new is created and returned.
Note that the callable statement may contain warnings from previous usage, do a cs.clearWarnings() immediatelly after this call, if you read warnings. (this is not done automatically, since it creates a 15% delay!!!)
The CS must be returned to the pool via a call to freeCS().
Typical example of valid call to this function:
CallableStatement cs;
try
{
cs=hlcs.allocCS("mysqlKey");
} catch {...}
{ ... }
finally
{
hlcs.freeCS(cs)
}

Parameters:
key - The key by which a CS pool is found.
Returns:
A CallableStatement.
Throws:
java.sql.SQLException - -

allocTransactionalCS

public java.sql.CallableStatement allocTransactionalCS(java.sql.Connection con,
                                                       java.lang.String key)
                                                throws java.sql.SQLException
Gets a CallableStatement for the key. Free it with a CallableStatement.close() call. The usage of this method is in transactions, where the pool can't be used.

Parameters:
con - The connection
key - The key of the sql
Returns:
A CallableStatement.
Throws:
java.sql.SQLException - -

freeCS

public java.sql.CallableStatement freeCS(java.sql.CallableStatement cs)
Returns an allocated CS back to it's CS pool.

Parameters:
cs - The CS which was allocated with hlCS.allocCS(). If null, the call has no effect.

execCS

public void execCS(java.lang.String key)
            throws java.sql.SQLException
Executes a simple sql which doesn't have parameters.
NOTE: For optimal performance, don't use this in a loop. Allocate and free the cs outside of the loop instead.

Parameters:
key - The key by which a CS pool is found.
Throws:
java.sql.SQLException - -

execCSID

public int execCSID(java.sql.CallableStatement cs)
             throws java.sql.SQLException
Executes a CallableStatement that returns 1 row with an integer. Usefull when you insert data in a database, and you want to retrieve the autoincrement value.
i.e. it can be used for this insert sql
INSERT INTO PhoneBook(Name,..............
SELECT @@IDENTITY
NOTE: For optimal performance, don't use this in a loop. Allocate and free the cs outside of the loop instead.

Parameters:
cs - The callable statement to execute.
Returns:
The 1 and only integer result value.
Throws:
java.sql.SQLException - -

execCS

public java.lang.String execCS(java.lang.String key,
                               int parameter)
                        throws java.sql.SQLException
Executes a query with 1 int parameter and returns the 1 single string result, or null if there are no results.
NOTE: For optimal performance, don't use this in a loop. Allocate and free the cs outside of the loop instead.

Parameters:
key - The query key
parameter - the one and only query parameter. Typically an table ID.
Returns:
The 1st string result.
Throws:
java.sql.SQLException - -

dumpAllocated

public void dumpAllocated(java.io.PrintStream out)
This function is used for debugging reasons. Call it at the end of a program to see if you got CS which hasn't been hlCS.free(cs)'d.
This writes to a PrintWriter (i.e. System.err). If it contains key values, then some CS leak and aren't free'd correctly (which in time increases the memory used by your program)

Parameters:
out - The output PrintWriter.