| Title: DBCPDataSourceFactory |
| |
| |
| <P>As an alternative to a simple and easy-to-use DataSource bundled with Cayenne, it is possible to configure a more feature-rich DataSource based on Apache Jakarta <A href="http://jakarta.apache.org/commons/dbcp" class="external-link" rel="nofollow">commons-dbcp</A>. To enable commons-dbcp pool, select <TT>DBCPDataSourceFactory</TT> in the Modeler for a DataNode:</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="dbcpdatasourcefactory.data/dbcp-step1.jpg" style="border: 0px solid black"></SPAN></P> |
| |
| <P>Configuration is done in a properties file that has to be edited in a text editor outside CayenneModeler. The name of this file is specified in the Modeler (with path relative to cayenne.xml location):</P> |
| |
| <P><SPAN class="image-wrap" style=""><IMG src="dbcpdatasourcefactory.data/dbcp-step2.jpg" style="border: 0px solid black"></SPAN></P> |
| |
| <P>Here is an example of such properties file contents:</P> |
| |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>sample-dbcp.properties</B></DIV><DIV class="codeContent panelContent"> |
| <PRE class="code-java">cayenne.dbcp.driverClassName=com.mysql.jdbc.Driver |
| cayenne.dbcp.url=jdbc:mysql:<SPAN class="code-comment">//localhost/cayenne |
| </SPAN>cayenne.dbcp.username=john |
| cayenne.dbcp.password=secret |
| cayenne.dbcp.maxActive=20 |
| cayenne.dbcp.minIdle=5 |
| cayenne.dbcp.maxIdle=8 |
| cayenne.dbcp.maxWait=10000</PRE> |
| </DIV></DIV> |
| |
| <H2><A name="DBCPDataSourceFactory-SupportedProperties"></A>Supported Properties</H2> |
| |
| <P>Below is a full list of supported properties, that fall into three categories - DataSource properties, connection pool properties and prepared statement pool properties. Only DataSource properties are required.</P> |
| |
| <H3><A name="DBCPDataSourceFactory-DataSourceProperties"></A>DataSource Properties</H3> |
| |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Property</TH> |
| <TH class="confluenceTh">Description</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.driverClassName</TD> |
| <TD class="confluenceTd">JDBC driver class</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.url</TD> |
| <TD class="confluenceTd">Database JDBC URL</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.username</TD> |
| <TD class="confluenceTd">Database login user name</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.password</TD> |
| <TD class="confluenceTd">Database login password</TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
| |
| <H3><A name="DBCPDataSourceFactory-ConnectionPoolProperties"></A>Connection Pool Properties</H3> |
| |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Property</TH> |
| <TH class="confluenceTh">Description</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.maxActive</TD> |
| <TD class="confluenceTd">Maximum number of active connections in the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.minIdle</TD> |
| <TD class="confluenceTd">Minimum number of idle connections to keep in the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.maxIdle</TD> |
| <TD class="confluenceTd">Maximum number of idle connections to keep in the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.maxWait</TD> |
| <TD class="confluenceTd">A maximum time in milliseconds a caller should wait for a connection to be returned from the pool. -1 for indefinite.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.validationQuery</TD> |
| <TD class="confluenceTd">A SQL query used to validate a connection, before returning it to the user. Must return at least one row. E.g. <TT>"select 1 from dual"</TT></TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.testOnBorrow</TD> |
| <TD class="confluenceTd">A boolean specifying whether connection should be validated before being returned <B>from</B> the pool to the caller.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.testOnReturn</TD> |
| <TD class="confluenceTd">A boolean specifying whether connection should be validated before being returned back <B>to</B> the pool.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.testWhileIdle</TD> |
| <TD class="confluenceTd">A boolean specifying whether connection should be validated while it is idle.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.timeBetweenEvictionRunsMillis</TD> |
| <TD class="confluenceTd">A number of milliseconds an eviction thread should sleep between the runs.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.numTestsPerEvictionRun</TD> |
| <TD class="confluenceTd">A number of objects that an idle objects evictor should inspect on each run</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.minEvictableIdleTimeMillis</TD> |
| <TD class="confluenceTd">Minimum time an object should sit in the pool, before it can be considered for eviction.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.whenExhaustedAction</TD> |
| <TD class="confluenceTd">Specifies a pool behavior when the pool is exhausted and more connections are requested. Possible values are strings that follow the constant names defined in <TT>org.apache.commons.pool.impl.GenericObjectPool}: {{WHEN_EXHAUSTED_BLOCK</TT>, <TT>WHEN_EXHAUSTED_GROW</TT>, <TT>WHEN_EXHAUSTED_FAIL</TT>. If ommitted, <TT>WHEN_EXHAUSTED_BLOCK</TT> is assumed.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">caynne.dbcp.defaultAutoCommit</TD> |
| <TD class="confluenceTd">Auto-commit policy for connections returned from the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.defaultReadOnly</TD> |
| <TD class="confluenceTd">Read-only policy for connections returned from the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.defaultTransactionIsolation</TD> |
| <TD class="confluenceTd">Specifies transaction isolation for connections returned from the pool. Possible values are strings that follow the constant names defined in the <TT>java.sql.Connection</TT> interface: <TT>TRANSACTION_NONE</TT>, <TT>TRANSACTION_READ_COMMITTED</TT>, <TT>TRANSACTION_READ_UNCOMMITTED</TT>, <TT>TRANSACTION_REPEATABLE_READ</TT>, <TT>TRANSACTION_SERIALIZABLE</TT></TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.accessToUnderlyingConnectionAllowed</TD> |
| <TD class="confluenceTd">If set to true the application will be able to get access to the actual connection object which is normally wrapped by a poolable connections</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.defaultCatalog</TD> |
| <TD class="confluenceTd">Default catalog of connections created by the pool</TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
| |
| <H3><A name="DBCPDataSourceFactory-PreparedStatementPoolProperties"></A>PreparedStatement Pool Properties</H3> |
| |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Property</TH> |
| <TH class="confluenceTh">Description</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.poolPreparedStatements</TD> |
| <TD class="confluenceTd">Specifies whether PreparedStatements should be pooled</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.maxActive</TD> |
| <TD class="confluenceTd">Specifies the maximum number of PreparedStatements that can be borrowed from the pool at one time</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.maxIdle</TD> |
| <TD class="confluenceTd">Maximum number of idle PreparedStatements in the pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.maxTotal</TD> |
| <TD class="confluenceTd">Maximum number of PreparedStatements that can exist in the pool at one time</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.maxWait</TD> |
| <TD class="confluenceTd">A maximum time in milliseconds a caller should wait for a PreparedStatement to be returned from the pool. -1 for indefinite.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.minEvictableIdleTimeMillis</TD> |
| <TD class="confluenceTd">Number of milliseconds a PreparedStatement can sit idle in the pool before it is elegible for eviction</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.numTestsPerEvictionRun</TD> |
| <TD class="confluenceTd">Number of idle PreparedStatements that should be examined per eviction run</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.testOnBorrow</TD> |
| <TD class="confluenceTd">Specifies whether a PreparedStatement should be validated before being borrowed from this pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.testOnReturn</TD> |
| <TD class="confluenceTd">Specifies whether a PreparedStatement should be validated before being returne to this pool</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.testWhileIdle</TD> |
| <TD class="confluenceTd">Specifies whether PreparedStatements should be validated in the idle eviction thread</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">cayenne.dbcp.ps.timeBetweenEvictionRunsMillis</TD> |
| <TD class="confluenceTd">Specifies the time between the runs of the eviction thread</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd"> cayenne.dbcp.ps.whenExhaustedAction</TD> |
| <TD class="confluenceTd">Specifies a pool behavior when the pool is exhausted and more PreparedStatements are requested. Possible values are strings that follow the constant names defined in <TT>org.apache.commons.pool.impl.GenericObjectPool}: {{WHEN_EXHAUSTED_BLOCK</TT>, <TT>WHEN_EXHAUSTED_GROW</TT>, <TT>WHEN_EXHAUSTED_FAIL</TT>. If ommitted, <TT>WHEN_EXHAUSTED_BLOCK</TT> is assumed.</TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
