org.x4juli.handlers
Class FileHandler

java.lang.Object
  java.util.logging.Handler
      org.x4juli.global.components.AbstractHandler
          org.x4juli.handlers.WriterHandler
              org.x4juli.handlers.FileHandler

All Implemented Interfaces:

Component, ExtendedHandler, Handler, OptionHandler

Direct Known Subclasses:

RollingFileHandler

public class FileHandler

extends WriterHandler

FileHandler publishes log records to a file. Please refer also to parent classes for further configuration information.

Attribute	Description	Required
.append	Append to existing files. Allowed values "true" or "false".	No. Default false.
.filename	Full or relative Path and Name of the file.	YES. Default value of "user.home"/juli.log
.bufferedIO	To buffer write access to the file. Allowed values "true" or "false".	No. Default false.
.buffersize	Size of the IO buffer. Allowed value is an integer.	No. Default 8kb.

FileHandler can be configured programattically or using configuration by file. Do not use the default constructor in programattically use.

Logging API as a whole was originally done for Apache log4j. Juli is a port of main parts of that to complete the Java Logging APIs. All credits for initial idea, design, implementation, documentation belong to the log4j crew. This file was originally published by Ceki Gülcü. Please use exclusively the appropriate mailing lists for questions, remarks and contribution.

Since:

0.5

Author:

Boris Unckel

Field Summary

protected boolean	bufferedIO Do we do bufferedIO?
protected int	bufferSize The size of the IO buffer.
protected static int	DEFAULT_BUFFER_SIZE Default Size of an Buffered IO.
protected boolean	fileAppend Append to or truncate the file?
protected java.lang.String	fileName The name of the log file.

Fields inherited from class org.x4juli.handlers.WriterHandler

immediateFlush, writer

Fields inherited from class org.x4juli.global.components.AbstractHandler

active, closed, extFormatter, headFilter, manager, name, repository, tailFilter

Fields inherited from class java.util.logging.Handler

Constructor Summary

FileHandler()
Default Constructor instantiation used for configuration by file.

FileHandler(java.lang.String handlerName)
Utility Constructor.

Method Summary

void	activateOptions() Activate the options that were previously set with calls to option setters. This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set. Subclasses have not set active to true, but call super as last statement!
void	configure() Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.
boolean	getAppend() Returns the value of the Append option.
boolean	getBufferedIO() Get the value of the BufferedIO option.
int	getBufferSize() Get the size of the IO buffer.
java.lang.String	getFile() Returns the value of the File option.
java.lang.String	getFullQualifiedClassName() Determine performant the FullQualifiedClassName. Subclasses should overwrite this method. Dynamic determination is not recommended.
void	setAppend(boolean flag) The Append option takes a boolean value.
void	setBufferedIO(boolean bufferedIO) The BufferedIO option takes a boolean value.
void	setBufferSize(int bufferSize) Set the size of the IO buffer.
void	setFile(java.lang.String file) The File property takes a string value which should be the name of the file to append to.
void	setFile(java.lang.String filename, boolean append, boolean bufferedIO, int bufferSize) Sets and opens the file where the log output will go.

Methods inherited from class org.x4juli.handlers.WriterHandler

appendLogRecord, checkEntryConditions, close, closeWriter, createWriter, flush, getImmediateFlush, setImmediateFlush, setWriter, subAppend, writeFooter, writeHeader

Methods inherited from class org.x4juli.global.components.AbstractHandler

addFilter, clearFilters, finalize, getFilter, getFormatter, getLogger, getLoggerRepository, getMessageProperties, getName, getNonFloodingLogger, getProperty, getProperty, getProperty, isActive, isClosed, isLoggable, isLoggable, publish, publish, resetErrorCount, setFilter, setFormatter, setName, setObjectStore, toString

Methods inherited from class java.util.logging.Handler

getEncoding, getErrorManager, getLevel, reportError, setEncoding, setErrorManager, setLevel

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.x4juli.global.spi.ExtendedHandler

getEncoding, getErrorManager, getLevel, setEncoding, setErrorManager, setLevel

Field Detail

fileAppend

protected boolean fileAppend

Append to or truncate the file? The default value for this variable is true, meaning that by default a FileAppender will append to an existing file and not truncate it.

This option is meaningful only if the FileAppender opens the file.

fileName

protected java.lang.String fileName

The name of the log file.

bufferedIO

protected boolean bufferedIO

Do we do bufferedIO?

DEFAULT_BUFFER_SIZE

protected static final int DEFAULT_BUFFER_SIZE

Default Size of an Buffered IO.

See Also:

Constant Field Values

bufferSize

protected int bufferSize

The size of the IO buffer. Default is 8K.

Constructor Detail

FileHandler

public FileHandler()

Default Constructor instantiation used for configuration by file. This automaticaly activatesOptions(). Avoid in programmatically use.

FileHandler

public FileHandler(java.lang.String handlerName)

Utility Constructor. All properties must be set programmatically. Finally you need to call actiavtesOptions().

Parameters:

handlerName - of the current instance.

Since:

0.5

Method Detail

getFullQualifiedClassName

public java.lang.String getFullQualifiedClassName()

Determine performant the FullQualifiedClassName. Subclasses should overwrite this method. Dynamic determination is not recommended.

Specified by:

getFullQualifiedClassName in interface ExtendedHandler

Overrides:

getFullQualifiedClassName in class WriterHandler

Since:

0.5

setFile

public void setFile(java.lang.String file)

The File property takes a string value which should be the name of the file to append to.

Note: Actual opening of the file is made when activateOptions() is called, not when the options are set.

Parameters:

file - name of the file to use.

Since:

0.5

getAppend

public boolean getAppend()

Returns the value of the Append option.

Since:

0.5

getFile

public java.lang.String getFile()

Returns the value of the File option.

Since:

0.5

activateOptions

public void activateOptions()

Activate the options that were previously set with calls to option setters.

This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set.
Subclasses have not set active to true, but call super as last statement!

Specified by:

activateOptions in interface OptionHandler

Overrides:

activateOptions in class WriterHandler

Since:

0.5

configure

public void configure()

Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.

Overrides:

configure in class WriterHandler

Since:

0.5

getBufferedIO

public boolean getBufferedIO()

Get the value of the BufferedIO option.

BufferedIO will significatnly increase performance on heavily loaded systems.

Since:

0.5

getBufferSize

public int getBufferSize()

Get the size of the IO buffer.

Since:

0.5

setAppend

public void setAppend(boolean flag)

The Append option takes a boolean value. It is set to true by default. If true, then File will be opened in append mode by setFile(String) (see above). Otherwise, setFile(String) will open File in truncate mode.

Note: Actual opening of the file is made when activateOptions() is called, not when the options are set.

Parameters:

flag - to append or not

Since:

0.5

setBufferedIO

public void setBufferedIO(boolean bufferedIO)

The BufferedIO option takes a boolean value. It is set to false by default. If true, then File will be opened and the resulting Writer wrapped around a BufferedWriter. BufferedIO will significatnly increase performance on heavily loaded systems.

Parameters:

bufferedIO - to buffer IO or not

Since:

0.5

setBufferSize

public void setBufferSize(int bufferSize)

Set the size of the IO buffer.

Parameters:

bufferSize - size of the buffer, used if buffered IO is true

Since:

0.5

setFile

public void setFile(java.lang.String filename,
                    boolean append,
                    boolean bufferedIO,
                    int bufferSize)
             throws java.io.IOException

Sets and opens the file where the log output will go. The specified file must be writable.

If there was already an opened file, then the previous file is closed first.

Do not use this method directly. To configure a FileAppender or one of its subclasses, set its properties one by one and then call activateOptions.

Parameters:

filename - The path to the log file.

append - If true will append to fileName. Otherwise will truncate fileName.

bufferedIO - to buffer IO or not.

bufferSize - size of the buffer for IO.

Throws:

java.io.IOException - if file does not exist and cannot be created.

Since:

0.5