You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by mi...@apache.org on 2015/11/09 17:15:22 UTC

[2/2] logging-log4j2 git commit: Scala documentation

Scala documentation


Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/9a7bdffb
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/9a7bdffb
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/9a7bdffb

Branch: refs/heads/LOG4J-1181
Commit: 9a7bdffbee0684b601b180b04620757d8ae77ed1
Parents: 0a0d14d
Author: Mikael Ståldal <mi...@magine.com>
Authored: Mon Nov 9 17:15:04 2015 +0100
Committer: Mikael Ståldal <mi...@magine.com>
Committed: Mon Nov 9 17:15:04 2015 +0100

----------------------------------------------------------------------
 src/site/site.xml                  |  1 +
 src/site/xdoc/manual/scala-api.xml | 72 +++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/9a7bdffb/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 0cb6f9c..c100d06 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -57,6 +57,7 @@
         <item name="Event Logging" href="/manual/eventlogging.html"/>
         <item name="Messages" href="/manual/messages.html"/>
         <item name="ThreadContext" href="/manual/thread-context.html"/>
+        <item name="Scala API" href="/manual/scala-api.html"/>
       </item>
 
       <item name="Configuration" href="/manual/configuration.html" collapse="true">

http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/9a7bdffb/src/site/xdoc/manual/scala-api.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/scala-api.xml b/src/site/xdoc/manual/scala-api.xml
new file mode 100644
index 0000000..555bc0d
--- /dev/null
+++ b/src/site/xdoc/manual/scala-api.xml
@@ -0,0 +1,72 @@
+<?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 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>Log4j 2 API</title>
+        <author email="mikes@apache.org">Mikael Ståldal</author>
+    </properties>
+
+    <body>
+        <section name="Log4j 2 API">
+            <a name="ScalaAPI"/>
+            <subsection name="Scala API">
+                <p>
+                    Log4j 2 contains a convenient Scala wrapper for the
+                    <a href="../log4j-api/apidocs/org/apache/logging/log4j/Logger.html">Logger</a>
+                    API.
+                </p>
+                <h4>Example</h4>
+                <pre class="prettyprint linenums">import org.apache.logging.log4j.scala.Logging
+
+class MyClass extends BaseClass with Logging {
+    def doStuff(): Unit = {
+        logger.info("Doing stuff")
+    }
+}</pre>
+                <p>
+                    The output from the call to logger.info() will vary significantly depending on the configuration
+                    used. See the
+                    <a href="./configuration.html">Configuration</a>
+                    section for more details.
+                </p>
+                <h4>Substituting Parameters</h4>
+                <p>
+                    Frequently the purpose of logging is to provide information about what is happening in the system,
+                    which requires including information about the objects being manipulated. In Scala, you can use
+                    <a href="http://docs.scala-lang.org/overviews/core/string-interpolation.html">string interpolation</a>
+                    to achieve this:
+                </p>
+                <pre class="prettyprint">logger.debug(s"Logging in user ${user.getName} with birthday ${user.calcBrithday}")</pre>
+                <p>
+                    Since the Scala Logger is implemented with macros, the String construction and method invocations will only occur when debug logging is enabled.
+                </p>
+
+                <h4>Logger Names</h4>
+                <p>
+                    Most logging implementations use a hierarchical scheme for matching logger names with logging
+                    configuration. In this scheme the logger name hierarchy is represented by '.' characters in the
+                    logger name, in a fashion very similar to the hierarchy used for Java/Scala package names.
+                    The Logging trait will automatically name the Logger accordingly to the class it is being used in.
+                </p>
+            </subsection>
+        </section>
+    </body>
+</document>