<?xml version="1.0" encoding="UTF-8"?>
<!--

       Copyright ${license.git.copyrightYears} the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.

-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>MyBatis 3 | ロギング</title>
    <author email="clinton.begin@gmail.com">Clinton Begin</author>
    <author email="harawata@gmail.com">Iwao AVE!</author>
  </properties>

  <body>
    <section name="ロギング">
      <p></p>
      <p>MyBatis は、内部の Log Factory を通してログ情報を出力します。この Log Factory は、ログ情報を次に挙げる実装のいずれかに委譲（delegate）します。
      </p>
      <ul>
        <li>
          SLF4J
        </li>
        <li>
          Apache Commons Logging
        </li>
        <li>
          Log4j 2
        </li>
        <li>
          Log4j
        </li>
        <li>
          JDK logging
        </li>
      </ul>
      <p>実際に使用されるのは、MyBatis 内部の Log Factory が検出した実装になります。MyBatis の Log Factory は上に挙げた順番でロギング実装を検索し、最初に見つけた実装を使用します。上記の実装が検出できなかった場合、ログは出力されません。
      </p>
      <p>アプリケーションサーバーでは、出荷時のクラスパスに Commons Logging が含まれていることがよくあります（Tomcat や WebSphere は良い例でしょう）。重要なのは、このような環境では MyBatis は Commons Logging を使用するということです。これはつまり、独自の Commons Logging 実装を使う WebSphere のような環境では、あなたが追加した Log4J の設定は無視されるということを意味しています。この現象が厄介なのは、MyBatis が Log4J の設定を無視しているように見えるということです（実は、このような環境では MyBatis が Commons Loggin を使用するため、Log4J の設定が無視されているのです）。クラスパスに Commons Logging を含む環境で動作するアプリケーションでも、mybatis-config.xml に設定を追加することで別のロギング実装を使用することができます。
      </p>
      <source><![CDATA[<configuration>
  <settings>
    ...
    <setting name="logImpl" value="LOG4J"/>
    ...
  </settings>
</configuration>]]>
      </source>
      <p>指定可能な値は SLF4J, LOG4J, LOG4J2, JDK_LOGGING, COMMONS_LOGGING, STDOUT_LOGGING, NO_LOGGING ですが、<code>org.apache.ibatis.logging.Log</code> インターフェイスを実装し、コンストラクター引数として String を受け取る独自に実装したクラスの完全修飾クラス名を指定することもできます。
      </p>
      <p>下記のメソッドを呼び出すことでロギング実装を指定することも可能です。
      </p>
      <source><![CDATA[org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
org.apache.ibatis.logging.LogFactory.useLog4JLogging();
org.apache.ibatis.logging.LogFactory.useJdkLogging();
org.apache.ibatis.logging.LogFactory.useCommonsLogging();
org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]></source>
      <p>これらのメソッドは、他の MyBatis のメソッドより前に呼び出す必要があります。また、要求された実装が実行時のクラスパスに含まれている場合にのみ切り替えることが可能です。例えば、Log4J に切り替えようとして、実行時に Log4J が見つからない場合、MyBatis は切り替えの要求を無視して通常のアルゴリズムでロギング実装を検索します。
      </p>
      <p>SLF4J, Apache Commons Logging, Apache Log4J, JDK Logging API についての詳細はこのドキュメントの範囲外となりますが、後述の設定例は参考になると思います。これらのフレームワークについての詳しい情報は、以下の各サイトを参照してください。
      </p>
      <ul>
        <li>
          <a href="http://www.slf4j.org/">SLF4J</a>
        </li>
        <li>
          <a href="http://commons.apache.org/logging">Apache Commons Logging</a>
        </li>
        <li>
          <a href="http://logging.apache.org/log4j/">Apache Log4j</a>
        </li>
        <li>
          <a href="http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/">JDK Logging API</a>
        </li>
      </ul>
      <subsection name="Logging Configuration">
        <p>実行されるステートメントのログを出力するためには、パッケージ、Mapper の完全修飾名、ネームスペース、あるいはステートメントの完全修飾名に対してログ出力を有効にしてください。
        </p>
        <p>具体的な設定方法は使用するロギング実装によります。以下は Log4J での設定例です。ロギングサービスの設定は、単純にいくつかの設定ファイル（例えば log4j.properties）と、場合によっては新しい JAR（例えば log4j.jar）を追加するだけのことです。以下は、Log4J をプロバイダーとして完全なロギングサービスを設定する手順です。
        </p>
        <p></p>
        <h4>
          ステップ１: Log4J の JAR ファイルを追加する。
        </h4>
        <p>Log4J を使うので、Log4J の JAR ファイルがアプリケーションから利用できるようにしておく必要があります。Log4J の JAR ファイルをダウンロードしてあなたのアプリケーションのクラスパスに追加してください。JAR ファイルは先ほど挙げた URL からダウンロードできます。
        </p>
        <p>Web あるいはエンタープライズアプリケーションの場合は、ダウンロードした <code>log4j.jar</code> を <code>WEB-INF/lib</code> ディレクトリに追加します。スタンドアローンアプリケーションの場合は起動時の JVM の引数に <code>-classpath</code> に追加するだけです。
        </p>
        <p></p>
        <h4>
          ステップ２: Log4J を設定する。
        </h4>
        <p>Log4J の設定はシンプルです。例えば次の Mapper のログを出力する場合：
        </p>
        <source><![CDATA[package org.mybatis.example;
public interface BlogMapper {
  @Select("SELECT * FROM blog WHERE id = #{id}")
  Blog selectBlog(int id);
}]]></source>
        <p>次のテキストを含む <code>log4j.properties</code> というファイルを作成し、クラスパスに配置します。
        </p>
        <source><![CDATA[# Global logging configuration
log4j.rootLogger=ERROR, stdout
# MyBatis logging configuration...
log4j.logger.org.mybatis.example.BlogMapper=TRACE
# Console output...
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
        <p>上記のように設定すると、Log4J は <code>org.mybatis.example.BlogMapper</code> について詳細なログを出力し、それ以外のクラスについてはエラーのみを出力します。</p>
        <p>ログに出力される情報を細かく調整したいのなら、Mapper ファイル全体ではなく特定のステートメントを指定することもできます。次の例では <code>selectBlog</code> ステートメントのみログを出力します。</p>

        <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>

        <p>逆に、複数の Mapper に対するログを有効化したい場合もあるでしょう。その場合は、対象となる Mapper を含むパッケージを指定することができます。</p>

        <source>log4j.logger.org.mybatis.example=TRACE</source>

        <p>クエリが大量の結果セットを返すようなケースでSQLステートメントのみを出力したい場合に対応できるよう、SQLステートメントは DEBUG（JDK logging では FINE）レベル、結果は TRACE（JDK logging では FINER）レベルで出力されるようになっています。SQLステートメントのみを出力したい場合、ログレベルに DEBUG を設定します。</p>

        <source>log4j.logger.org.mybatis.example=DEBUG</source>

        <p>Mapper インターフェイスを使っていない場合、例えば次のような Mapper XML ファイルを使っていたらどうすれば良いのでしょうか。
        </p>

      <source><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.mybatis.example.BlogMapper">
  <select id="selectBlog" resultType="Blog">
    select * from Blog where id = #{id}
  </select>
</mapper>]]></source>

        <p>この場合、次のようにネームスペースを指定することでこの XML ファイル全体のログを有効化することができます。</p>

        <source>log4j.logger.org.mybatis.example.BlogMapper=TRACE</source>

        <p>特定のステートメントのみを対象とする場合は次のように指定します。</p>

        <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>

        <p>お気づきのように、Mapper インターフェイスと XML のどちらを使っている場合でも、設定方法に違いはありません。</p>

        <p><span class="label important">NOTE</span> SLF4J or Log4j 2 をお使いの場合、MyBatis のログは MYBATIS というマーカーで出力されます。</p>

        <p>上記の <code>log4j.properties</code> の残りの部分はアペンダーの設定になっていますが、このドキュメントでは説明しません。Log4J のサイト（上記URL）を参照してください。あるいは、設定値を変更してみてどのような結果になるか試してみるのも良いでしょう。
        </p>
      </subsection>
    </section>
  </body>
</document>