Handler


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