Back to index...

	/*
	* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/


	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();
	}
	}
	}

Back to index...