001/* LogRecord.java --
002   A class for the state associated with individual logging events
003   Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039
040package java.util.logging;
041
042import java.util.ResourceBundle;
043
044
045/**
046 * A <code>LogRecord</code> contains the state for an individual
047 * event to be logged.
048 *
049 * <p>As soon as a LogRecord instance has been handed over to the
050 * logging framework, applications should not manipulate it anymore.
051 *
052 * @author Sascha Brawer (brawer@acm.org)
053 */
054public class LogRecord
055  implements java.io.Serializable
056{
057  /**
058   * The severity level of this <code>LogRecord</code>.
059   */
060  private Level      level;
061
062
063  /**
064   * The sequence number of this <code>LogRecord</code>.
065   */
066  private long       sequenceNumber;
067
068
069  /**
070   * The name of the class that issued the logging request, or
071   * <code>null</code> if this information could not be obtained.
072   */
073  private String     sourceClassName;
074
075
076  /**
077   * The name of the method that issued the logging request, or
078   * <code>null</code> if this information could not be obtained.
079   */
080  private String sourceMethodName;
081
082
083  /**
084   * The message for this <code>LogRecord</code> before
085   * any localization or formatting.
086   */
087  private String message;
088
089
090  /**
091   * An identifier for the thread in which this <code>LogRecord</code>
092   * was created.  The identifier is not necessarily related to any
093   * thread identifiers used by the operating system.
094   */
095  private int threadID;
096
097
098  /**
099   * 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}