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