001    /* Handler.java -- a class for publishing log messages
002       Copyright (C) 2002, 2004 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.util.logging;
040    
041    import java.io.UnsupportedEncodingException;
042    
043    /**
044     * A <code>Handler</code> publishes <code>LogRecords</code> to
045     * a sink, for example a file, the console or a network socket.
046     * There are different subclasses of <code>Handler</code>
047     * to deal with different kinds of sinks.
048     *
049     * <p>FIXME: Are handlers thread-safe, or is the assumption that only
050     * loggers are, and a handler can belong only to one single logger? If
051     * the latter, should we enforce it? (Spec not clear). In any
052     * case, it needs documentation.
053     *
054     * @author Sascha Brawer (brawer@acm.org)
055     */
056    public abstract class Handler
057    {
058      Formatter     formatter;
059      Filter        filter;
060      Level         level;
061      ErrorManager  errorManager;
062      String        encoding;
063    
064      /**
065       * Constructs a Handler with a logging severity level of
066       * <code>Level.ALL</code>, no formatter, no filter, and
067       * an instance of <code>ErrorManager</code> managing errors.
068       *
069       * <p><strong>Specification Note:</strong> The specification of the
070       * Java<sup>TM</sup> Logging API does not mention which character
071       * encoding is to be used by freshly constructed Handlers.  The GNU
072       * implementation uses the default platform encoding, but other
073       * Java implementations might behave differently.
074       *
075       * <p><strong>Specification Note:</strong> While a freshly constructed
076       * Handler is required to have <em>no filter</em> according to the
077       * specification, <code>null</code> is not a valid parameter for
078       * <code>Handler.setFormatter</code>.  Therefore, the following
079       * code will throw a <code>java.lang.NullPointerException</code>:
080       *
081       * <p><pre>Handler h = new MyConcreteSubclassOfHandler();
082    h.setFormatter(h.getFormatter());</pre>
083       *
084       * It seems strange that a freshly constructed Handler is not
085       * supposed to provide a Formatter, but this is what the specification
086       * says.
087       */
088      protected Handler()
089      {
090        level = Level.ALL;
091      }
092    
093    
094      /**
095       * Publishes a <code>LogRecord</code> to an appropriate sink,
096       * provided the record passes all tests for being loggable.  The
097       * <code>Handler</code> will localize the message of the log
098       * record and substitute any message parameters.
099       *
100       * <p>Most applications do not need to call this method directly.
101       * Instead, they will use use a {@link Logger}, which will
102       * create LogRecords and distribute them to registered handlers.
103       *
104       * <p>In case of an I/O failure, the <code>ErrorManager</code>
105       * of this <code>Handler</code> will be informed, but the caller
106       * of this method will not receive an exception.
107       *
108       * @param record the log event to be published.
109       */
110      public abstract void publish(LogRecord record);
111    
112    
113      /**
114       * Forces any data that may have been buffered to the underlying
115       * output device.
116       *
117       * <p>In case of an I/O failure, the <code>ErrorManager</code>
118       * of this <code>Handler</code> will be informed, but the caller
119       * of this method will not receive an exception.
120       */
121      public abstract void flush();
122    
123    
124      /**
125       * Closes this <code>Handler</code> after having flushed
126       * the buffers.  As soon as <code>close</code> has been called,
127       * a <code>Handler</code> should not be used anymore. Attempts
128       * to publish log records, to flush buffers, or to modify the
129       * <code>Handler</code> in any other way may throw runtime
130       * exceptions after calling <code>close</code>.
131       *
132       * <p>In case of an I/O failure, the <code>ErrorManager</code>
133       * of this <code>Handler</code> will be informed, but the caller
134       * of this method will not receive an exception.
135       *
136       * @throws SecurityException if a security manager exists and
137       *         the caller is not granted the permission to control
138       *         the logging infrastructure.
139       */
140      public abstract void close()
141        throws SecurityException;
142    
143    
144      /**
145       * Returns the <code>Formatter</code> which will be used to
146       * localize the text of log messages and to substitute
147       * message parameters.  A <code>Handler</code> is encouraged,
148       * but not required to actually use an assigned
149       * <code>Formatter</code>.
150       *
151       * @return the <code>Formatter</code> being used, or
152       *         <code>null</code> if this <code>Handler</code>
153       *         does not use formatters and no formatter has
154       *         ever been set by calling <code>setFormatter</code>.
155       */
156      public Formatter getFormatter()
157      {
158        return formatter;
159      }
160    
161    
162      /**
163       * Sets the <code>Formatter</code> which will be used to
164       * localize the text of log messages and to substitute
165       * message parameters.  A <code>Handler</code> is encouraged,
166       * but not required to actually use an assigned
167       * <code>Formatter</code>.
168       *
169       * @param formatter the new <code>Formatter</code> to use.
170       *
171       * @throws SecurityException if a security manager exists and
172       *         the caller is not granted the permission to control
173       *         the logging infrastructure.
174       *
175       * @throws NullPointerException if <code>formatter</code> is
176       *         <code>null</code>.
177       */
178      public void setFormatter(Formatter formatter)
179        throws SecurityException
180      {
181        LogManager.getLogManager().checkAccess();
182    
183        /* Throws a NullPointerException if formatter is null. */
184        formatter.getClass();
185    
186        this.formatter = formatter;
187      }
188    
189    
190      /**
191       * Returns the character encoding which this handler uses for publishing
192       * log records.
193       *
194       * @return the name of a character encoding, or <code>null</code>
195       *         for the default platform encoding.
196       */
197      public String getEncoding()
198      {
199        return encoding;
200      }
201    
202    
203      /**
204       * Sets the character encoding which this handler uses for publishing
205       * log records.  The encoding of a <code>Handler</code> must be
206       * set before any log records have been published.
207       *
208       * @param encoding the name of a character encoding, or <code>null</code>
209       *            for the default encoding.
210       *
211       * @exception SecurityException if a security manager exists and
212       *            the caller is not granted the permission to control
213       *            the logging infrastructure.
214       *
215       */
216      public void setEncoding(String encoding)
217        throws SecurityException, UnsupportedEncodingException
218      {
219        /* Should any developer ever change this implementation, they are
220         * advised to have a look at StreamHandler.setEncoding(String),
221         * which overrides this method without calling super.setEncoding.
222         */
223        LogManager.getLogManager().checkAccess();
224    
225        /* Simple check for supported encodings. This is more expensive
226         * than it could be, but this method is overwritten by StreamHandler
227         * anyway.
228         */
229        if (encoding != null)
230          new String(new byte[0], encoding);
231    
232        this.encoding = encoding;
233      }
234    
235    
236      /**
237       * Returns the <code>Filter</code> that currently controls which
238       * log records are being published by this <code>Handler</code>.
239       *
240       * @return the currently active <code>Filter</code>, or
241       *         <code>null</code> if no filter has been associated.
242       *         In the latter case, log records are filtered purely
243       *         based on their severity level.
244       */
245      public Filter getFilter()
246      {
247        return filter;
248      }
249    
250    
251      /**
252       * Sets the <code>Filter</code> for controlling which
253       * log records will be published by this <code>Handler</code>.
254       *
255       * @param filter the <code>Filter</code> to use, or
256       *         <code>null</code> to filter log records purely based
257       *         on their severity level.
258       */
259      public void setFilter(Filter filter)
260        throws SecurityException
261      {
262        LogManager.getLogManager().checkAccess();
263        this.filter = filter;
264      }
265    
266    
267      /**
268       * Returns the <code>ErrorManager</code> that currently deals
269       * with errors originating from this Handler.
270       *
271       * @exception SecurityException if a security manager exists and
272       *            the caller is not granted the permission to control
273       *            the logging infrastructure.
274       */
275      public ErrorManager getErrorManager()
276      {
277        LogManager.getLogManager().checkAccess();
278    
279        /* Developers wanting to change the subsequent code should
280         * have a look at Handler.reportError -- it also can create
281         * an ErrorManager, but does so without checking permissions
282         * to control the logging infrastructure.
283         */
284        if (errorManager == null)
285          errorManager = new ErrorManager();
286    
287        return errorManager;
288      }
289    
290    
291      public void setErrorManager(ErrorManager manager)
292      {
293        LogManager.getLogManager().checkAccess();
294    
295        /* Make sure manager is not null. */
296        manager.getClass();
297    
298        this.errorManager = manager;
299      }
300    
301    
302      protected void reportError(String message, Exception ex, int code)
303      {
304        if (errorManager == null)
305          errorManager = new ErrorManager();
306    
307        errorManager.error(message, ex, code);
308      }
309    
310    
311      /**
312       * Returns the severity level threshold for this <code>Handler</code>
313       * All log records with a lower severity level will be discarded;
314       * a log record of the same or a higher level will be published
315       * unless an installed <code>Filter</code> decides to discard it.
316       *
317       * @return the severity level below which all log messages
318       *         will be discarded.
319       */
320      public Level getLevel()
321      {
322        return level;
323      }
324    
325    
326      /**
327       * Sets the severity level threshold for this <code>Handler</code>.
328       * All log records with a lower severity level will be discarded;
329       * a log record of the same or a higher level will be published
330       * unless an installed <code>Filter</code> decides to discard it.
331       *
332       * @param level the severity level below which all log messages
333       *              will be discarded.
334       *
335       * @exception SecurityException if a security manager exists and
336       *            the caller is not granted the permission to control
337       *            the logging infrastructure.
338       *
339       * @exception NullPointerException if <code>level</code> is
340       *            <code>null</code>.
341       */
342      public void setLevel(Level level)
343      {
344        LogManager.getLogManager().checkAccess();
345    
346        /* Throw NullPointerException if level is null.  */
347        level.getClass();
348        this.level = level;
349      }
350    
351    
352      /**
353       * Checks whether a <code>LogRecord</code> would be logged
354       * if it was passed to this <code>Handler</code> for publication.
355       *
356       * <p>The <code>Handler</code> implementation considers a record as
357       * loggable if its level is greater than or equal to the severity
358       * level threshold.  In a second step, if a {@link Filter} has
359       * been installed, its {@link Filter#isLoggable(LogRecord) isLoggable}
360       * method is invoked. Subclasses of <code>Handler</code> can override
361       * this method to impose their own constraints.
362       *
363       * @param record the <code>LogRecord</code> to be checked.
364       *
365       * @return <code>true</code> if <code>record</code> would
366       *         be published by {@link #publish(LogRecord) publish},
367       *         <code>false</code> if it would be discarded.
368       *
369       * @see #setLevel(Level)
370       * @see #setFilter(Filter)
371       * @see Filter#isLoggable(LogRecord)
372       *
373       * @throws NullPointerException if <code>record</code>
374       *         is <code>null</code>.
375       */
376      public boolean isLoggable(LogRecord record)
377      {
378        if (record.getLevel().intValue() < level.intValue())
379          return false;
380    
381        if (filter != null)
382          return filter.isLoggable(record);
383        else
384          return true;
385      }
386    }