Author: seb
Date: Wed Nov 8 11:26:40 2006
New Revision: 884
Modified:
logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Log:
on going work
Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
==============================================================================
--- logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
(original)
+++ logback/trunk/logback-site/src/site/xdocTemplates/manual/appenders.xml
Wed Nov 8 11:26:40 2006
@@ -1678,7 +1678,7 @@
</p>
<p>
- The table below summarizes the database tapes and their
support of the
+ The table below summarizes the database types and their
support of the
<code>getGeneratedKeys()</code> method.
</p>
@@ -1740,82 +1740,13 @@
<p>
Configuring logback to use <code>DBAppender</code> can
be done
in several different ways, depending on the tools one
has to
- connect to the database, and the database itself.
+ connect to the database, and the database itself. All
manners of
+ configuring <code>DBAppender</code> are about setting
its
+ <code>ConnectionSource</code> object, which we will
cover in
+ a short moment.
</p>
<p>
- The first example that we will review is a
configuration using
- <code>DriverManagerConnectionSource</code> and a MySQL
database.
- The following configuration file is what one would need.
- </p>
-
-<em>Example 4.6: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em>
-<div class="source"><pre><configuration>
-
- <b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
- <connectionSource
class="ch.qos.logback.core.db.DriverManagerConnectionSource">
- <driverClass>com.mysql.jdbc.Driver</driverClass>
- <url>jdbc:mysql://host_name:3306/datebase_name</url>
- <user>username</user>
- <password>password</password>
- </connectionSource>
- </appender></b>
-
- <!-- Prevent internal logback DEBUG messages from polluting the output.
-->
- <logger name="ch.qos.logback.core.joran"><level value="INFO"
/></logger>
- <logger name="ch.qos.logback.classic.joran"><level value="INFO"
/></logger>
-
- <root>
- <level value="debug" />
- <appender-ref ref="DB" />
- </root>
-</configuration></pre></div>
-
- <p>
- The correct driver must be declared. Here, the
<code>com.mysql.jdbc.Driver</code>
- class is used. The <span class="option">url</span> must
begin with <em>jdbc:myslq://</em>.
- </p>
-
- <p>Connecting to a database using a <code>DataSource</code> is
rather similar:</p>
-
-<em>Example 4.7: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em>
-<div class="source"><pre><configuration>
-
- <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
- <b><connectionSource
class="ch.qos.logback.core.db.DataSourceConnectionSource">
-
- <dataSource class="${dataSourceClass}">
- </b><!-- Joran cannot substitute variables
- that are not attribute values. Therefore, we cannot
- declare the next parameter like the others.
- -->
- <b><param name="${url-key:-url}" value="${url_value}"/>
- <serverName>${serverName}</serverName>
- <databaseName>${databaseName}</databaseName>
- </dataSource></b>
-
- <user>${user}</user>
- <password>${password}</password>
- </connectionSource>
- </appender>
-
- <!-- Prevent internal logback DEBUG messages from polluting the output.
-->
- <logger name="ch.qos.logback.core.joran"><level value="INFO"
/></logger>
- <logger name="ch.qos.logback.classic.joran"><level value="INFO"
/></logger>
-
- <root>
- <level value ="debug"/>
- <appender-ref ref="DB" />
- </root>
-</configuration></pre></div>
-
- <p>
- Not that in this configuration sample, we make heavy
use of substitution variables.
- They are sometimes handy when connection details have
to be centralised in a
- single configuration file and shared by logback and
other frameworks.
- </p>
-
- <p>
Once logback is configured properly, the logging events
are sent to
the specified database. As stated previously, there are
three tables
used by logback to store logging event data.
@@ -1970,8 +1901,189 @@
<img src="images/chapter4/dbAppenderLEProperty.gif"
alt="Logging Event Property table" />
+
+ <h4>ConnectionSource</h4>
+
+ <p>
+ The <id>ConnectionSource</id> interface provides a
pluggable means of
+ transparently obtaining JDBC Connections for logback
classes that
+ require the use of a <code>java.sql.Connection</code>.
There are currently
+ three implementations of <code>ConnectionSource</code>,
namely
+ <code>DataSourceConnectionSource</code>,
<code>DriverManagerConnectionSource</code>
+ and <code>JNDIConnectionSource</code>.
+ </p>
+
+ <p>
+ The first example that we will review is a
configuration using
+ <code>DriverManagerConnectionSource</code> and a MySQL
database.
+ The following configuration file is what one would need.
+ </p>
+
+<em>Example 4.6: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-toMySQL-with-driverManager.xml)</em>
+<div class="source"><pre><configuration>
+
+ <b><appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
+ <connectionSource
class="ch.qos.logback.core.db.DriverManagerConnectionSource">
+ <driverClass>com.mysql.jdbc.Driver</driverClass>
+ <url>jdbc:mysql://host_name:3306/datebase_name</url>
+ <user>username</user>
+ <password>password</password>
+ </connectionSource>
+ </appender></b>
+
+ <!-- Prevent internal logback DEBUG messages from polluting the output.
-->
+ <logger name="ch.qos.logback.core.joran"><level value="INFO"
/></logger>
+ <logger name="ch.qos.logback.classic.joran"><level value="INFO"
/></logger>
+
+ <root>
+ <level value="debug" />
+ <appender-ref ref="DB" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ The correct driver must be declared. Here, the
<code>com.mysql.jdbc.Driver</code>
+ class is used. The <span class="option">url</span> must
begin with <em>jdbc:myslq://</em>.
+ </p>
+
+ <p>
+ The
+ <a
href="../xref/ch/qos/logback/core/db/DriverManagerConnectionSource.html">
+ <code>DriverManagerConnectionSource</code></a> is an
implementation of
+ <code>ConnectionSource</code> that obtains the
connection in the
+ traditional JDBC manner based on the connection URL.
+ </p>
+ <p>
+ Note that this class will establish a new
<code>Connection</code> for
+ each call to <code>getConnection()</code>. It is
recommended
+ that you either use a JDBC driver that natively supports
+ connection pooling or that you create your own
+ implementation of <code>ConnectionSource</code> that
taps into
+ whatever pooling mechanism you are already using. (If
you
+ have access to a JNDI implementation that supports
+ <code>javax.sql.DataSource</code>, e.g. within a J2EE
application
+ server, see <code>JNDIConnectionSource</code>).
+ </p>
+
+ <p>
+ If you do not have another connection pooling mechanism
built
+ into your application, you can use the
+ <a
href="http://jakarta.apache.org/commons/dbcp/index.html";>
+ commons-dbcp </a> package from Apache:
+ </p>
+
+<div class="source"><pre>
+ <connectionSource
+ class="ch.qos.logback.core.db.DriverManagerConnectionSource">
+ <param name="driver"
value="org.apache.commons.dbcp.PoolingDriver"/>
+ <param name="url"
value="jdbc:apache:commons:dbcp:/myPoolingDriver"/>
+ </connectionSource>
+</pre></div>
+
+ <p>
+ Then the configuration information for the commons-dbcp
+ package goes into the file
<em>myPoolingDriver.jocl</em> and is
+ placed in the classpath. See the
+ <a
href="http://jakarta.apache.org/commons/dbcp/index.html";> commons-dbcp </a>
+ documentation for details.
+ </p>
+
+ <p>
+ Connecting to a database using a
<code>DataSource</code> is rather similar.
+ The configuration now uses
+ <a
href="../xref/ch/qos/logback/core/db/DataSourceConnectionSource.html">
+ <code>DataSourceConnectionSource</code></a>,
+ which is an implementation of
<code>ConnectionSource</code> that obtains the
+ <code>Connection</code> in the recommended JDBC manner
based on a
+ <code>javax.sql.DataSource</code>.
+ </p>
+
+<em>Example 4.7: <code>DBAppender</code> configuration
(logback-examples/src/main/java/chapter4/db/append-with-datasource.xml)</em>
+<div class="source"><pre><configuration>
+
+ <appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
+ <b><connectionSource
class="ch.qos.logback.core.db.DataSourceConnectionSource">
+
+ <dataSource class="${dataSourceClass}">
+ </b><!-- Joran cannot substitute variables
+ that are not attribute values. Therefore, we cannot
+ declare the next parameter like the others.
+ -->
+ <b><param name="${url-key:-url}" value="${url_value}"/>
+ <serverName>${serverName}</serverName>
+ <databaseName>${databaseName}</databaseName>
+ </dataSource></b>
+
+ <user>${user}</user>
+ <password>${password}</password>
+ </connectionSource>
+ </appender>
+
+ <!-- Prevent internal logback DEBUG messages from polluting the output.
-->
+ <logger name="ch.qos.logback.core.joran"><level value="INFO"
/></logger>
+ <logger name="ch.qos.logback.classic.joran"><level value="INFO"
/></logger>
+
+ <root>
+ <level value ="debug"/>
+ <appender-ref ref="DB" />
+ </root>
+</configuration></pre></div>
+
+ <p>
+ Not that in this configuration sample, we make heavy
use of substitution variables.
+ They are sometimes handy when connection details have
to be centralised in a
+ single configuration file and shared by logback and
other frameworks.
+ </p>
+
+ <p>
+ The third implementation of
<code>ConnectionSource</code> that is shipped with
+ logback is the <code>JNDIConnectionSource</code>.
+ </p>
+
+ <p>
+ The
+ <a
href="../xref/ch/qos/logback/core/db/JNDIConnectionSource.html">
+ <code>JNDIConnectionSource</code></a>
+ is an implementation of <code>ConnectionSource</code>
that
+ obtains a <code>javax.sql.DataSource</code> from a JNDI
provider
+ and uses it to obtain a
<code>java.sql.Connection</code>. It is
+ primarily designed to be used inside of J2EE application
+ servers or application server clients, assuming the
+ application server supports remote access of
<code>javax.sql.DataSource</code>.
+ In this way one can take advantage of connection
pooling and whatever other goodies the
+ application server provides.
+ </p>
+
+<div class="source"><pre>
+<connectionSource
class="ch.qos.logback.core.db.JNDIConnectionSource">
+ <param name="jndiLocation" value="jdbc/MySQLDS" />
+ <param name="username" value="myUser" />
+ <param name="password" value="myPassword" />
+</connectionSource>
+ </pre></div>
+
+ <p>
+ Note that this class will obtain an
+ <code>javax.naming.InitialContext</code>
+ using the no-argument constructor. This will usually
work
+ when executing within a J2EE environment. When outside
the
+ J2EE environment, make sure that you provide a
+ <em>jndi.properties</em>
+ file as described by your JNDI provider's documentation.
+ </p>
+
+
+ <p>
+ <b>MORE INFO TO ADD HERE JNDI + BindAction +
DataSourceCS? Or directly
+ with JNDICS??</b>
+ </p>
+
<h3>SyslogAppender</h3>
+
+ <p>
+
+ </p>
<h2>Logback Access</h2>
_______________________________________________
logback-dev mailing list
[email protected]
http://qos.ch/mailman/listinfo/logback-dev
