patternformatter.java

MoMELog是J2ME的日志框架。它是非常简单的

package momelog.formatter;

import java.util.Vector;

import momelog.Configurable;
import momelog.Formatter;
import momelog.LogEvent;
import momelog.Logger;

/**
 * <p>
 * Formatter intended to convert logging events to strings based on
 * <em>conversion pattern</em>. It's functionality and format of conversion
 * pattern resemble very much that of the {@code log4J} framework.
 * </p>
 * <p>
 * Conversion pattern is a string that specifies the way, logging events are
 * converted. It's format resembles very much format of conversion pattern in
 * {@code log4J} framework.
 * </p>
 * 
 * <p>
 * Conversion pattern consists of <em>literal text</em> and
 * <em>conversion specifiers</em>. 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.
 * </p>
 * 
 * <p>
 * Each conversion specifier starts with a percent sign ({@code %}) followed
 * by the optional <em>format modifiers</em> and <em>conversion character</em>.
 * 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.
 * </p>
 * <p>
 * {@link PatternFormatter} recognizes following conversion characters.
 * </p>
 * 
 * <table width="100%" border="1" cellpadding="2" cellspacing="0"> <col
 * width="10%"> <col width="*">
 * <tr valign="top">
 * <td>
 * <p>
 * <strong>Conversion character</strong>
 * </p>
 * </td>
 * <td>
 * <p>
 * <strong>Description</strong>
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td valign="top">
 * <p>
 * <strong>c</strong>
 * </p>
 * </td>
 * <td valign="top">
 * <p>
 * Designates the place where category of logger generated this logging event
 * should be inserted.
 * </p>
 * <p>
 * <strong>Note:</strong> Unlike in {@code log4J} framework,
 * <em>category conversion specifier</em> <strong>can not</strong> be
 * followed by the optional <em>precision specifier</em>,
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td valign="top">
 * <p>
 * <strong>C</strong>
 * </p>
 * </td>
 * <td valign="top">
 * <p>
 * Designates the place where last part of category of logger generated this
 * logging event should be inserted. Category is separated on parts by dots ({@code .}).
 * For example the last part of category {@code foo.bar.SomeCategory} is
 * {@code SomeCategory}.
 * </p>
 * <p>
 * <strong>Note:</strong> Unlike in {@code log4J} framework, the
 * <em>last part category conversion specifier</em> <strong>can not</strong>
 * be followed by optional <em>precision specifier</em>,
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td valign="top">
 * <p>
 * <strong>m</strong>
 * </p>
 * </td>
 * <td valign="top">
 * <p>
 * Designates the place where message of logging event should be inserted. If
 * message is {@code null} an empty string is inserted.
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td valign="top">
 * <p>
 * <strong>e</strong>
 * </p>
 * </td>
 * <td valign="top">
 * <p>
 * Designates the place where error of logging event should be inserted. Error
 * is converted to the string by {@link Throwable#toString()} method. If error
 * is {@code null} an empty string is inserted.
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td width="10%" valign="top">
 * <p>
 * <strong>t</strong>
 * </p>
 * </td>
 * <td width="*" valign="top">
 * <p>
 * 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 {@link Logger} class loading. It can be set to now by
 * {@link Logger#resetBaseTime()} method.
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td width="10%" valign="top">
 * <p>
 * <strong>h</strong>
 * </p>
 * </td>
 * <td width="*" valign="top">
 * <p>
 * Designates the place where the name of thread, in which logging event was
 * issued, should be inserted.
 * </p>
 * </td>
 * </tr>
 * <tr>
 * <td width="10%" valign="top">
 * <p>
 * <strong>%%</strong>
 * </p>
 * </td>
 * <td width="*" valign="top">
 * <p>
 * Sequence %% outputs a single percent sign ({@code %}).
 * </p>
 * </td>
 * </tr>
 * </table>
 * <p>
 * By default the relevant information is output as is. However, by use of an
 * optional <em>format modifiers</em> it is possible to specify minimum,
 * maximum field's width and justification. Format modifiers are placed between
 * the percent sign and the conversion character.
 * </p>
 * <p>
 * Format modifiers string is of the format {@code [-][min][.max]}
 * </p>
 * <p>
 * The first optional minus ({@code -}) character designates left
 * justification. If it is specified, field is left justified, right justified
 * otherwise (by default).
 * </p>
 * <p>
 * Optional {@code 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.
 * </p>
 * <p>
 * Optional {@code max} modifier is the decimal constant, that specifies maximum
 * width of the field. It is designated by preceding dot ({@code .}). If
 * field's width is greater than maximum, then the extra characters (as in
 * {@code log4J} framework) are deleted from the beginning of the field
 * <strong>not from the end</strong>.
 * </p>
 * <p>
 * For example. The conversion pattern is set to
 * {@code "Logging of '%7.7c' in thread %h is %m %e %%at %10t"}. Then the
 * following code snippet
 * </p>
 * 
 * <pre>
 *  public class SomeClass
 *  {
 *    ...
 *          
 *    private static final Logger log = Logger.getLogger(SomeClass.class);
 *          
 *    ...
 *          
 *    public void someMethod()
 *    {
 *      ...
 *          
 *      log.log( &quot;Connection with &quot; + url + &quot; established&quot;);
 *          
 *      ...
 *          
 *    }
 *          
 *    ...
 *  }
 * </pre>
 * 
 * <p>
 * produces the logging event that is converted to
 * </p>
 * 
 * <pre>
 *  Logging of 'meClass' in thread Thread-7 is Connection with http://somedomain.org/somepage/index.html established  %at      17785
 * </pre>
 * 
 * <p>
 * {@link PatternFormatter} can be instantiated by using one of the following
 * constructors {@link PatternFormatter#PatternFormatter(String)} or
 * {@link PatternFormatter#PatternFormatter()}. In the first case it is
 * initialized with specified conversion pattern and in second - with default
 * one. {@code MoMELog} logging framework is preset with
 * {@link PatternFormatter} initialized with default pattern ({@code "%C> %m %e (%t)"}).
 * That's why, if another formatter is not specified declaratively or
 * programmatically, {@link PatternFormatter} instance can be obtained by
 * calling {@link Logger#getFormatter()} static method.
 * </p>
 * <p>
 * Conversion pattern can be set by using {@link #setPattern(String)} setter
 * method. After this method returns, all new logging events are formatted using
 * new conversion pattern.
 * </p>
 * <p>
 * {@link PatternFormatter} implements {@link Configurable} interface. It can be
 * configured programmatically by invoking respective setter method or
 * declaratively from configuration file. See <a
 * href="../../../patternformatter-guide.html#config">PatternFormatter Guide</a>
 * for more details.
 * </p>
 * 
 * @author Sergio Morozov
 * @version 1.0
 */
public class PatternFormatter extends Formatter implements Configurable
{
  /**
   * Default conversion pattern. The value is {@code "%C> %m %e (%t)"}.
   */
  public static final String DEFAULT_PATTERN = "%C> %m %e (%t)";

  private static final int RECORD_UNKNOWN = 0;

  private static final int RECORD_MESSAGE = 1;

  private static final int RECORD_CATEGORY = 2;

  private static final int RECORD_FINAL_CATEGORY = 3;

  private static final int RECORD_ERROR = 4;

  private static final int RECORD_TIMESTAMP = 5;

  private static final int RECORD_THREADNAME = 6;

  private Object[] patternParts = null;

  /**
   * Instantiates {@link PatternFormatter} initialized with the specified
   * conversion pattern.
   * 
   * @param pattern
   *          conversion pattern.
   * @throws IllegalArgumentException
   *           if specified {@code pattern} is of invalid format.
   */
  public PatternFormatter(String pattern)
  {
    super();
    setPattern(pattern);
  }

  /**
   * Instantiates {@link PatternFormatter} initialized with
   * {@link #DEFAULT_PATTERN} ({@code "%C> %m %e (%t)"}).
   */
  public PatternFormatter()
  {
    super();
    setPattern(DEFAULT_PATTERN);
  }

  /**
   * Converts specified logging event to the string based on conversion pattern
   * and appends it to the given {@link StringBuffer}.
   *