<?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 | Logging</title>
    <author email="clinton.begin@gmail.com">Clinton Begin</author>
    <author email="eduardo.macarron@gmail.com">Eduardo Macarron</author>
  </properties>

  <body>
    <section name="Logging">
      <p></p>
      <p>MyBatis proporciona información de logging mediante el uso interno de una factoría. La factoría interna delega la información de logging en alguna de las siguientes implementaciones.
      </p>
      <ul>
        <li>
          SLF4J
        </li>
        <li>
          Apache Commons Logging
        </li>
        <li>
          Log4j 2
        </li>
        <li>
          Log4j
        </li>
        <li>
          JDK logging
        </li>
      </ul>
      <p>La solución de logging elegida se basa en una introspección en tiempo de ejecución de la propia factoría interna de MyBatis. La factoría usará la primera implementación de logging que encuentre (el orden de búsqueda es el de la lista de más arriba). Si no se encuentra ninguna, el logging se desactivará.
      </p>
      <p>Muchos entornos vienen con Commons Logging incluido como pare del classpath del servidor (por ejemplo Tomcat y WebSphere). Es importante conocer que en esos entorno, MyBatis usará JCL como implementación de logging. En un entorno como WebSphere esto significa que tu configuración de log4j será ignorada dado que WebSphere proporciona su propia implementación de JCL. Esto puede ser muy frustrante porque parece que MyBatis está ignorando tu configuración de logging (en realidad, MyBatis está ignorando tu configuración de log4j porque está usando JCL en dicho entorno). Si tu aplicación se ejecuta en un entorno que lleva JCL incluido pero quieres usar un método distinto de logging puedes añadir un setting a tu fichero mybatis-config.xml:
      </p>
      <source><![CDATA[<configuration>
  <settings>
    ...
    <setting name="logImpl" value="LOG4J"/>
    ...
  </settings>
</configuration>]]>
      </source>
      <p>Los valores válidos son: SLF4J, LOG4J, LOG4J2, JDK_LOGGING, COMMONS_LOGGING, STDOUT_LOGGING, NO_LOGGING o
      un nombre de clase plenamente cualificado que implemente <code>org.apache.ibatis.logging.Log</code> y reciba
      un string como parametro de constructor.
      </p>
      <p>Tambien puedes seleccionar el método de logging llamando a uno de los siguientes métodos:
      </p>
      <source><![CDATA[org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
org.apache.ibatis.logging.LogFactory.useLog4JLogging();
org.apache.ibatis.logging.LogFactory.useLog4J2Logging();
org.apache.ibatis.logging.LogFactory.useJdkLogging();
org.apache.ibatis.logging.LogFactory.useCommonsLogging();
org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]></source>
      <p>Si eliges llamar a alguno de estos métodos, deberías hacerlo antes de llamar a ningún otro método de MyBatis. Además, estos métodos solo establecerán la implementación de log indicada si dicha implementación está disponible en el classpath. Por ejemplo, si intentas seleccionar log4j y log4j no está disponible en el classpath, MyBatis ignorará la petición y usará su algoritmo normal de descubrimiento de implementaciones de logging.
      </p>
      <p>Los temas específicos de JCL, Log4j y el Java Logging API quedan fuera del alcance de este documento. Sin embargo la configuración de ejemplo que se proporciona más abajo te ayudará a comenzar. Si quieres conocer más sobre estos frameworks, puedes obtener más información en las siguientes ubicaciones:
      </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 1.x y 2.x</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="Configuración">
        <p>Para ver el log de las sentencias debes activar el log en un paquete, el nombre plenamente cualificado de una clase, un namespace o un nombre plenamente cualificado de un mapped statement.</p>
        <p>Nuevamente, cómo hagas esto es dependiente de la implementación de logging que se esté usando. Mostraremos cómo hacerlo con Log4j. Configurar los servicios de logging es simplemente cuestión de añadir uno o varios ficheros de configuración (por ejemplo log4j.properties) y a veces un nuevo JAR (por ejemplo log4j.jar). El ejemplo siguiente configura todos los servicios de logging para que usen log4j como proveedor. Sólo son dos pasos:
        </p>
        <h4>Paso 1: Añade el fichero Log4j JAR
        </h4>
        <p>Dado que usamos Log4j, necesitaremos asegurarnos que el fichero JAR está disponible para nuestra aplicación. Para usar Log4j, necesitas añadir el fichero JAR al classpath de tu aplicación. Puedes descargar Log4j desde la URL indicada más arriba.
        </p>
        <p>En aplicaciones Web o de empresa debes añadir tu fichero log4j.java a tu directorio WEB-INF/lib, y en una aplicación standalone simplemente añádela al parámetro –classpath de la JVM.
        </p>
        <h4>
          Paso 2: Configurar Log4j
        </h4>
        <p>Configurar Log4j es sencillo. Supongamos que quieres habilitar el log para este mapper:</p>
        <source><![CDATA[package org.mybatis.example;
public interface BlogMapper {
  @Select("SELECT * FROM blog WHERE id = #{id}")
  Blog selectBlog(int id);
}]]></source>
        <p>Crea un fichero con nombre <code>log4j.properties</code>
        como el que se muestra a continuación y colocalo en tu classpath:
        </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>El fichero anterior hará que log4j reporte información detallada para <code>org.mybatis.example.BlogMapper</code> e información de errores para el resto de las clases de tu aplicación.</p>
        <p>Si quieres activar un nivel más fino de logging puedes activar el logging para statements específicos en lugar de para todo un mapper. La siguiente línea activa el logging sólo para el statement <code>selectBlog</code>:</p>

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

        <p>Si por el contrario quieres activar el log para un grupo de mappers debes añadir un logger para el paquete raiz donde residen tus mappers:</p>

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

        <p>Hay consultas que pueden devolver una gran cantidad de datos. En esos casos puedes querer ver las sentencias SQL pero no los datos. Para conseguirlo las sentencias se loguean con nivel DEBUG (FINE en JDK) y los resultados con TRACE (FINER en JDK), por tanto si quieres ver la sentencia pero no el resultado establece el nivel a DEBUG</p>

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

        <p>Y si estás usando ficheros XML como este?</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>En tal caso puedes activar el logging de todo el fichero añadiendo un logger para el namespace como se muestra a continuación:</p>

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

		<p>O para un statement específico:</p>

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

		<p>Sí, como ya te habrás dado cuenta, no hay ninguna diferencia entre configurar el logging para un mapper o para un fichero XML.</p>

        <p><span class="label important">NOTA</span> Si usas SLF4J o Log4j 2 MyBatis le llamará usando MYBATIS como marker.</p>

        <p>El resto de la configuración sirve para configurar los appenders, lo cual queda fuera del ámbito de este documento. Sin embargo, puedes encontrar más información en el site de Log4j (la url está más arriba). O, puedes simplemente experimentar para ver los efectos que consigues con las distintas opciones de configuración.</p>
      </subsection>
    </section>
  </body>
</document>
