Source for java.util.logging.Logger

   1: /* Logger.java -- a class for logging messages
   2:    Copyright (C) 2002, 2004, 2006, 2007 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.util.List;
  42: import java.util.MissingResourceException;
  43: import java.util.ResourceBundle;
  44: import java.security.AccessController;
  45: import java.security.PrivilegedAction;
  46: 
  47: /**
  48:  * A Logger is used for logging information about events. Usually, there
  49:  * is a seprate logger for each subsystem or component, although there
  50:  * is a shared instance for components that make only occasional use of
  51:  * the logging framework.
  52:  *
  53:  * <p>It is common to name a logger after the name of a corresponding
  54:  * Java package.  Loggers are organized into a hierarchical namespace;
  55:  * for example, the logger <code>"org.gnu.foo"</code> is the
  56:  * <em>parent</em> of logger <code>"org.gnu.foo.bar"</code>.
  57:  *
  58:  * <p>A logger for a named subsystem can be obtained through {@link
  59:  * java.util.logging.Logger#getLogger(java.lang.String)}.  However,
  60:  * only code which has been granted the permission to control the
  61:  * logging infrastructure will be allowed to customize that logger.
  62:  * Untrusted code can obtain a private, anonymous logger through
  63:  * {@link #getAnonymousLogger()} if it wants to perform any
  64:  * modifications to the logger.
  65:  *
  66:  * <p>FIXME: Write more documentation.
  67:  *
  68:  * @author Sascha Brawer (brawer@acm.org)
  69:  */
  70: public class Logger
  71: {
  72: 
  73:   static final Logger root = new Logger("", null);
  74: 
  75:   /**
  76:    * A logger provided to applications that make only occasional use
  77:    * of the logging framework, typically early prototypes.  Serious
  78:    * products are supposed to create and use their own Loggers, so
  79:    * they can be controlled individually.
  80:    */
  81:   public static final Logger global;
  82: 
  83:   static
  84:     {
  85:       // Our class might be initialized from an unprivileged context
  86:       global = (Logger) AccessController.doPrivileged
  87:     (new PrivilegedAction()
  88:       {
  89:         public Object run()
  90:         {
  91:           return getLogger("global");
  92:         }
  93:       });
  94:     }
  95: 
  96: 
  97:   /**
  98:    * The name of the Logger, or <code>null</code> if the logger is
  99:    * anonymous.
 100:    *
 101:    * <p>A previous version of the GNU Classpath implementation granted
 102:    * untrusted code the permission to control any logger whose name
 103:    * was null.  However, test code revealed that the Sun J2SE 1.4
 104:    * reference implementation enforces the security control for any
 105:    * logger that was not created through getAnonymousLogger, even if
 106:    * it has a null name.  Therefore, a separate flag {@link
 107:    * Logger#anonymous} was introduced.
 108:    */
 109:   private final String name;
 110: 
 111: 
 112:   /**
 113:    * The name of the resource bundle used for localization.
 114:    *
 115:    * <p>This variable cannot be declared as <code>final</code>
 116:    * because its value can change as a result of calling
 117:    * getLogger(String,String).
 118:    */
 119:   private String resourceBundleName;
 120: 
 121: 
 122:   /**
 123:    * The resource bundle used for localization.
 124:    *
 125:    * <p>This variable cannot be declared as <code>final</code>
 126:    * because its value can change as a result of calling
 127:    * getLogger(String,String).
 128:    */
 129:   private ResourceBundle resourceBundle;
 130: 
 131:   private Filter filter;
 132: 
 133:   private final List handlerList = new java.util.ArrayList(4);
 134:   private Handler[] handlers = new Handler[0];
 135: 
 136:   /**
 137:    * Indicates whether or not this logger is anonymous.  While
 138:    * a LoggingPermission is required for any modifications to
 139:    * a normal logger, untrusted code can obtain an anonymous logger
 140:    * and modify it according to its needs.
 141:    *
 142:    * <p>A previous version of the GNU Classpath implementation
 143:    * granted access to every logger whose name was null.
 144:    * However, test code revealed that the Sun J2SE 1.4 reference
 145:    * implementation enforces the security control for any logger
 146:    * that was not created through getAnonymousLogger, even
 147:    * if it has a null name.
 148:    */
 149:   private boolean anonymous;
 150: 
 151: 
 152:   private boolean useParentHandlers;
 153: 
 154:   private Level level;
 155: 
 156:   private Logger parent;
 157: 
 158:   /**
 159:    * Constructs a Logger for a subsystem.  Most applications do not
 160:    * need to create new Loggers explicitly; instead, they should call
 161:    * the static factory methods
 162:    * {@link #getLogger(java.lang.String,java.lang.String) getLogger}
 163:    * (with ResourceBundle for localization) or
 164:    * {@link #getLogger(java.lang.String) getLogger} (without
 165:    * ResourceBundle), respectively.
 166:    *
 167:    * @param name the name for the logger, for example "java.awt"
 168:    *             or "com.foo.bar". The name should be based on
 169:    *             the name of the package issuing log records
 170:    *             and consist of dot-separated Java identifiers.
 171:    *
 172:    * @param resourceBundleName the name of a resource bundle
 173:    *        for localizing messages, or <code>null</code>
 174:    *        to indicate that messages do not need to be localized.
 175:    *
 176:    * @throws java.util.MissingResourceException if
 177:    *         <code>resourceBundleName</code> is not <code>null</code>
 178:    *         and no such bundle could be located.
 179:    */
 180:   protected Logger(String name, String resourceBundleName)
 181:     throws MissingResourceException
 182:   {
 183:     this.name = name;
 184:     this.resourceBundleName = resourceBundleName;
 185: 
 186:     if (resourceBundleName == null)
 187:       resourceBundle = null;
 188:     else
 189:       resourceBundle = ResourceBundle.getBundle(resourceBundleName);
 190: 
 191:     level = null;
 192: 
 193:     /* This is null when the root logger is being constructed,
 194:      * and the root logger afterwards.
 195:      */
 196:     parent = root;
 197: 
 198:     useParentHandlers = (parent != null);
 199:   }
 200: 
 201: 
 202: 
 203:   /**
 204:    * Finds a registered logger for a subsystem, or creates one in
 205:    * case no logger has been registered yet.
 206:    *
 207:    * @param name the name for the logger, for example "java.awt"
 208:    *             or "com.foo.bar". The name should be based on
 209:    *             the name of the package issuing log records
 210:    *             and consist of dot-separated Java identifiers.
 211:    *
 212:    * @throws IllegalArgumentException if a logger for the subsystem
 213:    *         identified by <code>name</code> has already been created,
 214:    *         but uses a a resource bundle for localizing messages.
 215:    *
 216:    * @throws NullPointerException if <code>name</code> is
 217:    *         <code>null</code>.
 218:    *
 219:    * @return a logger for the subsystem specified by <code>name</code>
 220:    *         that does not localize messages.
 221:    */
 222:   public static Logger getLogger(String name)
 223:   {
 224:     return getLogger(name, null);
 225:   }
 226: 
 227:     
 228:   /**
 229:    * Finds a registered logger for a subsystem, or creates one in case
 230:    * no logger has been registered yet.
 231:    *
 232:    * <p>If a logger with the specified name has already been
 233:    * registered, the behavior depends on the resource bundle that is
 234:    * currently associated with the existing logger.
 235:    *
 236:    * <ul><li>If the existing logger uses the same resource bundle as
 237:    * specified by <code>resourceBundleName</code>, the existing logger
 238:    * is returned.</li>
 239:    *
 240:    * <li>If the existing logger currently does not localize messages,
 241:    * the existing logger is modified to use the bundle specified by
 242:    * <code>resourceBundleName</code>.  The existing logger is then
 243:    * returned.  Therefore, all subsystems currently using this logger
 244:    * will produce localized messages from now on.</li>
 245:    *
 246:    * <li>If the existing logger already has an associated resource
 247:    * bundle, but a different one than specified by
 248:    * <code>resourceBundleName</code>, an
 249:    * <code>IllegalArgumentException</code> is thrown.</li></ul>
 250:    *
 251:    * @param name the name for the logger, for example "java.awt"
 252:    *             or "org.gnu.foo". The name should be based on
 253:    *             the name of the package issuing log records
 254:    *             and consist of dot-separated Java identifiers.
 255:    *
 256:    * @param resourceBundleName the name of a resource bundle
 257:    *        for localizing messages, or <code>null</code>
 258:    *        to indicate that messages do not need to be localized.
 259:    *
 260:    * @return a logger for the subsystem specified by <code>name</code>.
 261:    *
 262:    * @throws java.util.MissingResourceException if
 263:    *         <code>resourceBundleName</code> is not <code>null</code>
 264:    *         and no such bundle could be located.   
 265:    *
 266:    * @throws IllegalArgumentException if a logger for the subsystem
 267:    *         identified by <code>name</code> has already been created,
 268:    *         but uses a different resource bundle for localizing
 269:    *         messages.
 270:    *
 271:    * @throws NullPointerException if <code>name</code> is
 272:    *         <code>null</code>.
 273:    */
 274:   public static Logger getLogger(String name, String resourceBundleName)
 275:   {
 276:     LogManager lm = LogManager.getLogManager();
 277:     Logger     result;
 278: 
 279:     if (name == null)
 280:       throw new NullPointerException();
 281: 
 282:     /* Without synchronized(lm), it could happen that another thread
 283:      * would create a logger between our calls to getLogger and
 284:      * addLogger.  While addLogger would indicate this by returning
 285:      * false, we could not be sure that this other logger was still
 286:      * existing when we called getLogger a second time in order
 287:      * to retrieve it -- note that LogManager is only allowed to
 288:      * keep weak references to registered loggers, so Loggers
 289:      * can be garbage collected at any time in general, and between
 290:      * our call to addLogger and our second call go getLogger
 291:      * in particular.
 292:      *
 293:      * Of course, we assume here that LogManager.addLogger etc.
 294:      * are synchronizing on the global LogManager object. There
 295:      * is a comment in the implementation of LogManager.addLogger
 296:      * referring to this comment here, so that any change in
 297:      * the synchronization of LogManager will be reflected here.
 298:      */
 299:     synchronized (lm)
 300:     {
 301:       result = lm.getLogger(name);
 302:       if (result == null)
 303:       {
 304:     boolean couldBeAdded;
 305: 
 306:     result = new Logger(name, resourceBundleName);
 307:     couldBeAdded = lm.addLogger(result);
 308:     if (!couldBeAdded)
 309:       throw new IllegalStateException("cannot register new logger");
 310:       }
 311:       else
 312:       {
 313:     /* The logger already exists. Make sure it uses
 314:      * the same resource bundle for localizing messages.
 315:      */
 316:     String existingBundleName = result.getResourceBundleName();
 317: 
 318:     /* The Sun J2SE 1.4 reference implementation will return the
 319:      * registered logger object, even if it does not have a resource
 320:      * bundle associated with it. However, it seems to change the
 321:      * resourceBundle of the registered logger to the bundle
 322:      * whose name was passed to getLogger.
 323:      */
 324:     if ((existingBundleName == null) && (resourceBundleName != null))
 325:     {
 326:       /* If ResourceBundle.getBundle throws an exception, the
 327:        * existing logger will be unchanged.  This would be
 328:        * different if the assignment to resourceBundleName
 329:        * came first.
 330:        */
 331:       result.resourceBundle = ResourceBundle.getBundle(resourceBundleName);
 332:       result.resourceBundleName = resourceBundleName;
 333:       return result;
 334:     }
 335: 
 336:     if ((existingBundleName != resourceBundleName)
 337:         && ((existingBundleName == null)
 338:         || !existingBundleName.equals(resourceBundleName)))
 339:     {
 340:       throw new IllegalArgumentException();
 341:     }
 342:       }
 343:     }
 344: 
 345:     return result;
 346:   }
 347: 
 348:   
 349:   /**
 350:    * Creates a new, unnamed logger.  Unnamed loggers are not
 351:    * registered in the namespace of the LogManager, and no special
 352:    * security permission is required for changing their state.
 353:    * Therefore, untrusted applets are able to modify their private
 354:    * logger instance obtained through this method.
 355:    *
 356:    * <p>The parent of the newly created logger will the the root
 357:    * logger, from which the level threshold and the handlers are
 358:    * inherited.
 359:    */
 360:   public static Logger getAnonymousLogger()
 361:   {
 362:     return getAnonymousLogger(null);
 363:   }
 364: 
 365: 
 366:   /**
 367:    * Creates a new, unnamed logger.  Unnamed loggers are not
 368:    * registered in the namespace of the LogManager, and no special
 369:    * security permission is required for changing their state.
 370:    * Therefore, untrusted applets are able to modify their private
 371:    * logger instance obtained through this method.
 372:    *
 373:    * <p>The parent of the newly created logger will the the root
 374:    * logger, from which the level threshold and the handlers are
 375:    * inherited.
 376:    *
 377:    * @param resourceBundleName the name of a resource bundle
 378:    *        for localizing messages, or <code>null</code>
 379:    *        to indicate that messages do not need to be localized.
 380:    *
 381:    * @throws java.util.MissingResourceException if
 382:    *         <code>resourceBundleName</code> is not <code>null</code>
 383:    *         and no such bundle could be located.
 384:    */
 385:   public static Logger getAnonymousLogger(String resourceBundleName)
 386:     throws MissingResourceException
 387:   {
 388:     Logger  result;
 389: 
 390:     result = new Logger(null, resourceBundleName);
 391:     result.anonymous = true;
 392:     return result;
 393:   }
 394: 
 395: 
 396:   /**
 397:    * Returns the name of the resource bundle that is being used for
 398:    * localizing messages.
 399:    *
 400:    * @return the name of the resource bundle used for localizing messages,
 401:    *         or <code>null</code> if the parent's resource bundle
 402:    *         is used for this purpose.
 403:    */
 404:   public synchronized String getResourceBundleName()
 405:   {
 406:     return resourceBundleName;
 407:   }
 408: 
 409: 
 410:   /**
 411:    * Returns the resource bundle that is being used for localizing
 412:    * messages.
 413:    *
 414:    * @return the resource bundle used for localizing messages,
 415:    *         or <code>null</code> if the parent's resource bundle
 416:    *         is used for this purpose.
 417:    */
 418:   public synchronized ResourceBundle getResourceBundle()
 419:   {
 420:     return resourceBundle;
 421:   }
 422: 
 423: 
 424:   /**
 425:    * Returns the severity level threshold for this <code>Handler</code>.
 426:    * All log records with a lower severity level will be discarded;
 427:    * a log record of the same or a higher level will be published
 428:    * unless an installed <code>Filter</code> decides to discard it.
 429:    *
 430:    * @return the severity level below which all log messages will be
 431:    *         discarded, or <code>null</code> if the logger inherits
 432:    *         the threshold from its parent.
 433:    */
 434:   public synchronized Level getLevel()
 435:   {
 436:     return level;
 437:   }
 438: 
 439: 
 440:   /**
 441:    * Returns whether or not a message of the specified level
 442:    * would be logged by this logger.
 443:    *
 444:    * @throws NullPointerException if <code>level</code>
 445:    *         is <code>null</code>.
 446:    */
 447:   public synchronized boolean isLoggable(Level level)
 448:   {
 449:     if (this.level != null)
 450:       return this.level.intValue() <= level.intValue();
 451: 
 452:     if (parent != null)
 453:       return parent.isLoggable(level);
 454:     else
 455:       return false;
 456:   }
 457: 
 458: 
 459:   /**
 460:    * Sets the severity level threshold for this <code>Handler</code>.
 461:    * All log records with a lower severity level will be discarded
 462:    * immediately.  A log record of the same or a higher level will be
 463:    * published unless an installed <code>Filter</code> decides to
 464:    * discard it.
 465:    *
 466:    * @param level the severity level below which all log messages
 467:    *              will be discarded, or <code>null</code> to
 468:    *              indicate that the logger should inherit the
 469:    *              threshold from its parent.
 470:    *
 471:    * @throws SecurityException if this logger is not anonymous, a
 472:    *     security manager exists, and the caller is not granted
 473:    *     the permission to control the logging infrastructure by
 474:    *     having LoggingPermission("control").  Untrusted code can
 475:    *     obtain an anonymous logger through the static factory method
 476:    *     {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
 477:    */
 478:   public synchronized void setLevel(Level level)
 479:   {
 480:     /* An application is allowed to control an anonymous logger
 481:      * without having the permission to control the logging
 482:      * infrastructure.
 483:      */
 484:     if (!anonymous)
 485:       LogManager.getLogManager().checkAccess();
 486: 
 487:     this.level = level;
 488:   }
 489: 
 490: 
 491:   public synchronized Filter getFilter()
 492:   {
 493:     return filter;
 494:   }
 495: 
 496: 
 497:   /**
 498:    * @throws SecurityException if this logger is not anonymous, a
 499:    *     security manager exists, and the caller is not granted
 500:    *     the permission to control the logging infrastructure by
 501:    *     having LoggingPermission("control").  Untrusted code can
 502:    *     obtain an anonymous logger through the static factory method
 503:    *     {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
 504:    */
 505:   public synchronized void setFilter(Filter filter)
 506:     throws SecurityException
 507:   {
 508:     /* An application is allowed to control an anonymous logger
 509:      * without having the permission to control the logging
 510:      * infrastructure.
 511:      */
 512:     if (!anonymous)
 513:       LogManager.getLogManager().checkAccess();
 514: 
 515:     this.filter = filter;
 516:   }
 517: 
 518: 
 519: 
 520: 
 521:   /**
 522:    * Returns the name of this logger.
 523:    *
 524:    * @return the name of this logger, or <code>null</code> if
 525:    *         the logger is anonymous.
 526:    */
 527:   public String getName()
 528:   {
 529:     /* Note that the name of a logger cannot be changed during
 530:      * its lifetime, so no synchronization is needed.
 531:      */
 532:     return name;
 533:   }
 534: 
 535: 
 536:   /**
 537:    * Passes a record to registered handlers, provided the record
 538:    * is considered as loggable both by {@link #isLoggable(Level)}
 539:    * and a possibly installed custom {@link #setFilter(Filter) filter}.
 540:    *
 541:    * <p>If the logger has been configured to use parent handlers,
 542:    * the record will be forwarded to the parent of this logger
 543:    * in addition to being processed by the handlers registered with
 544:    * this logger.
 545:    *
 546:    * <p>The other logging methods in this class are convenience methods
 547:    * that merely create a new LogRecord and pass it to this method.
 548:    * Therefore, subclasses usually just need to override this single
 549:    * method for customizing the logging behavior.
 550:    *
 551:    * @param record the log record to be inspected and possibly forwarded.
 552:    */
 553:   public synchronized void log(LogRecord record)
 554:   {
 555:     if (!isLoggable(record.getLevel()))
 556:       return;
 557: 
 558:     if ((filter != null) && !filter.isLoggable(record))
 559:       return;
 560: 
 561:     /* If no logger name has been set for the log record,
 562:      * use the name of this logger.
 563:      */
 564:     if (record.getLoggerName() == null)
 565:       record.setLoggerName(name);
 566: 
 567:     /* Avoid that some other thread is changing the logger hierarchy
 568:      * while we are traversing it.
 569:      */
 570:     synchronized (LogManager.getLogManager())
 571:     {
 572:       Logger curLogger = this;
 573: 
 574:       do
 575:       {
 576:         /* The Sun J2SE 1.4 reference implementation seems to call the
 577:      * filter only for the logger whose log method is called,
 578:      * never for any of its parents.  Also, parent loggers publish
 579:      * log record whatever their level might be.  This is pretty
 580:      * weird, but GNU Classpath tries to be as compatible as
 581:      * possible to the reference implementation.
 582:      */
 583:         for (int i = 0; i < curLogger.handlers.length; i++)
 584:           curLogger.handlers[i].publish(record);
 585: 
 586:     if (curLogger.getUseParentHandlers() == false)
 587:       break;
 588:     
 589:     curLogger = curLogger.getParent();
 590:       }
 591:       while (parent != null);
 592:     }
 593:   }
 594: 
 595: 
 596:   public void log(Level level, String message)
 597:   {
 598:     if (isLoggable(level))
 599:       log(level, message, (Object[]) null);
 600:   }
 601: 
 602: 
 603:   public synchronized void log(Level level,
 604:                    String message,
 605:                    Object param)
 606:   {
 607:     if (isLoggable(level))
 608:       {
 609:         StackTraceElement caller = getCallerStackFrame();
 610:         logp(level,
 611:              caller != null ? caller.getClassName() : "<unknown>",
 612:              caller != null ? caller.getMethodName() : "<unknown>",
 613:              message,
 614:              param);
 615:       }
 616:   }
 617: 
 618: 
 619:   public synchronized void log(Level level,
 620:                    String message,
 621:                    Object[] params)
 622:   {
 623:     if (isLoggable(level))
 624:       {
 625:         StackTraceElement caller = getCallerStackFrame();
 626:         logp(level,
 627:              caller != null ? caller.getClassName() : "<unknown>",
 628:              caller != null ? caller.getMethodName() : "<unknown>",
 629:              message,
 630:              params);
 631:       }
 632:   }
 633: 
 634: 
 635:   public synchronized void log(Level level,
 636:                    String message,
 637:                    Throwable thrown)
 638:   {
 639:     if (isLoggable(level))
 640:       {
 641:         StackTraceElement caller = getCallerStackFrame();    
 642:         logp(level,
 643:              caller != null ? caller.getClassName() : "<unknown>",
 644:              caller != null ? caller.getMethodName() : "<unknown>",
 645:              message,
 646:              thrown);
 647:       }
 648:   }
 649: 
 650: 
 651:   public synchronized void logp(Level level,
 652:                 String sourceClass,
 653:                 String sourceMethod,
 654:                 String message)
 655:   {
 656:     logp(level, sourceClass, sourceMethod, message,
 657:      (Object[]) null);
 658:   }
 659: 
 660: 
 661:   public synchronized void logp(Level level,
 662:                 String sourceClass,
 663:                 String sourceMethod,
 664:                 String message,
 665:                 Object param)
 666:   {
 667:     logp(level, sourceClass, sourceMethod, message,
 668:      new Object[] { param });
 669:   }
 670: 
 671: 
 672:   private synchronized ResourceBundle findResourceBundle()
 673:   {
 674:     if (resourceBundle != null)
 675:       return resourceBundle;
 676: 
 677:     if (parent != null)
 678:       return parent.findResourceBundle();
 679: 
 680:     return null;
 681:   }
 682: 
 683: 
 684:   private synchronized void logImpl(Level level,
 685:                     String sourceClass,
 686:                     String sourceMethod,
 687:                     String message,
 688:                     Object[] params)
 689:   {
 690:     LogRecord rec = new LogRecord(level, message);
 691: 
 692:     rec.setResourceBundle(findResourceBundle());
 693:     rec.setSourceClassName(sourceClass);
 694:     rec.setSourceMethodName(sourceMethod);
 695:     rec.setParameters(params);
 696: 
 697:     log(rec);
 698:   }
 699: 
 700: 
 701:   public synchronized void logp(Level level,
 702:                 String sourceClass,
 703:                 String sourceMethod,
 704:                 String message,
 705:                 Object[] params)
 706:   {
 707:     logImpl(level, sourceClass, sourceMethod, message, params);
 708:   }
 709: 
 710: 
 711:   public synchronized void logp(Level level,
 712:                 String sourceClass,
 713:                 String sourceMethod,
 714:                 String message,
 715:                 Throwable thrown)
 716:   {
 717:     LogRecord rec = new LogRecord(level, message);
 718: 
 719:     rec.setResourceBundle(resourceBundle);
 720:     rec.setSourceClassName(sourceClass);
 721:     rec.setSourceMethodName(sourceMethod);
 722:     rec.setThrown(thrown);
 723: 
 724:     log(rec);
 725:   }
 726: 
 727: 
 728:   public synchronized void logrb(Level level,
 729:                  String sourceClass,
 730:                  String sourceMethod,
 731:                  String bundleName,
 732:                  String message)
 733:   {
 734:     logrb(level, sourceClass, sourceMethod, bundleName,
 735:       message, (Object[]) null);
 736:   }
 737: 
 738: 
 739:   public synchronized void logrb(Level level,
 740:                  String sourceClass,
 741:                  String sourceMethod,
 742:                  String bundleName,
 743:                  String message,
 744:                  Object param)
 745:   {
 746:     logrb(level, sourceClass, sourceMethod, bundleName,
 747:       message, new Object[] { param });
 748:   }
 749: 
 750: 
 751:   public synchronized void logrb(Level level,
 752:                  String sourceClass,
 753:                  String sourceMethod,
 754:                  String bundleName,
 755:                  String message,
 756:                  Object[] params)
 757:   {
 758:     LogRecord rec = new LogRecord(level, message);
 759: 
 760:     rec.setResourceBundleName(bundleName);
 761:     rec.setSourceClassName(sourceClass);
 762:     rec.setSourceMethodName(sourceMethod);
 763:     rec.setParameters(params);
 764: 
 765:     log(rec);
 766:   }
 767: 
 768: 
 769:   public synchronized void logrb(Level level,
 770:                  String sourceClass,
 771:                  String sourceMethod,
 772:                  String bundleName,
 773:                  String message,
 774:                  Throwable thrown)
 775:   {
 776:     LogRecord rec = new LogRecord(level, message);
 777: 
 778:     rec.setResourceBundleName(bundleName);
 779:     rec.setSourceClassName(sourceClass);
 780:     rec.setSourceMethodName(sourceMethod);
 781:     rec.setThrown(thrown);
 782: 
 783:     log(rec);
 784:   }
 785: 
 786: 
 787:   public synchronized void entering(String sourceClass,
 788:                     String sourceMethod)
 789:   {
 790:     if (isLoggable(Level.FINER))
 791:       logp(Level.FINER, sourceClass, sourceMethod, "ENTRY");
 792:   }
 793: 
 794: 
 795:   public synchronized void entering(String sourceClass,
 796:                     String sourceMethod,
 797:                     Object param)
 798:   {
 799:     if (isLoggable(Level.FINER))
 800:       logp(Level.FINER, sourceClass, sourceMethod, "ENTRY {0}", param);
 801:   }
 802: 
 803: 
 804:   public synchronized void entering(String sourceClass,
 805:                     String sourceMethod,
 806:                     Object[] params)
 807:   {
 808:     if (isLoggable(Level.FINER))
 809:     {
 810:       StringBuffer buf = new StringBuffer(80);
 811:       buf.append("ENTRY");
 812:       for (int i = 0; i < params.length; i++)
 813:       {
 814:     buf.append(" {");
 815:     buf.append(i);
 816:     buf.append('}');
 817:       }
 818:       
 819:       logp(Level.FINER, sourceClass, sourceMethod, buf.toString(), params);
 820:     }
 821:   }
 822: 
 823: 
 824:   public synchronized void exiting(String sourceClass,
 825:                    String sourceMethod)
 826:   {
 827:     if (isLoggable(Level.FINER))
 828:       logp(Level.FINER, sourceClass, sourceMethod, "RETURN");
 829:   }
 830: 
 831:    
 832:   public synchronized void exiting(String sourceClass,
 833:                    String sourceMethod,
 834:                    Object result)
 835:   {
 836:     if (isLoggable(Level.FINER))
 837:       logp(Level.FINER, sourceClass, sourceMethod, "RETURN {0}", result);
 838:   }
 839: 
 840:  
 841:   public synchronized void throwing(String sourceClass,
 842:                     String sourceMethod,
 843:                     Throwable thrown)
 844:   {
 845:     if (isLoggable(Level.FINER))
 846:       logp(Level.FINER, sourceClass, sourceMethod, "THROW", thrown);
 847:   }
 848: 
 849: 
 850:   /**
 851:    * Logs a message with severity level SEVERE, indicating a serious
 852:    * failure that prevents normal program execution.  Messages at this
 853:    * level should be understandable to an inexperienced, non-technical
 854:    * end user.  Ideally, they explain in simple words what actions the
 855:    * user can take in order to resolve the problem.
 856:    *
 857:    * @see Level#SEVERE
 858:    *
 859:    * @param message the message text, also used as look-up key if the
 860:    *                logger is localizing messages with a resource
 861:    *                bundle.  While it is possible to pass
 862:    *                <code>null</code>, this is not recommended, since
 863:    *                a logging message without text is unlikely to be
 864:    *                helpful.
 865:    */
 866:   public synchronized void severe(String message)
 867:   {
 868:     if (isLoggable(Level.SEVERE))
 869:       log(Level.SEVERE, message);
 870:   }
 871: 
 872: 
 873:   /**
 874:    * Logs a message with severity level WARNING, indicating a
 875:    * potential problem that does not prevent normal program execution.
 876:    * Messages at this level should be understandable to an
 877:    * inexperienced, non-technical end user.  Ideally, they explain in
 878:    * simple words what actions the user can take in order to resolve
 879:    * the problem.
 880:    *
 881:    * @see Level#WARNING
 882:    *
 883:    * @param message the message text, also used as look-up key if the
 884:    *                logger is localizing messages with a resource
 885:    *                bundle.  While it is possible to pass
 886:    *                <code>null</code>, this is not recommended, since
 887:    *                a logging message without text is unlikely to be
 888:    *                helpful.
 889:    */
 890:   public synchronized void warning(String message)
 891:   {
 892:     if (isLoggable(Level.WARNING))
 893:       log(Level.WARNING, message);
 894:   }
 895: 
 896: 
 897:   /**
 898:    * Logs a message with severity level INFO.  {@link Level#INFO} is
 899:    * intended for purely informational messages that do not indicate
 900:    * error or warning situations. In the default logging
 901:    * configuration, INFO messages will be written to the system
 902:    * console.  For this reason, the INFO level should be used only for
 903:    * messages that are important to end users and system
 904:    * administrators.  Messages at this level should be understandable
 905:    * to an inexperienced, non-technical user.
 906:    *
 907:    * @param message the message text, also used as look-up key if the
 908:    *                logger is localizing messages with a resource
 909:    *                bundle.  While it is possible to pass
 910:    *                <code>null</code>, this is not recommended, since
 911:    *                a logging message without text is unlikely to be
 912:    *                helpful.
 913:    */
 914:   public synchronized void info(String message)
 915:   {
 916:     if (isLoggable(Level.INFO))
 917:       log(Level.INFO, message);
 918:   }
 919: 
 920: 
 921:   /**
 922:    * Logs a message with severity level CONFIG.  {@link Level#CONFIG} is
 923:    * intended for static configuration messages, for example about the
 924:    * windowing environment, the operating system version, etc.
 925:    *
 926:    * @param message the message text, also used as look-up key if the
 927:    *     logger is localizing messages with a resource bundle.  While
 928:    *     it is possible to pass <code>null</code>, this is not
 929:    *     recommended, since a logging message without text is unlikely
 930:    *     to be helpful.
 931:    */
 932:   public synchronized void config(String message)
 933:   {
 934:     if (isLoggable(Level.CONFIG))
 935:       log(Level.CONFIG, message);
 936:   }
 937: 
 938: 
 939:   /**
 940:    * Logs a message with severity level FINE.  {@link Level#FINE} is
 941:    * intended for messages that are relevant for developers using
 942:    * the component generating log messages. Examples include minor,
 943:    * recoverable failures, or possible inefficiencies.
 944:    *
 945:    * @param message the message text, also used as look-up key if the
 946:    *                logger is localizing messages with a resource
 947:    *                bundle.  While it is possible to pass
 948:    *                <code>null</code>, this is not recommended, since
 949:    *                a logging message without text is unlikely to be
 950:    *                helpful.
 951:    */
 952:   public synchronized void fine(String message)
 953:   {
 954:     if (isLoggable(Level.FINE))
 955:       log(Level.FINE, message);
 956:   }
 957: 
 958: 
 959:   /**
 960:    * Logs a message with severity level FINER.  {@link Level#FINER} is
 961:    * intended for rather detailed tracing, for example entering a
 962:    * method, returning from a method, or throwing an exception.
 963:    *
 964:    * @param message the message text, also used as look-up key if the
 965:    *                logger is localizing messages with a resource
 966:    *                bundle.  While it is possible to pass
 967:    *                <code>null</code>, this is not recommended, since
 968:    *                a logging message without text is unlikely to be
 969:    *                helpful.
 970:    */
 971:   public synchronized void finer(String message)
 972:   {
 973:     if (isLoggable(Level.FINER))
 974:       log(Level.FINER, message);
 975:   }
 976: 
 977: 
 978:   /**
 979:    * Logs a message with severity level FINEST.  {@link Level#FINEST}
 980:    * is intended for highly detailed tracing, for example reaching a
 981:    * certain point inside the body of a method.
 982:    *
 983:    * @param message the message text, also used as look-up key if the
 984:    *                logger is localizing messages with a resource
 985:    *                bundle.  While it is possible to pass
 986:    *                <code>null</code>, this is not recommended, since
 987:    *                a logging message without text is unlikely to be
 988:    *                helpful.
 989:    */
 990:   public synchronized void finest(String message)
 991:   {
 992:     if (isLoggable(Level.FINEST))
 993:       log(Level.FINEST, message);
 994:   }
 995: 
 996: 
 997:   /**
 998:    * Adds a handler to the set of handlers that get notified
 999:    * when a log record is to be published.
1000:    *
1001:    * @param handler the handler to be added.
1002:    *
1003:    * @throws NullPointerException if <code>handler</code>
1004:    *     is <code>null</code>.
1005:    *
1006:    * @throws SecurityException if this logger is not anonymous, a
1007:    *     security manager exists, and the caller is not granted
1008:    *     the permission to control the logging infrastructure by
1009:    *     having LoggingPermission("control").  Untrusted code can
1010:    *     obtain an anonymous logger through the static factory method
1011:    *     {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
1012:    */
1013:   public synchronized void addHandler(Handler handler)
1014:     throws SecurityException
1015:   {
1016:     if (handler == null)
1017:       throw new NullPointerException();
1018: 
1019:     /* An application is allowed to control an anonymous logger
1020:      * without having the permission to control the logging
1021:      * infrastructure.
1022:      */
1023:     if (!anonymous)
1024:       LogManager.getLogManager().checkAccess();
1025: 
1026:     if (!handlerList.contains(handler))
1027:     {
1028:       handlerList.add(handler);
1029:       handlers = getHandlers();
1030:     }
1031:   }
1032: 
1033: 
1034:   /**
1035:    * Removes a handler from the set of handlers that get notified
1036:    * when a log record is to be published.
1037:    *
1038:    * @param handler the handler to be removed.
1039:    *
1040:    * @throws SecurityException if this logger is not anonymous, a
1041:    *     security manager exists, and the caller is not granted the
1042:    *     permission to control the logging infrastructure by having
1043:    *     LoggingPermission("control").  Untrusted code can obtain an
1044:    *     anonymous logger through the static factory method {@link
1045:    *     #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
1046:    *
1047:    * @throws NullPointerException if <code>handler</code>
1048:    *     is <code>null</code>.
1049:    */
1050:   public synchronized void removeHandler(Handler handler)
1051:     throws SecurityException
1052:   {
1053:     /* An application is allowed to control an anonymous logger
1054:      * without having the permission to control the logging
1055:      * infrastructure.
1056:      */
1057:     if (!anonymous)
1058:       LogManager.getLogManager().checkAccess();
1059: 
1060:     if (handler == null)
1061:       throw new NullPointerException();
1062: 
1063:     handlerList.remove(handler);
1064:     handlers = getHandlers();
1065:   }
1066: 
1067: 
1068:   /**
1069:    * Returns the handlers currently registered for this Logger.
1070:    * When a log record has been deemed as being loggable,
1071:    * it will be passed to all registered handlers for
1072:    * publication.  In addition, if the logger uses parent handlers
1073:    * (see {@link #getUseParentHandlers() getUseParentHandlers}
1074:    * and {@link #setUseParentHandlers(boolean) setUseParentHandlers},
1075:    * the log record will be passed to the parent's handlers.
1076:    */
1077:   public synchronized Handler[] getHandlers()
1078:   {
1079:     /* We cannot return our internal handlers array
1080:      * because we do not have any guarantee that the
1081:      * caller would not change the array entries.
1082:      */
1083:     return (Handler[]) handlerList.toArray(new Handler[handlerList.size()]);
1084:   }
1085: 
1086: 
1087:   /**
1088:    * Returns whether or not this Logger forwards log records to
1089:    * handlers registered for its parent loggers.
1090:    *
1091:    * @return <code>false</code> if this Logger sends log records
1092:    *         merely to Handlers registered with itself;
1093:    *         <code>true</code> if this Logger sends log records
1094:    *         not only to Handlers registered with itself, but also
1095:    *         to those Handlers registered with parent loggers.
1096:    */
1097:   public synchronized boolean getUseParentHandlers()
1098:   {
1099:     return useParentHandlers;
1100:   }
1101: 
1102: 
1103:   /**
1104:    * Sets whether or not this Logger forwards log records to
1105:    * handlers registered for its parent loggers.
1106:    *
1107:    * @param useParentHandlers <code>false</code> to let this
1108:    *         Logger send log records merely to Handlers registered
1109:    *         with itself; <code>true</code> to let this Logger
1110:    *         send log records not only to Handlers registered
1111:    *         with itself, but also to those Handlers registered with
1112:    *         parent loggers.
1113:    *
1114:    * @throws SecurityException if this logger is not anonymous, a
1115:    *     security manager exists, and the caller is not granted
1116:    *     the permission to control the logging infrastructure by
1117:    *     having LoggingPermission("control").  Untrusted code can
1118:    *     obtain an anonymous logger through the static factory method
1119:    *     {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
1120:    *
1121:    */
1122:   public synchronized void setUseParentHandlers(boolean useParentHandlers)
1123:   {
1124:     /* An application is allowed to control an anonymous logger
1125:      * without having the permission to control the logging
1126:      * infrastructure.
1127:      */
1128:     if (!anonymous)
1129:       LogManager.getLogManager().checkAccess();
1130: 
1131:     this.useParentHandlers = useParentHandlers;
1132:   }
1133: 
1134: 
1135:   /**
1136:    * Returns the parent of this logger.  By default, the parent is
1137:    * assigned by the LogManager by inspecting the logger's name.
1138:    *
1139:    * @return the parent of this logger (as detemined by the LogManager
1140:    *     by inspecting logger names), the root logger if no other
1141:    *     logger has a name which is a prefix of this logger's name, or
1142:    *     <code>null</code> for the root logger.
1143:    */
1144:   public synchronized Logger getParent()
1145:   {
1146:     return parent;
1147:   }
1148: 
1149: 
1150:   /**
1151:    * Sets the parent of this logger.  Usually, applications do not
1152:    * call this method directly.  Instead, the LogManager will ensure
1153:    * that the tree of loggers reflects the hierarchical logger
1154:    * namespace.  Basically, this method should not be public at all,
1155:    * but the GNU implementation follows the API specification.
1156:    *
1157:    * @throws NullPointerException if <code>parent</code> is
1158:    *     <code>null</code>.
1159:    *
1160:    * @throws SecurityException if this logger is not anonymous, a
1161:    *     security manager exists, and the caller is not granted
1162:    *     the permission to control the logging infrastructure by
1163:    *     having LoggingPermission("control").  Untrusted code can
1164:    *     obtain an anonymous logger through the static factory method
1165:    *     {@link #getAnonymousLogger(java.lang.String) getAnonymousLogger}.
1166:    */
1167:   public synchronized void setParent(Logger parent)
1168:   {
1169:     if (parent == null)
1170:       throw new NullPointerException();
1171: 
1172:     if (this == root)
1173:         throw new IllegalArgumentException(
1174:           "the root logger can only have a null parent");
1175: 
1176:     /* An application is allowed to control an anonymous logger
1177:      * without having the permission to control the logging
1178:      * infrastructure.
1179:      */
1180:     if (!anonymous)
1181:       LogManager.getLogManager().checkAccess();
1182: 
1183:     this.parent = parent;
1184:   }
1185:   
1186:   /**
1187:    * Gets the StackTraceElement of the first class that is not this class.
1188:    * That should be the initial caller of a logging method.
1189:    * @return caller of the initial logging method or null if unknown.
1190:    */
1191:   private native StackTraceElement getCallerStackFrame();
1192:   
1193:   /**
1194:    * Reset and close handlers attached to this logger. This function is package
1195:    * private because it must only be avaiable to the LogManager.
1196:    */
1197:   void resetLogger()
1198:   {
1199:     for (int i = 0; i < handlers.length; i++)
1200:       {
1201:         handlers[i].close();
1202:         handlerList.remove(handlers[i]);
1203:       }
1204:     handlers = getHandlers();
1205:   }
1206: }