001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.util.logging;
027
028 import java.io.UnsupportedEncodingException;
029
030 /**
031 * A <tt>Handler</tt> object takes log messages from a <tt>Logger</tt> and
032 * exports them. It might for example, write them to a console
033 * or write them to a file, or send them to a network logging service,
034 * or forward them to an OS log, or whatever.
035 * <p>
036 * A <tt>Handler</tt> can be disabled by doing a <tt>setLevel(Level.OFF)</tt>
037 * and can be re-enabled by doing a <tt>setLevel</tt> with an appropriate level.
038 * <p>
039 * <tt>Handler</tt> classes typically use <tt>LogManager</tt> properties to set
040 * default values for the <tt>Handler</tt>'s <tt>Filter</tt>, <tt>Formatter</tt>,
041 * and <tt>Level</tt>. See the specific documentation for each concrete
042 * <tt>Handler</tt> class.
043 *
044 *
045 * @version 1.27, 05/05/07
046 * @since 1.4
047 */
048
049 public abstract class Handler {
050 private static final int offValue = Level.OFF.intValue();
051 private LogManager manager = LogManager.getLogManager();
052 private Filter filter;
053 private Formatter formatter;
054 private Level logLevel = Level.ALL;
055 private ErrorManager errorManager = new ErrorManager();
056 private String encoding;
057
058 // Package private support for security checking. When sealed
059 // is true, we access check updates to the class.
060 boolean sealed = true;
061
062 /**
063 * Default constructor. The resulting <tt>Handler</tt> has a log
064 * level of <tt>Level.ALL</tt>, no <tt>Formatter</tt>, and no
065 * <tt>Filter</tt>. A default <tt>ErrorManager</tt> instance is installed
066 * as the <tt>ErrorManager</tt>.
067 */
068 protected Handler() {
069 }
070
071 /**
072 * Publish a <tt>LogRecord</tt>.
073 * <p>
074 * The logging request was made initially to a <tt>Logger</tt> object,
075 * which initialized the <tt>LogRecord</tt> and forwarded it here.
076 * <p>
077 * The <tt>Handler</tt> is responsible for formatting the message, when and
078 * if necessary. The formatting should include localization.
079 *
080 * @param record description of the log event. A null record is
081 * silently ignored and is not published
082 */
083 public abstract void publish(LogRecord record);
084
085 /**
086 * Flush any buffered output.
087 */
088 public abstract void flush();
089
090 /**
091 * Close the <tt>Handler</tt> and free all associated resources.
092 * <p>
093 * The close method will perform a <tt>flush</tt> and then close the
094 * <tt>Handler</tt>. After close has been called this <tt>Handler</tt>
095 * should no longer be used. Method calls may either be silently
096 * ignored or may throw runtime exceptions.
097 *
098 * @exception SecurityException if a security manager exists and if
099 * the caller does not have <tt>LoggingPermission("control")</tt>.
100 */
101 public abstract void close() throws SecurityException;
102
103 /**
104 * Set a <tt>Formatter</tt>. This <tt>Formatter</tt> will be used
105 * to format <tt>LogRecords</tt> for this <tt>Handler</tt>.
106 * <p>
107 * Some <tt>Handlers</tt> may not use <tt>Formatters</tt>, in
108 * which case the <tt>Formatter</tt> will be remembered, but not used.
109 * <p>
110 * @param newFormatter the <tt>Formatter</tt> to use (may not be null)
111 * @exception SecurityException if a security manager exists and if
112 * the caller does not have <tt>LoggingPermission("control")</tt>.
113 */
114 public void setFormatter(Formatter newFormatter)
115 throws SecurityException {
116 checkAccess();
117 // Check for a null pointer:
118 newFormatter.getClass();
119 formatter = newFormatter;
120 }
121
122 /**
123 * Return the <tt>Formatter</tt> for this <tt>Handler</tt>.
124 * @return the <tt>Formatter</tt> (may be null).
125 */
126 public Formatter getFormatter() {
127 return formatter;
128 }
129
130 /**
131 * Set the character encoding used by this <tt>Handler</tt>.
132 * <p>
133 * The encoding should be set before any <tt>LogRecords</tt> are written
134 * to the <tt>Handler</tt>.
135 *
136 * @param encoding The name of a supported character encoding.
137 * May be null, to indicate the default platform encoding.
138 * @exception SecurityException if a security manager exists and if
139 * the caller does not have <tt>LoggingPermission("control")</tt>.
140 * @exception UnsupportedEncodingException if the named encoding is
141 * not supported.
142 */
143 public void setEncoding(String encoding) throws SecurityException,
144 java.io.UnsupportedEncodingException {
145 checkAccess();
146 if (encoding != null) {
147 try {
148 if (!java.nio.charset.Charset.isSupported(encoding)) {
149 throw new UnsupportedEncodingException(encoding);
150 }
151 } catch (java.nio.charset.IllegalCharsetNameException e) {
152 throw new UnsupportedEncodingException(encoding);
153 }
154 }
155 this .encoding = encoding;
156 }
157
158 /**
159 * Return the character encoding for this <tt>Handler</tt>.
160 *
161 * @return The encoding name. May be null, which indicates the
162 * default encoding should be used.
163 */
164 public String getEncoding() {
165 return encoding;
166 }
167
168 /**
169 * Set a <tt>Filter</tt> to control output on this <tt>Handler</tt>.
170 * <P>
171 * For each call of <tt>publish</tt> the <tt>Handler</tt> will call
172 * this <tt>Filter</tt> (if it is non-null) to check if the
173 * <tt>LogRecord</tt> should be published or discarded.
174 *
175 * @param newFilter a <tt>Filter</tt> object (may be null)
176 * @exception SecurityException if a security manager exists and if
177 * the caller does not have <tt>LoggingPermission("control")</tt>.
178 */
179 public void setFilter(Filter newFilter) throws SecurityException {
180 checkAccess();
181 filter = newFilter;
182 }
183
184 /**
185 * Get the current <tt>Filter</tt> for this <tt>Handler</tt>.
186 *
187 * @return a <tt>Filter</tt> object (may be null)
188 */
189 public Filter getFilter() {
190 return filter;
191 }
192
193 /**
194 * Define an ErrorManager for this Handler.
195 * <p>
196 * The ErrorManager's "error" method will be invoked if any
197 * errors occur while using this Handler.
198 *
199 * @param em the new ErrorManager
200 * @exception SecurityException if a security manager exists and if
201 * the caller does not have <tt>LoggingPermission("control")</tt>.
202 */
203 public void setErrorManager(ErrorManager em) {
204 checkAccess();
205 if (em == null) {
206 throw new NullPointerException();
207 }
208 errorManager = em;
209 }
210
211 /**
212 * Retrieves the ErrorManager for this Handler.
213 *
214 * @exception SecurityException if a security manager exists and if
215 * the caller does not have <tt>LoggingPermission("control")</tt>.
216 */
217 public ErrorManager getErrorManager() {
218 checkAccess();
219 return errorManager;
220 }
221
222 /**
223 * Protected convenience method to report an error to this Handler's
224 * ErrorManager. Note that this method retrieves and uses the ErrorManager
225 * without doing a security check. It can therefore be used in
226 * environments where the caller may be non-privileged.
227 *
228 * @param msg a descriptive string (may be null)
229 * @param ex an exception (may be null)
230 * @param code an error code defined in ErrorManager
231 */
232 protected void reportError(String msg, Exception ex, int code) {
233 try {
234 errorManager.error(msg, ex, code);
235 } catch (Exception ex2) {
236 System.err.println("Handler.reportError caught:");
237 ex2.printStackTrace();
238 }
239 }
240
241 /**
242 * Set the log level specifying which message levels will be
243 * logged by this <tt>Handler</tt>. Message levels lower than this
244 * value will be discarded.
245 * <p>
246 * The intention is to allow developers to turn on voluminous
247 * logging, but to limit the messages that are sent to certain
248 * <tt>Handlers</tt>.
249 *
250 * @param newLevel the new value for the log level
251 * @exception SecurityException if a security manager exists and if
252 * the caller does not have <tt>LoggingPermission("control")</tt>.
253 */
254 public synchronized void setLevel(Level newLevel)
255 throws SecurityException {
256 if (newLevel == null) {
257 throw new NullPointerException();
258 }
259 checkAccess();
260 logLevel = newLevel;
261 }
262
263 /**
264 * Get the log level specifying which messages will be
265 * logged by this <tt>Handler</tt>. Message levels lower
266 * than this level will be discarded.
267 * @return the level of messages being logged.
268 */
269 public synchronized Level getLevel() {
270 return logLevel;
271 }
272
273 /**
274 * Check if this <tt>Handler</tt> would actually log a given <tt>LogRecord</tt>.
275 * <p>
276 * This method checks if the <tt>LogRecord</tt> has an appropriate
277 * <tt>Level</tt> and whether it satisfies any <tt>Filter</tt>. It also
278 * may make other <tt>Handler</tt> specific checks that might prevent a
279 * handler from logging the <tt>LogRecord</tt>. It will return false if
280 * the <tt>LogRecord</tt> is Null.
281 * <p>
282 * @param record a <tt>LogRecord</tt>
283 * @return true if the <tt>LogRecord</tt> would be logged.
284 *
285 */
286 public boolean isLoggable(LogRecord record) {
287 int levelValue = getLevel().intValue();
288 if (record.getLevel().intValue() < levelValue
289 || levelValue == offValue) {
290 return false;
291 }
292 Filter filter = getFilter();
293 if (filter == null) {
294 return true;
295 }
296 return filter.isLoggable(record);
297 }
298
299 // Package-private support method for security checks.
300 // If "sealed" is true, we check that the caller has
301 // appropriate security privileges to update Handler
302 // state and if not throw a SecurityException.
303 void checkAccess() throws SecurityException {
304 if (sealed) {
305 manager.checkAccess();
306 }
307 }
308 }
|