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      */
Handler()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      */
publish(LogRecord record)90     public abstract void publish(LogRecord record);
91 
92     /**
93      * Flush any buffered output.
94      */
flush()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      */
close()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      */
setFormatter(Formatter newFormatter)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      */
getFormatter()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      */
setEncoding(String encoding)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      */
getEncoding()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      */
setFilter(Filter newFilter)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      */
getFilter()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      */
setErrorManager(ErrorManager em)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      */
getErrorManager()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      */
reportError(String msg, Exception ex, int code)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      */
setLevel(Level newLevel)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      */
getLevel()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      */
isLoggable(LogRecord record)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.
checkPermission()308     void checkPermission() throws SecurityException {
309         if (sealed) {
310             manager.checkPermission();
311         }
312     }
313 }
314