libjava/java/util/logging/Handler.java

   1 /* Handler.java -- a class for publishing log messages
   2    Copyright (C) 2002, 2004 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.util.logging;
  40
  41 import java.io.UnsupportedEncodingException;
  42
  43 /**
  44  * A <code>Handler</code> publishes <code>LogRecords</code> to
  45  * a sink, for example a file, the console or a network socket.
  46  * There are different subclasses of <code>Handler</code>
  47  * to deal with different kinds of sinks.
  48  *
  49  * <p>FIXME: Are handlers thread-safe, or is the assumption that only
  50  * loggers are, and a handler can belong only to one single logger? If
  51  * the latter, should we enforce it? (Spec not clear). In any
  52  * case, it needs documentation.
  53  *
  54  * @author Sascha Brawer (brawer@acm.org)
  55  */
  56 public abstract class Handler
  57 {
  58   Formatter     formatter;
  59   Filter        filter;
  60   Level         level;
  61   ErrorManager  errorManager;
  62   String        encoding;
  63
  64   /**
  65    * Constructs a Handler with a logging severity level of
  66    * <code>Level.ALL</code>, no formatter, no filter, and
  67    * an instance of <code>ErrorManager</code> managing errors.
  68    *
  69    * <p><strong>Specification Note:</strong> The specification of the
  70    * Java<sup>TM</sup> Logging API does not mention which character
  71    * encoding is to be used by freshly constructed Handlers.  The GNU
  72    * implementation uses the default platform encoding, but other
  73    * Java implementations might behave differently.
  74    *
  75    * <p><strong>Specification Note:</strong> While a freshly constructed
  76    * Handler is required to have <em>no filter</em> according to the
  77    * specification, <code>null</code> is not a valid parameter for
  78    * <code>Handler.setFormatter</code>.  Therefore, the following
  79    * code will throw a <code>java.lang.NullPointerException</code>:
  80    *
  81    * <p><pre>Handler h = new MyConcreteSubclassOfHandler();
  82 h.setFormatter(h.getFormatter());</pre>
  83    *
  84    * It seems strange that a freshly constructed Handler is not
  85    * supposed to provide a Formatter, but this is what the specification
  86    * says.
  87    */
  88   protected Handler()
  89   {
  90     level = Level.ALL;
  91   }
  92
  93
  94   /**
  95    * Publishes a <code>LogRecord</code> to an appropriate sink,
  96    * provided the record passes all tests for being loggable.  The
  97    * <code>Handler</code> will localize the message of the log
  98    * record and substitute any message parameters.
  99    *
 100    * <p>Most applications do not need to call this method directly.
 101    * Instead, they will use use a {@link Logger}, which will
 102    * create LogRecords and distribute them to registered handlers.
 103    *
 104    * <p>In case of an I/O failure, the <code>ErrorManager</code>
 105    * of this <code>Handler</code> will be informed, but the caller
 106    * of this method will not receive an exception.
 107    *
 108    * @param record the log event to be published.
 109    */
 110   public abstract void publish(LogRecord record);
 111
 112
 113   /**
 114    * Forces any data that may have been buffered to the underlying
 115    * output device.
 116    *
 117    * <p>In case of an I/O failure, the <code>ErrorManager</code>
 118    * of this <code>Handler</code> will be informed, but the caller
 119    * of this method will not receive an exception.
 120    */
 121   public abstract void flush();
 122
 123
 124   /**
 125    * Closes this <code>Handler</code> after having flushed
 126    * the buffers.  As soon as <code>close</code> has been called,
 127    * a <code>Handler</code> should not be used anymore. Attempts
 128    * to publish log records, to flush buffers, or to modify the
 129    * <code>Handler</code> in any other way may throw runtime
 130    * exceptions after calling <code>close</code>.
 131    *
 132    * <p>In case of an I/O failure, the <code>ErrorManager</code>
 133    * of this <code>Handler</code> will be informed, but the caller
 134    * of this method will not receive an exception.
 135    *
 136    * @throws SecurityException if a security manager exists and
 137    *         the caller is not granted the permission to control
 138    *         the logging infrastructure.
 139    */
 140   public abstract void close()
 141     throws SecurityException;
 142
 143
 144   /**
 145    * Returns the <code>Formatter</code> which will be used to
 146    * localize the text of log messages and to substitute
 147    * message parameters.  A <code>Handler</code> is encouraged,
 148    * but not required to actually use an assigned
 149    * <code>Formatter</code>.
 150    *
 151    * @return the <code>Formatter</code> being used, or
 152    *         <code>null</code> if this <code>Handler</code>
 153    *         does not use formatters and no formatter has
 154    *         ever been set by calling <code>setFormatter</code>.
 155    */
 156   public Formatter getFormatter()
 157   {
 158     return formatter;
 159   }
 160
 161
 162   /**
 163    * Sets the <code>Formatter</code> which will be used to
 164    * localize the text of log messages and to substitute
 165    * message parameters.  A <code>Handler</code> is encouraged,
 166    * but not required to actually use an assigned
 167    * <code>Formatter</code>.
 168    *
 169    * @param formatter the new <code>Formatter</code> to use.
 170    *
 171    * @throws SecurityException if a security manager exists and
 172    *         the caller is not granted the permission to control
 173    *         the logging infrastructure.
 174    *
 175    * @throws NullPointerException if <code>formatter</code> is
 176    *         <code>null</code>.
 177    */
 178   public void setFormatter(Formatter formatter)
 179     throws SecurityException
 180   {
 181     LogManager.getLogManager().checkAccess();
 182
 183     /* Throws a NullPointerException if formatter is null. */
 184     formatter.getClass();
 185
 186     this.formatter = formatter;
 187   }
 188
 189
 190   /**
 191    * Returns the character encoding which this handler uses for publishing
 192    * log records.
 193    *
 194    * @param encoding the name of a character encoding, or <code>null</code>
 195    *            for the default platform encoding.
 196    */
 197   public String getEncoding()
 198   {
 199     return encoding;
 200   }
 201
 202
 203   /**
 204    * Sets the character encoding which this handler uses for publishing
 205    * log records.  The encoding of a <code>Handler</code> must be
 206    * set before any log records have been published.
 207    *
 208    * @param encoding the name of a character encoding, or <code>null</code>
 209    *            for the default encoding.
 210    *
 211    * @exception SecurityException if a security manager exists and
 212    *            the caller is not granted the permission to control
 213    *            the logging infrastructure.
 214    *
 215    */
 216   public void setEncoding(String encoding)
 217     throws SecurityException, UnsupportedEncodingException
 218   {
 219     /* Should any developer ever change this implementation, they are
 220      * advised to have a look at StreamHandler.setEncoding(String),
 221      * which overrides this method without calling super.setEncoding.
 222      */
 223     LogManager.getLogManager().checkAccess();
 224
 225     /* Simple check for supported encodings. This is more expensive
 226      * than it could be, but this method is overwritten by StreamHandler
 227      * anyway.
 228      */
 229     if (encoding != null)
 230       new String(new byte[0], encoding);
 231
 232     this.encoding = encoding;
 233   }
 234
 235
 236   /**
 237    * Returns the <code>Filter</code> that currently controls which
 238    * log records are being published by this <code>Handler</code>.
 239    *
 240    * @return the currently active <code>Filter</code>, or
 241    *         <code>null</code> if no filter has been associated.
 242    *         In the latter case, log records are filtered purely
 243    *         based on their severity level.
 244    */
 245   public Filter getFilter()
 246   {
 247     return filter;
 248   }
 249
 250
 251   /**
 252    * Sets the <code>Filter</code> for controlling which
 253    * log records will be published by this <code>Handler</code>.
 254    *
 255    * @return the <code>Filter</code> to use, or
 256    *         <code>null</code> to filter log records purely based
 257    *         on their severity level.
 258    */
 259   public void setFilter(Filter filter)
 260     throws SecurityException
 261   {
 262     LogManager.getLogManager().checkAccess();
 263     this.filter = filter;
 264   }
 265
 266
 267   /**
 268    * Returns the <code>ErrorManager</code> that currently deals
 269    * with errors originating from this Handler.
 270    *
 271    * @exception SecurityException if a security manager exists and
 272    *            the caller is not granted the permission to control
 273    *            the logging infrastructure.
 274    */
 275   public ErrorManager getErrorManager()
 276   {
 277     LogManager.getLogManager().checkAccess();
 278
 279     /* Developers wanting to change the subsequent code should
 280      * have a look at Handler.reportError -- it also can create
 281      * an ErrorManager, but does so without checking permissions
 282      * to control the logging infrastructure.
 283      */
 284     if (errorManager == null)
 285       errorManager = new ErrorManager();
 286
 287     return errorManager;
 288   }
 289
 290
 291   public void setErrorManager(ErrorManager manager)
 292   {
 293     LogManager.getLogManager().checkAccess();
 294
 295     /* Make sure manager is not null. */
 296     manager.getClass();
 297
 298     this.errorManager = manager;
 299   }
 300
 301
 302   protected void reportError(String message, Exception ex, int code)
 303   {
 304     if (errorManager == null)
 305       errorManager = new ErrorManager();
 306
 307     errorManager.error(message, ex, code);
 308   }
 309
 310
 311   /**
 312    * Returns the severity level threshold for this <code>Handler</code>
 313    * All log records with a lower severity level will be discarded;
 314    * a log record of the same or a higher level will be published
 315    * unless an installed <code>Filter</code> decides to discard it.
 316    *
 317    * @return the severity level below which all log messages
 318    *         will be discarded.
 319    */
 320   public Level getLevel()
 321   {
 322     return level;
 323   }
 324
 325
 326   /**
 327    * Sets the severity level threshold for this <code>Handler</code>.
 328    * All log records with a lower severity level will be discarded;
 329    * a log record of the same or a higher level will be published
 330    * unless an installed <code>Filter</code> decides to discard it.
 331    *
 332    * @param level the severity level below which all log messages
 333    *              will be discarded.
 334    *
 335    * @exception SecurityException if a security manager exists and
 336    *            the caller is not granted the permission to control
 337    *            the logging infrastructure.
 338    *
 339    * @exception NullPointerException if <code>level</code> is
 340    *            <code>null</code>.
 341    */
 342   public void setLevel(Level level)
 343   {
 344     LogManager.getLogManager().checkAccess();
 345
 346     /* Throw NullPointerException if level is null.  */
 347     level.getClass();
 348     this.level = level;
 349   }
 350
 351
 352   /**
 353    * Checks whether a <code>LogRecord</code> would be logged
 354    * if it was passed to this <code>Handler</code> for publication.
 355    *
 356    * <p>The <code>Handler</code> implementation considers a record as
 357    * loggable if its level is greater than or equal to the severity
 358    * level threshold.  In a second step, if a {@link Filter} has
 359    * been installed, its {@link Filter#isLoggable(LogRecord) isLoggable}
 360    * method is invoked. Subclasses of <code>Handler</code> can override
 361    * this method to impose their own constraints.
 362    *
 363    * @param record the <code>LogRecord</code> to be checked.
 364    *
 365    * @return <code>true</code> if <code>record</code> would
 366    *         be published by {@link #publish(LogRecord) publish},
 367    *         <code>false</code> if it would be discarded.
 368    *
 369    * @see #setLevel(Level)
 370    * @see #setFilter(Filter)
 371    * @see Filter#isLoggable(LogRecord)
 372    *
 373    * @throws NullPointerException if <code>record</code>
 374    *         is <code>null</code>.
 375    */
 376   public boolean isLoggable(LogRecord record)
 377   {
 378     if (record.getLevel().intValue() < level.intValue())
 379       return false;
 380
 381     if (filter != null)
 382       return filter.isLoggable(record);
 383     else
 384       return true;
 385   }
 386 }