config-database.xtp
来自「RESIN 3.2 最新源码」· XTP 代码 · 共 729 行 · 第 1/2 页
XTP
729 行
<document><header> <product>resin</product> <title>Database Configuration</title> <version>Resin 3.0</version> <description><p>Resin provides a robust and tested connection pool that is used toobtain connections to databases. </p> </description></header><body><localtoc/><s1 title="See also"><ul><li><a href="db-thirdparty.xtp">Sample configurations</a> for several database drivers</li><li><a href="../examples/db-jdbc/index.xtp">Basic JNDI/JDBC usage tutorial</a></li><li>Using <a href="../examples/db-jdbc-ioc/index.xtp">Dependency Injection for Databases</a></li></ul></s1><s1 title="Basic Configuration"><p>A basic <database> configuration specifies the following:</p><ul><li>The JNDI name where the configured DataSource will be stored</li><li>The database driver's main class</li><li>The driver-specific url for the database.</li><li>Any user and password information.</li></ul><example title="Example: mysql configuration"><database jndi-name='jdbc/test_mysql'> <driver type="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"> <url>jdbc:mysql://localhost:3306/test</url> <user></user> <password></password> </driver></database></example><p>This <database> will configure a javax.sql.DataSource andstore it in JNDI at java:comp/env/jdbc/test_mysql. To use the datasource, follow the database use pattern in the<a href="../examples/db-jdbc/index.xtp">DataSource tutorial.</a></p><p>Sample <database> configurationsare available in the <a href="db-thirdparty.xtp">thirdparty driver page.</a></p><p>Although some deployments will specify driver andconnection pool parameters, the default values will be fine for mostapplications.</p></s1><s1 title="Core Concepts"><s2 title="Connection"><glossary title="connection" type="inline">An established channel of communication between a client and a server. Theclient and the server may be on separate machines, on the same machine, or evenrunning in the same JVM. Often the connection is established using TCP/IP asthe transport of communication.</glossary><p>A database connection is used to allow the Java program, running in a JVM,to communicate with a database server.</p></s2><s2 title="Connection Pool"><glossary title="connection pool" type="inline">A set of connections maintained so that the connections can be reused whenthere is a future need for the conneciton.</glossary><p>Connection pools are used to reduce the overhead of using a database.Establishing a connection to the database is a costly operation. A connectionpool keeps a pool of open connections, each connection can be used for a timeas needed, and then released back to the pool. A connection that has beenreleased back to the pool can then be reused. </p><p>Connection pooling is especially important in server applications. Theoverhead of opening a new connection for each new client request is too costly.Instead, the database pool allows for a connection to be opened once and thenreused for many requests.</p></s2><s2 title="DataSource"><glossary title="DataSource" type="inline">A JDBC term (and interface name) used for a factory that is used to obtain connections.</glossary><p>Resin provides an implementation of <code>DataSource</code>. Resin'simplementation of <code>DataSource</code> is a connection pool.</p></s2><s2 title="Driver"><glossary title="driver" type="inline">An implemetation of a defined interface that hides the details ofcommunication with a device or other resource, such as a database.</glossary><p>A Driver provides an interface and is responsible for the communicationwith the database. Every different database (i.e Oracle, MySQL) has their ownmeans of enabling communication from the client (in this case Resin and youapplications) and the database. The Driver provides a common interface thathides the details of that communication. </p></s2><s2 title="Transaction"><glossary title="transaction" type="inline">A transaction is used to mark a group of operations and provide a guaranteethat all of the operations happen, or none of them happen. Transactionsprotect the integrity of the database.</glossary><p>Transactions are especially important in server applications where manythreads of processing may be interacting with the database at the sametime.</p><p>For a simple example, imagine a set of operations that reads a value,calculates a new value, and then updates the database.<example title="Example: simple set of database operations">read value A=1 calculate A=A+1 update A=2read value A=2 calculate A=A+1 update A=3</example></p><p>Imagine if one thread is performing this operation, and in the middle ofthis read/calculate/update, another thread performs an update. The data thatthe first thread obtained from the read and is using for the calculation andupdate is no longer valid.</p><example title="Example: 2 Threads with database race condition">Thread 1 Thread 2-------- --------read value A=1 read value A=1calculate A=A+1 calculate A=A+1 update A=2update A=2</example><p>Placing the read/calculate/update operations in a transactions guaranteesthat only one thread can perform those operations at a time, if a second threadcomes along and tries to perform the operation, it will have to wait for thefirst thread to finish before it can begin.</p><example title="Example: 2 Threads protected with transactions">Thread1 Thread 2------- --------read value A=1 calculate A=A+1 (tries to read A, but has to wait for thread 1)update A=2 read value A=2 calculate A=A+1 update A=3</example></s2><s2 title="Distributed Transaction"><glossary title="distributed transaction" type="inline">A distributed transaction is a transaction that involves more than oneconnection.</glossary><p>If the guarantees that transactions apply need to apply to operations thatoccur on two databases within the same transaction,distributed transactions are needed.</p><p>If <code>A</code> and <code>B</code> in the following example are in twodifferent databases, then a distributed transaction is needed:</p><example title="Example: Simple set of database operations">read value db1.A=1 read value db2.B=99calculate A=A+1 calculate B=B-A update db1.A=2update db2.B=97</example><p>Distributed transactions are rarely needed, and few databases really supportthem.</p></s2></s1><s1 title="Core Configuration"><s2 title="database" version="Resin 3.0" type="defun"><parents>server, host-default, host, web-app-default, web-app</parents><p>Configure a <var>database</var> resource, which is a database pool that managesand provides connections to a database.</p> <deftable-childtags><tr> <th>attribute</th> <th>Description</th> <th>Default</th></tr><tr><td>jndi-name</td><td>JNDI name to store the pool under. Servlets, jsp, andother java code use this name. The path is relative to<code>java:comp/env</code></td><td> </td></tr><tr><td>driver</td><td>Configure the database <a href="#driver">driver</a>.</td><td></td></tr><tr><td>backup-driver</td><td>Configure a backup <a href="#driver">driver</a>.</td><td></td></tr><tr><td>max-connections</td><td><a href="#pooling">Pooling parameter</a> - maximum number of allowed connections</td><td>20</td></tr><tr><td>max-idle-time</td><td><a href="#pooling">Pooling parameter</a> - maximum time an idle connection is kept inthe pool</td><td>30 sec</td></tr><tr><td>max-active-time</td><td><a href="#pooling">Pooling parameter</a> - maximum time a connection allowed to be active</td><td>6 hours</td></tr><tr><td>max-pool-time</td><td><a href="#pooling">Pooling parameter</a> - maximum time a connection is kept in the pool</td><td>24 hours</td></tr><tr><td>connection-wait-time</td><td><a href="#pooling">Pooling parameter</a> - how long to wait for an idle connection (Resin 1.2.3)</td><td>10 minutes</td></tr><tr><td>max-overflow-connections</td><td><a href="#pooling">Pooling parameter</a> - how many "overflow" connection are allowed if the connection wait times out.</td><td>0</td></tr><tr><td>ping-table</td><td><a href="#reliability">Reliability parameter</a> - The database table used to "ping", checking that the connection is still live.</td><td>n/a</td></tr><tr><td>ping</td><td><a href="#reliability">Reliability parameter</a> - test for live connections before allocating them from the pool.</td><td>false</td></tr><tr><td>ping-interval</td><td><a href="#reliability">Reliability parameter</a> - set the minimum interval for pings, instead of doing a ping every time</td><td>1s</td></tr><tr><td>prepared-statement-cache-size</td><td>A cache that holds prepared statements, a reused prepared statement avoids the overhead of the driver making the prepared statement</td><td>0</td></tr><tr><td>spy</td><td>A debugging aid, if true, generate <code>info</code> level log events that reveal the SQL that is used with the connections.</td><td>false<!--<tr><td>xa<td><td>Set true o--></td></tr></deftable-childtags><p>All times default to seconds, but can use longer time periods:</p><deftable title="Time suffixes"><tr> <th>Suffix</th> <th>Description</th></tr><tr><td>s</td><td>seconds</td></tr><tr><td>m</td><td>minutes</td></tr><tr><td>h</td><td>hours</td></tr><tr><td>D</td><td>days</td></tr></deftable><p>The class that corresponds to <database> is <a href="javadoc|com.caucho.sql.DBPool|"/></p></s2></s1><s1 name="driver-config" title="Driver Configuration"><s2 title="driver" version="Resin 3.0" type="defun"><parents>database</parents><p>Configure a database <var>driver</var>. The driver is a class provided by thedatabase vendor, it is responsible for the communication with the database.</p><p>The jar file with the driver in it can be placed in <code>WEB-INF/lib</code>,although it is often best to place your datbase driver's jar file in<code>$RESIN_HOME/lib/local/</code>, which makes the driver available to all ofyour web applications.</p><p>Examples of common driver configurations are in <a href="db-thirdparty.xtp">Third-party Database Configuration</a>.</p><p>The class that corresponds to <driver> is <a href="javadoc|com.caucho.sql.DriverConfig"/></p><deftable-childtags><tr> <th>Attribute</th> <th>Description</th></tr><tr><td>type</td><td>The Java class name of the database driver.</td><td> </td></tr><tr><td>url</td><td>The driver specific database url.</td><td> </td></tr><tr><td>user</td><td>The username to give the database driver.</td><td> </td></tr><tr><td>password</td><td>The password to give the database driver.</td><td> </td></tr><tr><td>init-param</td><td>Set <a href="#init-param">driver specific properties</a> not known to Resin.</td><td> </td></tr></deftable-childtags></s2> <!-- driver --><s2 name="choosing-driver" title="Choosing a driver class for <type>"><p>Database vendors usually provide many different classes that are potentialcandidates for <var>type</var>. The JDBC api has developed over time, and is nowbeing replaced by the more general JCA architecture. The driver you choosedepends on the options the vendor offers, and whether or not you needdistributed transactions.</p><s3 title="JCA drivers"><p>JCA is replacing JDBC as the API for database drivers. JCA is a much moreflexible approach that defines an API that can be used for any kind ofconnection, not just a connection to a database. If a database vendor providesa JCA interface, it is the best one to use.</p><p>A JCA driver implements <code>ManagedConnectionFactory</code>. When youspecify such a class for <var>type</var>, Resin will notice that it is a JCA driverand take advantage of the added functionality that the JCA interfaceprovides.</p><p>The same JCA driver is used for both non-distributed and distributedtransactions</p></s3><s3 title="JDBC 2.0 - ConnectionPoolDataSource"><p>JDBC 2.0 defined the interface <var>ConnectionPoolDataSource</var>. A<code>ConnectionPoolDataSource</code> is <i>not</i> a connection pool, but itdoes provide some extra information that helps Resin to pool the connectionmore effectively.</p><p>A driver that implements <var>ConnectionPoolDataSource</var> is better than aJDBC 1.0 driver that implements <var>Driver</var>. </p></s3><s3 title="JDBC 2.0 - XADataSource"><p>JDBC 2.0 defined the interface <var>XADataSource</var> for connections that canparticipate in <var>distributed transactions</var>. A distributed transaction isneeded when transactions involve multiple connections. For example, with twodifferent database backends, if the guarantees that transactions apply need toapply to operations that occur on both databases within the same transaction,distributed transactions are needed.</p><p>Distributed transactions are rarely needed, and few databases really supportthem. Some vendors will provide <code>XADataSource</code> drivers even thoughthe database does not really support distributed transactions. Often,<code>XADataSource</code> drivers are slower than their<code>ConnectionPoolDataSource</code> counterparts.</p><p><code>XADataSource</code> should only be used if distributed transactionsare really needed, and can probably be safely ignored for mostapplications.</p></s3><s3 title="JDBC 1.0 - Driver"><p>⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?