From 5275f20dac11d4fb1b5ea8619a83ff8e00332393 Mon Sep 17 00:00:00 2001 From: Simon Kitching Date: Mon, 22 Oct 2007 20:02:23 +0000 Subject: [PATCH] Improve docs. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/logging/trunk@587225 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/guide.xml | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/xdocs/guide.xml b/xdocs/guide.xml index 171f8f6..9eeda42 100644 --- a/xdocs/guide.xml +++ b/xdocs/guide.xml @@ -113,13 +113,21 @@ Familiarity with high-level details of the relevant Logging implementations is p As far as possible, JCL tries to be as unobtrusive as possible. In most cases, including the (full) commons-logging.jar in the classpath should result in JCL configuring itself in a reasonable manner. -There's a good chance that it'll guess your preferred logging system and you won't -need to do any configuration at all! +There's a good chance that it'll guess (discover) your preferred logging system and you won't +need to do any configuration of JCL at all!

Note, however, that if you have a particular preference then providing a simple commons-logging.properties file which specifies the concrete logging library to be used is recommended, since (in this case) JCL will log only to that system and will report any configuration problems that prevent that system being used. +

+

+When no particular logging library is specified then JCL will silently ignore any logging library +that it finds but cannot initialise and continue to look for other alternatives. This is a deliberate +design decision; no application should fail to run because a "guessed" logging library cannot be +used. To ensure an exception is reported when a particular logging library cannot be used, use one +of the available JCL configuration mechanisms to force that library to be selected (ie disable +JCL's discovery process).

@@ -194,6 +202,16 @@ sort of configuration API for the underlying logging system.

Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. Please consult the documentation for the chosen logging system. +

+

+JCL is NOT responsible for initialisation, configuration or shutdown of the underlying logging library. +In many cases logging libraries will automatically initialise/configure themselves when first used, and +need no explicit shutdown process. In these situations an application can simply use JCL and not depend +directly on the API of the underlying logging system in any way. However if the logging library being used +requires special initialisation, configuration or shutdown then some logging-library-specific code will +be required in the application. JCL simply forwards logging method calls to the correct underlying +implementation. When writing library code this issue is of course not relevant as the calling application +is responsible for handling such issues.