libjava/classpath/java/util/logging/LogRecord.java

   1 /* LogRecord.java --
   2    A class for the state associated with individual logging events
   3    Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
   4
   5 This file is part of GNU Classpath.
   6
   7 GNU Classpath is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Classpath is distributed in the hope that it will be useful, but
  13 WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Classpath; see the file COPYING.  If not, write to the
  19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20 02110-1301 USA.
  21
  22 Linking this library statically or dynamically with other modules is
  23 making a combined work based on this library.  Thus, the terms and
  24 conditions of the GNU General Public License cover the whole
  25 combination.
  26
  27 As a special exception, the copyright holders of this library give you
  28 permission to link this library with independent modules to produce an
  29 executable, regardless of the license terms of these independent
  30 modules, and to copy and distribute the resulting executable under
  31 terms of your choice, provided that you also meet, for each linked
  32 independent module, the terms and conditions of the license of that
  33 module.  An independent module is a module which is not derived from
  34 or based on this library.  If you modify this library, you may extend
  35 this exception to your version of the library, but you are not
  36 obligated to do so.  If you do not wish to do so, delete this
  37 exception statement from your version. */
  38
  39
  40 package java.util.logging;
  41
  42 import java.util.ResourceBundle;
  43
  44
  45 /**
  46  * A <code>LogRecord</code> contains the state for an individual
  47  * event to be logged.
  48  *
  49  * <p>As soon as a LogRecord instance has been handed over to the
  50  * logging framework, applications should not manipulate it anymore.
  51  *
  52  * @author Sascha Brawer (brawer@acm.org)
  53  */
  54 public class LogRecord
  55   implements java.io.Serializable
  56 {
  57   /**
  58    * The severity level of this <code>LogRecord</code>.
  59    */
  60   private Level      level;
  61
  62
  63   /**
  64    * The sequence number of this <code>LogRecord</code>.
  65    */
  66   private long       sequenceNumber;
  67
  68
  69   /**
  70    * The name of the class that issued the logging request, or
  71    * <code>null</code> if this information could not be obtained.
  72    */
  73   private String     sourceClassName;
  74
  75
  76   /**
  77    * The name of the method that issued the logging request, or
  78    * <code>null</code> if this information could not be obtained.
  79    */
  80   private String sourceMethodName;
  81
  82
  83   /**
  84    * The message for this <code>LogRecord</code> before
  85    * any localization or formatting.
  86    */
  87   private String message;
  88
  89
  90   /**
  91    * An identifier for the thread in which this <code>LogRecord</code>
  92    * was created.  The identifier is not necessarily related to any
  93    * thread identifiers used by the operating system.
  94    */
  95   private int threadID;
  96
  97
  98   /**
  99    * The time when this <code>LogRecord</code> was created,
 100    * in milliseconds since the beginning of January 1, 1970.
 101    */
 102   private long millis;
 103
 104
 105   /**
 106    * The Throwable associated with this <code>LogRecord</code>, or
 107    * <code>null</code> if the logged event is not related to an
 108    * exception or error.
 109    */
 110   private Throwable thrown;
 111
 112
 113   /**
 114    * The name of the logger where this <code>LogRecord</code> has
 115    * originated, or <code>null</code> if this <code>LogRecord</code>
 116    * does not originate from a <code>Logger</code>.
 117    */
 118   private String  loggerName;
 119
 120
 121   /**
 122    * The name of the resource bundle used for localizing log messages,
 123    * or <code>null</code> if no bundle has been specified.
 124    */
 125   private String resourceBundleName;
 126
 127   private transient Object[] parameters;
 128
 129   private transient ResourceBundle bundle;
 130
 131
 132   /**
 133    * Constructs a <code>LogRecord</code> given a severity level and
 134    * an unlocalized message text.  In addition, the sequence number,
 135    * creation time (as returned by <code>getMillis()</code>) and
 136    * thread ID are assigned. All other properties are set to
 137    * <code>null</code>.
 138    *
 139    * @param level the severity level, for example <code>Level.WARNING</code>.
 140    *
 141    * @param message the message text (which will be used as key
 142    *                for looking up the localized message text
 143    *                if a resource bundle has been associated).
 144    */
 145   public LogRecord(Level level, String message)
 146   {
 147     this.level = level;
 148     this.message = message;
 149     this.millis = System.currentTimeMillis();
 150
 151     /* A subclass of java.lang.Thread could override hashCode(),
 152      * in which case the result would not be guaranteed anymore
 153      * to be unique among all threads.  While System.identityHashCode
 154      * is not necessarily unique either, it at least cannot be
 155      * overridden by user code.  However, is might be a good idea
 156      * to use something better for generating thread IDs.
 157      */
 158     this.threadID = System.identityHashCode(Thread.currentThread());
 159
 160     sequenceNumber = allocateSeqNum();
 161   }
 162
 163
 164   /**
 165    * Determined with the serialver tool of the Sun J2SE 1.4.
 166    */
 167   static final long serialVersionUID = 5372048053134512534L;
 168
 169   private void readObject(java.io.ObjectInputStream in)
 170     throws java.io.IOException, java.lang.ClassNotFoundException
 171   {
 172     in.defaultReadObject();
 173
 174     /* We assume that future versions will be downwards compatible,
 175      * so we can ignore the versions.
 176      */
 177     byte majorVersion = in.readByte();
 178     byte minorVersion = in.readByte();
 179
 180     int numParams = in.readInt();
 181     if (numParams >= 0)
 182     {
 183       parameters = new Object[numParams];
 184       for (int i = 0; i < numParams; i++)
 185         parameters[i] = in.readObject();
 186     }
 187   }
 188
 189
 190   /**
 191    * @serialData The default fields, followed by a major byte version
 192    * number, followed by a minor byte version number, followed by
 193    * information about the log record parameters.  If
 194    * <code>parameters</code> is <code>null</code>, the integer -1 is
 195    * written, otherwise the length of the <code>parameters</code>
 196    * array (which can be zero), followed by the result of calling
 197    * {@link Object#toString() toString()} on the parameter (or
 198    * <code>null</code> if the parameter is <code>null</code>).
 199    *
 200    * <p><strong>Specification Note:</strong> The Javadoc for the
 201    * Sun reference implementation does not specify the version
 202    * number. FIXME: Reverse-engineer the JDK and file a bug
 203    * report with Sun, asking for amendment of the specification.
 204    */
 205   private void writeObject(java.io.ObjectOutputStream out)
 206     throws java.io.IOException
 207   {
 208     out.defaultWriteObject();
 209
 210     /* Major, minor version number: The Javadoc for J2SE1.4 does not
 211      * specify the values.
 212      */
 213     out.writeByte(0);
 214     out.writeByte(0);
 215
 216     if (parameters == null)
 217       out.writeInt(-1);
 218     else
 219     {
 220       out.writeInt(parameters.length);
 221       for (int i = 0; i < parameters.length; i++)
 222       {
 223         if (parameters[i] == null)
 224           out.writeObject(null);
 225         else
 226           out.writeObject(parameters[i].toString());
 227       }
 228     }
 229   }
 230
 231
 232   /**
 233    * Returns the name of the logger where this <code>LogRecord</code>
 234    * has originated.
 235    *
 236    * @return the name of the source {@link Logger}, or
 237    *         <code>null</code> if this <code>LogRecord</code>
 238    *         does not originate from a <code>Logger</code>.
 239    */
 240   public String getLoggerName()
 241   {
 242     return loggerName;
 243   }
 244
 245
 246   /**
 247    * Sets the name of the logger where this <code>LogRecord</code>
 248    * has originated.
 249    *
 250    * <p>As soon as a <code>LogRecord</code> has been handed over
 251    * to the logging framework, applications should not modify it
 252    * anymore.  Therefore, this method should only be called on
 253    * freshly constructed LogRecords.
 254    *
 255    * @param name the name of the source logger, or <code>null</code> to
 256    *             indicate that this <code>LogRecord</code> does not
 257    *             originate from a <code>Logger</code>.
 258    */
 259   public void setLoggerName(String name)
 260   {
 261     loggerName = name;
 262   }
 263
 264
 265   /**
 266    * Returns the resource bundle that is used when the message
 267    * of this <code>LogRecord</code> needs to be localized.
 268    *
 269    * @return the resource bundle used for localization,
 270    *         or <code>null</code> if this message does not need
 271    *         to be localized.
 272    */
 273   public ResourceBundle getResourceBundle()
 274   {
 275     return bundle;
 276   }
 277
 278
 279   /**
 280    * Sets the resource bundle that is used when the message
 281    * of this <code>LogRecord</code> needs to be localized.
 282    *
 283    * <p>As soon as a <code>LogRecord</code> has been handed over
 284    * to the logging framework, applications should not modify it
 285    * anymore.  Therefore, this method should only be called on
 286    * freshly constructed LogRecords.
 287    *
 288    * @param bundle  the resource bundle to be used, or
 289    *                <code>null</code> to indicate that this
 290    *                message does not need to be localized.
 291    */
 292   public void setResourceBundle(ResourceBundle bundle)
 293   {
 294     this.bundle = bundle;
 295
 296     /* FIXME: Is there a way to infer the name
 297      * of a resource bundle from a ResourceBundle object?
 298      */
 299     this.resourceBundleName = null;
 300   }
 301
 302
 303   /**
 304    * Returns the name of the resource bundle that is used when the
 305    * message of this <code>LogRecord</code> needs to be localized.
 306    *
 307    * @return the name of the resource bundle used for localization,
 308    *         or <code>null</code> if this message does not need
 309    *         to be localized.
 310    */
 311   public String getResourceBundleName()
 312   {
 313     return resourceBundleName;
 314   }
 315
 316
 317   /**
 318    * Sets the name of the resource bundle that is used when the
 319    * message of this <code>LogRecord</code> needs to be localized.
 320    *
 321    * <p>As soon as a <code>LogRecord</code> has been handed over
 322    * to the logging framework, applications should not modify it
 323    * anymore.  Therefore, this method should only be called on
 324    * freshly constructed LogRecords.
 325    *
 326    * @param name the name of the resource bundle to be used, or
 327    *             <code>null</code> to indicate that this message
 328    *             does not need to be localized.
 329    */
 330   public void setResourceBundleName(String name)
 331   {
 332     resourceBundleName = name;
 333     bundle = null;
 334
 335     try
 336     {
 337       if (resourceBundleName != null)
 338         bundle = ResourceBundle.getBundle(resourceBundleName);
 339     }
 340     catch (java.util.MissingResourceException _)
 341     {
 342     }
 343   }
 344
 345
 346   /**
 347    * Returns the level of the LogRecord.
 348    *
 349    * <p>Applications should be aware of the possibility that the
 350    *  result is not necessarily one of the standard logging levels,
 351    *  since the logging framework allows to create custom subclasses
 352    *  of <code>java.util.logging.Level</code>.  Therefore, filters
 353    *  should perform checks like <code>theRecord.getLevel().intValue()
 354    *  == Level.INFO.intValue()</code> instead of <code>theRecord.getLevel()
 355    *  == Level.INFO</code>.
 356    */
 357   public Level getLevel()
 358   {
 359     return level;
 360   }
 361
 362
 363   /**
 364    * Sets the severity level of this <code>LogRecord</code> to a new
 365    * value.
 366    *
 367    * <p>As soon as a <code>LogRecord</code> has been handed over
 368    * to the logging framework, applications should not modify it
 369    * anymore.  Therefore, this method should only be called on
 370    * freshly constructed LogRecords.
 371    *
 372    * @param level the new severity level, for example
 373    *              <code>Level.WARNING</code>.
 374    */
 375   public void setLevel(Level level)
 376   {
 377     this.level = level;
 378   }
 379
 380
 381   /**
 382    * The last used sequence number for any LogRecord.
 383    */
 384   private static long lastSeqNum;
 385
 386
 387   /**
 388    * Allocates a sequence number for a new LogRecord.  This class
 389    * method is only called by the LogRecord constructor.
 390    */
 391   private static synchronized long allocateSeqNum()
 392   {
 393     lastSeqNum += 1;
 394     return lastSeqNum;
 395   }
 396
 397
 398   /**
 399    * Returns the sequence number of this <code>LogRecord</code>.
 400    */
 401   public long getSequenceNumber()
 402   {
 403     return sequenceNumber;
 404   }
 405
 406
 407   /**
 408    * Sets the sequence number of this <code>LogRecord</code> to a new
 409    * value.
 410    *
 411    * <p>As soon as a <code>LogRecord</code> has been handed over
 412    * to the logging framework, applications should not modify it
 413    * anymore.  Therefore, this method should only be called on
 414    * freshly constructed LogRecords.
 415    *
 416    * @param seqNum the new sequence number.
 417    */
 418   public void setSequenceNumber(long seqNum)
 419   {
 420     this.sequenceNumber = seqNum;
 421   }
 422
 423
 424   /**
 425    * Returns the name of the class where the event being logged
 426    * has had its origin.  This information can be passed as
 427    * parameter to some logging calls, and in certain cases, the
 428    * logging framework tries to determine an approximation
 429    * (which may or may not be accurate).
 430    *
 431    * @return the name of the class that issued the logging request,
 432    *         or <code>null</code> if this information could not
 433    *         be obtained.
 434    */
 435   public String getSourceClassName()
 436   {
 437     if (sourceClassName != null)
 438       return sourceClassName;
 439
 440     /*  FIXME: Should infer this information from the call stack. */
 441     return null;
 442   }
 443
 444
 445   /**
 446    * Sets the name of the class where the event being logged
 447    * has had its origin.
 448    *
 449    * <p>As soon as a <code>LogRecord</code> has been handed over
 450    * to the logging framework, applications should not modify it
 451    * anymore.  Therefore, this method should only be called on
 452    * freshly constructed LogRecords.
 453    *
 454    * @param sourceClassName the name of the class that issued the
 455    *          logging request, or <code>null</code> to indicate that
 456    *          this information could not be obtained.
 457    */
 458   public void setSourceClassName(String sourceClassName)
 459   {
 460     this.sourceClassName = sourceClassName;
 461   }
 462
 463
 464   /**
 465    * Returns the name of the method where the event being logged
 466    * has had its origin.  This information can be passed as
 467    * parameter to some logging calls, and in certain cases, the
 468    * logging framework tries to determine an approximation
 469    * (which may or may not be accurate).
 470    *
 471    * @return the name of the method that issued the logging request,
 472    *         or <code>null</code> if this information could not
 473    *         be obtained.
 474    */
 475   public String getSourceMethodName()
 476   {
 477     if (sourceMethodName != null)
 478       return sourceMethodName;
 479
 480     /* FIXME: Should infer this information from the call stack. */
 481     return null;
 482   }
 483
 484
 485   /**
 486    * Sets the name of the method where the event being logged
 487    * has had its origin.
 488    *
 489    * <p>As soon as a <code>LogRecord</code> has been handed over
 490    * to the logging framework, applications should not modify it
 491    * anymore.  Therefore, this method should only be called on
 492    * freshly constructed LogRecords.
 493    *
 494    * @param sourceMethodName the name of the method that issued the
 495    *          logging request, or <code>null</code> to indicate that
 496    *          this information could not be obtained.
 497    */
 498   public void setSourceMethodName(String sourceMethodName)
 499   {
 500     this.sourceMethodName = sourceMethodName;
 501   }
 502
 503
 504   /**
 505    * Returns the message for this <code>LogRecord</code> before
 506    * any localization or parameter substitution.
 507    *
 508    * <p>A {@link Logger} will try to localize the message
 509    * if a resource bundle has been associated with this
 510    * <code>LogRecord</code>.  In this case, the logger will call
 511    * <code>getMessage()</code> and use the result as the key
 512    * for looking up the localized message in the bundle.
 513    * If no bundle has been associated, or if the result of
 514    * <code>getMessage()</code> is not a valid key in the
 515    * bundle, the logger will use the raw message text as
 516    * returned by this method.
 517    *
 518    * @return the message text, or <code>null</code> if there
 519    *         is no message text.
 520    */
 521   public String getMessage()
 522   {
 523     return message;
 524   }
 525
 526
 527   /**
 528    * Sets the message for this <code>LogRecord</code>.
 529    *
 530    * <p>A <code>Logger</code> will try to localize the message
 531    * if a resource bundle has been associated with this
 532    * <code>LogRecord</code>.  In this case, the logger will call
 533    * <code>getMessage()</code> and use the result as the key
 534    * for looking up the localized message in the bundle.
 535    * If no bundle has been associated, or if the result of
 536    * <code>getMessage()</code> is not a valid key in the
 537    * bundle, the logger will use the raw message text as
 538    * returned by this method.
 539    *
 540    * <p>It is possible to set the message to either an empty String or
 541    * <code>null</code>, although this does not make the the message
 542    * very helpful to human users.
 543    *
 544    * @param message the message text (which will be used as key
 545    *                for looking up the localized message text
 546    *                if a resource bundle has been associated).
 547    */
 548   public void setMessage(String message)
 549   {
 550     this.message = message;
 551   }
 552
 553
 554   /**
 555    * Returns the parameters to the log message.
 556    *
 557    * @return the parameters to the message, or <code>null</code> if
 558    *         the message has no parameters.
 559    */
 560   public Object[] getParameters()
 561   {
 562     return parameters;
 563   }
 564
 565
 566   /**
 567    * Sets the parameters to the log message.
 568    *
 569    * <p>As soon as a <code>LogRecord</code> has been handed over
 570    * to the logging framework, applications should not modify it
 571    * anymore.  Therefore, this method should only be called on
 572    * freshly constructed LogRecords.
 573    *
 574    * @param parameters the parameters to the message, or <code>null</code>
 575    *                   to indicate that the message has no parameters.
 576    */
 577   public void setParameters(Object[] parameters)
 578   {
 579     this.parameters = parameters;
 580   }
 581
 582
 583   /**
 584    * Returns an identifier for the thread in which this
 585    * <code>LogRecord</code> was created.  The identifier is not
 586    * necessarily related to any thread identifiers used by the
 587    * operating system.
 588    *
 589    * @return an identifier for the source thread.
 590    */
 591   public int getThreadID()
 592   {
 593     return threadID;
 594   }
 595
 596
 597   /**
 598    * Sets the identifier indicating in which thread this
 599    * <code>LogRecord</code> was created.  The identifier is not
 600    * necessarily related to any thread identifiers used by the
 601    * operating system.
 602    *
 603    * <p>As soon as a <code>LogRecord</code> has been handed over
 604    * to the logging framework, applications should not modify it
 605    * anymore.  Therefore, this method should only be called on
 606    * freshly constructed LogRecords.
 607    *
 608    * @param threadID the identifier for the source thread.
 609    */
 610   public void setThreadID(int threadID)
 611   {
 612     this.threadID = threadID;
 613   }
 614
 615
 616   /**
 617    * Returns the time when this <code>LogRecord</code> was created.
 618    *
 619    * @return the time of creation in milliseconds since the beginning
 620    *         of January 1, 1970.
 621    */
 622   public long getMillis()
 623   {
 624     return millis;
 625   }
 626
 627
 628   /**
 629    * Sets the time when this <code>LogRecord</code> was created.
 630    *
 631    * <p>As soon as a <code>LogRecord</code> has been handed over
 632    * to the logging framework, applications should not modify it
 633    * anymore.  Therefore, this method should only be called on
 634    * freshly constructed LogRecords.
 635    *
 636    * @param millis the time of creation in milliseconds since the
 637    *               beginning of January 1, 1970.
 638    */
 639   public void setMillis(long millis)
 640   {
 641     this.millis = millis;
 642   }
 643
 644
 645   /**
 646    * Returns the Throwable associated with this <code>LogRecord</code>,
 647    * or <code>null</code> if the logged event is not related to an exception
 648    * or error.
 649    */
 650   public Throwable getThrown()
 651   {
 652     return thrown;
 653   }
 654
 655
 656   /**
 657    * Associates this <code>LogRecord</code> with an exception or error.
 658    *
 659    * <p>As soon as a <code>LogRecord</code> has been handed over
 660    * to the logging framework, applications should not modify it
 661    * anymore.  Therefore, this method should only be called on
 662    * freshly constructed LogRecords.
 663    *
 664    * @param thrown the exception or error to associate with, or
 665    *               <code>null</code> if this <code>LogRecord</code>
 666    *               should be made unrelated to an exception or error.
 667    */
 668   public void setThrown(Throwable thrown)
 669   {
 670     this.thrown = thrown;
 671   }
 672 }