libjava/java/util/logging/Handler.java

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