Class StreamHandler

public StreamHandler()

Creates a StreamHandler without an output stream. Subclasses can later use setOutputStream(OutputStream) to associate an output stream with this 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.

public void close()
            throws SecurityException

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.

Overrides:

close in interface Handler

Throws:

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

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.

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.

Overrides:

flush in interface Handler

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 Filter has been installed, its isLoggable method is invoked. Subclasses of StreamHandler can override this method to impose their own constraints.

Overrides:

isLoggable in interface Handler

Parameters:

record - the LogRecord to be checked.

Returns:

true if record would be published by publish, false if it would be discarded.

Throws:

NullPointerException - if record is null.

See Also:

setLevel(Level), setFilter(Filter), Filter.isLoggable(LogRecord)

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 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.

Overrides:

publish in interface Handler

Parameters:

record - the log event to be published.

public void setEncoding(String encoding)
            throws SecurityException,
                   UnsupportedEncodingException

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.

Overrides:

setEncoding in interface Handler

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.

protected void setOutputStream(OutputStream out)
            throws SecurityException

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.