/* FileHandler.java -- a class for publishing log messages to log files   Copyright (C) 2002, 2003, 2004, 2005  Free Software Foundation, Inc.This file is part of GNU Classpath.GNU Classpath is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation; either version 2, or (at your option)any later version.GNU Classpath is distributed in the hope that it will be useful, butWITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNUGeneral Public License for more details.You should have received a copy of the GNU General Public Licensealong with GNU Classpath; see the file COPYING.  If not, write to theFree Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA02110-1301 USA.Linking this library statically or dynamically with other modules ismaking a combined work based on this library.  Thus, the terms andconditions of the GNU General Public License cover the wholecombination.As a special exception, the copyright holders of this library give youpermission to link this library with independent modules to produce anexecutable, regardless of the license terms of these independentmodules, and to copy and distribute the resulting executable underterms of your choice, provided that you also meet, for each linkedindependent module, the terms and conditions of the license of thatmodule.  An independent module is a module which is not derived fromor based on this library.  If you modify this library, you may extendthis exception to your version of the library, but you are notobligated to do so.  If you do not wish to do so, delete thisexception statement from your version. */package java.util.logging;import java.io.File;import java.io.FileOutputStream;import java.io.FilterOutputStream;import java.io.IOException;import java.io.OutputStream;import java.util.LinkedList;import java.util.ListIterator;/** * A <code>FileHandler</code> publishes log records to a set of log * files.  A maximum file size can be specified; as soon as a log file * reaches the size limit, it is closed and the next file in the set * is taken. * * <p><strong>Configuration:</strong> Values of the subsequent * <code>LogManager</code> properties are taken into consideration * when a <code>FileHandler</code> is initialized.  If a property is * not defined, or if it has an invalid value, a default is taken * without an exception being thrown. * * <ul> * * <li><code>java.util.FileHandler.level</code> - specifies *     the initial severity level threshold. Default value: *     <code>Level.ALL</code>.</li> * * <li><code>java.util.FileHandler.filter</code> - specifies *     the name of a Filter class. Default value: No Filter.</li> * * <li><code>java.util.FileHandler.formatter</code> - specifies *     the name of a Formatter class. Default value: *     <code>java.util.logging.XMLFormatter</code>.</li> * * <li><code>java.util.FileHandler.encoding</code> - specifies *     the name of the character encoding. Default value: *     the default platform encoding.</li> * * <li><code>java.util.FileHandler.limit</code> - specifies the number *     of bytes a log file is approximately allowed to reach before it *     is closed and the handler switches to the next file in the *     rotating set.  A value of zero means that files can grow *     without limit.  Default value: 0 (unlimited growth).</li> * * <li><code>java.util.FileHandler.count</code> - specifies the number *     of log files through which this handler cycles.  Default value: *     1.</li> * * <li><code>java.util.FileHandler.pattern</code> - specifies a *     pattern for the location and name of the produced log files. *     See the section on <a href="#filePatterns">file name *     patterns</a> for details.  Default value: *     <code>"%h/java%u.log"</code>.</li> * * <li><code>java.util.FileHandler.append</code> - specifies *     whether the handler will append log records to existing *     files, or whether the handler will clear log files *     upon switching to them. Default value: <code>false</code>, *     indicating that files will be cleared.</li> * * </ul> * * <p><a name="filePatterns"><strong>File Name Patterns:</strong></a> * The name and location and log files are specified with pattern * strings. The handler will replace the following character sequences * when opening log files: * * <p><ul> * <li><code>/</code> - replaced by the platform-specific path name *     separator.  This value is taken from the system property *     <code>file.separator</code>.</li> * * <li><code>%t</code> - replaced by the platform-specific location of *     the directory intended for temporary files.  This value is *     taken from the system property <code>java.io.tmpdir</code>.</li> * * <li><code>%h</code> - replaced by the location of the home *     directory of the current user.  This value is taken from the *     system property <code>file.separator</code>.</li> * * <li><code>%g</code> - replaced by a generation number for *     distinguisthing the individual items in the rotating set  *     of log files.  The generation number cycles through the *     sequence 0, 1, ..., <code>count</code> - 1.</li> * * <li><code>%u</code> - replaced by a unique number for *     distinguisthing the output files of several concurrently *     running processes.  The <code>FileHandler</code> starts *     with 0 when it tries to open a log file.  If the file *     cannot be opened because it is currently in use, *     the unique number is incremented by one and opening *     is tried again.  These steps are repeated until the *     opening operation succeeds. * *     <p>FIXME: Is the following correct? Please review.  The unique *     number is determined for each log file individually when it is *     opened upon switching to the next file.  Therefore, it is not *     correct to assume that all log files in a rotating set bear the *     same unique number. * *     <p>FIXME: The Javadoc for the Sun reference implementation *     says: "Note that the use of unique ids to avoid conflicts is *     only guaranteed to work reliably when using a local disk file *     system." Why? This needs to be mentioned as well, in case *     the reviewers decide the statement is true.  Otherwise, *     file a bug report with Sun.</li> * * <li><code>%%</code> - replaced by a single percent sign.</li> * </ul> * * <p>If the pattern string does not contain <code>%g</code> and * <code>count</code> is greater than one, the handler will append * the string <code>.%g</code> to the specified pattern. * * <p>If the handler attempts to open a log file, this log file * is being used at the time of the attempt, and the pattern string * does not contain <code>%u</code>, the handler will append * the string <code>.%u</code> to the specified pattern. This * step is performed after any generation number has been * appended. * * <p><em>Examples for the GNU platform:</em>  * * <p><ul> * * <li><code>%h/java%u.log</code> will lead to a single log file *     <code>/home/janet/java0.log</code>, assuming <code>count</code> *     equals 1, the user's home directory is *     <code>/home/janet</code>, and the attempt to open the file *     succeeds.</li> * * <li><code>%h/java%u.log</code> will lead to three log files *     <code>/home/janet/java0.log.0</code>, *     <code>/home/janet/java0.log.1</code>, and *     <code>/home/janet/java0.log.2</code>, *     assuming <code>count</code> equals 3, the user's home *     directory is <code>/home/janet</code>, and all attempts *     to open files succeed.</li> * * <li><code>%h/java%u.log</code> will lead to three log files *     <code>/home/janet/java0.log.0</code>, *     <code>/home/janet/java1.log.1</code>, and *     <code>/home/janet/java0.log.2</code>, *     assuming <code>count</code> equals 3, the user's home *     directory is <code>/home/janet</code>, and the attempt *     to open <code>/home/janet/java0.log.1</code> fails.</li> * * </ul> * * @author Sascha Brawer (brawer@acm.org) */public class FileHandler  extends StreamHandler{  /**   * The number of bytes a log file is approximately allowed to reach   * before it is closed and the handler switches to the next file in   * the rotating set.  A value of zero means that files can grow   * without limit.   */  private final int limit; /**  * The number of log files through which this handler cycles.  */  private final int count;  /**   * The pattern for the location and name of the produced log files.   * See the section on <a href="#filePatterns">file name patterns</a>   * for details.   */  private final String pattern;  /**   * Indicates whether the handler will append log records to existing   * files (<code>true</code>), or whether the handler will clear log files   * upon switching to them (<code>false</code>).   */  private final boolean append;  /**   * The number of bytes that have currently been written to the stream.   * Package private for use in inner classes.   */  long written;  /**   * A linked list of files we are, or have written to. The entries   * are file path strings, kept in the order    */  private LinkedList logFiles;  /**   * Constructs a <code>FileHandler</code>, taking all property values   * from the current {@link LogManager LogManager} configuration.   *   * @throws java.io.IOException FIXME: The Sun Javadoc says: "if   *         there are IO problems opening the files."  This conflicts   *         with the general principle that configuration errors do   *         not prohibit construction. Needs review.   *   * @throws SecurityException if a security manager exists and   *         the caller is not granted the permission to control   *         the logging infrastructure.   */  public FileHandler()    throws IOException, SecurityException  {    this(/* pattern: use configiguration */ null,	 LogManager.getIntProperty("java.util.logging.FileHandler.limit",				   /* default */ 0),	 LogManager.getIntProperty("java.util.logging.FileHandler.count",				   /* default */ 1),	 LogManager.getBooleanProperty("java.util.logging.FileHandler.append",				       /* default */ false));  }  /* FIXME: Javadoc missing. */  public FileHandler(String pattern)    throws IOException, SecurityException  {    this(pattern,	 /* limit */ 0,	 /* count */ 1,	 /* append */ false);  }  /* FIXME: Javadoc missing. */  public FileHandler(String pattern, boolean append)    throws IOException, SecurityException  {    this(pattern,	 /* limit */ 0,	 /* count */ 1,	 append);  }  /* FIXME: Javadoc missing. */  public FileHandler(String pattern, int limit, int count)    throws IOException, SecurityException  {    this(pattern, limit, count, 	 LogManager.getBooleanProperty(	   "java.util.logging.FileHandler.append",	   /* default */ false));  }  /**   * Constructs a <code>FileHandler</code> given the pattern for the   * location and name of the produced log files, the size limit, the   * number of log files thorough which the handler will rotate, and   * the <code>append</code> property.  All other property values are   * taken from the current {@link LogManager LogManager}   * configuration.   *   * @param pattern The pattern for the location and name of the   *        produced log files.  See the section on <a   *        href="#filePatterns">file name patterns</a> for details.   *        If <code>pattern</code> is <code>null</code>, the value is   *        taken from the {@link LogManager LogManager} configuration   *        property   *        <code>java.util.logging.FileHandler.pattern</code>.   *        However, this is a pecularity of the GNU implementation,   *        and Sun's API specification does not mention what behavior   *        is to be expected for <code>null</code>. Therefore,   *        applications should not rely on this feature.   *   * @param limit specifies the number of bytes a log file is   *        approximately allowed to reach before it is closed and the