Source for java.util.logging.Handler

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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:    * @return 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:    * @param filter 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: }