You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2023/07/01 07:34:58 UTC
[logging-log4cxx] 01/01: Document the configuration options supported by each appender, layout and policy class.
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch document_supported_options
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit 327be40f66b10ea2e62873186f8848cd338e68cc
Author: Stephen Webb <sw...@gmail.com>
AuthorDate: Sat Jul 1 17:30:12 2023 +1000
Document the configuration options supported by each appender, layout and policy class.
---
src/main/include/log4cxx/appenderskeleton.h | 13 ++++++--
src/main/include/log4cxx/asyncappender.h | 12 +++++--
src/main/include/log4cxx/consoleappender.h | 14 ++++++++
src/main/include/log4cxx/db/dbappender.h | 13 +++++++-
src/main/include/log4cxx/db/odbcappender.h | 21 ++++++++++--
src/main/include/log4cxx/defaultconfigurator.h | 2 +-
src/main/include/log4cxx/fileappender.h | 23 +++++++++++--
src/main/include/log4cxx/fmtlayout.h | 14 ++++++++
.../include/log4cxx/helpers/onlyonceerrorhandler.h | 12 ++++++-
.../include/log4cxx/helpers/simpledateformat.h | 38 ++++++++++++++++++---
src/main/include/log4cxx/jsonlayout.h | 12 ++++++-
src/main/include/log4cxx/net/smtpappender.h | 35 ++++++++++++++++---
.../include/log4cxx/net/socketappenderskeleton.h | 19 ++++++++++-
src/main/include/log4cxx/net/syslogappender.h | 21 ++++++++++--
src/main/include/log4cxx/net/telnetappender.h | 17 ++++++++--
src/main/include/log4cxx/nt/nteventlogappender.h | 21 ++++++++++++
.../include/log4cxx/pattern/datepatternconverter.h | 39 +++++++++++++++++-----
.../log4cxx/pattern/filedatepatternconverter.h | 9 +++--
src/main/include/log4cxx/patternlayout.h | 27 +++++++++++++--
.../log4cxx/rolling/filterbasedtriggeringpolicy.h | 7 +++-
.../log4cxx/rolling/fixedwindowrollingpolicy.h | 24 +++++++++++++
.../log4cxx/rolling/manualtriggeringpolicy.h | 13 ++++++++
.../rolling/multiprocessrollingfileappender.h | 7 ++++
.../include/log4cxx/rolling/rollingfileappender.h | 28 ++++++++++++++--
.../include/log4cxx/rolling/rollingpolicybase.h | 29 ++++++++++++++--
.../log4cxx/rolling/sizebasedtriggeringpolicy.h | 18 ++++++++++
.../log4cxx/rolling/timebasedrollingpolicy.h | 22 ++++++++++++
src/main/include/log4cxx/spi/filter.h | 9 +++--
.../include/log4cxx/varia/fallbackerrorhandler.h | 7 +++-
src/main/include/log4cxx/writerappender.h | 32 ++++++++++++++----
30 files changed, 498 insertions(+), 60 deletions(-)
diff --git a/src/main/include/log4cxx/appenderskeleton.h b/src/main/include/log4cxx/appenderskeleton.h
index 5de14e6c..5e44cc5a 100644
--- a/src/main/include/log4cxx/appenderskeleton.h
+++ b/src/main/include/log4cxx/appenderskeleton.h
@@ -71,10 +71,19 @@ class LOG4CXX_EXPORT AppenderSkeleton :
void finalize();
/**
- Derived appenders should override this method if option structure
- requires it.
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
*/
void activateOptions(helpers::Pool& /* pool */) override {}
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ Threshold | Trace,Debug,Info,Warn,Error,Fatal,Off,All | All
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/asyncappender.h b/src/main/include/log4cxx/asyncappender.h
index 9bba926f..b276deca 100644
--- a/src/main/include/log4cxx/asyncappender.h
+++ b/src/main/include/log4cxx/asyncappender.h
@@ -176,9 +176,15 @@ class LOG4CXX_EXPORT AsyncAppender :
/**
- * Set appender properties by name.
- * @param option property name.
- * @param value property value.
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ LocationInfo | True,False | False
+ BufferSize | int | 128
+ Blocking | True,False | True
+
+ \sa AppenderSkeleton::setOption()
*/
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/consoleappender.h b/src/main/include/log4cxx/consoleappender.h
index 21a92075..f7fd4454 100644
--- a/src/main/include/log4cxx/consoleappender.h
+++ b/src/main/include/log4cxx/consoleappender.h
@@ -76,7 +76,21 @@ class LOG4CXX_EXPORT ConsoleAppender : public WriterAppender
*/
LogString getTarget() const;
+ /**
+ \copybrief WriterAppender::activateOptions()
+
+ No action is performed in this implementation.
+ */
void activateOptions(helpers::Pool& p) override;
+ /**
+ \copybrief WriterAppender::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ Target | System.err,System.out | System.out
+
+ \sa WriterAppender::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/db/dbappender.h b/src/main/include/log4cxx/db/dbappender.h
index 595c6f2e..8325e16e 100644
--- a/src/main/include/log4cxx/db/dbappender.h
+++ b/src/main/include/log4cxx/db/dbappender.h
@@ -123,7 +123,18 @@ class LOG4CXX_EXPORT DBAppender : public AppenderSkeleton
virtual ~DBAppender();
/**
- Set options
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ DriverName | {any} | -
+ DriverParams | {any} | -
+ DatabaseName | {any} | -
+ SQL | {any} | -
+ ColumnMapping | (\ref rep "^") | -
+
+ \anchor rep ^. One value for each '%%' character in the SQL value.
+ \sa AppenderSkeleton::setOption()
*/
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/db/odbcappender.h b/src/main/include/log4cxx/db/odbcappender.h
index 3b308add..5256e3b9 100644
--- a/src/main/include/log4cxx/db/odbcappender.h
+++ b/src/main/include/log4cxx/db/odbcappender.h
@@ -83,8 +83,8 @@ The following <b>param</b> elements are optional:
- <b>method</b> - the function in which the logging event was generated (\ref usingMacros "1")
- <b>message</b> - the data sent by the logging statement
- <b>mdc</b> - A JSON format string of all entries in the logging thread's mapped diagnostic context
- - <b>mdc{key}</b> - the value associated with the <b>key</b> entry in the logging thread's mapped diagnostic context
- - <b>ndc</b> - the last entry the logging thread's nested diagnostic context
+ - <b>mdc{key}</b> - the value associated with the <b>key</b> entry in the logging thread's mapped diagnostic context
+ - <b>ndc</b> - the last entry the logging thread's nested diagnostic context
\anchor usingMacros 1. Only available when the LOG4CXX_* macros are used to issue the logging request.
@@ -152,7 +152,22 @@ class LOG4CXX_EXPORT ODBCAppender : public AppenderSkeleton
virtual ~ODBCAppender();
/**
- Set options
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ BufferSize | {int} | 1
+ ConnectionString | {any} | -
+ URL | {any} | -
+ DSN | {any} | -
+ User | {any} | -
+ Password | {any} | -
+ SQL | {any} | -
+ ColumnMapping | (\ref colName "^") | -
+
+ \anchor colName ^. One value for each '?' character in the SQL value.
+
+ \sa AppenderSkeleton::setOption()
*/
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/defaultconfigurator.h b/src/main/include/log4cxx/defaultconfigurator.h
index caceac20..860b8062 100644
--- a/src/main/include/log4cxx/defaultconfigurator.h
+++ b/src/main/include/log4cxx/defaultconfigurator.h
@@ -93,7 +93,7 @@ class LOG4CXX_EXPORT DefaultConfigurator
* a valid configuration file is found or the end of the list is reached.
*
* @param directories The directories to look in.
- * @param filenamse The names of the files to look for
+ * @param filenames The names of the files to look for
* @return The status of the configuration, and the filename loaded(if a file was found).
*/
static std::tuple<log4cxx::spi::ConfigurationStatus,LogString> configureFromFile(const std::vector<LogString>& directories,
diff --git a/src/main/include/log4cxx/fileappender.h b/src/main/include/log4cxx/fileappender.h
index d2e199c0..c757acb7 100644
--- a/src/main/include/log4cxx/fileappender.h
+++ b/src/main/include/log4cxx/fileappender.h
@@ -112,12 +112,29 @@ class LOG4CXX_EXPORT FileAppender : public WriterAppender
LogString getFile() const;
/**
- <p>Sets and <i>opens</i> the file where the log output will
+ \copybrief AppenderSkeleton::activateOptions()
+
+ Sets and <i>opens</i> the file where the log output will
go. The specified file must be writable.
- <p>If there was already an opened file, then the previous file
- is closed first.*/
+ If there was already an opened file, then the previous file
+ is closed first.
+ */
void activateOptions(helpers::Pool& p) override;
+
+ /**
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ FileName | {any} | -
+ Append | True,False | True
+ BufferedIO | True,False | True
+ ImmediateFlush | True,False | False
+ BufferSize | {int} | 8 KB
+
+ \sa AppenderSkeleton::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/fmtlayout.h b/src/main/include/log4cxx/fmtlayout.h
index 79fb9e28..3abe6041 100644
--- a/src/main/include/log4cxx/fmtlayout.h
+++ b/src/main/include/log4cxx/fmtlayout.h
@@ -257,7 +257,21 @@ class LOG4CXX_EXPORT FMTLayout : public Layout
return true;
}
+ /**
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
+ */
void activateOptions(helpers::Pool& /* p */) override;
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ ConversionPattern | {any} | -
+
+ */
void setOption(const LogString& /* option */,
const LogString& /* value */) override;
};
diff --git a/src/main/include/log4cxx/helpers/onlyonceerrorhandler.h b/src/main/include/log4cxx/helpers/onlyonceerrorhandler.h
index 2395d5ab..168acb62 100644
--- a/src/main/include/log4cxx/helpers/onlyonceerrorhandler.h
+++ b/src/main/include/log4cxx/helpers/onlyonceerrorhandler.h
@@ -60,9 +60,19 @@ class LOG4CXX_EXPORT OnlyOnceErrorHandler :
/**
- No options to activate.
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
*/
void activateOptions(helpers::Pool& p) override;
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ - | - | -
+ */
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/helpers/simpledateformat.h b/src/main/include/log4cxx/helpers/simpledateformat.h
index 802975bb..ab5b2034 100644
--- a/src/main/include/log4cxx/helpers/simpledateformat.h
+++ b/src/main/include/log4cxx/helpers/simpledateformat.h
@@ -39,19 +39,47 @@ LOG4CXX_LIST_DEF(PatternTokenList, log4cxx::helpers::SimpleDateFormatImpl::Patte
/**
- * Concrete class for formatting and parsing dates in a
- * locale-sensitive manner.
+ * Concrete class for converting and formatting a date/time
+ * in a locale-sensitive manner.
+ *
+ * Specifier | Date/time component
+ * --------- | ---------------------
+ * G | era
+ * y | year
+ * M | month number
+ * MMM | abbreviated month name
+ * MMMM | full month name
+ * w | week in year
+ * W | week in month
+ * D | day in year
+ * d | day in month
+ * EEE | abbreviated day name
+ * EEEE | full day name
+ * a | AM or PM
+ * H | hour 0 - 23
+ * k | hour 1 - 24
+ * K | hour 0 - 11
+ * h | hour 1 - 12
+ * m | minute
+ * s | second
+ * S | millisecond
+ * z | time zone identifier
+ * Z | RFC822 time zone
*/
class LOG4CXX_EXPORT SimpleDateFormat : public DateFormat
{
public:
/**
- * Constructs a DateFormat using the given pattern and the default
- * time zone.
+ * A time converter and formatter using \c pattern and the default std::locale.
*
- * @param pattern the pattern describing the date and time format
+ * @param pattern the specifiers describing the date and time format
*/
SimpleDateFormat(const LogString& pattern);
+ /**
+ * A time converter and formatter using \c pattern and \c locale.
+ *
+ * @param pattern the specifiers describing the date and time format
+ */
SimpleDateFormat(const LogString& pattern, const std::locale* locale);
~SimpleDateFormat();
diff --git a/src/main/include/log4cxx/jsonlayout.h b/src/main/include/log4cxx/jsonlayout.h
index b53009b4..a3aa3cf5 100644
--- a/src/main/include/log4cxx/jsonlayout.h
+++ b/src/main/include/log4cxx/jsonlayout.h
@@ -89,10 +89,20 @@ class LOG4CXX_EXPORT JSONLayout : public Layout
*/
LogString getContentType() const override;
+ /**
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
+ */
void activateOptions(helpers::Pool& /* p */) override;
/**
- Set options
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ LocationInfo | True,False | false
+ PrettyPrint | True,False | false
*/
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/net/smtpappender.h b/src/main/include/log4cxx/net/smtpappender.h
index 3881a2bd..fe8d1fd2 100644
--- a/src/main/include/log4cxx/net/smtpappender.h
+++ b/src/main/include/log4cxx/net/smtpappender.h
@@ -38,7 +38,7 @@ A value must be provided for the following <b>param</b> elements :
The email address in the <b>from</b> field of the message.
- one of <b>to</b>, <b>cc</b>, <b>bcc</b> -
An email address in the message.
-
+
The following <b>param</b> elements are optional:
- <b>smtpPort</b> -
The TCP/IP port number on the SMTP server.
@@ -136,13 +136,40 @@ class LOG4CXX_EXPORT SMTPAppender : public AppenderSkeleton
~SMTPAppender();
/**
- Set options
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ smtpHost | {any} | -
+ smtpPort | {int} | 25
+ smtpUserName | {any} | -
+ smtpPassword | {any} | -
+ from | (\ref asciiCheck "1") | -
+ to | (\ref asciiCheck "1") | -
+ cc | (\ref asciiCheck "1") | -
+ bcc | (\ref asciiCheck "1") | -
+ subject | {any} | -
+ subject | {any} | -
+ buffersize | {int} | 512
+ evaluatorClass | (\ref AppenderSkeleton "2") | -
+
+ \anchor asciiCheck "1". Only ASCII charaters
+
+ \anchor TriggeringEventEvaluator "2". A registered class deriving from TriggeringEventEvaluator
+
+ \sa AppenderSkeleton::setOption()
*/
void setOption(const LogString& option, const LogString& value) override;
/**
- Activate the specified options, such as the smtp host, the
- recipient, from, etc.
+ \copybrief AppenderSkeleton::activateOptions()
+
+ Will not activate and will log an error message if:<ul>
+ <li>no layout is provided</li>
+ <li>no TriggeringEventEvaluator is provided</li>
+ <li>any required field is missing</li>
+ <li>a non-ascii character is detected where not permitted</li>
+ </ul>.
*/
void activateOptions(helpers::Pool& p) override;
diff --git a/src/main/include/log4cxx/net/socketappenderskeleton.h b/src/main/include/log4cxx/net/socketappenderskeleton.h
index a5a01313..b4455efa 100644
--- a/src/main/include/log4cxx/net/socketappenderskeleton.h
+++ b/src/main/include/log4cxx/net/socketappenderskeleton.h
@@ -52,7 +52,9 @@ class LOG4CXX_EXPORT SocketAppenderSkeleton : public AppenderSkeleton
SocketAppenderSkeleton(const LogString& host, int port, int reconnectionDelay);
/**
- Connect to the specified <b>RemoteHost</b> and <b>Port</b>.
+ \copybrief AppenderSkeleton::activateOptions()
+
+ Connects to the specified <b>RemoteHost</b> and <b>Port</b>.
*/
void activateOptions(helpers::Pool& p) override;
@@ -122,6 +124,21 @@ class LOG4CXX_EXPORT SocketAppenderSkeleton : public AppenderSkeleton
void fireConnector();
+ /**
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ RemoteHost | (\ref inetAddress "1") | -
+ Port | {int} | (\ref defaultPort "2")
+ LocationInfo | True,False | False
+
+ \anchor inetAddress 1. A valid internet address.
+
+ \anchor defaultPort 2. Provided by the derived class.
+
+ \sa AppenderSkeleton::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
protected:
diff --git a/src/main/include/log4cxx/net/syslogappender.h b/src/main/include/log4cxx/net/syslogappender.h
index db8acd3b..6180a97e 100644
--- a/src/main/include/log4cxx/net/syslogappender.h
+++ b/src/main/include/log4cxx/net/syslogappender.h
@@ -76,10 +76,27 @@ class LOG4CXX_EXPORT SyslogAppender : public AppenderSkeleton
void append(const spi::LoggingEventPtr& event, helpers::Pool& p) override;
/**
- This method returns immediately as options are activated when they
- are set.
+ \copybrief AppenderSkeleton::activateOptions()
+
+ No action is performed in this implementation.
*/
void activateOptions(helpers::Pool& p) override;
+
+ /**
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ SysLogHost | (\ref sysLogAddress "1") | -
+ Facility | (\ref facility "2") | -
+ MaxMessageLength | {int} | 1024
+
+ \anchor sysLogAddress 1. A valid internet address, optionally with the port number as a suffix after a ':'.
+
+ \anchor facility 2. One of kern,user,mail,daemon,auth,syslog,lpr,news,uucp,cron,ftp,local0,local1,local2,local3,local4,local5,local6,local7 2. Provided by the derived class.
+
+ \sa AppenderSkeleton::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/net/telnetappender.h b/src/main/include/log4cxx/net/telnetappender.h
index 42b3db03..504c65c6 100644
--- a/src/main/include/log4cxx/net/telnetappender.h
+++ b/src/main/include/log4cxx/net/telnetappender.h
@@ -91,12 +91,23 @@ class LOG4CXX_EXPORT TelnetAppender : public AppenderSkeleton
void setEncoding(const LogString& value);
- /** all of the options have been set, create the socket handler and
- wait for connections. */
+ /**
+ \copybrief AppenderSkeleton::activateOptions()
+
+ Create the socket handler and wait for connections.
+ */
void activateOptions(helpers::Pool& p) override;
+
/**
- Set options
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ Port | {int} | 23
+ Encoding | C,UTF-8,UTF-16,UTF-16BE,UTF-16LE,646,US-ASCII,ISO646-US,ANSI_X3.4-1968,ISO-8859-1,ISO-LATIN-1 | UTF-8
+
+ \sa AppenderSkeleton::setOption()
*/
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/nt/nteventlogappender.h b/src/main/include/log4cxx/nt/nteventlogappender.h
index 6ae09e4e..c0282df8 100644
--- a/src/main/include/log4cxx/nt/nteventlogappender.h
+++ b/src/main/include/log4cxx/nt/nteventlogappender.h
@@ -42,8 +42,29 @@ class LOG4CXX_EXPORT NTEventLogAppender : public AppenderSkeleton
virtual ~NTEventLogAppender();
+ /**
+ \copybrief AppenderSkeleton::activateOptions()
+
+ Calls <a href="https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-registereventsourcew">RegisterEventSource</a>.
+ */
void activateOptions(helpers::Pool& p) override;
void close() override;
+
+ /**
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ Server | (\ref winapi "1") | NULL
+ Source | (\ref winapi "1") | -
+ Log | (\ref eventLog "2") | Application
+
+ \anchor winapi 1. Passed to the Win32 API method <a href="https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-registereventsourcew">RegisterEventSource</a>.
+
+ \anchor eventLog 2. An event log name.
+
+ \sa AppenderSkeleton::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/pattern/datepatternconverter.h b/src/main/include/log4cxx/pattern/datepatternconverter.h
index 66ea38ac..f95a1240 100644
--- a/src/main/include/log4cxx/pattern/datepatternconverter.h
+++ b/src/main/include/log4cxx/pattern/datepatternconverter.h
@@ -30,10 +30,7 @@ namespace pattern
/**
- * Convert and format the event's date in a StringBuffer.
- *
- *
- *
+ * Convert and format a date or timestamp into a string.
*/
class LOG4CXX_EXPORT DatePatternConverter : public LoggingEventPatternConverter
{
@@ -52,25 +49,51 @@ class LOG4CXX_EXPORT DatePatternConverter : public LoggingEventPatternConverter
LOG4CXX_CAST_ENTRY_CHAIN(LoggingEventPatternConverter)
END_LOG4CXX_CAST_MAP()
+ /**
+ * An object that can convert a date or timestamp to the format
+ * described by the conversion specifier in the first element in \c options.
+ *
+ * If the conversion specifier contains a \% character,
+ * the date is formated using <a href="https://en.cppreference.com/w/cpp/chrono/c/strftime">strftime</a>.
+ *
+ * Otherwise the conversion specifier must be a pattern compatible with
+ * java.text.SimpleDateFormat, "ABSOLUTE", "DATE" or "ISO8601".
+ * For example, "HH:mm:ss,SSS", "dd MMM yyyy HH:mm:ss,SSS" or "DATE".
+ *
+ * ISO8601 format is assumed if the first element in \c options missing or empty.
+ *
+ * If \c options has a second element, it is assumed to be a time zone specifier,
+ * for example, "GMT-6"
+ */
DatePatternConverter(const OptionsList& options);
~DatePatternConverter();
+ /**
+ * \copydoc #DatePatternConverter::DatePatternConverter()
+ */
static PatternConverterPtr newInstance(
const std::vector<LogString>& options);
-
- using LoggingEventPatternConverter::format;
-
-
+ /**
+ * Append to \c output a textual version of the timestamp in \c event.
+ */
void format(const spi::LoggingEventPtr& event,
LogString& output,
helpers::Pool& p) const override;
+ /**
+ * Append to \c output a textual version of the date or timestamp in \c obj.
+ *
+ * Nothing is added to \c output if \c obj does not point to a Date or spi::LoggingEvent.
+ */
void format(const helpers::ObjectPtr& obj,
LogString& output,
helpers::Pool& p) const override;
+ /**
+ * Append to \c toAppendTo a textual version of \c date.
+ */
void format(const helpers::DatePtr& date,
LogString& toAppendTo,
helpers::Pool& p) const;
diff --git a/src/main/include/log4cxx/pattern/filedatepatternconverter.h b/src/main/include/log4cxx/pattern/filedatepatternconverter.h
index 0495ea96..839ee39d 100644
--- a/src/main/include/log4cxx/pattern/filedatepatternconverter.h
+++ b/src/main/include/log4cxx/pattern/filedatepatternconverter.h
@@ -43,9 +43,12 @@ class LOG4CXX_EXPORT FileDatePatternConverter
public:
/**
- * Obtains an instance of pattern converter.
- * @param options options, may be null.
- * @return instance of pattern converter.
+ * An instance of pattern converter for date conversion and formatting.
+ *
+ * \sa DatePatternConverter::newInstance()
+ *
+ * @param options If empty, used the patterm "yyyy-MM-dd".
+ * @return The date conversion and formatting instance.
*/
static PatternConverterPtr newInstance(
const std::vector<LogString>& options);
diff --git a/src/main/include/log4cxx/patternlayout.h b/src/main/include/log4cxx/patternlayout.h
index 8c9d4d04..bde271aa 100644
--- a/src/main/include/log4cxx/patternlayout.h
+++ b/src/main/include/log4cxx/patternlayout.h
@@ -467,8 +467,9 @@ class LOG4CXX_EXPORT PatternLayout : public Layout
~PatternLayout();
/**
- * Set the <strong>ConversionPattern</strong> option. This is the string which
- * controls formatting and consists of a mix of literal content and
+ * Use \c conversionPattern as to control formatting.
+ *
+ * The pattern can be a mix of literal content and
* conversion specifiers.
*/
void setConversionPattern(const LogString& conversionPattern);
@@ -479,10 +480,30 @@ class LOG4CXX_EXPORT PatternLayout : public Layout
LogString getConversionPattern() const;
/**
- * Call createPatternParser
+ \copybrief spi::OptionHandler::activateOptions()
+
+ Calls createPatternParser
*/
void activateOptions(helpers::Pool& p) override;
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ ConversionPattern | {any} | \%m\%n
+ FatalColor | (\ref validColors "1") | -
+ ErrorColor | (\ref validColors "1") | -
+ WarnColor | (\ref validColors "1") | -
+ InfoColor | (\ref validColors "1") | -
+ DebugColor | (\ref validColors "1") | -
+ TraceColor | (\ref validColors "1") | -
+
+ \anchor validColors "1". A <a href="https://en.wikipedia.org/wiki/ANSI_escape_code">valid ANSI escape sequence</a>.
+ The string prefix "\\x1b[" and suffix "m" will be added if not present.
+
+ \sa setConversionPattern
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/rolling/filterbasedtriggeringpolicy.h b/src/main/include/log4cxx/rolling/filterbasedtriggeringpolicy.h
index d702ecc8..d57d2cbf 100644
--- a/src/main/include/log4cxx/rolling/filterbasedtriggeringpolicy.h
+++ b/src/main/include/log4cxx/rolling/filterbasedtriggeringpolicy.h
@@ -101,10 +101,15 @@ class LOG4CXX_EXPORT FilterBasedTriggeringPolicy : public TriggeringPolicy
spi::FilterPtr& getFilter();
/**
- * Prepares the instance for use.
+ \copybrief spi::OptionHandler::activateOptions()
+
+ Activates all attached filters.
*/
void activateOptions(helpers::Pool&) override;
+ /**
+ \copybrief spi::OptionHandler::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
};
diff --git a/src/main/include/log4cxx/rolling/fixedwindowrollingpolicy.h b/src/main/include/log4cxx/rolling/fixedwindowrollingpolicy.h
index 511c32aa..a1dcfaa1 100644
--- a/src/main/include/log4cxx/rolling/fixedwindowrollingpolicy.h
+++ b/src/main/include/log4cxx/rolling/fixedwindowrollingpolicy.h
@@ -90,7 +90,26 @@ class LOG4CXX_EXPORT FixedWindowRollingPolicy : public RollingPolicyBase
FixedWindowRollingPolicy();
~FixedWindowRollingPolicy();
+ /**
+ \copybrief RollingPolicyBase::activateOptions()
+
+ Logs a warning if an option is not valid.
+
+ \sa RollingPolicyBase::activateOptions()
+ */
void activateOptions(helpers::Pool& p) override;
+
+ /**
+ \copybrief RollingPolicyBase::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ MinIndex | 1-12 | 1
+ MaxIndex | 1-12 | 7
+ ThrowIOExceptionOnForkFailure | True,False | True
+
+ \sa RollingPolicyBase::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
void rollover();
@@ -119,6 +138,11 @@ class LOG4CXX_EXPORT FixedWindowRollingPolicy : public RollingPolicyBase
helpers::Pool& pool) override;
protected:
+ /**
+ * A map from "i" and "index" to a integer conversion formatter.
+ *
+ * \sa IntegerPatternConverter
+ */
log4cxx::pattern::PatternMap getFormatSpecifiers() const override;
};
diff --git a/src/main/include/log4cxx/rolling/manualtriggeringpolicy.h b/src/main/include/log4cxx/rolling/manualtriggeringpolicy.h
index f3a1b099..242259f6 100644
--- a/src/main/include/log4cxx/rolling/manualtriggeringpolicy.h
+++ b/src/main/include/log4cxx/rolling/manualtriggeringpolicy.h
@@ -67,7 +67,20 @@ class LOG4CXX_EXPORT ManualTriggeringPolicy : public TriggeringPolicy
const LogString& filename,
size_t fileLength) override;
+ /**
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
+ */
void activateOptions(helpers::Pool&) override;
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ - | - | -
+ */
void setOption(const LogString& option, const LogString& value) override;
};
}
diff --git a/src/main/include/log4cxx/rolling/multiprocessrollingfileappender.h b/src/main/include/log4cxx/rolling/multiprocessrollingfileappender.h
index a61795ab..1d79385b 100644
--- a/src/main/include/log4cxx/rolling/multiprocessrollingfileappender.h
+++ b/src/main/include/log4cxx/rolling/multiprocessrollingfileappender.h
@@ -47,6 +47,13 @@ class LOG4CXX_EXPORT MultiprocessRollingFileAppender : public FileAppender
public:
MultiprocessRollingFileAppender();
+ /**
+ \copybrief FileAppender::activateOptions()
+
+ Activate the attached TriggeringPolicy and RollingPolicy.
+
+ \sa FileAppender::activateOptions()
+ */
void activateOptions(helpers::Pool&) override;
diff --git a/src/main/include/log4cxx/rolling/rollingfileappender.h b/src/main/include/log4cxx/rolling/rollingfileappender.h
index ed3b7cbc..d5c37e65 100644
--- a/src/main/include/log4cxx/rolling/rollingfileappender.h
+++ b/src/main/include/log4cxx/rolling/rollingfileappender.h
@@ -127,13 +127,37 @@ class LOG4CXX_EXPORT RollingFileAppender : public FileAppender
LogString makeFileNamePattern(const LogString& datePattern);
+ /**
+ \copybrief FileAppender::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ FileDatePattern | (\ref dateChars "1") | -
+ MaxBackupIndex | 1-12 | 0
+ MaxFileSize | (\ref fileSz "1") | 10 MB
+
+ \anchor dateChars 1. A pattern compatible with
+ java.text.SimpleDateFormat, "ABSOLUTE", "DATE" or "ISO8601".
+ For example, "HH:mm:ss,SSS", "dd MMM yyyy HH:mm:ss,SSS" or "DATE".
+
+ \anchor fileSz 2. An integer in the range 0 - 2^63.
+ You can specify the value with the suffixes "KB", "MB" or "GB" so that the integer is
+ interpreted being expressed respectively in kilobytes, megabytes
+ or gigabytes. For example, the value "10KB" will be interpreted as 10240.
+
+ \sa FileAppender::setOption()
+ */
void setOption( const LogString& option, const LogString& value ) override;
- /** Prepares RollingFileAppender for use. */
+ /**
+ \copybrief FileAppender::activateOptions()
+
+ \sa FileAppender::activateOptions()
+ */
void activateOptions(helpers::Pool& pool ) override;
/**
- Implements the usual roll over behaviour.
+ Implements the configured roll over behaviour.
<p>If <code>MaxBackupIndex</code> is positive, then files
{<code>File.1</code>, ..., <code>File.MaxBackupIndex -1</code>}
diff --git a/src/main/include/log4cxx/rolling/rollingpolicybase.h b/src/main/include/log4cxx/rolling/rollingpolicybase.h
index 4ab30008..5ea5464f 100644
--- a/src/main/include/log4cxx/rolling/rollingpolicybase.h
+++ b/src/main/include/log4cxx/rolling/rollingpolicybase.h
@@ -56,9 +56,34 @@ class LOG4CXX_EXPORT RollingPolicyBase :
public:
RollingPolicyBase();
virtual ~RollingPolicyBase();
- void activateOptions(log4cxx::helpers::Pool& p) override;
- virtual log4cxx::pattern::PatternMap getFormatSpecifiers() const = 0;
+ /**
+ \copybrief RollingPolicy::activateOptions()
+
+ Logs a warning if FileNamePattern is not set.
+
+ \sa RollingPolicy::activateOptions()
+ */
+ void activateOptions(helpers::Pool& p) override;
+
+ /**
+ A map from a name to the object implementing the (date or index) formatting.
+ */
+ virtual pattern::PatternMap getFormatSpecifiers() const = 0;
+
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ FileNamePattern | (\ref legalChars "^") | -
+ CreateIntermediateDirectories | True,False | False
+
+ \anchor legalChars ^. Legal file name characters plus any conversion specifier supported by the concrete class.
+
+ \sa getFormatSpecifiers()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/rolling/sizebasedtriggeringpolicy.h b/src/main/include/log4cxx/rolling/sizebasedtriggeringpolicy.h
index b0d71e1f..51698274 100644
--- a/src/main/include/log4cxx/rolling/sizebasedtriggeringpolicy.h
+++ b/src/main/include/log4cxx/rolling/sizebasedtriggeringpolicy.h
@@ -74,7 +74,25 @@ class LOG4CXX_EXPORT SizeBasedTriggeringPolicy : public TriggeringPolicy
void setMaxFileSize(size_t l);
+ /**
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
+ */
void activateOptions(helpers::Pool&) override;
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ MaxFileSize | (\ref fileSize "1") | 10 MB
+
+ \anchor fileSize 1. An integer in the range 0 - 2^63.
+ You can specify the value with the suffixes "KB", "MB" or "GB" so that the integer is
+ interpreted being expressed respectively in kilobytes, megabytes
+ or gigabytes. For example, the value "10KB" will be interpreted as 10240.
+ */
void setOption(const LogString& option, const LogString& value) override;
};
diff --git a/src/main/include/log4cxx/rolling/timebasedrollingpolicy.h b/src/main/include/log4cxx/rolling/timebasedrollingpolicy.h
index b1cfd221..dcbaadba 100755
--- a/src/main/include/log4cxx/rolling/timebasedrollingpolicy.h
+++ b/src/main/include/log4cxx/rolling/timebasedrollingpolicy.h
@@ -153,6 +153,14 @@ class LOG4CXX_EXPORT TimeBasedRollingPolicy : public virtual RollingPolicyBase,
public:
TimeBasedRollingPolicy();
virtual ~TimeBasedRollingPolicy();
+
+ /**
+ \copybrief RollingPolicyBase::activateOptions()
+
+ Logs a warning if an option is not valid.
+
+ \sa RollingPolicyBase::activateOptions()
+ */
void activateOptions(helpers::Pool& ) override;
void setMultiprocess(bool multiprocess);
@@ -190,9 +198,23 @@ class LOG4CXX_EXPORT TimeBasedRollingPolicy : public virtual RollingPolicyBase,
const LogString& filename,
size_t fileLength) override;
+ /**
+ \copybrief RollingPolicyBase::setOption()
+
+ Supported options | Supported values | Default value
+ :-------------- | :----------------: | :---------------:
+ ThrowIOExceptionOnForkFailure | True,False | True
+
+ \sa RollingPolicyBase::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
protected:
+ /**
+ * A map from "d" and "date" to a date conversion formatter.
+ *
+ * \sa FileDatePatternConverter
+ */
log4cxx::pattern::PatternMap getFormatSpecifiers() const override;
private:
diff --git a/src/main/include/log4cxx/spi/filter.h b/src/main/include/log4cxx/spi/filter.h
index 15eb05f6..26756581 100644
--- a/src/main/include/log4cxx/spi/filter.h
+++ b/src/main/include/log4cxx/spi/filter.h
@@ -102,13 +102,16 @@ class LOG4CXX_EXPORT Filter : public virtual OptionHandler
};
-
/**
- Usually filters options become active when set. We provide a
+ \copybrief spi::OptionHandler::activateOptions()
- default do-nothing implementation for convenience.
+ No action is performed in this implementation.
*/
void activateOptions(helpers::Pool& p) override;
+
+ /**
+ \copybrief spi::OptionHandler::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
diff --git a/src/main/include/log4cxx/varia/fallbackerrorhandler.h b/src/main/include/log4cxx/varia/fallbackerrorhandler.h
index 7676fac3..313801f2 100644
--- a/src/main/include/log4cxx/varia/fallbackerrorhandler.h
+++ b/src/main/include/log4cxx/varia/fallbackerrorhandler.h
@@ -62,9 +62,14 @@ class LOG4CXX_EXPORT FallbackErrorHandler :
/**
- No options to activate.
+ \copybrief spi::OptionHandler::activateOptions()
+
+ No action is performed in this implementation.
*/
void activateOptions(helpers::Pool& p) override;
+ /**
+ \copybrief spi::OptionHandler::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
diff --git a/src/main/include/log4cxx/writerappender.h b/src/main/include/log4cxx/writerappender.h
index 1d2b5aa2..861297a5 100644
--- a/src/main/include/log4cxx/writerappender.h
+++ b/src/main/include/log4cxx/writerappender.h
@@ -131,22 +131,40 @@ class LOG4CXX_EXPORT WriterAppender : public AppenderSkeleton
virtual helpers::WriterPtr createWriter(helpers::OutputStreamPtr& os);
public:
+ /**
+ The current encoding value.
+
+ \sa setOption
+ */
LogString getEncoding() const;
+ /**
+ Set the encoding to \c value.
+
+ \sa setOption
+ */
void setEncoding(const LogString& value);
+
+ /**
+ \copybrief AppenderSkeleton::setOption()
+
+ Supported options | Supported values | Default value
+ -------------- | ---------------- | ---------------
+ Encoding | C,UTF-8,UTF-16,UTF-16BE,UTF-16LE,646,US-ASCII,ISO646-US,ANSI_X3.4-1968,ISO-8859-1,ISO-LATIN-1 | UTF-8
+
+ \sa AppenderSkeleton::setOption()
+ */
void setOption(const LogString& option, const LogString& value) override;
/**
- <p>Sets the Writer where the log output will go. The
- specified Writer must be opened by the user and be
- writable.
+ <p>Send log output to \c writer which must be open and be writable.
- <p>The <code>java.io.Writer</code> will be closed when the
+ <p>The helpers::Writer will be closed when the
appender instance is closed.
+ <b>WARNING:</b> Logging to an unopened Writer will fail.
- <p><b>WARNING:</b> Logging to an unopened Writer will fail.
- <p>
- @param writer An already opened Writer. */
+ @param writer An already opened Writer.
+ */
void setWriter(const log4cxx::helpers::WriterPtr& writer);
const log4cxx::helpers::WriterPtr getWriter() const;