--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.logging/share/classes/java/util/logging/Handler.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,354 @@
+/*
+ * 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.util.Objects;
+import java.io.UnsupportedEncodingException;
+import java.security.AccessController;
+import java.security.PrivilegedAction;
+
+/**
+ * A {@code Handler} object takes log messages from a {@code Logger} 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 {@code Handler} can be disabled by doing a {@code setLevel(Level.OFF)}
+ * and can be re-enabled by doing a {@code setLevel} with an appropriate level.
+ * <p>
+ * {@code Handler} classes typically use {@code LogManager} properties to set
+ * default values for the {@code Handler}'s {@code Filter}, {@code Formatter},
+ * and {@code Level}. See the specific documentation for each concrete
+ * {@code 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;
+
+ /**
+ * Default constructor. The resulting {@code Handler} has a log
+ * level of {@code Level.ALL}, no {@code Formatter}, and no
+ * {@code Filter}. A default {@code ErrorManager} instance is installed
+ * as the {@code ErrorManager}.
+ */
+ protected Handler() {
+ }
+
+ /**
+ * Package-private constructor for chaining from subclass constructors
+ * that wish to configure the handler with specific default and/or
+ * specified values.
+ *
+ * @param defaultLevel a default {@link Level} to configure if one is
+ * not found in LogManager configuration properties
+ * @param defaultFormatter a default {@link Formatter} to configure if one is
+ * not specified by {@code specifiedFormatter} parameter
+ * nor found in LogManager configuration properties
+ * @param specifiedFormatter if not null, this is the formatter to configure
+ */
+ Handler(Level defaultLevel, Formatter defaultFormatter,
+ Formatter specifiedFormatter) {
+
+ LogManager manager = LogManager.getLogManager();
+ String cname = getClass().getName();
+
+ final Level level = manager.getLevelProperty(cname + ".level", defaultLevel);
+ final Filter filter = manager.getFilterProperty(cname + ".filter", null);
+ final Formatter formatter = specifiedFormatter == null
+ ? manager.getFormatterProperty(cname + ".formatter", defaultFormatter)
+ : specifiedFormatter;
+ final String encoding = manager.getStringProperty(cname + ".encoding", null);
+
+ AccessController.doPrivileged(new PrivilegedAction<Void>() {
+ @Override
+ public Void run() {
+ setLevel(level);
+ setFilter(filter);
+ setFormatter(formatter);
+ try {
+ setEncoding(encoding);
+ } catch (Exception ex) {
+ try {
+ setEncoding(null);
+ } catch (Exception ex2) {
+ // doing a setEncoding with null should always work.
+ // assert false;
+ }
+ }
+ return null;
+ }
+ }, null, LogManager.controlPermission);
+ }
+
+ /**
+ * Publish a {@code LogRecord}.
+ * <p>
+ * The logging request was made initially to a {@code Logger} object,
+ * which initialized the {@code LogRecord} and forwarded it here.
+ * <p>
+ * The {@code 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 {@code Handler} and free all associated resources.
+ * <p>
+ * The close method will perform a {@code flush} and then close the
+ * {@code Handler}. After close has been called this {@code 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 {@code LoggingPermission("control")}.
+ */
+ public abstract void close() throws SecurityException;
+
+ /**
+ * Set a {@code Formatter}. This {@code Formatter} will be used
+ * to format {@code LogRecords} for this {@code Handler}.
+ * <p>
+ * Some {@code Handlers} may not use {@code Formatters}, in
+ * which case the {@code Formatter} will be remembered, but not used.
+ *
+ * @param newFormatter the {@code Formatter} to use (may not be null)
+ * @exception SecurityException if a security manager exists and if
+ * the caller does not have {@code LoggingPermission("control")}.
+ */
+ public synchronized void setFormatter(Formatter newFormatter) throws SecurityException {
+ checkPermission();
+ formatter = Objects.requireNonNull(newFormatter);
+ }
+
+ /**
+ * Return the {@code Formatter} for this {@code Handler}.
+ * @return the {@code Formatter} (may be null).
+ */
+ public Formatter getFormatter() {
+ return formatter;
+ }
+
+ /**
+ * Set the character encoding used by this {@code Handler}.
+ * <p>
+ * The encoding should be set before any {@code LogRecords} are written
+ * to the {@code 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 {@code 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 {@code Handler}.
+ *
+ * @return The encoding name. May be null, which indicates the
+ * default encoding should be used.
+ */
+ public String getEncoding() {
+ return encoding;
+ }
+
+ /**
+ * Set a {@code Filter} to control output on this {@code Handler}.
+ * <P>
+ * For each call of {@code publish} the {@code Handler} will call
+ * this {@code Filter} (if it is non-null) to check if the
+ * {@code LogRecord} should be published or discarded.
+ *
+ * @param newFilter a {@code Filter} object (may be null)
+ * @exception SecurityException if a security manager exists and if
+ * the caller does not have {@code LoggingPermission("control")}.
+ */
+ public synchronized void setFilter(Filter newFilter) throws SecurityException {
+ checkPermission();
+ filter = newFilter;
+ }
+
+ /**
+ * Get the current {@code Filter} for this {@code Handler}.
+ *
+ * @return a {@code Filter} 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 {@code 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 {@code 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 {@code Handler}. 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
+ * {@code Handlers}.
+ *
+ * @param newLevel the new value for the log level
+ * @exception SecurityException if a security manager exists and if
+ * the caller does not have {@code 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 {@code 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 {@code Handler} would actually log a given {@code LogRecord}.
+ * <p>
+ * This method checks if the {@code LogRecord} has an appropriate
+ * {@code Level} and whether it satisfies any {@code Filter}. It also
+ * may make other {@code Handler} specific checks that might prevent a
+ * handler from logging the {@code LogRecord}. It will return false if
+ * the {@code LogRecord} is null.
+ *
+ * @param record a {@code LogRecord}
+ * @return true if the {@code 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.
+ // We check that the caller has appropriate security privileges
+ // to update Handler state and if not throw a SecurityException.
+ void checkPermission() throws SecurityException {
+ manager.checkPermission();
+ }
+}