FileAppender


1   /*
2    * Copyright 1999-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.log4j;
18  
19  import java.io.IOException  ;
20  import java.io.Writer  ;
21  import java.io.FileOutputStream  ;
22  import java.io.BufferedWriter  ;
23  
24  import org.apache.log4j.spi.ErrorCode;
25  import org.apache.log4j.helpers.QuietWriter;
26  import org.apache.log4j.helpers.LogLog;
27  
28  // Contibutors: Jens Uwe Pipka <jens.pipka@gmx.de>
29  //              Ben Sandee
30  
31  /**
32   *  FileAppender appends log events to a file.
33   *
34   *  <p>Support for <code>java.io.Writer</code> and console appending
35   *  has been deprecated and then removed. See the replacement
36   *  solutions: {@link WriterAppender} and {@link ConsoleAppender}.
37   *
38   * @author Ceki G&uuml;lc&uuml; 
39   * */
40  public class FileAppender extends WriterAppender {
41  
42    /** Controls file truncatation. The default value for this variable
43     * is <code>true</code>, meaning that by default a
44     * <code>FileAppender</code> will append to an existing file and not
45     * truncate it.
46     *
47     * <p>This option is meaningful only if the FileAppender opens the
48     * file.
49     */
50    protected boolean fileAppend = true;
51  
52    /**
53       The name of the log file. */
54    protected String   fileName = null;
55  
56    /**
57       Do we do bufferedIO? */
58    protected boolean bufferedIO = false;
59  
60    /**
61     * Determines the size of IO buffer be. Default is 8K. 
62     */
63    protected int bufferSize = 8*1024;
64  
65  
66    /**
67       The default constructor does not do anything.
68    */
69    public
70    FileAppender() {
71    }
72  
73    /**
74      Instantiate a <code>FileAppender</code> and open the file
75      designated by <code>filename</code>. The opened filename will
76      become the output destination for this appender.
77  
78      <p>If the <code>append</code> parameter is true, the file will be
79      appended to. Otherwise, the file designated by
80      <code>filename</code> will be truncated before being opened.
81  
82      <p>If the <code>bufferedIO</code> parameter is <code>true</code>,
83      then buffered IO will be used to write to the output file.
84  
85    */
86    public
87    FileAppender(Layout layout, String   filename, boolean append, boolean bufferedIO,
88             int bufferSize) throws IOException   {
89      this.layout = layout;
90      this.setFile(filename, append, bufferedIO, bufferSize);
91    }
92  
93    /**
94      Instantiate a FileAppender and open the file designated by
95      <code>filename</code>. The opened filename will become the output
96      destination for this appender.
97  
98      <p>If the <code>append</code> parameter is true, the file will be
99      appended to. Otherwise, the file designated by
100     <code>filename</code> will be truncated before being opened.
101   */
102   public
103   FileAppender(Layout layout, String   filename, boolean append)
104                                                              throws IOException   {
105     this.layout = layout;
106     this.setFile(filename, append, false, bufferSize);
107   }
108 
109   /**
110      Instantiate a FileAppender and open the file designated by
111     <code>filename</code>. The opened filename will become the output
112     destination for this appender.
113 
114     <p>The file will be appended to.  */
115   public
116   FileAppender(Layout layout, String   filename) throws IOException   {
117     this(layout, filename, true);
118   }
119 
120   /**
121      The <b>File</b> property takes a string value which should be the
122      name of the file to append to.
123 
124      <p><font color="#DD0044"><b>Note that the special values
125      "System.out" or "System.err" are no longer honored.</b></font>
126 
127      <p>Note: Actual opening of the file is made when {@link
128      #activateOptions} is called, not when the options are set.  */
129   public void setFile(String   file) {
130     // Trim spaces from both ends. The users probably does not want
131     // trailing spaces in file names.
132     String   val = file.trim();
133     fileName = val;
134   }
135 
136   /**
137       Returns the value of the <b>Append</b> option.
138    */
139   public
140   boolean getAppend() {
141     return fileAppend;
142   }
143 
144 
145   /** Returns the value of the <b>File</b> option. */
146   public
147   String   getFile() {
148     return fileName;
149   }
150 
151   /**
152      If the value of <b>File</b> is not <code>null</code>, then {@link
153      #setFile} is called with the values of <b>File</b>  and
154      <b>Append</b> properties.
155 
156      @since 0.8.1 */
157   public
158   void activateOptions() {
159     if(fileName != null) {
160       try {
161     setFile(fileName, fileAppend, bufferedIO, bufferSize);
162       }
163       catch(java.io.IOException   e) {
164     errorHandler.error("setFile("+fileName+","+fileAppend+") call failed.",
165                e, ErrorCode.FILE_OPEN_FAILURE);
166       }
167     } else {
168       //LogLog.error("File option not set for appender ["+name+"].");
169       LogLog.warn("File option not set for appender ["+name+"].");
170       LogLog.warn("Are you using FileAppender instead of ConsoleAppender?");
171     }
172   }
173 
174  /**
175      Closes the previously opened file.
176   */
177   protected
178   void closeFile() {
179     if(this.qw != null) {
180       try {
181     this.qw.close();
182       }
183       catch(java.io.IOException   e) {
184     // Exceptionally, it does not make sense to delegate to an
185     // ErrorHandler. Since a closed appender is basically dead.
186     LogLog.error("Could not close " + qw, e);
187       }
188     }
189   }
190 
191   /**
192      Get the value of the <b>BufferedIO</b> option.
193 
194      <p>BufferedIO will significatnly increase performance on heavily
195      loaded systems.
196 
197   */
198   public
199   boolean getBufferedIO() {
200     return this.bufferedIO;
201   }
202 
203 
204   /**
205      Get the size of the IO buffer.
206   */
207   public
208   int getBufferSize() {
209     return this.bufferSize;
210   }
211 
212 
213 
214   /**
215      The <b>Append</b> option takes a boolean value. It is set to
216      <code>true</code> by default. If true, then <code>File</code>
217      will be opened in append mode by {@link #setFile setFile} (see
218      above). Otherwise, {@link #setFile setFile} will open
219      <code>File</code> in truncate mode.
220 
221      <p>Note: Actual opening of the file is made when {@link
222      #activateOptions} is called, not when the options are set.
223    */
224   public
225   void setAppend(boolean flag) {
226     fileAppend = flag;
227   }
228 
229   /**
230      The <b>BufferedIO</b> option takes a boolean value. It is set to
231      <code>false</code> by default. If true, then <code>File</code>
232      will be opened and the resulting {@link java.io.Writer} wrapped
233      around a {@link BufferedWriter}.
234 
235      BufferedIO will significatnly increase performance on heavily
236      loaded systems.
237 
238   */
239   public
240   void setBufferedIO(boolean bufferedIO) {
241     this.bufferedIO = bufferedIO;
242     if(bufferedIO) {
243       immediateFlush = false;
244     }
245   }
246 
247 
248   /**
249      Set the size of the IO buffer.
250   */
251   public
252   void setBufferSize(int bufferSize) {
253     this.bufferSize = bufferSize;
254   }
255 
256   /**
257     <p>Sets and <i>opens</i> the file where the log output will
258     go. The specified file must be writable.
259 
260     <p>If there was already an opened file, then the previous file
261     is closed first.
262 
263     <p><b>Do not use this method directly. To configure a FileAppender
264     or one of its subclasses, set its properties one by one and then
265     call activateOptions.</b>
266 
267     @param fileName The path to the log file.
268     @param append   If true will append to fileName. Otherwise will
269         truncate fileName.  */
270   public
271   synchronized
272   void setFile(String   fileName, boolean append, boolean bufferedIO, int bufferSize)
273                                                             throws IOException   {
274     LogLog.debug("setFile called: "+fileName+", "+append);
275 
276     // It does not make sense to have immediate flush and bufferedIO.
277     if(bufferedIO) {
278       setImmediateFlush(false);
279     }
280 
281     reset();
282     Writer   fw = createWriter(new FileOutputStream  (fileName, append));
283     if(bufferedIO) {
284       fw = new BufferedWriter  (fw, bufferSize);
285     }
286     this.setQWForFiles(fw);
287     this.fileName = fileName;
288     this.fileAppend = append;
289     this.bufferedIO = bufferedIO;
290     this.bufferSize = bufferSize;
291     writeHeader();
292     LogLog.debug("setFile ended");
293   }
294 
295 
296   /**
297      Sets the quiet writer being used.
298 
299      This method is overriden by {@link RollingFileAppender}.
300    */
301   protected
302   void setQWForFiles(Writer   writer) {
303      this.qw = new QuietWriter(writer, errorHandler);
304   }
305 
306 
307   /**
308      Close any previously opened file and call the parent's
309      <code>reset</code>.  */
310   protected
311   void reset() {
312     closeFile();
313     this.fileName = null;
314     super.reset();
315   }
316 }
317 
318
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags