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 file.separator.%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.true), or whether the handler will clear log files
* upon switching to them (false).
*/
private final boolean append;
/**
* 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(/* 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 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(createFileStream(pattern, limit, count, append,
/* generation */ 0),
"java.util.logging.FileHandler",
/* default level */ Level.ALL,
/* formatter */ null,
/* default formatter */ XMLFormatter.class);
if ((limit <0) || (count < 1))
throw new IllegalArgumentException();
this.pattern = pattern;
this.limit = limit;
this.count = count;
this.append = append;
}
/* FIXME: Javadoc missing. */
private static java.io.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(
"java.util.logging.FileHandler.pattern");
if (pattern == null)
pattern = "%h/java%u.log";
do
{
path = replaceFileNameEscapes(pattern, generation, unique, count);
try
{
File file = new File(path);
if (file.createNewFile())
return new FileOutputStream(path, append);
}
catch (Exception ex)
{
ex.printStackTrace();
}
unique = unique + 1;
if (pattern.indexOf("%u") < 0)
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)
{
StringBuffer buf = new StringBuffer(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, implementation incomplete. */
public void publish(LogRecord record)
{
super.publish(record);
/* FIXME: Decide when to switch over. How do we get to
* the number of bytes published so far? Two possibilities:
* 1. File.length, 2. have metering wrapper around
* output stream counting the number of written bytes.
*/
/* FIXME: Switch over if needed! This implementation always
* writes into a single file, i.e. behaves as if limit
* always was zero. So, the implementation is somewhat
* functional but incomplete.
*/
}
}