From 7cd384f042fd504d5944a0803a3eb18b9d5d14b9 Mon Sep 17 00:00:00 2001 From: Simon Kitching Date: Sun, 22 Jan 2006 08:33:16 +0000 Subject: [PATCH] Move FAQ entries to wiki. Minor grammar/spelling fixes. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@371236 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/guide.xml | 72 +++++++++---------------------------------------- 1 file changed, 12 insertions(+), 60 deletions(-) diff --git a/xdocs/guide.xml b/xdocs/guide.xml index ae5b524..26fb81d 100644 --- a/xdocs/guide.xml +++ b/xdocs/guide.xml @@ -417,7 +417,7 @@ Code guards are typically used to guard code that only needs to execute in support of logging, that otherwise introduces undesirable runtime overhead in the general case (logging disabled). -Examples are multiple parameters, or expressions (i.e. string + " more") for parameters. +Examples are multiple parameters, or expressions (e.g. string + " more") for parameters. Use the guard methods of the form log.is<Priority>() to verify that logging should be performed, before incurring the overhead of the logging method call. Yes, the logging methods will perform the same check, but only after resolving parameters. @@ -518,15 +518,15 @@ listed in the 'throws' clause of a method signature.
Appropriate handling of these exceptions depends upon the type of code you are developing. -API's for utility functions and tools should log these at the debug level, +APIs for utility functions and tools should log these at the debug level, if they are caught at all.
For higher level frameworks and middleware components, -these exceptions should be caught immediatly prior to crossing +these exceptions should be caught immediately prior to crossing the API/SPI interface back to user code-space, logged with full stack trace at info level, and rethrown/wrapped as ComponentInternalError. -The assures that the log contains a record of the root cause for +This ensures that the log contains a record of the root cause for future analysis in the event that the exception is not caught and logged/reported as expected by the user's code. @@ -538,10 +538,9 @@ at the programmer's discretion.
  • Significant Internal Boundaries. -This typically only applies to middleware components -that span networks or runtime processes. -Exceptions that cross over significant internal component boundaries, such as networks. -These should be logged when caught as info messages. +This typically only applies to middleware components that span networks or runtime processes. +Exceptions that cross over significant internal component boundaries such as networks +should be logged when caught as info messages. Do not assume that such a (process/network) boundary will deliver exceptions to the 'other side'.
    • @@ -733,58 +732,11 @@ for details.
    - -

    -JCL doesn't (and cannot) impose any requirement on thread safety on the underlying implementation -and thus its SPI contract doesn't guarantee thread safety. -However, JCL can be safely used in a multi-threaded environment -as long as the underlying implementation is thread-safe. -

    -

    -It would be very unusual for a logging system to be thread unsafe. -Certainly, JCL is thread safe when used with the distributed Log implementations. -

    -     - -

    -Upon application startup (especially in a container environment), an exception is thrown -with message 'xxxLogger does not implement Log'! What's the cause and how can -I fix this problem? -

    -

    -This almost always a classloader issue. Log has been loaded by a different -classloader from the logging implementation. Please ensure that: -

    -
      -
    • -all the logging classes (both Log and the logging implementations) -are deployed by the same classloader -
      • -
    -
      -
    • -there is only copy of the classes to be found within the classloader hierarchy. -In application container environments this means ensuring that if the classes -are found in a parent classloader, they are not also present in the leaf classloader -associated with the application. -So, if the jar is deployed within the root classloader of the container then it -should be removed from the application's library. -
      • -
    -     - -

    -See -How Can I Change The Logging System Configuration? -

    -     - -

    -The configuration supported by JCL is limited to choosing the underlying logging system. -JCL does not (and will never) support changing the configuration of the wrapped logging system. -Please use the mechanisms provided by the underlying logging system. -

    -     +

    +See the FAQ document +on the commons-logging wiki site +

    +