* A Handler can be disabled by doing a setLevel(Level.OFF) * and can be re-enabled by doing a setLevel with an appropriate level. *
* Handler classes typically use LogManager properties to set * default values for the Handler's Filter, Formatter, * and Level. See the specific documentation for each concrete * Handler 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 Handler has a log * level of Level.ALL, no Formatter, and no * Filter. A default ErrorManager instance is installed * as the ErrorManager. */ protected Handler() { } /** * Publish a LogRecord. *
* The logging request was made initially to a Logger object, * which initialized the LogRecord and forwarded it here. *
* The Handler 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 Handler and free all associated resources. *
* The close method will perform a flush and then close the * Handler. After close has been called this Handler * 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 LoggingPermission("control"). */ public abstract void close() throws SecurityException; /** * Set a Formatter. This Formatter will be used * to format LogRecords for this Handler. *
* Some Handlers may not use Formatters, in * which case the Formatter will be remembered, but not used. *
* @param newFormatter the Formatter to use (may not be null) * @exception SecurityException if a security manager exists and if * the caller does not have LoggingPermission("control"). */ public synchronized void setFormatter(Formatter newFormatter) throws SecurityException { checkPermission(); // Check for a null pointer: newFormatter.getClass(); formatter = newFormatter; } /** * Return the Formatter for this Handler. * @return the Formatter (may be null). */ public Formatter getFormatter() { return formatter; } /** * Set the character encoding used by this Handler. *
* The encoding should be set before any LogRecords are written * to the Handler. * * @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 LoggingPermission("control"). * @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 Handler. * * @return The encoding name. May be null, which indicates the * default encoding should be used. */ public String getEncoding() { return encoding; } /** * Set a Filter to control output on this Handler. *
* For each call of publish the Handler will call * this Filter (if it is non-null) to check if the * LogRecord should be published or discarded. * * @param newFilter a Filter object (may be null) * @exception SecurityException if a security manager exists and if * the caller does not have LoggingPermission("control"). */ public synchronized void setFilter(Filter newFilter) throws SecurityException { checkPermission(); filter = newFilter; } /** * Get the current Filter for this Handler. * * @return a Filter object (may be null) */ public Filter getFilter() { return filter; } /** * Define an ErrorManager for this Handler. *
* 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 LoggingPermission("control"). */ 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 LoggingPermission("control"). */ 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 Handler. 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. * * @param newLevel the new value for the log level * @exception SecurityException if a security manager exists and if * the caller does not have LoggingPermission("control"). */ 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 Handler. Message levels lower * than this level will be discarded. * @return the level of messages being logged. */ public Level getLevel() { return logLevel; } /** * Check if this Handler would actually log a given LogRecord. *
* This method checks if the LogRecord has an appropriate * Level and whether it satisfies any Filter. It also * may make other Handler specific checks that might prevent a * handler from logging the LogRecord. It will return false if * the LogRecord is null. *
* @param record a LogRecord * @return true if the LogRecord 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(); } } }