Retrascope

h1. Logging

Currently, Retrascope logging subsystem is based on the JUL framework (java.util.logging).

h2. Format of entries

"date. level: message"

Date format: "yyyy.MM.dd HH:mm:ss.SSS". This field along with level field are automatically filled in by the log formatter, while the message field is constructed by logging object.

Message format: "header: message". Typically, header is a logging object class or instance name.

h2. Usage

The root logger is configured in the ru.ispras.retrascope.Retrascope class as logger with name ru.ispras.retrascope. All loggers of other Retrascope classes must be created with a name of the format "<class_package>.<class/instance_name>" (ru.ispras.retrascope.engine.efsm.simulator.EfsmSimulator, for example). Because of that all such loggers will use the root logger as parent and send their messages to root handlers, so generally there is no need to configure non-root handlers.

Logging must be used in all Engine classes.

Four log levels are used in Retrascope: LogLevel.ERROR (renamed Level.SEVERE), LogLevel.WARNING (equals to Level.WARNING), LogLevel.INFO (equals to Level.INFO), LogLevel.DEBUG (renamed Level.FINE).

h3. Examples

The usage examples from the EfsmSimulator and Retrascope classes are presented below.

h4. Logger creation

<pre><code class="java">

this.logger = Logger.getLogger(this.getClass().getCanonicalName());

</code></pre>

h4. Logging message without throwable object

<pre><code class="java">

if (this.logger.isLoggable(Level.INFO)) {

  this.logger.log(Level.INFO, this.logEntryHeader

      + ": starting to process the events: " + events);

}

</code></pre>

h4. Logging message with throwable object

<pre><code class="java">

catch (IOException | SecurityException e) {

  if (Retrascope.logger.isLoggable(Level.SEVERE)) {

    Retrascope.logger.log(Level.SEVERE, Retrascope.LOG_ENTRY_HEADER +

        ": the exception has been encountered during a logging file handler configuring: ", e);

  }

}

</code></pre>