/*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/
package java.util.logging;
import java.io.
UnsupportedEncodingException;
/**
* A <tt>Handler</tt> object takes log messages from a <tt>Logger</tt> 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.
* <p>
* A <tt>Handler</tt> can be disabled by doing a <tt>setLevel(Level.OFF)</tt>
* and can be re-enabled by doing a <tt>setLevel</tt> with an appropriate level.
* <p>
* <tt>Handler</tt> classes typically use <tt>LogManager</tt> properties to set
* default values for the <tt>Handler</tt>'s <tt>Filter</tt>, <tt>Formatter</tt>,
* and <tt>Level</tt>. See the specific documentation for each concrete
* <tt>Handler</tt> class.
*
*
* @since 1.4
*/
public abstract class
Handler {
private static final int
offValue =
Level.
OFF.
intValue();
private final
LogManager manager =
LogManager.
getLogManager();
// We're using volatile here to avoid synchronizing getters, which
// would prevent other threads from calling isLoggable()
// while publish() is executing.
// On the other hand, setters will be synchronized to exclude concurrent
// execution with more complex methods, such as StreamHandler.publish().
// We wouldn't want 'level' to be changed by another thread in the middle
// of the execution of a 'publish' call.
private volatile
Filter filter;
private volatile
Formatter formatter;
private volatile
Level logLevel =
Level.
ALL;
private volatile
ErrorManager errorManager = new
ErrorManager();
private volatile
String encoding;
// Package private support for security checking. When sealed
// is true, we access check updates to the class.
boolean
sealed = true;
/**
* Default constructor. The resulting <tt>Handler</tt> has a log
* level of <tt>Level.ALL</tt>, no <tt>Formatter</tt>, and no
* <tt>Filter</tt>. A default <tt>ErrorManager</tt> instance is installed
* as the <tt>ErrorManager</tt>.
*/
protected
Handler() {
}
/**
* Publish a <tt>LogRecord</tt>.
* <p>
* The logging request was made initially to a <tt>Logger</tt> object,
* which initialized the <tt>LogRecord</tt> and forwarded it here.
* <p>
* The <tt>Handler</tt> is responsible for formatting the message, when and
* if necessary. The formatting should include localization.
*
* @param record description of the log event. A null record is
* silently ignored and is not published
*/
public abstract void
publish(
LogRecord record);
/**
* Flush any buffered output.
*/
public abstract void
flush();
/**
* Close the <tt>Handler</tt> and free all associated resources.
* <p>
* The close method will perform a <tt>flush</tt> and then close the
* <tt>Handler</tt>. After close has been called this <tt>Handler</tt>
* should no longer be used. Method calls may either be silently
* ignored or may throw runtime exceptions.
*
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public abstract void
close() throws
SecurityException;
/**
* Set a <tt>Formatter</tt>. This <tt>Formatter</tt> will be used
* to format <tt>LogRecords</tt> for this <tt>Handler</tt>.
* <p>
* Some <tt>Handlers</tt> may not use <tt>Formatters</tt>, in
* which case the <tt>Formatter</tt> will be remembered, but not used.
* <p>
* @param newFormatter the <tt>Formatter</tt> to use (may not be null)
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public synchronized void
setFormatter(
Formatter newFormatter) throws
SecurityException {
checkPermission();
// Check for a null pointer:
newFormatter.
getClass();
formatter =
newFormatter;
}
/**
* Return the <tt>Formatter</tt> for this <tt>Handler</tt>.
* @return the <tt>Formatter</tt> (may be null).
*/
public
Formatter getFormatter() {
return
formatter;
}
/**
* Set the character encoding used by this <tt>Handler</tt>.
* <p>
* The encoding should be set before any <tt>LogRecords</tt> are written
* to the <tt>Handler</tt>.
*
* @param encoding The name of a supported character encoding.
* May be null, to indicate the default platform encoding.
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
* @exception UnsupportedEncodingException if the named encoding is
* not supported.
*/
public synchronized void
setEncoding(
String encoding)
throws
SecurityException, java.io.
UnsupportedEncodingException {
checkPermission();
if (
encoding != null) {
try {
if(!java.nio.charset.
Charset.
isSupported(
encoding)) {
throw new
UnsupportedEncodingException(
encoding);
}
} catch (java.nio.charset.
IllegalCharsetNameException e) {
throw new
UnsupportedEncodingException(
encoding);
}
}
this.
encoding =
encoding;
}
/**
* Return the character encoding for this <tt>Handler</tt>.
*
* @return The encoding name. May be null, which indicates the
* default encoding should be used.
*/
public
String getEncoding() {
return
encoding;
}
/**
* Set a <tt>Filter</tt> to control output on this <tt>Handler</tt>.
* <P>
* For each call of <tt>publish</tt> the <tt>Handler</tt> will call
* this <tt>Filter</tt> (if it is non-null) to check if the
* <tt>LogRecord</tt> should be published or discarded.
*
* @param newFilter a <tt>Filter</tt> object (may be null)
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public synchronized void
setFilter(
Filter newFilter) throws
SecurityException {
checkPermission();
filter =
newFilter;
}
/**
* Get the current <tt>Filter</tt> for this <tt>Handler</tt>.
*
* @return a <tt>Filter</tt> object (may be null)
*/
public
Filter getFilter() {
return
filter;
}
/**
* Define an ErrorManager for this Handler.
* <p>
* The ErrorManager's "error" method will be invoked if any
* errors occur while using this Handler.
*
* @param em the new ErrorManager
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public synchronized void
setErrorManager(
ErrorManager em) {
checkPermission();
if (
em == null) {
throw new
NullPointerException();
}
errorManager =
em;
}
/**
* Retrieves the ErrorManager for this Handler.
*
* @return the ErrorManager for this Handler
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public
ErrorManager getErrorManager() {
checkPermission();
return
errorManager;
}
/**
* 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.
*
* @param msg a descriptive string (may be null)
* @param ex an exception (may be null)
* @param code an error code defined in ErrorManager
*/
protected void
reportError(
String msg,
Exception ex, int
code) {
try {
errorManager.
error(
msg,
ex,
code);
} catch (
Exception ex2) {
System.
err.
println("Handler.reportError caught:");
ex2.
printStackTrace();
}
}
/**
* Set the log level specifying which message levels will be
* logged by this <tt>Handler</tt>. Message levels lower than this
* value will be discarded.
* <p>
* The intention is to allow developers to turn on voluminous
* logging, but to limit the messages that are sent to certain
* <tt>Handlers</tt>.
*
* @param newLevel the new value for the log level
* @exception SecurityException if a security manager exists and if
* the caller does not have <tt>LoggingPermission("control")</tt>.
*/
public synchronized void
setLevel(
Level newLevel) throws
SecurityException {
if (
newLevel == null) {
throw new
NullPointerException();
}
checkPermission();
logLevel =
newLevel;
}
/**
* Get the log level specifying which messages will be
* logged by this <tt>Handler</tt>. Message levels lower
* than this level will be discarded.
* @return the level of messages being logged.
*/
public
Level getLevel() {
return
logLevel;
}
/**
* Check if this <tt>Handler</tt> would actually log a given <tt>LogRecord</tt>.
* <p>
* This method checks if the <tt>LogRecord</tt> has an appropriate
* <tt>Level</tt> and whether it satisfies any <tt>Filter</tt>. It also
* may make other <tt>Handler</tt> specific checks that might prevent a
* handler from logging the <tt>LogRecord</tt>. It will return false if
* the <tt>LogRecord</tt> is null.
* <p>
* @param record a <tt>LogRecord</tt>
* @return true if the <tt>LogRecord</tt> would be logged.
*
*/
public boolean
isLoggable(
LogRecord record) {
final int
levelValue =
getLevel().
intValue();
if (
record.
getLevel().
intValue() <
levelValue ||
levelValue ==
offValue) {
return false;
}
final
Filter filter =
getFilter();
if (
filter == null) {
return true;
}
return
filter.
isLoggable(
record);
}
// Package-private support method for security checks.
// If "sealed" is true, we check that the caller has
// appropriate security privileges to update Handler
// state and if not throw a SecurityException.
void
checkPermission() throws
SecurityException {
if (
sealed) {
manager.
checkPermission();
}
}
}