Apache Log4cxx  Version 2.0.0
Loading...
Searching...
No Matches
log4cxx::FileAppender Class Reference

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

#include <fileappender.h>

Inheritance diagram for log4cxx::FileAppender:
log4cxx::WriterAppender log4cxx::AppenderSkeleton log4cxx::Appender log4cxx::spi::OptionHandler log4cxx::helpers::Object log4cxx::rolling::RollingFileAppender log4cxx::rolling::MultiprocessRollingFileAppender

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
 Override this method to set option to value.
bool getBufferedIO () const
 Get the value of the BufferedIO option.
size_t 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 (size_t newValue)
 Use newValue, a value up to 2^31, 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.
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
 Override this method to set option to value.
void activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::AppenderSkeleton
 AppenderSkeleton (const LayoutPtr &layout={})
virtual ~AppenderSkeleton ()
void addFilter (const spi::FilterPtr &newFilter) override
 Add newFilter to end of the spi::Filter chain.
void clearFilters () override
 Clear the spi::Filter chain.
void close () override
 Release any resources allocated within the appender such as file handles, network connections, etc.
const spi::ErrorHandlerPtr getErrorHandler () const
 The currently set spi::ErrorHandler for this Appender.
spi::FilterPtr getFilter () const override
 The first spi::Filter in the filter chain for this Appender.
const spi::FilterPtr getFirstFilter () const
 The first spi::Filter in the filter chain for this Appender.
LayoutPtr getLayout () const override
 The currently set Layout for this appender.
LogString getName () const override
 The name of this Appender.
const LevelPtr getThreshold () const
 This appender's current threshold level.
bool isAsSevereAsThreshold (const LevelPtr &level) const
 Is level greater than or equal to this appender's threshold?
void doAppend (const spi::LoggingEventPtr &event) override
 Call doAppendImpl after acquiring a lock that prevents other threads from concurrently executing doAppendImpl.
void setErrorHandler (const spi::ErrorHandlerPtr &newValue)
 Use newValue as the spi::ErrorHandler for this Appender.
void setLayout (const LayoutPtr &newValue) override
 Use newValue as the layout for this appender.
void setName (const LogString &newValue) override
 Use newValue for the name of this Appender.
void setThreshold (const LevelPtr &newValue)
 Use newValue as this appender's threshold level.
void activateOptions (helpers::Pool &)
Public Member Functions inherited from log4cxx::Appender
virtual ~Appender ()
void doAppend (const spi::LoggingEventPtr &event, helpers::Pool &pool)
virtual bool requiresLayout () const
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 size_t MaxBufferedByteCount = 2LL * 1024 * 1024 * 1024
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)
 Call the AppenderSkeleton::append method if the level of event is not lower than this appender's threshold and no attached spi::Filter indicates event is rejected.
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()

size_t 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 ( size_t newValue)

Use newValue, a value up to 2^31, 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

Override this method to 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^31. 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
namefile name
Returns
corrected file name

Member Data Documentation

◆ DefaultBufferedByteCount

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

◆ MaxBufferedByteCount

const size_t log4cxx::FileAppender::MaxBufferedByteCount = 2LL * 1024 * 1024 * 1024
static

The documentation for this class was generated from the following file: