[dbforms] documentation for connection providers ... PART 2 with Protomatter...

[Luca Fossato]

Hi,

this version includes the doc. for ProtomatterConnectionProvider.
Sources are into the cvs.

Now I suppose that connectionFactory stuff is finished, integrated and documented.
I hope it works, too ;^)

Luca

What a long subject !

Anyway:
in attachment there is a text file with the documentation to configure the connection pool provided by JakartaConnectionProvider class.

I already committed the related sources into the cvs... they seems to work fine.
I will do the same for Protomatter.

Regards,
Luca

Connection pool properties
--------------------------

Every connectionProvider class that uses a connection pool facility can manage its own 
connection pool properties.
The dbconnection element can configure those properties using "pool-property" child 
elements.


Protomatter ConnectionProvider supported properties
---------------------------------------------------

Protomatter ConnectionProvider class uses the following properties to configure its 
connection pool:

pool.initialSize:
The initial pool size (default is 0).

pool.maxSize: 
The max pool size (default is -1). If the max pool size is -1, the pool grows 
infinitely.

pool.growBlock: 
The grow size (default is 1). When a new object is needed, this many are created.

pool.createWaitTime: 
The time (in ms) to sleep between pool object creates (default is 0). 
This is useful for database connection pools where it's possible to overload the 
database 
by trying to make too many connections too quickly.

jdbc.validityCheckStatement:
A SQL statement that is guaranteed to return at least 1 row. For Oracle, 
this is "select 1 from dual" and for Sybase it is "select 1". 
This statement is used as a means of checking that a connection is indeed working.

pool.maxConnectionIdleTime:
If this property is present, and the pool.maidThreadCheckInterval property is also 
present, 
then a thread will be created that looks for connections that have been idle 
for more than pool.maxConnectionIdleTime seconds. When this thread finds them, it 
closed the connection and logs a warning with a stack trace of when 
the connection was checked out of the pool. 
This is primarily here as a debugging aid for finding places where connections are not 
getting close, 
and should not be used in a production environment. 

pool.maidThreadCheckInterval:
This is the number of seconds between attempts by the maid thread (if present) to find 
idle connections. 


For further details:
http://protomatter.sourceforge.net/1.1.8-pre5/javadoc/com/protomatter/jdbc/pool/JdbcConnectionPool.html




Protomatter ConnectionProvider configuration example
----------------------------------------------------

 <dbconnection
   id                      = "protomatter"
   isJndi                  = "false"
   isPow2                  = "true"
   defaultConnection       = "true"
   connectionProviderClass = "org.dbforms.conprovider.ProtomatterConnectionProvider"
   connectionPoolURL       = "jdbc:protomatter:pool:postgresPool"
   conClass                = "org.postgresql.Driver"
   name                    = "jdbc:postgresql://myHost/myDb"
   username                = "postgres"
   password                = "">

     <!-- jdbc properties -->
     <property name="charSet" value="ISO-8859-1" />

     <!-- Connection pool dataSource properties -->
     <pool-property name="pool.initialSize"             value="4"   />
     <pool-property name="pool.maxSize"                 value="10"  />
     <pool-property name="pool.growBlock"               value="2"   />
     <pool-property name="pool.createWaitTime"          value="100" />
     <pool-property name="pool.maxConnectionIdleTime"   value=""    />
     <pool-property name="pool.maidThreadCheckInterval" value=""    />
     <pool-property name="jdbc.validityCheckStatement"  value=""    />

 </dbconnection>




Jakarta ConnectionProvider supported properties
-----------------------------------------------

Jakarta ConnectionProvider class uses the following properties to configure its 
connection pool:

validationQuery:
The SQL query that will be used to validate connections from this pool before 
returning 
them to the caller. If specified, this query MUST be an SQL SELECT statement that 
returns at least one row. 


maxActive:
The maximum number of active connections that can be allocated from 
this pool at the same time, or zero for no limit.

maxIdle:
The maximum number of active connections that can remain idle in the pool, 
without extra ones being released, or zero for no limit.

maxWait:
The maximum number of milliseconds that the pool will wait (when there are no 
available connections) 
for a connection to be returned before throwing an exception, or -1 to wait 
indefinitely.


For further details:
http://jakarta.apache.org/commons/dbcp/api/org/apache/commons/dbcp/BasicDataSource.html


I added this one to activate the dataSource log.

useLog: "true" | "false"

if "true", force the dataSource to log its statements using log4j.




Jakarta ConnectionProvider configuration example
------------------------------------------------

<dbconnection
  id                      = "jakarta-commons-dbcp"
  isJndi                  = "false"
  isPow2                        = "true"
  default                 = "false"
  connectionProviderClass = "org.dbforms.conprovider.JakartaConnectionProvider"
  connectionPoolURL       = ""
  conClass                = "org.postgresql.Driver"
  name                    = "jdbc:postgresql://localhost/myDatabase"
  username                = "postgres"
  password                = "">
  
  <!-- jdbc properties -->
  <property name="charSet" value="ISO-8859-1" />

  <!-- connection pool dataSource properties -->
  <pool-property name="validationQuery" value=""     />
  <pool-property name="maxActive"       value="10"   />
  <pool-property name="maxIdle"         value="5"    />
  <pool-property name="maxWait"         value="-1"   />
  <pool-property name="useLog"          value="true" />

</dbconnection>