h1. Logging guidelines

h2. Framework

h3. SLF4J (Simple Logging Facade for Java)

"Documentation":http://www.slf4j.org/docs.html

h3. Maven

No dependency SHOULD be added to the module POM. The slf4j dependency is already defined in the ecard client root POM.
slf4j needs a backend implementation. For the tests, logback-classic is pulled in by the root POM. For production use, the client artifact must pull in a compile dependency on a backend and configure it appropriately.

h3. Preamble

<pre>
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);
</pre>

h3. SLF4J with java.util.logging backend

*TODO:* rewrite for logback-classic

This code SHOULD only be using in TestNG.

<pre>
// Reset configuration to avoid multiple log entries.
java.util.logging.LogManager.getLogManager().reset();
// Add new console handler
ConsoleHandler ch = new ConsoleHandler();
ch.setLevel(Level.ALL);
// Set logging level
LogManager.getLogger(MYCLASS.class.getName()).setLevel(Level.FINE);

// Log message as jdk logging level INFO
logger.info("Log my message: {}", message);
// Log message as jdk logging level FINE
logger.debug("Log my message: {}", message);
// Log message as jdk logging level WARNING
logger.warn("Log my message: {}", message);
// Log message as jdk logging level SEVERE
logger.error("Log my message: {}", message);
</pre>



h2. Levels

h3. Exceptions

<pre>
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);

try{
 ...
} catch (Exception e){
  logger.error(ex.getMessage(), ex);
}
</pre>
Or set a descriptive message:
<pre>
try{
 ...
} catch (Exception e){
  logger.error("Error while reading value X.", ex);
}
</pre>


h3. Messages

Messages including  APDUs, eCard-API messages, PAOS messages.

<pre>
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);

logger.debug("Message received:\n{}", message);
logger.debug("Message sent:\n{}", message);
</pre>

h3. Events

E.g. GUI events.

<pre>
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(MYCLASS.class);

logger.debug("Event: {}", event);
</pre>

h2. Notes

h3. Trace statements as the following example shows are omitted, because there is a "slf4j agent":http://www.slf4j.org/extensions.html#javaagent which can automate this task.

<pre>
public void foo(Bar b) {
    logger.trace("Enter function foo: {}", b);
    ...
</pre>