PatternFormatter Guide

Sergio Morozov


Contents

  1. Overview
  2. Description
  3. Configuration
    1. Declarative Configuration
    2. Programmatical Configuration

Overview

PatternFormatter is a Formatter implementation intended to convert logging events to strings based on conversion pattern. It's functionality and format of conversion pattern resemble very much that of the log4J framework.

Description

PatternFormatter is intended to convert logging events to strings based on conversion pattern. Conversion pattern is a string that specifies the way, logging events are converted. It's format resembles very much format of conversion pattern in log4J framework.

Conversion pattern consists of literal text and conversion specifiers. Literal text of pattern is inserted in result as is. Users are free to specify any literal text within the conversion pattern. Conversion specifiers designate where and how properties of logging event should be inserted.

Each conversion specifier starts with a percent sign (%) followed by the optional format modifiers and conversion character. Conversion character specifies property of logging event to be inserted (e.g. category, message, timestamp etc.). The format modifiers define minimum and/or maximum field's width and left or right justification.

PatternFormatter recognizes following conversion characters.

Conversion character

Description

c

Designates the place where category of logger generated this logging event should be inserted.

Note: Unlike in log4J framework, category conversion specifier can not be followed by the optional precision specifier,

C

Designates the place where last part of category of logger generated this logging event should be inserted. Category is separated on parts by dots (.). For example the last part of category foo.bar.SomeCategory is SomeCategory.

Note: Unlike in log4J framework, the last part category conversion specifier can not be followed by optional precision specifier,

m

Designates the place where message of logging event should be inserted. If message is null an empty string is inserted.

e

Designates the place where error of logging event should be inserted. Error is converted to the string by Throwable.toString() method. If error is null an empty string is inserted.

t

Designates the place where timestamp of logging event should be inserted. Timestamp is a long integer specifying number of milliseconds from some base time point till logging event generation. By default, base time point is the time of Logger class loading. It can be set to now by Logger.resetBaseTime() method.

h

Designates the place where the name of thread, in which logging event was issued, should be inserted.

%%

Sequence %% outputs a single percent sign (%).

By default the relevant information is output as is. However, by use of an optional format modifiers it is possible to specify minimum, maximum field's width and justification. Format modifiers are placed between the percent sign and the conversion character.

Format modifiers string is of the format [-][min][.max]

The first optional minus (-) character designates left justification. If it is specified, field is left justified, right justified otherwise (by default).

Optional min modifier is the decimal constant, that specifies minimum width of the field. If field's width is less than minimum, field is padded by spaces from left in a case of right justification or from right in a case of left justification.

Optional max modifier is the decimal constant, that specifies maximum width of the field. It is designated by preceding dot (.). If field's width is greater than maximum, then the extra characters (as in log4J framework) are deleted from the beginning of the field not from the end.

For example. The conversion pattern is set to "Logging of '%7.7c' in thread %h is %m %e %%at %10t". Then the following code snippet

  public class SomeClass
  {
    ...

    private static final Logger log = Logger.getLogger(SomeClass.class);

    ...

    public void someMethod()
    {
      ...

      log.log( "Connection with " + url + " established");

      ...

    }

    ...
  }

produces the logging event that is converted to

  Logging of 'meClass' in thread Thread-7 is Connection with http://somedomain.org/somepage/index.html established  %at      17785

Users don't need to set conversion pattern to use PatternFormatter, because it is preset with default pattern "%C> %m %e (%t)".

PatternFormatter implements Configurable interface. It can be configured declaratively from configuration file and/or programmatically by invoking respective setter method. See Configuration chapter for more details.


Configuration

  1. Declarative Configuration
  2. Programmatical Configuration

PatternFormatter can be configured declaratively from initialization file and/or programmatically by invoking setter methods. Declarative configuration is the preferred one. Declarative configuration takes place at Logger class loading time and programmatical configuration overrides it. PatternFormatter contains only one configuration property - pattern. It is preset with default conversion pattern ("%C> %m %e (%t)") and doesn't require configuration.

Declarative Configuration

PatternFormatter can be configured declaratively from initialization file.

PatternFormatter formatter supports the only property - pattern. If this property is specified more than one time, the last occurrence prevails.

Property Name

Description

Default Value

"pattern"

Designates conversion pattern to be used. Spaces around property value are significant (property value is not trimmed.).

Since version 1.0

%C> %m %e (%t)

For example following configuration file snippet

  #marker  is just the end of line. It is shown to emphasize trailing spaces.
  formatter.pattern =  %.5C:%m %e (%7t) [%h] <EOL>

sets pattern to " %.5C:%m %e (%7t) [%h] " (spaces around property value are significant).

Programmatical Configuration

As mentioned above PatternFormatter can be configured programmatically by invoking setter methods on it's instance.

PatternFormatter can be instantiated by using one of the following constructors PatternFormatter(String pattern) or PatternFormatter(). In the first case it is initialized with specified conversion pattern and in second - with default one. MoMELog logging framework is preset with PatternFormatter initialized with default pattern ("%C> %m %e (%t)"). That's why, if another formatter is not specified declaratively or programmatically, PatternFormatter instance can be obtained by calling Logger.getFormatter() static method.

PatternFormatter has the only configuration property - pattern, that can be set by using setPattern(String pattern) method. After this method returns, all new logging events are formatted using new conversion pattern.

Conversion pattern can be set at any time. In typical use it is, of course, set at the start of the application (e.g. in MIDlet.startApp() method). For example in MIDlet SomeMIDlet.

  ...

  protected void startApp()
  {
    if( !started)
    {
      ...

      // setting our conversion pattern.
      // as MoMELog is preset with PatternFormatter
      // we don't need to instantiate it.
      ((PatternFormatter) Logger.getFormatter()).setPattern( "%.5C>%m %e at %t [%h]");

      ...

      started = true;

      ...
    }

    ...
  }

  ...


Sergio Morozov. 2007