diff --git a/project.xml b/project.xml index 664f676..a153dc0 100644 --- a/project.xml +++ b/project.xml @@ -4,7 +4,6 @@ ../commons-build/project.xml Logging commons-logging - 1.0-dev @@ -16,7 +15,7 @@ 2001 Commons Logging -Commons Logging is a thin adapter allowing configurable bridging to other, +Commons Logging is a thin adapter allowing configurable bridging to other, well known logging systems. @@ -51,7 +50,7 @@ well known logging systems. Scott Sanders - sanders + sanders sanders at apache dot org Apache Software Foundation diff --git a/xdocs/guide.xml b/xdocs/guide.xml index c52daa4..7260c22 100644 --- a/xdocs/guide.xml +++ b/xdocs/guide.xml @@ -13,7 +13,7 @@

The Jakarta Commons Logging (JCL) provides a Log interface that is intended to be both light-weight and independent of numerous logging toolkits. -It provides the middleware/tooling developer a simple +It provides the middleware/tooling developer with a simple logging abstraction, that allows the user (application developer) to plug in a specific logging implementation.

@@ -25,8 +25,8 @@ Familiarity with high-level details of various Logging implementations is presum

The Jakarta Commons Logging provides a Log interface with thin-wrapper implementations for other logging tools, including -Log4J, -Avalon LogKit, +Log4J, +Avalon LogKit, and JDK 1.4. The interface maps closely to Log4J and LogKit. @@ -35,7 +35,7 @@ The interface maps closely to Log4J and LogKit.

-As far as possible, Commons-Logging tries to be as unobtrusive as possible. +As far as possible, Commons-Logging tries to be as unobtrusive as possible. In most cases, including the (full) commons-logging.jar in the classpath should result in Commons-Logging configuring itself in a reasonable manner. There's a good chance that it'll guess your preferred logging system and you won't @@ -43,10 +43,10 @@ need to do any configuration at all!

-There are two base abstractions used by Commons-Logging: Log +There are two base abstractions used by Commons-Logging: Log (the basic logger) and LogFactory (which knows how to create Log -instances). Using LogFactory implementations other than the default is a -subject for advanced users only, so let's concentrate on configuring the default +instances). Using LogFactory implementations other than the default is a +subject for advanced users only, so let's concentrate on configuring the default implementation.

@@ -104,7 +104,7 @@ import org.apache.commons.logging.LogFactory;

-Note that some components using commons-logging may +Note that some components using commons-logging may either extend Log, or provide a component-specific LogFactory implementation. Review the component documentation for guidelines @@ -165,7 +165,7 @@ In addition to the logging methods, the following are provided for code guards:

-Best practices for programming/planning are presented in two categories: +Best practices for programming/planning are presented in two categories: General and Enterprise. The general principles are fairly clear. Enterprise practices are a bit more involved and it is not always as clear as to why they are important. @@ -187,7 +187,7 @@ 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. -Use the guard methods of the form log.is<Priority>() to verify +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.

@@ -223,7 +223,7 @@ so be conservative and keep to a minimum. See also Internationalization.
  • -debug - detailed information on flow of through the system. +debug - detailed information on the flow through the system. Expect these to be written to logs only.
  • @@ -246,7 +246,7 @@ to follow the rules. Since any problems that result are going to be assigned to you, it's in your best interest to be prepared with the proactive tools necessary to demonstrate that your component works correctly, -or at worst that the problem analyzed from your logs. +or at worst that the problem can be analyzed from your logs. For this discussion, we must make a distinction between different types of exceptions based on what kind of boundaries they cross:

    @@ -344,7 +344,7 @@ for working with NLS messages.

    NLS enabled components are particularly appreciated -(thats an open-source-correct term for 'required by corporate end-users' :-) +(that's an open-source-correct term for 'required by corporate end-users' :-) for tooling and middleware components.

    @@ -391,7 +391,7 @@ for the following toolkits, in order of preference:

    • -Log4J +Log4J
    • JDK 1.4 @@ -443,13 +443,13 @@ can be configured to use different logging toolkits. Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. The JCL SPI uses -Log4J +Log4J by default if it is available (in the CLASSPATH).

      As -Log4J +Log4J is the default logger, a few details are presented herein to get the developer/integrator going.

      @@ -510,14 +510,14 @@ while limiting console output to INFO (and higher).
    • -

    -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 a multi-threaded environment +

    +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. +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.

    diff --git a/xdocs/index.xml b/xdocs/index.xml index 6923d96..140789d 100644 --- a/xdocs/index.xml +++ b/xdocs/index.xml @@ -31,7 +31,7 @@ Release Notes document the new features and bug fixes that have been included in the latest release.

    The -JavaDoc API documents for the latest release are available online. +JavaDoc API documents for the latest release are available online. In particular, you should read the package overview of the org.apache.commons.logging package. In addition, there is a (short) User Guide.

    @@ -42,13 +42,13 @@ package. In addition, there is a (short)

    -Releases after 1.0.2 should be downloaded from a mirror. Please remember to verify the -sigature of the release from the +Releases after 1.0.2 should be downloaded from a mirror. Please remember to verify the +signature of the release from the main apache site when downloading from a mirror.

    - Binary releases are available + Binary releases are available here. Source releases are available here diff --git a/xdocs/navigation.xml b/xdocs/navigation.xml index 5e6fcf0..8615969 100755 --- a/xdocs/navigation.xml +++ b/xdocs/navigation.xml @@ -1,7 +1,7 @@ + ]> @@ -13,7 +13,7 @@ -