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/06/23 02:25:59 UTC
[logging-log4cxx] branch master updated: Improve documentation by adding example code (#220)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/master by this push:
new a330ce95 Improve documentation by adding example code (#220)
a330ce95 is described below
commit a330ce9516374b962b0b2bd22afcad8021992709
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Fri Jun 23 12:25:54 2023 +1000
Improve documentation by adding example code (#220)
---
src/examples/cpp/CMakeLists.txt | 19 +++++-------
src/examples/cpp/custom-appender.cpp | 13 ++++----
...-configured.xml => example-auto-configured.xml} | 0
...om-appender.xml => example-custom-appender.xml} | 0
src/examples/cpp/trivial.cpp | 31 ++++++++-----------
src/site/markdown/extending.md | 9 ++++--
src/site/markdown/usage.md | 36 ++++++----------------
7 files changed, 45 insertions(+), 63 deletions(-)
diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt
index afd396cd..643ca743 100644
--- a/src/examples/cpp/CMakeLists.txt
+++ b/src/examples/cpp/CMakeLists.txt
@@ -29,28 +29,25 @@ else()
endif()
foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES)
- add_executable(${exampleName} ${exampleName}.cpp)
+ set(PROGRAM_NAME "example-${exampleName}")
+ add_executable(${PROGRAM_NAME} ${exampleName}.cpp)
if(${exampleName} STREQUAL MyApp2)
- target_sources(${exampleName} PRIVATE com/foo/config2.cpp com/foo/bar.cpp)
+ target_sources(${PROGRAM_NAME} PRIVATE com/foo/config2.cpp com/foo/bar.cpp)
endif()
if(${exampleName} STREQUAL auto-configured)
- target_sources(${exampleName} PRIVATE com/foo/config3.cpp )
+ target_sources(${PROGRAM_NAME} PRIVATE com/foo/config3.cpp )
endif()
- target_compile_definitions(${exampleName} PRIVATE ${EXAMPLE_COMPILE_DEFINITIONS} ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
- target_include_directories(${exampleName} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
- target_link_libraries(${exampleName} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${EXPAT_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS})
+ target_compile_definitions(${PROGRAM_NAME} PRIVATE ${EXAMPLE_COMPILE_DEFINITIONS} ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
+ target_include_directories(${PROGRAM_NAME} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
+ target_link_libraries(${PROGRAM_NAME} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${EXPAT_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS})
if( WIN32 )
- set_target_properties(${exampleName} PROPERTIES
+ set_target_properties(${PROGRAM_NAME} PROPERTIES
VS_DEBUGGER_ENVIRONMENT "PATH=${ESCAPED_PATH}"
VS_DEBUGGER_WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
)
endif()
endforeach()
-configure_file( custom-appender.xml
- ${CMAKE_CURRENT_BINARY_DIR}/custom-appender.xml
- COPYONLY )
-
# Custom handling for format string example, since it utilizes libfmt
if(${fmt_FOUND})
add_executable( format-string format-string.cpp )
diff --git a/src/examples/cpp/custom-appender.cpp b/src/examples/cpp/custom-appender.cpp
index 51c485e8..1507968d 100644
--- a/src/examples/cpp/custom-appender.cpp
+++ b/src/examples/cpp/custom-appender.cpp
@@ -15,9 +15,7 @@
* limitations under the License.
*/
-#include <stdlib.h>
#include <log4cxx/basicconfigurator.h>
-#include <log4cxx/helpers/object.h>
#include <log4cxx/appenderskeleton.h>
#include <log4cxx/helpers/stringhelper.h>
#include <log4cxx/xml/domconfigurator.h>
@@ -60,11 +58,14 @@ IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender)
}
-int main( int argc, char** argv ){
- log4cxx::xml::DOMConfigurator::configure( "custom-appender.xml" );
+int main( int argc, char** argv )
+{
+ using namespace log4cxx;
- log4cxx::LoggerPtr rootLogger = log4cxx::Logger::getRootLogger();
- log4cxx::LoggerPtr nullLogger = log4cxx::Logger::getLogger( "NullLogger" );
+ xml::DOMConfigurator::configure( "example-custom-appender.xml" );
+
+ LoggerPtr rootLogger = Logger::getRootLogger();
+ LoggerPtr nullLogger = Logger::getLogger( "NullLogger" );
LOG4CXX_INFO( rootLogger, "This is some root message" );
LOG4CXX_INFO( nullLogger, "This message will be discarded" );
diff --git a/src/examples/cpp/auto-configured.xml b/src/examples/cpp/example-auto-configured.xml
similarity index 100%
rename from src/examples/cpp/auto-configured.xml
rename to src/examples/cpp/example-auto-configured.xml
diff --git a/src/examples/cpp/custom-appender.xml b/src/examples/cpp/example-custom-appender.xml
similarity index 100%
rename from src/examples/cpp/custom-appender.xml
rename to src/examples/cpp/example-custom-appender.xml
diff --git a/src/examples/cpp/trivial.cpp b/src/examples/cpp/trivial.cpp
index 6e8726e2..23268f25 100644
--- a/src/examples/cpp/trivial.cpp
+++ b/src/examples/cpp/trivial.cpp
@@ -14,40 +14,35 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-#include <log4cxx/logstring.h>
#include <stdlib.h>
#include <log4cxx/logger.h>
#include <log4cxx/basicconfigurator.h>
-#include <log4cxx/helpers/exception.h>
#include <log4cxx/ndc.h>
#include <locale.h>
using namespace log4cxx;
-using namespace log4cxx::helpers;
int main()
{
- setlocale(LC_ALL, "");
+ setlocale(LC_ALL, ""); // Use the user-preferred locale
int result = EXIT_SUCCESS;
try
{
- BasicConfigurator::configure();
- LoggerPtr rootLogger = Logger::getRootLogger();
+ BasicConfigurator::configure();
+ LoggerPtr rootLogger = Logger::getRootLogger();
- NDC::push("trivial context");
-
- LOG4CXX_DEBUG(rootLogger, "debug message");
- LOG4CXX_INFO(rootLogger, "info message");
- LOG4CXX_WARN(rootLogger, "warn message");
- LOG4CXX_ERROR(rootLogger, "error message");
- LOG4CXX_FATAL(rootLogger, "fatal message");
-
- NDC::pop();
- }
- catch(std::exception&)
+ NDC context1("[outer]");
+ LOG4CXX_INFO(rootLogger, "info message"); // log entry contains "[outer]"
{
- result = EXIT_FAILURE;
+ NDC context2("[inner]");
+ LOG4CXX_DEBUG(rootLogger, "debug message"); // log entry contains "[outer] [inner]"
}
+ LOG4CXX_WARN(rootLogger, "warn message"); // log entry contains "[outer]"
+ }
+ catch(std::exception&)
+ {
+ result = EXIT_FAILURE;
+ }
return result;
}
diff --git a/src/site/markdown/extending.md b/src/site/markdown/extending.md
index c06e0389..1e826363 100644
--- a/src/site/markdown/extending.md
+++ b/src/site/markdown/extending.md
@@ -25,8 +25,7 @@ Sometimes, you may want to extend Log4cxx, for example by creating
a new appender to write out data in a new format. The following
guide shows how you can extend Log4cxx in order to add a new appender.
-The full sample application can be found in the src/examples/cpp
-directory.
+The full sample application can be found at \ref custom-appender.cpp and \ref custom-appender.xml .
The first thing for our example is to create a class that extends
log4cxx.AppenderSkeleton so that we don't need to implement all of
@@ -139,3 +138,9 @@ to Log4cxx, including(but not limited to):
* [Appenders](@ref log4cxx.Appender)
* [Layouts](@ref log4cxx.Layout)
* [Filters](@ref log4cxx.spi.Filter)
+
+\example custom-appender.cpp
+This example shows how to extend Log4cxx with a new appender.
+
+\example custom-appender.xml
+This example shows how to use a new appender in a configuration file.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index c376dcfb..14010d19 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -567,34 +567,15 @@ of Program Design 3*, edited by R. Martin, D. Riehle, and F. Buschmann
(Addison-Wesley, 1997).
To uniquely stamp each request, the user pushes contextual information
-into the NDC, the abbreviation of *Nested Diagnostic Context*. The NDC
-class is shown below.
-
-~~~{.cpp}
- namespace log4cxx {
- class NDC {
- public:
- // pushes the value on construction and pops on destruction.
- NDC(const std::string& value);
- NDC(const std::wstring& value);
-
- // Remove the top of the context from the NDC.
- static LogString pop();
-
- // Add diagnostic context for the current thread.
- static void push(const std::string& message);
- static void push(const std::wstring& message);
- }
- }
-~~~
+into the *Nested Diagnostic Context* (NDC) using the *log4cxx::NDC* class.
+For an example refer to \ref trivial.cpp.
+Note that all methods of the *log4cxx::NDC* class are static.
The NDC is managed per thread as a *stack* of contextual information.
-Note that all methods of the *log4cxx::NDC* class are static. Assuming
-that NDC printing is turned on, every time a log request is made, the
-appropriate Log4cxx component will include the *entire* NDC stack for
-the current thread in the log output. This is done without the
-intervention of the user, who is responsible only for placing the
-correct information in the NDC by using the *push* and *pop* methods at
+Each log entry will include the entire stack
+for the current thread (for better control use *log4cxx::MDC*).
+The user is responsible for placing the correct information in the NDC
+by using the *push* and *pop* methods at
a few well-defined points in the code. In contrast, the per-client
logger approach commands extensive changes in the code.
@@ -799,6 +780,9 @@ and sent to different and multiple output targets in user-chosen
formats. The Log4cxx package is designed so that log statements can
remain in shipped code without incurring a heavy performance cost.
+\example trivial.cpp
+This example shows how to add a context string to each logging message using the NDC.
+
\example auto-configured.cpp
This is an example of logging in static initialization code and
using the current module name to select the Log4cxx configuration file.