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    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    
040    package java.util.logging;
041    
042    import 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     */
054    public 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    }