config-database.xtp

来自「RESIN 3.2 最新源码」· XTP 代码 · 共 729 行 · 第 1/2 页

<var>Driver</var> is the original JDBC interface, and is the least desirable kind
of driver to use.  Resin can still pool database connections using these drivers, but it will not be as efficient as the newer drivers.
</p>

</s3>
</s2> <!-- choosing-driver -->

<s2 name="init-param" title="Set driver properties with init-param">

<p><var>init-param</var> is used to set properties of the database driver that are
specific to the driver and are not generic enough for resin to provide a
named configuration tag.</p>

<p>For example, MySQL drivers accept the <code>useUnicode</code> parameter, if
true the driver will use Unicode character encodings when handling
strings.</p>

<example title="Example: mysql configuration">
&lt;database&gt;
  &lt;jndi-name&gt;jdbc/mysql&lt;/jndi-name&gt;
  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://localhost:3306/dbname&lt;/url&gt;
    &lt;user&gt;username&lt;/user&gt;
    &lt;password&gt;password&lt;/password&gt;

    <b>&lt;init-param useUnicode="true"/&gt;</b>
  &lt;/driver&gt;
  ...
&lt;/database&gt;
</example>

</s2> <!-- init-driver -->

</s1> <!-- driver-config -->

<s1 name="pooling" title="Pooling Configuration">

<p>
Pooling configuration controls the behaviour of Resin's pooling of database
connections.  For most applications and databases the only needed change is to
increase the max-connections value to meet high demand.  Other pooling
parameters have defaults that are based on our years of experience with many
different databases in many different applications.  Changes from the defaults
should only be done in response to specific problems, and with a good
understanding of how pooling works.
</p>

</s1>


<s1 name="reliability" title="Reliability Configuration">

<s2 name="reliability-ping" title="ping">

<p>Resin's database pool can test if the pooled database connection
is still alive by configuring a <var>ping</var> query.  This is typically only
necessary if the <a href="#pooling">pooling</a> parameters are changed from
their default values.
</p>

<p>If the pool is configured with a long max-idle-time the database connection
may become stale if the database is restarted, or if the database is configured
with a shorter connection timeout value than the configuration of the Resin
pool.  Normally when a database connection is returned to the pool it will wait
there until the next request or the idle-time expires.  If the database goes
down in the meantime or closes the connection, the connection will become
stale.  The <var>ping</var> configuration can test the database connection.</p>

<p>When pinging, Resin's DBPool will test a table specified with the
<var>ping-table</var> parameter before returning the connection to the application.
If the ping fails, the connection is assumed to be no good and a different
connection from the pool is returned.  For a ping-table of BROOMS, Resin will
use the query <code>select 1 from BROOMS where 1=0</code>
</p>

<example title="Example: &lt;ping> configuration">
  &lt;database jndi-name="..."&gt;
    &lt;driver type="..."&gt;
      ...
    &lt;/driver&gt;

    &lt;ping&gt;true&lt;/ping&gt;
    &lt;ping-table&gt;BROOMS&lt;/ping-table&gt;
  &lt;/database&gt;
</example>


<p>You can test the ping using the following steps:
</p>

<ol>
<li>Configure the database with ping-table and ping.
</li><li>Execute some servlet that queries the database.
</li><li>Restart the database server.
</li><li>Execute another servlet that queries the database.
</li></ol>

</s2> <!-- reliability-ping -->

<s2 name="driver_list" title="&lt;driver> list">
<p>
If there is a pool of database servers available that can be used for database
operations, Resin can be configured with a list of &lt;driver> tags. 
Resin uses a round robin algorithm to cycle through the list of drivers when
obtaining connections.  If a particular &lt;driver> fails to provide a
connection, Resin continues the attempt to obtain a connection. If all of the
configured drivers fail to provide a connection the exception is propogated to
the caller.
</p>

<example title="Example: A &lt;driver> list">
&lt;database jndi-name="jdbc/hogwarts"&gt;
  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>110</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/driver&gt;

  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>111</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/driver&gt;
  ...
&lt;/database&gt;
</example>

<s3 name="backup-driver" title="&lt;backup-driver> list">
<p>
Drivers in a driver list can be marked as backups.  The drivers configured with
&lt;backup-driver&gt; are used only if all of the drivers configured with
&lt;driver&gt; have failed.
</p>

<p>
Each time a new connection is needed Resin goes through the process of first
attempting to use one of the &lt;driver> configured drivers to get a connection,
and if that fails then the &lt;backup-driver> are used.
A new connection is needed from the driver if the pool of connections that is
maintained by Resin does not contain an idle connection.  The
<a href="#pooling">Pooling configuration</a> and the usage pattern of the
application determine how often a connection is obtained from a driver.  The
pooling configuration typically allows a single real connection to be reused by
the application many times.
</p>

<p>
The lifetime of a connection obtained from a &lt;backup-driver> is determined by
the <a href="#pooling">Pooling configuration</a>, thus even if the main
&lt;driver> becomes available again a connection previously obtained from a
&lt;backup-driver> will continue to be used until it expires from the pool.
</p>

<example title="Example: A &lt;backup-driver> list">
&lt;database jndi-name="jdbc/hogwarts"&gt;
  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>110</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/driver&gt;

  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>111</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/driver&gt;

  &lt;backup-driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>112</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/backup-driver&gt;

  &lt;backup-driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://192.168.0.<b>113</b>:3306/hogwarts&lt;/url&gt;
    ...
  &lt;/backup-driver&gt;
  ...
&lt;/database&gt;
</example>

</s3>

</s2> <!-- driver-list -->

</s1> <!-- reliability -->

<s1 name="usage" title="Obtaining and using a database connection">

<s2 name="usage/lookup" title="Getting the DataSource">

<p>The <code>DataSource</code> is a factory that is used to obtain
a connection.  The <code>DataSource</code> is obtained using the <a config-tag="jndi-name"/> specified when configuring the database resource.  

</p><p>Ideally, the JNDI lookup of <code>DataSource</code> is done only once, the
<code>DataSource</code> obtained from the lookup can be stored in a member variable
or other appropriate place.  The stored <code>DataSource</code> can then be used
each time a connection is needed.  If it is not stored, there will be an impact
on performance from having to do the lookup each time you want to get a
connection.</p>

<example title="Example: Obtaining a DataSource">
import javax.sql.*;
import javax.webbeans.*;

public class .... {
  @Named("jdbc/test") DataSource _pool;

  ...
}
</example>
</s2> <!-- usage/lookup -->

<s2 name="usage/get-connection" title="Getting a Connection">

<p>A connection is obtained from the <code>DataSource</code>.  The
connection is used as needed, and then released with a call to close() so that
Resin knows it is available for a subsequent request.</p>

<p>It is very important that the <code>close()</code> is <i>always</i> called, even
if there as an exception. Without the <code>close()</code>, Resin's database pool
can loose connections.  If you fail to close() a connection, Resin does not know
that it is available for reuse, and cannot allocate it for another request.
Eventually, Resin may run out of connections.  </p>

<warn>Always put a <code>close()</code> in a finally block, to guarantee that it is called.</warn>

<p>The following example shows the use of a <code>finally</code> block that contains
the <code>close()</code>.  Because the <code>close()</code> is in a finally block, it
will happen even if the code using the connection throws an exception.</p>

<example title="Example: Getting a connection from the DataSource">
package javax.webbeans.*;
package javax.sql.*;

public class MyBean()
{
  @In DataSource _pool;

  public void doStuff()
  {
    Connection conn = null;
    try {
      conn = _pool.getConnection();

      Statement stmt = conn.createStatement();

      ResultSet rs = stmt.executeQuery(" ... ");

      ...

      rs.close();
      stmt.close();
    } catch (SQLException e) {
      throw new ServletException(e);
    } finally {
      try {
        if (conn != null)
          conn.close();
      } catch (SQLException e) {
      }
    }
  }
}
</example>

</s2> <!-- usage/get-connection -->

<s2 name="usage/get-driver-connection" title="Getting the underlying driver connection">

<p>
The connection obtained by <code>pool.getConnection()</code> is an instance of 
<a href="javadoc|com.caucho.sql.UserConnection|"/>.
</p>

<p>
<code>UserConnection</code> is a wrapper around the real driver connection, it
allows Resin to intercept the close() call and manage the underlying driver
connection.
</p>

<p>
In rare circumstances it is necessary to obtain the real connection returned by the driver.
Typically this is a requirement for situations where the driver provides a
specialized API that is not available with the standard JDBC API.
</p>

<example title="Example: Getting the underlying driver connection">
Connection driverConn = ((com.caucho.sql.UserConnection) connection).getConnection();

// never do this: driverConn.close()
</example>

</s2>

</s1> <!-- usage -->

<s1 title="Protecting the database password">

<p>
Resin provides facilities that allow you to plugin your own custom
code that returns a password to Resin.  However any solution is vulnerable,
unless you require a person to type in a password every time Resin starts (or
restarts).  Typically the security of the machine hosting Resin, and proper
permissions on the readability of the resin.xml file, are sufficient to
protect your database password.
</p>

<p>
The solution shown below is not really secure because you can disassemble the
Password code to get the decryption key, but it may be marginally better than
plaintext.</p>
 
<example title="Example: password encryption">
&lt;driver type="..."&gt; 
  &lt;password resin:type="com.hogwarts.Password"&gt;mX9aN9M==&lt;/password&gt; 
  ...
</example>
 
<p>
You will need to provide com.hogwarts.Password:
</p>
 
<example title="Example: Password class">
package com.hogwarts;

public class Password { 
  private String _value; 
 
  public void addText(String value) 
  { 
    _value = value; 
  } 
 
  public Object replaceObject() 
  { 
    return decrypt(_value); 
  } 

  private String decrypt(String encrypted)
  {
    ... custom code ...
  }
} 
</example>
 
<p>
This solution is completely general, you can use resin:type anywhere in the
configuration files where a string value is allowed.
</p>
 
<p>
Resin does not provide the equivalent of com.hogwarts.Password because it's not
really secure.  Providing that kind of solution would lead some to believe it
was a secure solution.
</p>

</s1>

</body>
</document>