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 <[email protected]> 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;
