FileAppender appends log events to a file. More...

#include <fileappender.h>

Inheritance diagram for log4cxx::FileAppender:

Public Member Functions
	FileAppender ()
	An unconfigured Appender.
	FileAppender (const LayoutPtr &layout, const LogString &fileName, bool appendToExistingFile=true, bool useBufferedOutput=false, int bufferByteCount=DefaultBufferedByteCount)
	Open `fileName` and prepare to write spi::LoggingEvent messages formatted by `layout`.
	~FileAppender ()
void	setFile (const LogString &file)
	The File property takes a string value which should be the name of the file to append to.
bool	getAppend () const
	Returns the value of the Append option.
LogString	getFile () const
	Returns the value of the File option.
void	activateOptions () override
	Derived appenders should override this method if option structure requires it.
void	setOption (const LogString &option, const LogString &value) override
	Set `option` to `value`.
bool	getBufferedIO () const
	Get the value of the BufferedIO option.
int	getBufferSize () const
	Get the size of the IO buffer.
int	getBufferedSeconds () const
	Get the number of seconds between file writes when the `BufferedIO` option is `true`.
void	setAppend (bool newValue)
	Set file open mode to `newValue`.
void	setBufferedIO (bool newValue)
	Set buffered output behavior to `newValue`.
void	setBufferSize (int newValue)
	Use `newValue` as the size of the output buffer.
void	setBufferedSeconds (int newValue)
	Flush the output buffer every `newValue` seconds.
void	setLazyFileCreation (bool newValue)
	Create the file when the first message is written (rather than in activateOptions) if `newValue` is true, so that no empty file is created when nothing is logged.
bool	getLazyFileCreation () const
	Get the value of the LazyFileCreation option.
Public Member Functions inherited from log4cxx::WriterAppender
	WriterAppender ()
	An uninitialised Appender.
	~WriterAppender ()
void	activateOptions () override
	Derived appenders should override this method if option structure requires it.
void	setImmediateFlush (bool value)
	If the ImmediateFlush option is set to `true`, the appender will flush at the end of each write.
bool	getImmediateFlush () const
	Returns value of the ImmediateFlush option.
void	append (const spi::LoggingEventPtr &event) override
	This method is called by the AppenderSkeleton::doAppend method.
void	close () override
	Close this appender instance.
LogString	getEncoding () const
	The current encoding value.
void	setEncoding (const LogString &value)
	Set the encoding to `value`.
void	setOption (const LogString &option, const LogString &value) override
	Set `option` to `value`.
bool	requiresLayout () const override
	Configurators call this method to determine if the appender requires a layout.
void	activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::AppenderSkeleton
	AppenderSkeleton ()
	AppenderSkeleton (const LayoutPtr &layout)
virtual	~AppenderSkeleton ()
void	addFilter (const spi::FilterPtr &newFilter) override
	Add a filter to end of the filter list.
void	clearFilters () override
	Clear the filters chain.
const spi::ErrorHandlerPtr	getErrorHandler () const
	Return the currently set spi::ErrorHandler for this Appender.
spi::FilterPtr	getFilter () const override
	Returns the head Filter.
const spi::FilterPtr	getFirstFilter () const
	Return the first filter in the filter chain for this Appender.
LayoutPtr	getLayout () const override
	Returns the layout of this appender.
LogString	getName () const override
	Returns the name of this Appender.
const LevelPtr	getThreshold () const
	Returns this appenders threshold level.
bool	isAsSevereAsThreshold (const LevelPtr &level) const
	Check whether the message level is below the appender's threshold.
void	doAppend (const spi::LoggingEventPtr &event) override
	Call AppenderSkeleton::doAppendImpl after acquiring a lock that prevents other threads from concurrently executing AppenderSkeleton::doAppendImpl.
void	setErrorHandler (const spi::ErrorHandlerPtr &eh)
	Set the `ErrorHandler` for this Appender.
void	setLayout (const LayoutPtr &layout1) override
	Set the layout for this appender.
void	setName (const LogString &name1) override
	Set the name of this Appender.
void	setThreshold (const LevelPtr &threshold)
	Set the threshold level.
void	activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::Appender
virtual	~Appender ()
void	doAppend (const spi::LoggingEventPtr &event, helpers::Pool &pool)
Public Member Functions inherited from log4cxx::spi::OptionHandler
virtual	~OptionHandler ()
void	activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::helpers::Object
virtual	~Object ()
virtual const helpers::Class &	getClass () const =0
virtual bool	instanceof (const Class &clazz) const =0
virtual const void *	cast (const Class &clazz) const =0

Static Public Member Functions
static LogString	stripDuplicateBackslashes (const LogString &name)
	Replaces double backslashes with single backslashes for compatibility with paths from earlier XML configurations files.

Static Public Attributes
static const int	DefaultBufferedByteCount = 8 * 1024

Protected Member Functions
	FileAppender (std::unique_ptr< FileAppenderPriv > priv)
Protected Member Functions inherited from log4cxx::WriterAppender
	WriterAppender (const LayoutPtr &layout, const helpers::WriterPtr &writer=helpers::WriterPtr())
	An appender that writes spi::LoggingEvent messages formatted by `layout` to the character stream attached to `writer`.
	WriterAppender (std::unique_ptr< WriterAppenderPriv > priv)
	An appender that uses the sub-classed `priv` instance data.
virtual bool	checkEntryConditions () const
	This method determines if there is a sense in attempting to append.
virtual void	subAppend (const spi::LoggingEventPtr &event)
	Format `event` as a message and write it to the character stream.
Protected Member Functions inherited from log4cxx::AppenderSkeleton
	AppenderSkeleton (LOG4CXX_PRIVATE_PTR(AppenderSkeletonPrivate) priv)
void	doAppendImpl (const spi::LoggingEventPtr &event)
	Compare `event` level against the appender threshold and check that `event` is accepted.
bool	isAccepted (const spi::LoggingEventPtr &event) const
	Does no attached filter deny `event` or does an attached filter accept `event`?

Detailed Description

FileAppender appends log events to a file.

The file is opened/created immediately by activateOptions() unless the LazyFileCreation option is set true, in which case the file is opened/created when the first spi::LoggingEvent is added.

Uses a background thread to periodically flush the output buffer when BufferedIO option is set true. Use the BufferedSeconds option to control the frequency, using 0 to disable the background output buffer flush. Refer to FileAppender::setOption() for more information.

Constructor & Destructor Documentation

◆ FileAppender() [1/3]

log4cxx::FileAppender::FileAppender ( )

An unconfigured Appender.

◆ FileAppender() [2/3]

log4cxx::FileAppender::FileAppender	(	const LayoutPtr &	layout,
		const LogString &	fileName,
		bool	appendToExistingFile = true,
		bool	useBufferedOutput = false,
		int	bufferByteCount = DefaultBufferedByteCount )

Open fileName and prepare to write spi::LoggingEvent messages formatted by layout.

The preexisting content of fileName will be preserved if appendToExistingFile is true, otherwise, it will be removed when fileName is opened.

If the useBufferedOutput parameter is true, log messages will be accumulated in a bufferByteCount sized buffer before being writen to fileName.

◆ ~FileAppender()

log4cxx::FileAppender::~FileAppender ( )

◆ FileAppender() [3/3]

log4cxx::FileAppender::FileAppender ( std::unique_ptr< FileAppenderPriv > priv )

protected

Member Function Documentation

◆ activateOptions()

void log4cxx::FileAppender::activateOptions ( )

overridevirtual

Derived appenders should override this method if option structure requires it.

When LazyFileCreation and Append are both set to true, the file is opened/created when the first spi::LoggingEvent is added, otherwise activateOptions will open/create the file.

When BufferedIO is true and BufferedSeconds is greater than zero, a background task is started that will periodically flush the buffer.

Reimplemented from log4cxx::AppenderSkeleton.

Reimplemented in log4cxx::rolling::MultiprocessRollingFileAppender, and log4cxx::rolling::RollingFileAppender.

◆ getAppend()

bool log4cxx::FileAppender::getAppend ( ) const

Returns the value of the Append option.

◆ getBufferedIO()

bool log4cxx::FileAppender::getBufferedIO ( ) const

Get the value of the BufferedIO option.

Using buffered output will significantly reduce logging overhead.

◆ getBufferedSeconds()

int log4cxx::FileAppender::getBufferedSeconds ( ) const

Get the number of seconds between file writes when the BufferedIO option is true.

◆ getBufferSize()

int log4cxx::FileAppender::getBufferSize ( ) const

Get the size of the IO buffer.

◆ getFile()

LogString log4cxx::FileAppender::getFile ( ) const

Returns the value of the File option.

◆ getLazyFileCreation()

bool log4cxx::FileAppender::getLazyFileCreation ( ) const

Get the value of the LazyFileCreation option.

◆ setAppend()

void log4cxx::FileAppender::setAppend ( bool newValue )

Set file open mode to newValue.

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 (see above). Otherwise, setFile will open File in truncate mode.

Note: The file is opened when activateOptions is called, not when the options are set.

◆ setBufferedIO()

void log4cxx::FileAppender::setBufferedIO ( bool newValue )

Set buffered output behavior to newValue.

By default buffered output is disabled and this appender writes each log message directly to the file. When buffered output is enabled, log messages are stored into a memory buffer and written to the file periodically or when the buffer is full.

Using buffered output will significantly reduce logging overhead.

Note: Behavior change occurs when activateOptions is called, not when the options are set.

◆ setBufferedSeconds()

void log4cxx::FileAppender::setBufferedSeconds ( int newValue )

Flush the output buffer every newValue seconds.

The default period is 5 seconds.

Note: activateOptions must be called after an option is changed to activate the new frequency.

◆ setBufferSize()

void log4cxx::FileAppender::setBufferSize ( int newValue )

Use newValue as the size of the output buffer.

◆ setFile()

void log4cxx::FileAppender::setFile ( const LogString & file )

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

Note that the special values "System.out" or "System.err" are no longer honored.

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

◆ setLazyFileCreation()

void log4cxx::FileAppender::setLazyFileCreation ( bool newValue )

Create the file when the first message is written (rather than in activateOptions) if newValue is true, so that no empty file is created when nothing is logged.

The default is false.

Note: Behavior change occurs when activateOptions is called, not when the options are set.

◆ setOption()

void log4cxx::FileAppender::setOption	(	const LogString &	option,
		const LogString &	value )

overridevirtual

Set option to value.

Supported options	Supported values	Default value
FileName	{any}	-
Append	True,False	True
BufferedIO	True,False	False
BufferedSeconds	{any}	5
LazyFileCreation	True,False	False
ImmediateFlush	True,False	False
BufferSize	(1)	8 KB

(1) An integer in the range 0 - 2^32. You can specify the value with the suffixes "KB" or "MB" so that the integer is interpreted being expressed respectively in kilobytes or megabytes. For example, the value "10KB" will be interpreted as 10240.

See also: AppenderSkeleton::setOption()

Reimplemented from log4cxx::AppenderSkeleton.

Reimplemented in log4cxx::rolling::RollingFileAppender.

◆ stripDuplicateBackslashes()

LogString log4cxx::FileAppender::stripDuplicateBackslashes ( const LogString & name )

static

Replaces double backslashes with single backslashes for compatibility with paths from earlier XML configurations files.

Parameters

name file name

Returns: corrected file name

Member Data Documentation

◆ DefaultBufferedByteCount

const int log4cxx::FileAppender::DefaultBufferedByteCount = 8 * 1024