1 /* StreamHandler.java --
2 A class for publishing log messages to instances of java.io.OutputStream
3 Copyright (C) 2002 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
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)
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.
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
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
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. */
40 package java.util.logging;
43 * A <code>StreamHandler</code> publishes <code>LogRecords</code> to
44 * a instances of <code>java.io.OutputStream</code>.
46 * @author Sascha Brawer (brawer@acm.org)
48 public class StreamHandler
51 private OutputStream out;
52 private Writer writer;
56 * Indicates the current state of this StreamHandler. The value
57 * should be one of STATE_FRESH, STATE_PUBLISHED, or STATE_CLOSED.
59 private int streamState = STATE_FRESH;
63 * streamState having this value indicates that the StreamHandler
64 * has been created, but the publish(LogRecord) method has not been
65 * called yet. If the StreamHandler has been constructed without an
66 * OutputStream, writer will be null, otherwise it is set to a
67 * freshly created OutputStreamWriter.
69 private static final int STATE_FRESH = 0;
73 * streamState having this value indicates that the publish(LocRecord)
74 * method has been called at least once.
76 private static final int STATE_PUBLISHED = 1;
80 * streamState having this value indicates that the close() method
83 private static final int STATE_CLOSED = 2;
87 * Creates a <code>StreamHandler</code> without an output stream.
88 * Subclasses can later use {@link
89 * #setOutputStream(java.io.OutputStream)} to associate an output
90 * stream with this StreamHandler.
92 public StreamHandler()
99 * Creates a <code>StreamHandler</code> that formats log messages
100 * with the specified Formatter and publishes them to the specified
103 * @param out the output stream to which the formatted log messages
106 * @param formatter the <code>Formatter</code> that will be used
107 * to format log messages.
109 public StreamHandler(OutputStream out, Formatter formatter)
111 this(out, "java.util.logging.StreamHandler", Level.INFO,
112 formatter/*, SimpleFormatter.class*/);
118 String propertyPrefix,
120 Formatter formatter/*, Class defaultFormatterClass*/)
122 this.level = //LogManager.getLevelProperty(propertyPrefix + ".level",
125 //this.filter = (Filter) LogManager.getInstanceProperty(
126 // propertyPrefix + ".filter",
127 // /* must be instance of */ Filter.class,
128 // /* default: new instance of */ null);
130 //if (formatter != null)
131 this.formatter = formatter;
133 // this.formatter = (Formatter) LogManager.getInstanceProperty(
134 //propertyPrefix + ".formatter",
135 // /* must be instance of */ Formatter.class,
136 // /* default: new instance of */ defaultFormatterClass);
140 String enc = LogManager.getLogManager().getProperty(propertyPrefix
143 /* make sure enc actually is a valid encoding */
144 /*if ((enc != null) && (enc.length() > 0))
145 new String(new byte[0], enc);
157 changeWriter(out, getEncoding());
159 catch (UnsupportedEncodingException uex)
161 /* This should never happen, since the validity of the encoding
162 * name has been checked above.
164 /*throw new RuntimeException(uex.getMessage());
166 writer = new OutputStreamWriter(out);
170 /*private void checkOpen()
172 if (streamState == STATE_CLOSED)
173 throw new IllegalStateException(this.toString() + " has been closed");
176 /*private void checkFresh()
179 if (streamState != STATE_FRESH)
180 throw new IllegalStateException("some log records have been published to " + this);
184 /*private void changeWriter(OutputStream out, String encoding)
185 throws UnsupportedEncodingException
187 OutputStreamWriter writer;
189 /* The logging API says that a null encoding means the default
190 * platform encoding. However, java.io.OutputStreamWriter needs
191 * another constructor for the default platform encoding,
192 * passing null would throw an exception.
194 /*if (encoding == null)
195 writer = new OutputStreamWriter(out);
197 writer = new OutputStreamWriter(out, encoding);
199 /* Closing the stream has side effects -- do this only after
200 * creating a new writer has been successful.
202 /*if ((streamState != STATE_FRESH) || (this.writer != null))
205 this.writer = writer;
207 this.encoding = encoding;
208 streamState = STATE_FRESH;
213 * Sets the character encoding which this handler uses for publishing
214 * log records. The encoding of a <code>StreamHandler</code> must be
215 * set before any log records have been published.
217 * @param encoding the name of a character encoding, or <code>null</code>
218 * for the default encoding.
220 * @throws SecurityException if a security manager exists and
221 * the caller is not granted the permission to control the
222 * the logging infrastructure.
224 * @exception IllegalStateException if any log records have been
225 * published to this <code>StreamHandler</code> before. Please
226 * be aware that this is a pecularity of the GNU implementation.
227 * While the API specification indicates that it is an error
228 * if the encoding is set after records have been published,
229 * it does not mandate any specific behavior for that case.
231 /*public void setEncoding(String encoding)
232 throws SecurityException, UnsupportedEncodingException
234 /* The inherited implementation first checks whether the invoking
235 * code indeed has the permission to control the logging infra-
236 * structure, and throws a SecurityException if this was not the
239 * Next, it verifies that the encoding is supported and throws
240 * an UnsupportedEncodingExcpetion otherwise. Finally, it remembers
241 * the name of the encoding.
243 /*super.setEncoding(encoding);
247 /* If out is null, setEncoding is being called before an output
248 * stream has been set. In that case, we need to check that the
249 * encoding is valid, and remember it if this is the case. Since
250 * this is exactly what the inherited implementation of
251 * Handler.setEncoding does, we can delegate.
255 /* The logging API says that a null encoding means the default
256 * platform encoding. However, java.io.OutputStreamWriter needs
257 * another constructor for the default platform encoding, passing
258 * null would throw an exception.
260 /*if (encoding == null)
261 writer = new OutputStreamWriter(out);
263 writer = new OutputStreamWriter(out, encoding);
269 * Changes the output stream to which this handler publishes
272 * @throws SecurityException if a security manager exists and
273 * the caller is not granted the permission to control
274 * the logging infrastructure.
276 * @throws NullPointerException if <code>out</code>
277 * is <code>null</code>.
279 /*protected void setOutputStream(OutputStream out)
280 throws SecurityException
282 LogManager.getLogManager().checkAccess();
284 /* Throw a NullPointerException if out is null. */
289 changeWriter(out, getEncoding());
291 catch (UnsupportedEncodingException ex)
293 /* This seems quite unlikely to happen, unless the underlying
294 * implementation of java.io.OutputStreamWriter changes its
295 * mind (at runtime) about the set of supported character
298 /*throw new RuntimeException(ex.getMessage());
304 * Publishes a <code>LogRecord</code> to the associated output
305 * stream, provided the record passes all tests for being loggable.
306 * The <code>StreamHandler</code> will localize the message of the
307 * log record and substitute any message parameters.
309 * <p>Most applications do not need to call this method directly.
310 * Instead, they will use use a {@link Logger}, which will create
311 * LogRecords and distribute them to registered handlers.
313 * <p>In case of an I/O failure, the <code>ErrorManager</code>
314 * of this <code>Handler</code> will be informed, but the caller
315 * of this method will not receive an exception.
317 * <p>If a log record is being published to a
318 * <code>StreamHandler</code> that has been closed earlier, the Sun
319 * J2SE 1.4 reference can be observed to silently ignore the
320 * call. The GNU implementation, however, intentionally behaves
321 * differently by informing the <code>ErrorManager</code> associated
322 * with this <code>StreamHandler</code>. Since the condition
323 * indicates a programming error, the programmer should be
324 * informed. It also seems extremely unlikely that any application
325 * would depend on the exact behavior in this rather obscure,
326 * erroneous case -- especially since the API specification does not
327 * prescribe what is supposed to happen.
329 * @param record the log event to be published.
331 /*public void publish(LogRecord record)
333 String formattedMessage;
335 if (!isLoggable(record))
338 if (streamState == STATE_FRESH)
342 writer.write(formatter.getHead(this));
344 catch (java.io.IOException ex)
346 reportError(null, ex, ErrorManager.WRITE_FAILURE);
351 reportError(null, ex, ErrorManager.GENERIC_FAILURE);
355 streamState = STATE_PUBLISHED;
360 formattedMessage = formatter.format(record);
364 reportError(null, ex, ErrorManager.FORMAT_FAILURE);
370 writer.write(formattedMessage);
374 reportError(null, ex, ErrorManager.WRITE_FAILURE);
380 * Checks whether or not a <code>LogRecord</code> would be logged
381 * if it was passed to this <code>StreamHandler</code> for publication.
383 * <p>The <code>StreamHandler</code> implementation first checks
384 * whether a writer is present and the handler's level is greater
385 * than or equal to the severity level threshold. In a second step,
386 * if a {@link Filter} has been installed, its {@link
387 * Filter#isLoggable(LogRecord) isLoggable} method is
388 * invoked. Subclasses of <code>StreamHandler</code> can override
389 * this method to impose their own constraints.
391 * @param record the <code>LogRecord</code> to be checked.
393 * @return <code>true</code> if <code>record</code> would
394 * be published by {@link #publish(LogRecord) publish},
395 * <code>false</code> if it would be discarded.
397 * @see #setLevel(Level)
398 * @see #setFilter(Filter)
399 * @see Filter#isLoggable(LogRecord)
401 * @throws NullPointerException if <code>record</code> is
402 * <code>null</code>. */
403 public boolean isLoggable(LogRecord record)
405 return (writer != null) && super.isLoggable(record);
410 * Forces any data that may have been buffered to the underlying
413 * <p>In case of an I/O failure, the <code>ErrorManager</code>
414 * of this <code>Handler</code> will be informed, but the caller
415 * of this method will not receive an exception.
417 * <p>If a <code>StreamHandler</code> that has been closed earlier
418 * is closed a second time, the Sun J2SE 1.4 reference can be
419 * observed to silently ignore the call. The GNU implementation,
420 * however, intentionally behaves differently by informing the
421 * <code>ErrorManager</code> associated with this
422 * <code>StreamHandler</code>. Since the condition indicates a
423 * programming error, the programmer should be informed. It also
424 * seems extremely unlikely that any application would depend on the
425 * exact behavior in this rather obscure, erroneous case --
426 * especially since the API specification does not prescribe what is
427 * supposed to happen.
429 /*public void flush()
439 reportError(null, ex, ErrorManager.FLUSH_FAILURE);
445 * Closes this <code>StreamHandler</code> after having forced any
446 * data that may have been buffered to the underlying output
449 * <p>As soon as <code>close</code> has been called,
450 * a <code>Handler</code> should not be used anymore. Attempts
451 * to publish log records, to flush buffers, or to modify the
452 * <code>Handler</code> in any other way may throw runtime
453 * exceptions after calling <code>close</code>.</p>
455 * <p>In case of an I/O failure, the <code>ErrorManager</code>
456 * of this <code>Handler</code> will be informed, but the caller
457 * of this method will not receive an exception.</p>
459 * <p>If a <code>StreamHandler</code> that has been closed earlier
460 * is closed a second time, the Sun J2SE 1.4 reference can be
461 * observed to silently ignore the call. The GNU implementation,
462 * however, intentionally behaves differently by informing the
463 * <code>ErrorManager</code> associated with this
464 * <code>StreamHandler</code>. Since the condition indicates a
465 * programming error, the programmer should be informed. It also
466 * seems extremely unlikely that any application would depend on the
467 * exact behavior in this rather obscure, erroneous case --
468 * especially since the API specification does not prescribe what is
469 * supposed to happen.
471 * @throws SecurityException if a security manager exists and
472 * the caller is not granted the permission to control
473 * the logging infrastructure.
475 /*public void close()
476 throws SecurityException
478 LogManager.getLogManager().checkAccess();
482 /* Although flush also calls checkOpen, it catches
483 * any exceptions and reports them to the ErrorManager
484 * as flush failures. However, we want to report
485 * a closed stream as a close failure, not as a
486 * flush failure here. Therefore, we call checkOpen()
494 if (formatter != null)
496 /* Even if the StreamHandler has never published a record,
497 * it emits head and tail upon closing. An earlier version
498 * of the GNU Classpath implementation did not emitted
499 * anything. However, this had caused XML log files to be
500 * entirely empty instead of containing no log records.
502 /*if (streamState == STATE_FRESH)
503 writer.write(formatter.getHead(this));
504 if (streamState != STATE_CLOSED)
505 writer.write(formatter.getTail(this));
507 streamState = STATE_CLOSED;
513 reportError(null, ex, ErrorManager.CLOSE_FAILURE);