Source for java.util.logging.Formatter

   1: /* Formatter.java --
   2:    A class for formatting log messages by localizing message texts
   3:    and performing substitution of parameters
   4:    Copyright (C) 2002, 2004 Free Software Foundation, Inc.
   5: 
   6: This file is part of GNU Classpath.
   7: 
   8: GNU Classpath is free software; you can redistribute it and/or modify
   9: it under the terms of the GNU General Public License as published by
  10: the Free Software Foundation; either version 2, or (at your option)
  11: any later version.
  12: 
  13: GNU Classpath is distributed in the hope that it will be useful, but
  14: WITHOUT ANY WARRANTY; without even the implied warranty of
  15: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16: General Public License for more details.
  17: 
  18: You should have received a copy of the GNU General Public License
  19: along with GNU Classpath; see the file COPYING.  If not, write to the
  20: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  21: 02110-1301 USA.
  22: 
  23: Linking this library statically or dynamically with other modules is
  24: making a combined work based on this library.  Thus, the terms and
  25: conditions of the GNU General Public License cover the whole
  26: combination.
  27: 
  28: As a special exception, the copyright holders of this library give you
  29: permission to link this library with independent modules to produce an
  30: executable, regardless of the license terms of these independent
  31: modules, and to copy and distribute the resulting executable under
  32: terms of your choice, provided that you also meet, for each linked
  33: independent module, the terms and conditions of the license of that
  34: module.  An independent module is a module which is not derived from
  35: or based on this library.  If you modify this library, you may extend
  36: this exception to your version of the library, but you are not
  37: obligated to do so.  If you do not wish to do so, delete this
  38: exception statement from your version. */
  39: 
  40: 
  41: package java.util.logging;
  42: 
  43: import java.text.MessageFormat;
  44: import java.util.ResourceBundle;
  45: 
  46: /**
  47:  * A <code>Formatter</code> supports handlers by localizing
  48:  * message texts and by subsituting parameter values for their
  49:  * placeholders.
  50:  *
  51:  * @author Sascha Brawer (brawer@acm.org)
  52:  */
  53: public abstract class Formatter
  54: {
  55:   /**
  56:    * Constructs a new Formatter.
  57:    */
  58:   protected Formatter()
  59:   {
  60:   }
  61: 
  62: 
  63:   /**
  64:    * Formats a LogRecord into a string.  Usually called by handlers
  65:    * which need a string for a log record, for example to append
  66:    * a record to a log file or to transmit a record over the network.
  67:    *
  68:    * @param record the log record for which a string form is requested.
  69:    */
  70:   public abstract String format(LogRecord record);
  71: 
  72: 
  73:   /**
  74:    * Returns a string that handlers are supposed to emit before
  75:    * the first log record.  The base implementation returns an
  76:    * empty string, but subclasses such as {@link XMLFormatter}
  77:    * override this method in order to provide a suitable header.
  78:    *
  79:    * @return a string for the header.
  80:    *
  81:    * @param handler the handler which will prepend the returned
  82:    *     string in front of the first log record.  This method
  83:    *     may inspect certain properties of the handler, for
  84:    *     example its encoding, in order to construct the header.
  85:    */
  86:   public String getHead(Handler handler)
  87:   {
  88:     return "";
  89:   }
  90: 
  91: 
  92:   /**
  93:    * Returns a string that handlers are supposed to emit after
  94:    * the last log record.  The base implementation returns an
  95:    * empty string, but subclasses such as {@link XMLFormatter}
  96:    * override this method in order to provide a suitable tail.
  97:    *
  98:    * @return a string for the header.
  99:    *
 100:    * @param handler the handler which will append the returned
 101:    *     string after the last log record.  This method
 102:    *     may inspect certain properties of the handler
 103:    *     in order to construct the tail.
 104:    */
 105:   public String getTail(Handler handler)
 106:   {
 107:     return "";
 108:   }
 109: 
 110: 
 111:   /**
 112:    * Formats the message part of a log record.
 113:    *
 114:    * <p>First, the Formatter localizes the record message to the
 115:    * default locale by looking up the message in the record's
 116:    * localization resource bundle.  If this step fails because there
 117:    * is no resource bundle associated with the record, or because the
 118:    * record message is not a key in the bundle, the raw message is
 119:    * used instead.
 120:    *
 121:    * <p>Second, the Formatter substitutes appropriate strings for
 122:    * the message parameters. If the record returns a non-empty
 123:    * array for <code>getParameters()</code> and the localized
 124:    * message string contains the character sequence "{0", the
 125:    * formatter uses <code>java.text.MessageFormat</code> to format
 126:    * the message.  Otherwise, no parameter substitution is performed.
 127:    *
 128:    * @param record the log record to be localized and formatted.
 129:    *
 130:    * @return the localized message text where parameters have been
 131:    *         substituted by suitable strings.
 132:    *
 133:    * @throws NullPointerException if <code>record</code>
 134:    *         is <code>null</code>.
 135:    */
 136:   public String formatMessage(LogRecord record)
 137:   {
 138:     String          msg;
 139:     ResourceBundle  bundle;
 140:     Object[]        params;
 141: 
 142:     /* This will throw a NullPointerExceptionif record is null. */
 143:     msg = record.getMessage();
 144:     if (msg == null)
 145:       msg = "";
 146: 
 147:     /* Try to localize the message. */
 148:     bundle = record.getResourceBundle();
 149:     if (bundle != null)
 150:     {
 151:       try
 152:       {
 153:     msg = bundle.getString(msg);
 154:       }
 155:       catch (java.util.MissingResourceException _)
 156:       {
 157:       }
 158:     }
 159: 
 160:     /* Format the message if there are parameters. */
 161:     params = record.getParameters();
 162:     if ((params != null)
 163:     && (params.length > 0)
 164:     && (msg.indexOf("{0") >= 0))
 165:     {
 166:       msg = MessageFormat.format(msg, params);
 167:     }
 168: 
 169:     return msg;
 170:   }
 171: }