- java.lang.Object
-
- java.util.logging.Handler
-
- Direct Known Subclasses:
MemoryHandler
,StreamHandler
public abstract class Handler extends Object
AHandler
object takes log messages from aLogger
and exports them. It might for example, write them to a console or write them to a file, or send them to a network logging service, or forward them to an OS log, or whatever.A
Handler
can be disabled by doing asetLevel(Level.OFF)
and can be re-enabled by doing asetLevel
with an appropriate level.Handler
classes typically useLogManager
properties to set default values for theHandler
'sFilter
,Formatter
, andLevel
. See the specific documentation for each concreteHandler
class.- Since:
- 1.4
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Handler()
Default constructor.
-
Method Summary
Modifier and Type Method Description abstract void
close()
Close theHandler
and free all associated resources.abstract void
flush()
Flush any buffered output.String
getEncoding()
Return the character encoding for thisHandler
.ErrorManager
getErrorManager()
Retrieves the ErrorManager for this Handler.Filter
getFilter()
Get the currentFilter
for thisHandler
.Formatter
getFormatter()
Return theFormatter
for thisHandler
.Level
getLevel()
Get the log level specifying which messages will be logged by thisHandler
.boolean
isLoggable(LogRecord record)
Check if thisHandler
would actually log a givenLogRecord
.abstract void
publish(LogRecord record)
Publish aLogRecord
.protected void
reportError(String msg, Exception ex, int code)
Protected convenience method to report an error to this Handler's ErrorManager.void
setEncoding(String encoding)
Set the character encoding used by thisHandler
.void
setErrorManager(ErrorManager em)
Define an ErrorManager for this Handler.void
setFilter(Filter newFilter)
Set aFilter
to control output on thisHandler
.void
setFormatter(Formatter newFormatter)
Set aFormatter
.void
setLevel(Level newLevel)
Set the log level specifying which message levels will be logged by thisHandler
.
-
-
-
Method Detail
-
publish
public abstract void publish(LogRecord record)
Publish aLogRecord
.The logging request was made initially to a
Logger
object, which initialized theLogRecord
and forwarded it here.The
Handler
is responsible for formatting the message, when and if necessary. The formatting should include localization.- Parameters:
record
- description of the log event. A null record is silently ignored and is not published
-
flush
public abstract void flush()
Flush any buffered output.
-
close
public abstract void close() throws SecurityException
Close theHandler
and free all associated resources.The close method will perform a
flush
and then close theHandler
. After close has been called thisHandler
should no longer be used. Method calls may either be silently ignored or may throw runtime exceptions.- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
setFormatter
public void setFormatter(Formatter newFormatter) throws SecurityException
Set aFormatter
. ThisFormatter
will be used to formatLogRecords
for thisHandler
.Some
Handlers
may not useFormatters
, in which case theFormatter
will be remembered, but not used.- Parameters:
newFormatter
- theFormatter
to use (may not be null)- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
getFormatter
public Formatter getFormatter()
Return theFormatter
for thisHandler
.- Returns:
- the
Formatter
(may be null).
-
setEncoding
public void setEncoding(String encoding) throws SecurityException, UnsupportedEncodingException
Set the character encoding used by thisHandler
.The encoding should be set before any
LogRecords
are written to theHandler
.- Parameters:
encoding
- The name of a supported character encoding. May be null, to indicate the default platform encoding.- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.UnsupportedEncodingException
- if the named encoding is not supported.
-
getEncoding
public String getEncoding()
Return the character encoding for thisHandler
.- Returns:
- The encoding name. May be null, which indicates the default encoding should be used.
-
setFilter
public void setFilter(Filter newFilter) throws SecurityException
Set aFilter
to control output on thisHandler
.For each call of
publish
theHandler
will call thisFilter
(if it is non-null) to check if theLogRecord
should be published or discarded.- Parameters:
newFilter
- aFilter
object (may be null)- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
getFilter
public Filter getFilter()
Get the currentFilter
for thisHandler
.- Returns:
- a
Filter
object (may be null)
-
setErrorManager
public void setErrorManager(ErrorManager em)
Define an ErrorManager for this Handler.The ErrorManager's "error" method will be invoked if any errors occur while using this Handler.
- Parameters:
em
- the new ErrorManager- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
getErrorManager
public ErrorManager getErrorManager()
Retrieves the ErrorManager for this Handler.- Returns:
- the ErrorManager for this Handler
- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
reportError
protected void reportError(String msg, Exception ex, int code)
Protected convenience method to report an error to this Handler's ErrorManager. Note that this method retrieves and uses the ErrorManager without doing a security check. It can therefore be used in environments where the caller may be non-privileged.- Parameters:
msg
- a descriptive string (may be null)ex
- an exception (may be null)code
- an error code defined in ErrorManager
-
setLevel
public void setLevel(Level newLevel) throws SecurityException
Set the log level specifying which message levels will be logged by thisHandler
. Message levels lower than this value will be discarded.The intention is to allow developers to turn on voluminous logging, but to limit the messages that are sent to certain
Handlers
.- Parameters:
newLevel
- the new value for the log level- Throws:
SecurityException
- if a security manager exists and if the caller does not haveLoggingPermission("control")
.
-
getLevel
public Level getLevel()
Get the log level specifying which messages will be logged by thisHandler
. Message levels lower than this level will be discarded.- Returns:
- the level of messages being logged.
-
isLoggable
public boolean isLoggable(LogRecord record)
Check if thisHandler
would actually log a givenLogRecord
.This method checks if the
LogRecord
has an appropriateLevel
and whether it satisfies anyFilter
. It also may make otherHandler
specific checks that might prevent a handler from logging theLogRecord
. It will return false if theLogRecord
is null.- Parameters:
record
- aLogRecord
- Returns:
- true if the
LogRecord
would be logged.
-
-