java.util.logging

Class StreamHandler

public class StreamHandler extends Handler

A StreamHandler publishes LogRecords to a instances of java.io.OutputStream.

Constructor Summary
	StreamHandler() Creates a `StreamHandler` without an output stream.
	StreamHandler(OutputStream out, Formatter formatter) Creates a `StreamHandler` that formats log messages with the specified Formatter and publishes them to the specified output stream.

Method Summary
void	close() Closes this `StreamHandler` after having forced any data that may have been buffered to the underlying output device.
void	flush() Forces any data that may have been buffered to the underlying output device.
boolean	isLoggable(LogRecord record) Checks whether or not a `LogRecord` would be logged if it was passed to this `StreamHandler` for publication.
void	publish(LogRecord record) Publishes a `LogRecord` to the associated output stream, provided the record passes all tests for being loggable.
void	setEncoding(String encoding) Sets the character encoding which this handler uses for publishing log records.
protected void	setOutputStream(OutputStream out) Changes the output stream to which this handler publishes logging records.

Constructor Detail

StreamHandler

public StreamHandler()

Creates a StreamHandler without an output stream. Subclasses can later use {@link #setOutputStream(java.io.OutputStream)} to associate an output stream with this StreamHandler.

StreamHandler

public StreamHandler(OutputStream out, Formatter formatter)

Creates a StreamHandler that formats log messages with the specified Formatter and publishes them to the specified output stream.

Parameters: out the output stream to which the formatted log messages are published. formatter the Formatter that will be used to format log messages.

Method Detail

close

public void close()

Closes this StreamHandler after having forced any data that may have been buffered to the underlying output device.

As soon as close has been called, a Handler should not be used anymore. Attempts to publish log records, to flush buffers, or to modify the Handler in any other way may throw runtime exceptions after calling close.

In case of an I/O failure, the ErrorManager of this Handler will be informed, but the caller of this method will not receive an exception.

If a StreamHandler that has been closed earlier is closed a second time, the Sun J2SE 1.4 reference can be observed to silently ignore the call. The GNU implementation, however, intentionally behaves differently by informing the ErrorManager associated with this StreamHandler. Since the condition indicates a programming error, the programmer should be informed. It also seems extremely unlikely that any application would depend on the exact behavior in this rather obscure, erroneous case -- especially since the API specification does not prescribe what is supposed to happen.

Throws: SecurityException if a security manager exists and the caller is not granted the permission to control the logging infrastructure.

flush

public void flush()

Forces any data that may have been buffered to the underlying output device.

In case of an I/O failure, the ErrorManager of this Handler will be informed, but the caller of this method will not receive an exception.

isLoggable

public boolean isLoggable(LogRecord record)

Checks whether or not a LogRecord would be logged if it was passed to this StreamHandler for publication.

The StreamHandler implementation first checks whether a writer is present and the handler's level is greater than or equal to the severity level threshold. In a second step, if a {@link Filter} has been installed, its {@link Filter#isLoggable(LogRecord) isLoggable} method is invoked. Subclasses of StreamHandler can override this method to impose their own constraints.

Parameters: record the LogRecord to be checked.

Returns: true if record would be published by {@link #publish(LogRecord) publish}, false if it would be discarded.

Throws: NullPointerException if record is null.

publish

public void publish(LogRecord record)

Publishes a LogRecord to the associated output stream, provided the record passes all tests for being loggable. The StreamHandler will localize the message of the log record and substitute any message parameters.

Most applications do not need to call this method directly. Instead, they will use use a {@link Logger}, which will create LogRecords and distribute them to registered handlers.

In case of an I/O failure, the ErrorManager of this Handler will be informed, but the caller of this method will not receive an exception.

If a log record is being published to a StreamHandler that has been closed earlier, the Sun J2SE 1.4 reference can be observed to silently ignore the call. The GNU implementation, however, intentionally behaves differently by informing the ErrorManager associated with this StreamHandler. Since the condition indicates a programming error, the programmer should be informed. It also seems extremely unlikely that any application would depend on the exact behavior in this rather obscure, erroneous case -- especially since the API specification does not prescribe what is supposed to happen.

Parameters: record the log event to be published.

setEncoding

public void setEncoding(String encoding)

Sets the character encoding which this handler uses for publishing log records. The encoding of a StreamHandler must be set before any log records have been published.

Parameters: encoding the name of a character encoding, or null for the default encoding.

Throws: SecurityException if a security manager exists and the caller is not granted the permission to control the the logging infrastructure. IllegalStateException if any log records have been published to this StreamHandler before. Please be aware that this is a pecularity of the GNU implementation. While the API specification indicates that it is an error if the encoding is set after records have been published, it does not mandate any specific behavior for that case.

setOutputStream

protected void setOutputStream(OutputStream out)

Changes the output stream to which this handler publishes logging records.

Throws: SecurityException if a security manager exists and the caller is not granted the permission to control the logging infrastructure. NullPointerException if out is null.