Home Code Other Software

Table of Contents

Introduction

The Grizzled SLF4J package provides a very thin Scala-friendly layer on top of the SLF4J (Simple Logging Fa├žade for Java) API. It is released under a BSD license.

Installation

Grizzled SLF4J is published to the oss.sonatype.org repository and automatically sync’d with the Maven Central Repository.

Installing with Maven

If you’re using Maven, just specify the artifact, and Maven will do the rest for you:

For example:

<dependency>
  <groupId>org.clapper</groupId>
  <artifactId>grizzled-slf4j_2.10</artifactId>
  <version>1.0.1</version>
</dependency>

For more information on using Maven and Scala, see Josh Suereth’s Scala Maven Guide.

Using with SBT

0.7.x

If you’re using SBT 0.7.x to compile your code, you can place the following line in your project file (i.e., the Scala file in your project/build/ directory):

val grizzled_sl4fj = "org.clapper" %% "grizzled-slf4j" % "0.6.9"

0.11.x

If you’re using SBT 0.11.x to compile your code, you can use the following line in your build.sbt file (for Quick Configuration). If you’re using an SBT 0.11.x Full Configuration, you’re obviously smart enough to figure out what to do, on your own.

If you’re using Scala 2.10, use:

libraryDependencies += "org.clapper" % "grizzled-slf4j_2.10" % "1.0.1"

If you’re using Scala 2.9.x or earlier, use:

libraryDependencies += "org.clapper" %% "grizzled-slf4j" % "0.6.10"

Grizzled SLF4J is also registered with Doug Tangren’s excellent ls.implicit.ly catalog. If you use the ls SBT plugin, you can install Grizzled SLF4J with

sbt> ls-install grizzled-slf4j

Building from Source

You can also build Grizzled SLF4J from source. There are two ways to get the source:

Downloading a snapshot of the source

You can download a tarball or zip file of the source from the downloads page.

Source Code Repository

The source code for Grizzled SLF4J is maintained on GitHub. To clone the repository, run this command:

$ git clone git://github.com/bmc/grizzled-slf4j.git

Note: That gets you the trunk, which supports Scala 2.10 and later. If you want the code for Scala 2.9, switch to the release-0.6.10-fixes branch:

$ cd grizzled-scala
$ git co release-0.6.10-fixes

Building

Building the library requires SBT. Install SBT, as described at the SBT web site. Then, assuming you have an sbt shell script (or .BAT file, for Windows), run:

sbt +update

That command will pull down the external jars on which the Grizzled SLF4J Library depends. After that step, build the library with:

sbt +compile +package

The resulting jar files will be under the top-level target directory, in subdirectories specific to each Scala version.

Using the Grizzled SLF4J library

Grizzled SLF4J is a thin, Scala-friendly wrapper around SLF4J. It’s simpler to use than direct SLF4J, primarily because it uses Scala’s call-by-name magic so that you can use make logger calls easily, without incurring any overhead.

For example, the various logging methods are defined as follows:

@inline final def debug(message: => Any)

Thus, debug() isn’t a method taking a string; instead, it’s a method taking a function that returns a string. Under the covers, debug() does what you’d expect:

@inline final def debug(message: => Any) =
    if (debugIsEnabled) log(message)

However, because message is a function that returns a string, it isn’t evaluated until it is called–which is after the test that determines whether it should be logged.

Because of Scala’s rich syntactic sugar, you can still call debug() in a straightforward way:

log.debug("Failed to open file \"" + file.getCanonicalPath + "\"")

However, the argument to debug() is a function, not a string, so the string concatenation and the call to file.getCanonicalPath do not happen until and unless the debug() function determines that debug logging is enabled.

Note, too, that the method definitions are annotated with @inline final, giving the Scala compiler the opportunity to pull them inline, for greater efficiency.

Thus, Grizzled SLF4J gives you a simple, Scala-friendly API for SLF4J (with no need to use SLF4J format strings), while retaining the performance benefits of delayed evaluation.

Getting a Logger

To get a logger, use the Logger object and pass it a name, a class, or a type. (By convention, a name should be a class name.) Examples:

Using a name:

import grizzled.slf4j.Logger

class Foo {
  val logger = Logger("org.example.foo")
}

Using a class:

import grizzled.slf4j.Logger

class Foo {
  val logger = Logger(classOf[Foo])
}

Using a type:

import grizzled.slf4j.Logger

class Foo {
  val logger = Logger[this.type] // or Logger[Foo]
}

Mixing in the Logging Trait

As of version 0.4, this API supports a Logging trait. Instead of instantiating a Logger object and invoking its methods explicitly, you can mix the Logging trait into any class, which automatically:

without changing the class’s public API.

This approach is similar to the Logging trait in the Scalate source. (See Scalate’s Logging.scala.)

Example:

class Foo extends Logging {
  def test: Unit =
    info("test")
}

Logging messages

The Logger class supports the following methods:

def debug(msg => Any, t: => Throwable): Unit
def debug(msg => Any, t: => Throwable): Unit
def isDebugEnabled: Boolean

error(msg => Any, t: => Throwable)
error(msg => Any, t: => Throwable)
def isErrorEnabled: Boolean

info(msg => Any, t: => Throwable)
info(msg => Any, t: => Throwable)
def isInfoEnabled: Boolean

trace(msg => Any, t: => Throwable)
trace(msg => Any, t: => Throwable)
def isTraceEnabled: Boolean

warn(msg => Any, t: => Throwable)
warn(msg => Any, t: => Throwable)
def isWarnEnabled: Boolean

See the API documentation for complete details.

API Documentation

The Scaladoc-generated the API documentation is available locally. In addition, you can generate your own version with:

sbt doc

Change log

The change log for all releases is here.

Author

Brian M. Clapper, bmc@clapper.org

Grizzled SLF4J is copyright © 2010 Brian M. Clapper and is released under a BSD License.

Patches

I gladly accept patches from their original authors. Feel free to email patches to me or to fork the GitHub repository and send me a pull request. Along with any patch you send: