<?xml version="1.0"?>
<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You 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>
    <properties>
        <title>Log4j 2 API</title>
        <author email="rgoers@apache.org">Ralph Goers</author>
    </properties>

    <body>
        <section name="Log4j 2 API">
          <a name="Markers"/>
          <subsection name="Markers">
            <p>
              One of the primary purpose of a logging framework is to provide the means to generate debugging and
              diagnostic information only when it is needed, and to allow filtering of that information so that it
              does not overwhelm the system or the individuals who need to make use of it. As an example, an
              application desires to log its entry, exit and other operations separately from SQL statements
              being executed, and wishes to be able to log queries separate from updates. One way to accomplish
              this is shown below:
            </p>
        <pre class="prettyprint linenums"><![CDATA[
import org.apache.logging.log4j.Logger;
import org.apache.logging.log4j.LogManager;
import java.util.Map;

public class MyApp {

    private Logger logger = LogManager.getLogger(MyApp.class.getName());
    private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
    private static final Marker UPDATE_MARKER = MarkerManager.getMarker("SQL_UPDATE", SQL_MARKER);
    private static final Marker QUERY_MARKER = MarkerManager.getMarker("SQL_QUERY", SQL_MARKER);

    public String doQuery(String table) {
        logger.entry(param);

        logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);

        return logger.exit();
    }

    public String doUpdate(String table, Map<String, String> params) {
        logger.entry(param);

        if (logger.isDebugEnabled()) {
          logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, formatCols());

        return logger.exit();
    }

    private String formatCols(Map<String, String> cols) {
        StringBuilder sb = new StringBuilder();
        boolean first = true;
        for (Map.Entry<String, String> entry : cols.entrySet()) {
            if (!first) {
                sb.append(", ");
            }
            sb.append(entry.getKey()).append("=").append(entry.getValue());
            first = false;
        }
        return sb.toString();
    }
}]]></pre>
            <p>
              In the example above it is now possible to add MarkerFilters to only allow SQL update operations
              to be logged, all SQL updates to be logged or to log everything in MyApp.
            </p>
            <p>
              Some important rules about Markers must be considered when using them.
              <ol>
                <li>Markers must be unique. They are permanently registered by name so care should be taken
                  to insure that Markers used in your application are distinct from those in the application's
                  dependencies, unless that is what is desired.</li>
                <li>Like many objects in Log4j 2, Markers are immutable. If a marker has a parent, the parent
                  must be named when the Marker is created and the parent cannot be changed after creation.</li>
                <li>Markers only have a single parent. Markers can, however, have many children that reference
                  them.</li>
              </ol>
            </p>
          </subsection>
        </section>
    </body>
</document>
