FileHandler 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.
*
* Configuration: Values of the subsequent
* LogManager properties are taken into consideration
* when a FileHandler is initialized. If a property is
* not defined, or if it has an invalid value, a default is taken
* without an exception being thrown.
*
*
java.util.FileHandler.level - specifies
* the initial severity level threshold. Default value:
* Level.ALL.java.util.FileHandler.filter - specifies
* the name of a Filter class. Default value: No Filter.java.util.FileHandler.formatter - specifies
* the name of a Formatter class. Default value:
* java.util.logging.XMLFormatter.java.util.FileHandler.encoding - specifies
* the name of the character encoding. Default value:
* the default platform encoding.java.util.FileHandler.limit - 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).java.util.FileHandler.count - specifies the number
* of log files through which this handler cycles. Default value:
* 1.java.util.FileHandler.pattern - specifies a
* pattern for the location and name of the produced log files.
* See the section on file name
* patterns for details. Default value:
* "%h/java%u.log".java.util.FileHandler.append - 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: false,
* indicating that files will be cleared.File Name Patterns: * The name and location and log files are specified with pattern * strings. The handler will replace the following character sequences * when opening log files: * *
/ - replaced by the platform-specific path name
* separator. This value is taken from the system property
* file.separator.%t - replaced by the platform-specific location of
* the directory intended for temporary files. This value is
* taken from the system property java.io.tmpdir.%h - replaced by the location of the home
* directory of the current user. This value is taken from the
* system property user.home.%g - 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, ..., count - 1.%u - replaced by a unique number for
* distinguisthing the output files of several concurrently
* running processes. The FileHandler 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.
*
* 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. * *
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.
%% - replaced by a single percent sign.If the pattern string does not contain %g and
* count is greater than one, the handler will append
* the string .%g to the specified pattern.
*
*
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 %u, the handler will append
* the string .%u to the specified pattern. This
* step is performed after any generation number has been
* appended.
*
*
Examples for the GNU platform: * *
%h/java%u.log will lead to a single log file
* /home/janet/java0.log, assuming count
* equals 1, the user's home directory is
* /home/janet, and the attempt to open the file
* succeeds.%h/java%u.log will lead to three log files
* /home/janet/java0.log.0,
* /home/janet/java0.log.1, and
* /home/janet/java0.log.2,
* assuming count equals 3, the user's home
* directory is /home/janet, and all attempts
* to open files succeed.%h/java%u.log will lead to three log files
* /home/janet/java0.log.0,
* /home/janet/java1.log.1, and
* /home/janet/java0.log.2,
* assuming count equals 3, the user's home
* directory is /home/janet, and the attempt
* to open /home/janet/java0.log.1 fails.PATTERN_KEY property was
* not specified in the logging.properties file.
*/
private static final String DEFAULT_PATTERN = "%h/java%u.log";
/**
* The name of the property to set for specifying an approximate maximum
* amount, in bytes, to write to any one log output file. A value of zero
* (which is the default) implies a no limit.
*/
private static final String LIMIT_KEY = PROPERTY_PREFIX + ".limit";
private static final int DEFAULT_LIMIT = 0;
/**
* The name of the property to set for specifying how many output files to
* cycle through. The default value is 1.
*/
private static final String COUNT_KEY = PROPERTY_PREFIX + ".count";
private static final int DEFAULT_COUNT = 1;
/**
* The name of the property to set for specifying whether this handler should
* append, or not, its output to existing files. The default value is
* false meaning NOT to append.
*/
private static final String APPEND_KEY = PROPERTY_PREFIX + ".append";
private static final boolean DEFAULT_APPEND = false;
/**
* 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 file name patterns
* for details.
*/
private final String pattern;
/**
* Indicates whether the handler will append log records to existing
* files (true), or whether the handler will clear log files
* upon switching to them (false).
*/
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 FileHandler, 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(LogManager.getLogManager().getProperty(PATTERN_KEY),
LogManager.getIntProperty(LIMIT_KEY, DEFAULT_LIMIT),
LogManager.getIntProperty(COUNT_KEY, DEFAULT_COUNT),
LogManager.getBooleanProperty(APPEND_KEY, DEFAULT_APPEND));
}
/* FIXME: Javadoc missing. */
public FileHandler(String pattern)
throws IOException, SecurityException
{
this(pattern, DEFAULT_LIMIT, DEFAULT_COUNT, DEFAULT_APPEND);
}
/* FIXME: Javadoc missing. */
public FileHandler(String pattern, boolean append)
throws IOException, SecurityException
{
this(pattern, DEFAULT_LIMIT, DEFAULT_COUNT, append);
}
/* FIXME: Javadoc missing. */
public FileHandler(String pattern, int limit, int count)
throws IOException, SecurityException
{
this(pattern, limit, count,
LogManager.getBooleanProperty(APPEND_KEY, DEFAULT_APPEND));
}
/**
* Constructs a FileHandler 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 append 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 file name patterns for details.
* If pattern is null, the value is
* taken from the {@link LogManager LogManager} configuration
* property
* java.util.logging.FileHandler.pattern.
* However, this is a pecularity of the GNU implementation,
* and Sun's API specification does not mention what behavior
* is to be expected for null. 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
* handler switches to the next file in the rotating set. A
* value of zero means that files can grow without limit.
*
* @param count specifies the number of log files through which this
* handler cycles.
*
* @param append specifies whether the handler will append log
* records to existing files (true), or whether the
* handler will clear log files upon switching to them
* (false).
*
* @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.
* FIXME: This seems in contrast to all other handler
* constructors -- verify this by running tests against
* the Sun reference implementation.
*/
public FileHandler(String pattern,
int limit,
int count,
boolean append)
throws IOException, SecurityException
{
super(/* output stream, created below */ null,
PROPERTY_PREFIX,
/* default level */ Level.ALL,
/* formatter */ null,
/* default formatter */ XMLFormatter.class);
if ((limit <0) || (count < 1))
throw new IllegalArgumentException();
this.pattern = pattern != null ? pattern : DEFAULT_PATTERN;
this.limit = limit;
this.count = count;
this.append = append;
this.written = 0;
this.logFiles = new LinkedList ();
setOutputStream (createFileStream (this.pattern, limit, count, append,
/* generation */ 0));
}
/* FIXME: Javadoc missing. */
private OutputStream createFileStream(String pattern,
int limit,
int count,
boolean append,
int generation)
{
String path;
int unique = 0;
/* Throws a SecurityException if the caller does not have
* LoggingPermission("control").
*/
LogManager.getLogManager().checkAccess();
/* Default value from the java.util.logging.FileHandler.pattern
* LogManager configuration property.
*/
if (pattern == null)
pattern = LogManager.getLogManager().getProperty(PATTERN_KEY);
if (pattern == null)
pattern = DEFAULT_PATTERN;
if (count > 1 && !has (pattern, 'g'))
pattern = pattern + ".%g";
do
{
path = replaceFileNameEscapes(pattern, generation, unique, count);
try
{
File file = new File(path);
if (!file.exists () || append)
{
FileOutputStream fout = new FileOutputStream (file, append);
// FIXME we need file locks for this to work properly, but they
// are not implemented yet in Classpath! Madness!
// FileChannel channel = fout.getChannel ();
// FileLock lock = channel.tryLock ();
// if (lock != null) // We've locked the file.
// {
if (logFiles.isEmpty ())
logFiles.addFirst (path);
return new ostr (fout);
// }
}
}
catch (Exception ex)
{
reportError (null, ex, ErrorManager.OPEN_FAILURE);
}
unique = unique + 1;
if (!has (pattern, 'u'))
pattern = pattern + ".%u";
}
while (true);
}
/**
* Replaces the substrings "/" by the value of the
* system property "file.separator", "%t"
* by the value of the system property
* "java.io.tmpdir", "%h" by the value of
* the system property "user.home", "%g"
* by the value of generation, "%u" by the
* value of uniqueNumber, and "%%" by a
* single percent character. If pattern does
* not contain the sequence "%g",
* the value of generation will be appended to
* the result.
*
* @throws NullPointerException if one of the system properties
* "file.separator",
* "java.io.tmpdir", or
* "user.home" has no value and the
* corresponding escape sequence appears in
* pattern.
*/
private static String replaceFileNameEscapes(String pattern,
int generation,
int uniqueNumber,
int count)
{
CPStringBuilder buf = new CPStringBuilder(pattern);
String replaceWith;
boolean foundGeneration = false;
int pos = 0;
do
{
// Uncomment the next line for finding bugs.
// System.out.println(buf.substring(0,pos) + '|' + buf.substring(pos));
if (buf.charAt(pos) == '/')
{
/* The same value is also provided by java.io.File.separator. */
replaceWith = System.getProperty("file.separator");
buf.replace(pos, pos + 1, replaceWith);
pos = pos + replaceWith.length() - 1;
continue;
}
if (buf.charAt(pos) == '%')
{
switch (buf.charAt(pos + 1))
{
case 't':
replaceWith = System.getProperty("java.io.tmpdir");
break;
case 'h':
replaceWith = System.getProperty("user.home");
break;
case 'g':
replaceWith = Integer.toString(generation);
foundGeneration = true;
break;
case 'u':
replaceWith = Integer.toString(uniqueNumber);
break;
case '%':
replaceWith = "%";
break;
default:
replaceWith = "??";
break; // FIXME: Throw exception?
}
buf.replace(pos, pos + 2, replaceWith);
pos = pos + replaceWith.length() - 1;
continue;
}
}
while (++pos < buf.length() - 1);
if (!foundGeneration && (count > 1))
{
buf.append('.');
buf.append(generation);
}
return buf.toString();
}
/* FIXME: Javadoc missing. */
public void publish(LogRecord record)
{
if (limit > 0 && written >= limit)
rotate ();
super.publish(record);
flush ();
}
/**
* Rotates the current log files, possibly removing one if we
* exceed the file count.
*/
private synchronized void rotate ()
{
if (logFiles.size () > 0)
{
File f1 = null;
ListIterator lit = null;
// If we reach the file count, ditch the oldest file.
if (logFiles.size () == count)
{
f1 = new File ((String) logFiles.getLast ());
f1.delete ();
lit = logFiles.listIterator (logFiles.size () - 1);
}
// Otherwise, move the oldest to a new location.
else
{
String path = replaceFileNameEscapes (pattern, logFiles.size (),
/* unique */ 0, count);
f1 = new File (path);
logFiles.addLast (path);
lit = logFiles.listIterator (logFiles.size () - 1);
}
// Now rotate the files.
while (lit.hasPrevious ())
{
String s = (String) lit.previous ();
File f2 = new File (s);
f2.renameTo (f1);
f1 = f2;
}
}
setOutputStream (createFileStream (pattern, limit, count, append,
/* generation */ 0));
// Reset written count.
written = 0;
}
/**
* Tell if pattern contains the pattern sequence
* with character escape. That is, if escape
* is 'g', this method returns true if the given pattern contains
* "%g", and not just the substring "%g" (for example, in the case of
* "%%g").
*
* @param pattern The pattern to test.
* @param escape The escape character to search for.
* @return True iff the pattern contains the escape sequence with the
* given character.
*/
private static boolean has (final String pattern, final char escape)
{
final int len = pattern.length ();
boolean sawPercent = false;
for (int i = 0; i < len; i++)
{
char c = pattern.charAt (i);
if (sawPercent)
{
if (c == escape)
return true;
if (c == '%') // Double percent
{
sawPercent = false;
continue;
}
}
sawPercent = (c == '%');
}
return false;
}
/**
* An output stream that tracks the number of bytes written to it.
*/
private final class ostr extends FilterOutputStream
{
private ostr (OutputStream out)
{
super (out);
}
public void write (final int b) throws IOException
{
out.write (b);
FileHandler.this.written++; // FIXME: synchronize?
}
public void write (final byte[] b) throws IOException
{
write (b, 0, b.length);
}
public void write (final byte[] b, final int offset, final int length)
throws IOException
{
out.write (b, offset, length);
FileHandler.this.written += length; // FIXME: synchronize?
}
}
}