001/* Handler.java -- a class for publishing log messages 002 Copyright (C) 2002, 2004 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.util.logging; 040 041import java.io.UnsupportedEncodingException; 042 043/** 044 * A <code>Handler</code> publishes <code>LogRecords</code> to 045 * a sink, for example a file, the console or a network socket. 046 * There are different subclasses of <code>Handler</code> 047 * to deal with different kinds of sinks. 048 * 049 * <p>FIXME: Are handlers thread-safe, or is the assumption that only 050 * loggers are, and a handler can belong only to one single logger? If 051 * the latter, should we enforce it? (Spec not clear). In any 052 * case, it needs documentation. 053 * 054 * @author Sascha Brawer (brawer@acm.org) 055 */ 056public abstract class Handler 057{ 058 Formatter formatter; 059 Filter filter; 060 Level level; 061 ErrorManager errorManager; 062 String encoding; 063 064 /** 065 * Constructs a Handler with a logging severity level of 066 * <code>Level.ALL</code>, no formatter, no filter, and 067 * an instance of <code>ErrorManager</code> managing errors. 068 * 069 * <p><strong>Specification Note:</strong> The specification of the 070 * Java<sup>TM</sup> Logging API does not mention which character 071 * encoding is to be used by freshly constructed Handlers. The GNU 072 * implementation uses the default platform encoding, but other 073 * Java implementations might behave differently. 074 * 075 * <p><strong>Specification Note:</strong> While a freshly constructed 076 * Handler is required to have <em>no filter</em> according to the 077 * specification, <code>null</code> is not a valid parameter for 078 * <code>Handler.setFormatter</code>. Therefore, the following 079 * code will throw a <code>java.lang.NullPointerException</code>: 080 * 081 * <p><pre>Handler h = new MyConcreteSubclassOfHandler(); 082h.setFormatter(h.getFormatter());</pre> 083 * 084 * It seems strange that a freshly constructed Handler is not 085 * supposed to provide a Formatter, but this is what the specification 086 * says. 087 */ 088 protected Handler() 089 { 090 level = Level.ALL; 091 } 092 093 094 /** 095 * Publishes a <code>LogRecord</code> to an appropriate sink, 096 * provided the record passes all tests for being loggable. The 097 * <code>Handler</code> will localize the message of the log 098 * record and substitute any message parameters. 099 * 100 * <p>Most applications do not need to call this method directly. 101 * Instead, they will use use a {@link Logger}, which will 102 * create LogRecords and distribute them to registered handlers. 103 * 104 * <p>In case of an I/O failure, the <code>ErrorManager</code> 105 * of this <code>Handler</code> will be informed, but the caller 106 * of this method will not receive an exception. 107 * 108 * @param record the log event to be published. 109 */ 110 public abstract void publish(LogRecord record); 111 112 113 /** 114 * Forces any data that may have been buffered to the underlying 115 * output device. 116 * 117 * <p>In case of an I/O failure, the <code>ErrorManager</code> 118 * of this <code>Handler</code> will be informed, but the caller 119 * of this method will not receive an exception. 120 */ 121 public abstract void flush(); 122 123 124 /** 125 * Closes this <code>Handler</code> after having flushed 126 * the buffers. As soon as <code>close</code> has been called, 127 * a <code>Handler</code> should not be used anymore. Attempts 128 * to publish log records, to flush buffers, or to modify the 129 * <code>Handler</code> in any other way may throw runtime 130 * exceptions after calling <code>close</code>. 131 * 132 * <p>In case of an I/O failure, the <code>ErrorManager</code> 133 * of this <code>Handler</code> will be informed, but the caller 134 * of this method will not receive an exception. 135 * 136 * @throws SecurityException if a security manager exists and 137 * the caller is not granted the permission to control 138 * the logging infrastructure. 139 */ 140 public abstract void close() 141 throws SecurityException; 142 143 144 /** 145 * Returns the <code>Formatter</code> which will be used to 146 * localize the text of log messages and to substitute 147 * message parameters. A <code>Handler</code> is encouraged, 148 * but not required to actually use an assigned 149 * <code>Formatter</code>. 150 * 151 * @return the <code>Formatter</code> being used, or 152 * <code>null</code> if this <code>Handler</code> 153 * does not use formatters and no formatter has 154 * ever been set by calling <code>setFormatter</code>. 155 */ 156 public Formatter getFormatter() 157 { 158 return formatter; 159 } 160 161 162 /** 163 * Sets the <code>Formatter</code> which will be used to 164 * localize the text of log messages and to substitute 165 * message parameters. A <code>Handler</code> is encouraged, 166 * but not required to actually use an assigned 167 * <code>Formatter</code>. 168 * 169 * @param formatter the new <code>Formatter</code> to use. 170 * 171 * @throws SecurityException if a security manager exists and 172 * the caller is not granted the permission to control 173 * the logging infrastructure. 174 * 175 * @throws NullPointerException if <code>formatter</code> is 176 * <code>null</code>. 177 */ 178 public void setFormatter(Formatter formatter) 179 throws SecurityException 180 { 181 LogManager.getLogManager().checkAccess(); 182 183 /* Throws a NullPointerException if formatter is null. */ 184 formatter.getClass(); 185 186 this.formatter = formatter; 187 } 188 189 190 /** 191 * Returns the character encoding which this handler uses for publishing 192 * log records. 193 * 194 * @return the name of a character encoding, or <code>null</code> 195 * for the default platform encoding. 196 */ 197 public String getEncoding() 198 { 199 return encoding; 200 } 201 202 203 /** 204 * Sets the character encoding which this handler uses for publishing 205 * log records. The encoding of a <code>Handler</code> must be 206 * set before any log records have been published. 207 * 208 * @param encoding the name of a character encoding, or <code>null</code> 209 * for the default encoding. 210 * 211 * @exception SecurityException if a security manager exists and 212 * the caller is not granted the permission to control 213 * the logging infrastructure. 214 * 215 */ 216 public void setEncoding(String encoding) 217 throws SecurityException, UnsupportedEncodingException 218 { 219 /* Should any developer ever change this implementation, they are 220 * advised to have a look at StreamHandler.setEncoding(String), 221 * which overrides this method without calling super.setEncoding. 222 */ 223 LogManager.getLogManager().checkAccess(); 224 225 /* Simple check for supported encodings. This is more expensive 226 * than it could be, but this method is overwritten by StreamHandler 227 * anyway. 228 */ 229 if (encoding != null) 230 new String(new byte[0], encoding); 231 232 this.encoding = encoding; 233 } 234 235 236 /** 237 * Returns the <code>Filter</code> that currently controls which 238 * log records are being published by this <code>Handler</code>. 239 * 240 * @return the currently active <code>Filter</code>, or 241 * <code>null</code> if no filter has been associated. 242 * In the latter case, log records are filtered purely 243 * based on their severity level. 244 */ 245 public Filter getFilter() 246 { 247 return filter; 248 } 249 250 251 /** 252 * Sets the <code>Filter</code> for controlling which 253 * log records will be published by this <code>Handler</code>. 254 * 255 * @param filter the <code>Filter</code> to use, or 256 * <code>null</code> to filter log records purely based 257 * on their severity level. 258 */ 259 public void setFilter(Filter filter) 260 throws SecurityException 261 { 262 LogManager.getLogManager().checkAccess(); 263 this.filter = filter; 264 } 265 266 267 /** 268 * Returns the <code>ErrorManager</code> that currently deals 269 * with errors originating from this Handler. 270 * 271 * @exception SecurityException if a security manager exists and 272 * the caller is not granted the permission to control 273 * the logging infrastructure. 274 */ 275 public ErrorManager getErrorManager() 276 { 277 LogManager.getLogManager().checkAccess(); 278 279 /* Developers wanting to change the subsequent code should 280 * have a look at Handler.reportError -- it also can create 281 * an ErrorManager, but does so without checking permissions 282 * to control the logging infrastructure. 283 */ 284 if (errorManager == null) 285 errorManager = new ErrorManager(); 286 287 return errorManager; 288 } 289 290 291 public void setErrorManager(ErrorManager manager) 292 { 293 LogManager.getLogManager().checkAccess(); 294 295 /* Make sure manager is not null. */ 296 manager.getClass(); 297 298 this.errorManager = manager; 299 } 300 301 302 protected void reportError(String message, Exception ex, int code) 303 { 304 if (errorManager == null) 305 errorManager = new ErrorManager(); 306 307 errorManager.error(message, ex, code); 308 } 309 310 311 /** 312 * Returns the severity level threshold for this <code>Handler</code> 313 * All log records with a lower severity level will be discarded; 314 * a log record of the same or a higher level will be published 315 * unless an installed <code>Filter</code> decides to discard it. 316 * 317 * @return the severity level below which all log messages 318 * will be discarded. 319 */ 320 public Level getLevel() 321 { 322 return level; 323 } 324 325 326 /** 327 * Sets the severity level threshold for this <code>Handler</code>. 328 * All log records with a lower severity level will be discarded; 329 * a log record of the same or a higher level will be published 330 * unless an installed <code>Filter</code> decides to discard it. 331 * 332 * @param level the severity level below which all log messages 333 * will be discarded. 334 * 335 * @exception SecurityException if a security manager exists and 336 * the caller is not granted the permission to control 337 * the logging infrastructure. 338 * 339 * @exception NullPointerException if <code>level</code> is 340 * <code>null</code>. 341 */ 342 public void setLevel(Level level) 343 { 344 LogManager.getLogManager().checkAccess(); 345 346 /* Throw NullPointerException if level is null. */ 347 level.getClass(); 348 this.level = level; 349 } 350 351 352 /** 353 * Checks whether a <code>LogRecord</code> would be logged 354 * if it was passed to this <code>Handler</code> for publication. 355 * 356 * <p>The <code>Handler</code> implementation considers a record as 357 * loggable if its level is greater than or equal to the severity 358 * level threshold. In a second step, if a {@link Filter} has 359 * been installed, its {@link Filter#isLoggable(LogRecord) isLoggable} 360 * method is invoked. Subclasses of <code>Handler</code> can override 361 * this method to impose their own constraints. 362 * 363 * @param record the <code>LogRecord</code> to be checked. 364 * 365 * @return <code>true</code> if <code>record</code> would 366 * be published by {@link #publish(LogRecord) publish}, 367 * <code>false</code> if it would be discarded. 368 * 369 * @see #setLevel(Level) 370 * @see #setFilter(Filter) 371 * @see Filter#isLoggable(LogRecord) 372 * 373 * @throws NullPointerException if <code>record</code> 374 * is <code>null</code>. 375 */ 376 public boolean isLoggable(LogRecord record) 377 { 378 if (record.getLevel().intValue() < level.intValue()) 379 return false; 380 381 if (filter != null) 382 return filter.isLoggable(record); 383 else 384 return true; 385 } 386}