|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.util.logging.Handler
java.util.logging.StreamHandler
public class StreamHandler
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. |
Methods inherited from class java.util.logging.Handler |
---|
getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setErrorManager, setFilter, setFormatter, setLevel |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public StreamHandler()
StreamHandler
without an output stream.
Subclasses can later use setOutputStream(java.io.OutputStream)
to associate an output
stream with this StreamHandler.
public StreamHandler(OutputStream out, Formatter formatter)
StreamHandler
that formats log messages
with the specified Formatter and publishes them to the specified
output stream.
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 |
---|
public void setEncoding(String encoding) throws SecurityException, UnsupportedEncodingException
StreamHandler
must be
set before any log records have been published.
setEncoding
in class Handler
encoding
- the name of a character encoding, or null
for the default encoding.
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.
UnsupportedEncodingException
protected void setOutputStream(OutputStream out) throws SecurityException
SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.
NullPointerException
- if out
is null
.public void publish(LogRecord record)
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.
publish
in class Handler
record
- the log event to be published.public boolean isLoggable(LogRecord record)
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.
isLoggable
in class Handler
record
- the LogRecord
to be checked.
true
if record
would
be published by publish
,
false
if it would be discarded.
NullPointerException
- if record
is
null
.Handler.setLevel(Level)
,
Handler.setFilter(Filter)
,
Filter.isLoggable(LogRecord)
public void flush()
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.
flush
in class Handler
public void close() throws SecurityException
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.
close
in class Handler
SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |