1 /*
   2  * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 
  27 package java.util.logging;
  28 
  29 import java.io.UnsupportedEncodingException;



  30 /**
  31  * A <tt>Handler</tt> object takes log messages from a <tt>Logger</tt> and
  32  * exports them.  It might for example, write them to a console
  33  * or write them to a file, or send them to a network logging service,
  34  * or forward them to an OS log, or whatever.
  35  * <p>
  36  * A <tt>Handler</tt> can be disabled by doing a <tt>setLevel(Level.OFF)</tt>
  37  * and can  be re-enabled by doing a <tt>setLevel</tt> with an appropriate level.
  38  * <p>
  39  * <tt>Handler</tt> classes typically use <tt>LogManager</tt> properties to set
  40  * default values for the <tt>Handler</tt>'s <tt>Filter</tt>, <tt>Formatter</tt>,
  41  * and <tt>Level</tt>.  See the specific documentation for each concrete
  42  * <tt>Handler</tt> class.
  43  *
  44  *
  45  * @since 1.4
  46  */
  47 
  48 public abstract class Handler {
  49     private static final int offValue = Level.OFF.intValue();
  50     private final LogManager manager = LogManager.getLogManager();
  51 
  52     // We're using volatile here to avoid synchronizing getters, which
  53     // would prevent other threads from calling isLoggable()
  54     // while publish() is executing.
  55     // On the other hand, setters will be synchronized to exclude concurrent
  56     // execution with more complex methods, such as StreamHandler.publish().
  57     // We wouldn't want 'level' to be changed by another thread in the middle
  58     // of the execution of a 'publish' call.
  59     private volatile Filter filter;
  60     private volatile Formatter formatter;
  61     private volatile Level logLevel = Level.ALL;
  62     private volatile ErrorManager errorManager = new ErrorManager();
  63     private volatile String encoding;
  64 
  65     // Package private support for security checking.  When sealed
  66     // is true, we access check updates to the class.
  67     boolean sealed = true;
  68 
  69     /**
  70      * Default constructor.  The resulting <tt>Handler</tt> has a log
  71      * level of <tt>Level.ALL</tt>, no <tt>Formatter</tt>, and no
  72      * <tt>Filter</tt>.  A default <tt>ErrorManager</tt> instance is installed
  73      * as the <tt>ErrorManager</tt>.
  74      */
  75     protected Handler() {
  76     }
  77 
  78     /**
  79      * Publish a <tt>LogRecord</tt>.
  80      * <p>
  81      * The logging request was made initially to a <tt>Logger</tt> object,
  82      * which initialized the <tt>LogRecord</tt> and forwarded it here.
  83      * <p>
  84      * The <tt>Handler</tt>  is responsible for formatting the message, when and
  85      * if necessary.  The formatting should include localization.
  86      *
  87      * @param  record  description of the log event. A null record is
  88      *                 silently ignored and is not published
  89      */
  90     public abstract void publish(LogRecord record);
  91 
  92     /**
  93      * Flush any buffered output.
  94      */
  95     public abstract void flush();
  96 
  97     /**
  98      * Close the <tt>Handler</tt> and free all associated resources.
  99      * <p>
 100      * The close method will perform a <tt>flush</tt> and then close the
 101      * <tt>Handler</tt>.   After close has been called this <tt>Handler</tt>
 102      * should no longer be used.  Method calls may either be silently
 103      * ignored or may throw runtime exceptions.
 104      *
 105      * @exception  SecurityException  if a security manager exists and if
 106      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 107      */
 108     public abstract void close() throws SecurityException;
 109 
 110     /**
 111      * Set a <tt>Formatter</tt>.  This <tt>Formatter</tt> will be used
 112      * to format <tt>LogRecords</tt> for this <tt>Handler</tt>.
 113      * <p>
 114      * Some <tt>Handlers</tt> may not use <tt>Formatters</tt>, in
 115      * which case the <tt>Formatter</tt> will be remembered, but not used.
 116      * <p>
 117      * @param newFormatter the <tt>Formatter</tt> to use (may not be null)
 118      * @exception  SecurityException  if a security manager exists and if
 119      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 120      */
 121     public synchronized void setFormatter(Formatter newFormatter) throws SecurityException {
 122         checkPermission();
 123         // Check for a null pointer:
 124         newFormatter.getClass();
 125         formatter = newFormatter;
 126     }
 127 
 128     /**
 129      * Return the <tt>Formatter</tt> for this <tt>Handler</tt>.
 130      * @return the <tt>Formatter</tt> (may be null).
 131      */
 132     public Formatter getFormatter() {
 133         return formatter;
 134     }
 135 
 136     /**
 137      * Set the character encoding used by this <tt>Handler</tt>.
 138      * <p>
 139      * The encoding should be set before any <tt>LogRecords</tt> are written
 140      * to the <tt>Handler</tt>.
 141      *
 142      * @param encoding  The name of a supported character encoding.
 143      *        May be null, to indicate the default platform encoding.
 144      * @exception  SecurityException  if a security manager exists and if
 145      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 146      * @exception  UnsupportedEncodingException if the named encoding is
 147      *          not supported.
 148      */
 149     public synchronized void setEncoding(String encoding)
 150                         throws SecurityException, java.io.UnsupportedEncodingException {
 151         checkPermission();
 152         if (encoding != null) {
 153             try {
 154                 if(!java.nio.charset.Charset.isSupported(encoding)) {
 155                     throw new UnsupportedEncodingException(encoding);
 156                 }
 157             } catch (java.nio.charset.IllegalCharsetNameException e) {
 158                 throw new UnsupportedEncodingException(encoding);
 159             }
 160         }
 161         this.encoding = encoding;
 162     }
 163 
 164     /**
 165      * Return the character encoding for this <tt>Handler</tt>.
 166      *
 167      * @return  The encoding name.  May be null, which indicates the
 168      *          default encoding should be used.
 169      */
 170     public String getEncoding() {
 171         return encoding;
 172     }
 173 
 174     /**
 175      * Set a <tt>Filter</tt> to control output on this <tt>Handler</tt>.
 176      * <P>
 177      * For each call of <tt>publish</tt> the <tt>Handler</tt> will call
 178      * this <tt>Filter</tt> (if it is non-null) to check if the
 179      * <tt>LogRecord</tt> should be published or discarded.
 180      *
 181      * @param   newFilter  a <tt>Filter</tt> object (may be null)
 182      * @exception  SecurityException  if a security manager exists and if
 183      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 184      */
 185     public synchronized void setFilter(Filter newFilter) throws SecurityException {
 186         checkPermission();
 187         filter = newFilter;
 188     }
 189 
 190     /**
 191      * Get the current <tt>Filter</tt> for this <tt>Handler</tt>.
 192      *
 193      * @return  a <tt>Filter</tt> object (may be null)
 194      */
 195     public Filter getFilter() {
 196         return filter;
 197     }
 198 
 199     /**
 200      * Define an ErrorManager for this Handler.
 201      * <p>
 202      * The ErrorManager's "error" method will be invoked if any
 203      * errors occur while using this Handler.
 204      *
 205      * @param em  the new ErrorManager
 206      * @exception  SecurityException  if a security manager exists and if
 207      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 208      */
 209     public synchronized void setErrorManager(ErrorManager em) {
 210         checkPermission();
 211         if (em == null) {
 212            throw new NullPointerException();
 213         }
 214         errorManager = em;
 215     }
 216 
 217     /**
 218      * Retrieves the ErrorManager for this Handler.
 219      *
 220      * @return the ErrorManager for this Handler
 221      * @exception  SecurityException  if a security manager exists and if
 222      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 223      */
 224     public ErrorManager getErrorManager() {
 225         checkPermission();
 226         return errorManager;
 227     }
 228 
 229    /**
 230      * Protected convenience method to report an error to this Handler's
 231      * ErrorManager.  Note that this method retrieves and uses the ErrorManager
 232      * without doing a security check.  It can therefore be used in
 233      * environments where the caller may be non-privileged.
 234      *
 235      * @param msg    a descriptive string (may be null)
 236      * @param ex     an exception (may be null)
 237      * @param code   an error code defined in ErrorManager
 238      */
 239     protected void reportError(String msg, Exception ex, int code) {
 240         try {
 241             errorManager.error(msg, ex, code);
 242         } catch (Exception ex2) {
 243             System.err.println("Handler.reportError caught:");
 244             ex2.printStackTrace();
 245         }
 246     }
 247 
 248     /**
 249      * Set the log level specifying which message levels will be
 250      * logged by this <tt>Handler</tt>.  Message levels lower than this
 251      * value will be discarded.
 252      * <p>
 253      * The intention is to allow developers to turn on voluminous
 254      * logging, but to limit the messages that are sent to certain
 255      * <tt>Handlers</tt>.
 256      *
 257      * @param newLevel   the new value for the log level
 258      * @exception  SecurityException  if a security manager exists and if
 259      *             the caller does not have <tt>LoggingPermission("control")</tt>.
 260      */
 261     public synchronized void setLevel(Level newLevel) throws SecurityException {
 262         if (newLevel == null) {
 263             throw new NullPointerException();
 264         }
 265         checkPermission();
 266         logLevel = newLevel;
 267     }
 268 
 269     /**
 270      * Get the log level specifying which messages will be
 271      * logged by this <tt>Handler</tt>.  Message levels lower
 272      * than this level will be discarded.
 273      * @return  the level of messages being logged.
 274      */
 275     public Level getLevel() {
 276         return logLevel;
 277     }
 278 
 279     /**
 280      * Check if this <tt>Handler</tt> would actually log a given <tt>LogRecord</tt>.
 281      * <p>
 282      * This method checks if the <tt>LogRecord</tt> has an appropriate
 283      * <tt>Level</tt> and  whether it satisfies any <tt>Filter</tt>.  It also
 284      * may make other <tt>Handler</tt> specific checks that might prevent a
 285      * handler from logging the <tt>LogRecord</tt>. It will return false if
 286      * the <tt>LogRecord</tt> is null.
 287      * <p>
 288      * @param record  a <tt>LogRecord</tt>
 289      * @return true if the <tt>LogRecord</tt> would be logged.
 290      *
 291      */
 292     public boolean isLoggable(LogRecord record) {
 293         final int levelValue = getLevel().intValue();
 294         if (record.getLevel().intValue() < levelValue || levelValue == offValue) {
 295             return false;
 296         }
 297         final Filter filter = getFilter();
 298         if (filter == null) {
 299             return true;
 300         }
 301         return filter.isLoggable(record);
 302     }
 303 
 304     // Package-private support method for security checks.
 305     // If "sealed" is true, we check that the caller has
 306     // appropriate security privileges to update Handler
 307     // state and if not throw a SecurityException.
 308     void checkPermission() throws SecurityException {
 309         if (sealed) {
 310             manager.checkPermission();
 311         }










 312     }
 313 }
--- EOF ---