KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > util > logging > StreamHandler


1 /*
2  * @(#)StreamHandler.java 1.18 03/12/19
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 import java.io.*;
12
13 /**
14  * Stream based logging <tt>Handler</tt>.
15  * <p>
16  * This is primarily intended as a base class or support class to
17  * be used in implementing other logging <tt>Handlers</tt>.
18  * <p>
19  * <tt>LogRecords</tt> are published to a given <tt>java.io.OutputStream</tt>.
20  * <p>
21  * <b>Configuration:</b>
22  * By default each <tt>StreamHandler</tt> is initialized using the following
23  * <tt>LogManager</tt> configuration properties. If properties are not defined
24  * (or have invalid values) then the specified default values are used.
25  * <ul>
26  * <li> java.util.logging.StreamHandler.level
27  * specifies the default level for the <tt>Handler</tt>
28  * (defaults to <tt>Level.INFO</tt>).
29  * <li> java.util.logging.StreamHandler.filter
30  * specifies the name of a <tt>Filter</tt> class to use
31  * (defaults to no <tt>Filter</tt>).
32  * <li> java.util.logging.StreamHandler.formatter
33  * specifies the name of a <tt>Formatter</tt> class to use
34  * (defaults to <tt>java.util.logging.SimpleFormatter</tt>).
35  * <li> java.util.logging.StreamHandler.encoding
36  * the name of the character set encoding to use (defaults to
37  * the default platform encoding).
38  * </ul>
39  *
40  * @version 1.18, 12/19/03
41  * @since 1.4
42  */
43
44 public class StreamHandler extends Handler JavaDoc {
45     private LogManager JavaDoc manager = LogManager.getLogManager();
46     private OutputStream output;
47     private boolean doneHeader;
48     private Writer writer;
49
50     // Private method to configure a StreamHandler from LogManager
51 // properties and/or default values as specified in the class
52 // javadoc.
53 private void configure() {
54         LogManager JavaDoc manager = LogManager.getLogManager();
55     String JavaDoc cname = getClass().getName();
56
57     setLevel(manager.getLevelProperty(cname +".level", Level.INFO));
58     setFilter(manager.getFilterProperty(cname +".filter", null));
59     setFormatter(manager.getFormatterProperty(cname +".formatter", new SimpleFormatter JavaDoc()));
60     try {
61         setEncoding(manager.getStringProperty(cname +".encoding", null));
62     } catch (Exception JavaDoc ex) {
63         try {
64             setEncoding(null);
65         } catch (Exception JavaDoc ex2) {
66         // doing a setEncoding with null should always work.
67 // assert false;
68 }
69     }
70     }
71
72     /**
73      * Create a <tt>StreamHandler</tt>, with no current output stream.
74      */
75     public StreamHandler() {
76     sealed = false;
77     configure();
78     sealed = true;
79     }
80
81     /**
82      * Create a <tt>StreamHandler</tt> with a given <tt>Formatter</tt>
83      * and output stream.
84      * <p>
85      * @param out the target output stream
86      * @param formatter Formatter to be used to format output
87      */
88     public StreamHandler(OutputStream out, Formatter JavaDoc formatter) {
89     sealed = false;
90     configure();
91     setFormatter(formatter);
92     setOutputStream(out);
93     sealed = true;
94     }
95
96     /**
97      * Change the output stream.
98      * <P>
99      * If there is a current output stream then the <tt>Formatter</tt>'s
100      * tail string is written and the stream is flushed and closed.
101      * Then the output stream is replaced with the new output stream.
102      *
103      * @param out New output stream. May not be null.
104      * @exception SecurityException if a security manager exists and if
105      * the caller does not have <tt>LoggingPermission("control")</tt>.
106      */
107     protected synchronized void setOutputStream(OutputStream out) throws SecurityException JavaDoc {
108     if (out == null) {
109         throw new NullPointerException JavaDoc();
110     }
111     flushAndClose();
112     output = out;
113     doneHeader = false;
114     String JavaDoc encoding = getEncoding();
115     if (encoding == null) {
116         writer = new OutputStreamWriter(output);
117     } else {
118         try {
119             writer = new OutputStreamWriter(output, encoding);
120         } catch (UnsupportedEncodingException ex) {
121         // This shouldn't happen. The setEncoding method
122 // should have validated that the encoding is OK.
123 throw new Error JavaDoc("Unexpected exception " + ex);
124         }
125     }
126     }
127
128     /**
129      * Set (or change) the character encoding used by this <tt>Handler</tt>.
130      * <p>
131      * The encoding should be set before any <tt>LogRecords</tt> are written
132      * to the <tt>Handler</tt>.
133      *
134      * @param encoding The name of a supported character encoding.
135      * May be null, to indicate the default platform encoding.
136      * @exception SecurityException if a security manager exists and if
137      * the caller does not have <tt>LoggingPermission("control")</tt>.
138      * @exception UnsupportedEncodingException if the named encoding is
139      * not supported.
140      */
141     public void setEncoding(String JavaDoc encoding)
142             throws SecurityException JavaDoc, java.io.UnsupportedEncodingException JavaDoc {
143     super.setEncoding(encoding);
144     if (output == null) {
145         return;
146     }
147     // Replace the current writer with a writer for the new encoding.
148 flush();
149     if (encoding == null) {
150         writer = new OutputStreamWriter(output);
151     } else {
152         writer = new OutputStreamWriter(output, encoding);
153     }
154     }
155
156     /**
157      * Format and publish a <tt>LogRecord</tt>.
158      * <p>
159      * The <tt>StreamHandler</tt> first checks if there is an <tt>OutputStream</tt>
160      * and if the given <tt>LogRecord</tt> has at least the required log level.
161      * If not it silently returns. If so, it calls any associated
162      * <tt>Filter</tt> to check if the record should be published. If so,
163      * it calls its <tt>Formatter</tt> to format the record and then writes
164      * the result to the current output stream.
165      * <p>
166      * If this is the first <tt>LogRecord</tt> to be written to a given
167      * <tt>OutputStream</tt>, the <tt>Formatter</tt>'s "head" string is
168      * written to the stream before the <tt>LogRecord</tt> is written.
169      *
170      * @param record description of the log event. A null record is
171      * silently ignored and is not published
172      */
173     public synchronized void publish(LogRecord JavaDoc record) {
174     if (!isLoggable(record)) {
175         return;
176     }
177     String JavaDoc msg;
178     try {
179         msg = getFormatter().format(record);
180     } catch (Exception JavaDoc ex) {
181         // We don't want to throw an exception here, but we
182 // report the exception to any registered ErrorManager.
183 reportError(null, ex, ErrorManager.FORMAT_FAILURE);
184         return;
185     }
186
187     try {
188         if (!doneHeader) {
189             writer.write(getFormatter().getHead(this));
190         doneHeader = true;
191         }
192         writer.write(msg);
193     } catch (Exception JavaDoc ex) {
194         // We don't want to throw an exception here, but we
195 // report the exception to any registered ErrorManager.
196 reportError(null, ex, ErrorManager.WRITE_FAILURE);
197     }
198     }
199
200
201     /**
202      * Check if this <tt>Handler</tt> would actually log a given <tt>LogRecord</tt>.
203      * <p>
204      * This method checks if the <tt>LogRecord</tt> has an appropriate level and
205      * whether it satisfies any <tt>Filter</tt>. It will also return false if
206      * no output stream has been assigned yet or the LogRecord is Null.
207      * <p>
208      * @param record a <tt>LogRecord</tt>
209      * @return true if the <tt>LogRecord</tt> would be logged.
210      *
211      */
212     public boolean isLoggable(LogRecord JavaDoc record) {
213     if (writer == null || record == null) {
214         return false;
215     }
216     return super.isLoggable(record);
217     }
218
219     /**
220      * Flush any buffered messages.
221      */
222     public synchronized void flush() {
223     if (writer != null) {
224         try {
225             writer.flush();
226         } catch (Exception JavaDoc ex) {
227             // We don't want to throw an exception here, but we
228 // report the exception to any registered ErrorManager.
229 reportError(null, ex, ErrorManager.FLUSH_FAILURE);
230         }
231     }
232     }
233
234     private synchronized void flushAndClose() throws SecurityException JavaDoc {
235         checkAccess();
236     if (writer != null) {
237         try {
238             if (!doneHeader) {
239                 writer.write(getFormatter().getHead(this));
240             doneHeader = true;
241             }
242         writer.write(getFormatter().getTail(this));
243         writer.flush();
244             writer.close();
245         } catch (Exception JavaDoc ex) {
246             // We don't want to throw an exception here, but we
247 // report the exception to any registered ErrorManager.
248 reportError(null, ex, ErrorManager.CLOSE_FAILURE);
249         }
250         writer = null;
251         output = null;
252     }
253     }
254
255     /**
256      * Close the current output stream.
257      * <p>
258      * The <tt>Formatter</tt>'s "tail" string is written to the stream before it
259      * is closed. In addition, if the <tt>Formatter</tt>'s "head" string has not
260      * yet been written to the stream, it will be written before the
261      * "tail" string.
262      *
263      * @exception SecurityException if a security manager exists and if
264      * the caller does not have LoggingPermission("control").
265      * @exception SecurityException if a security manager exists and if
266      * the caller does not have LoggingPermission("control").
267      */
268     public synchronized void close() throws SecurityException JavaDoc {
269     flushAndClose();
270     }
271 }
272
Popular Tags