You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2024/01/26 13:12:52 UTC
(commons-logging) branch master updated: Remove references to very old JDK and commons logging versions (#201)
This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-logging.git
The following commit(s) were added to refs/heads/master by this push:
new ff386ee Remove references to very old JDK and commons logging versions (#201)
ff386ee is described below
commit ff386ee3071c3b6078cd9eaaae9119679dcde16c
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Fri Jan 26 08:12:45 2024 -0500
Remove references to very old JDK and commons logging versions (#201)
* remove referencs to very old JDK and commons logging versions
* fix urls
* commas
* runon
* redundancy
* comma
---
src/site/xdoc/guide.xml | 52 ++++++++++++++++++++++---------------------------
1 file changed, 23 insertions(+), 29 deletions(-)
diff --git a/src/site/xdoc/guide.xml b/src/site/xdoc/guide.xml
index b199e1e..ddafc7c 100644
--- a/src/site/xdoc/guide.xml
+++ b/src/site/xdoc/guide.xml
@@ -103,30 +103,29 @@ a specific logging implementation.
<p>
<strong>Warning:</strong> implementations for older logging backends such as
- <a href="https//logging.apache.org/log4j/1.2/">Log4j 1.2</a>,
- <a href="https//avalon.apache.org">Avalon LogKit</a> and
+ <a href="https://logging.apache.org/log4j/1.2/">Log4j 1.2</a>,
+ <a href="https://avalon.apache.org">Avalon LogKit</a>, and
<a href="https://javalogging.sourceforge.net">Lumberjack</a> are also provided, although they are disabled by default.
</p>
-
<p>
Familiarity with high-level details of the relevant Logging implementations is presumed.
</p>
</section>
<section name="Quick Start">
<p>
-As far as possible, JCL tries to be as unobtrusive as possible.
+JCL tries to be as unobtrusive as possible.
In most cases, including the (full) <code>commons-logging.jar</code> in the classpath
should result in JCL configuring itself in a reasonable manner.
-There's a good chance that it'll guess (discover) your preferred logging system and you won't
+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!
</p><p>
-Note, however, that if you have a particular preference then providing a simple
+Note, however, that if you have a particular preference, then providing a simple
<code>commons-logging.properties</code> 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.
</p>
<p>
-When no particular logging library is specified then JCL will silently ignore any logging library
+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
@@ -163,7 +162,7 @@ to determine what type of <code>Log</code> implementation it should use
<li>
<p>
Look for a configuration attribute of this factory named
-<code>org.apache.commons.logging.Log</code> (for backwards compatibility to
+<code>org.apache.commons.logging.Log</code> (for backwards compatibility with
pre-1.0 versions of this API, an attribute
<code>org.apache.commons.logging.log</code> is also consulted).
</p>
@@ -185,17 +184,17 @@ way of explicitly selecting a Log implementation.
<li>
Look for a system property named
<code>org.apache.commons.logging.Log</code> (for backwards
-compatibility to pre-1.0 versions of this API, a system property
+compatibility with pre-1.0 versions of this API, a system property
<code>org.apache.commons.logging.log</code> is also consulted).
</li>
<li>
If the <code>java.logging</code> module is available, use
the corresponding wrapper class
-(<a href="https//commons.apache.org/logging/apidocs/org/apache/commons/logging/impl/Jdk14Logger.html">Jdk14Logger</a>).
+(<a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/impl/Jdk14Logger.html">Jdk14Logger</a>).
</li>
<li>
Fall back to the default simple logging wrapper
-(<a href="https//commons.apache.org/logging/apidocs/org/apache/commons/logging/impl/SimpleLog.html">SimpleLog</a>).
+(<a href="https://commons.apache.org/logging/apidocs/org/apache/commons/logging/impl/SimpleLog.html">SimpleLog</a>).
</li>
</ol>
<p>
@@ -216,11 +215,11 @@ Configuration of the behavior of the JCL ultimately depends upon the
logging toolkit being used. Please consult the documentation for the chosen logging system.
</p>
<p>
-JCL is NOT responsible for initialisation, configuration or shutdown of the underlying logging library.
+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
+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.
@@ -266,7 +265,7 @@ Note that for application code, declaring the log member as "static" is more
efficient as one Log object is created per class, and is recommended.
However this is not safe to do for a class which may be deployed via a "shared"
classloader in a servlet or j2ee container or similar environment. If the class
-may end up invoked with different thread-context-classloader values set then the
+may end up invoked with different thread-context-classloader values set, then the
member must <i>not</i> be declared static. The use of "static" should therefore
be avoided in code within any "library" type project.
</p>
@@ -316,7 +315,7 @@ In addition to the logging methods, the following are provided for code guards:
<subsection name="Serialization Issues">
<p>Prior to release 1.0.4, none of the standard Log implementations were
Serializable. If you are using such a release and have a Serializable class
- with a member that is of type Log then it is necessary to declare
+ with a member that is of type Log, then it is necessary to declare
that member to be transient and to ensure that the value is restored on
deserialization. The recommended approach is to define a custom
readObject method on the class which reinitializes that member.</p>
@@ -330,7 +329,7 @@ In addition to the logging methods, the following are provided for code guards:
library) is not Serializable for technical reasons.</p>
<p>Custom Log implementations not distributed with commons-logging may
or may not be Serializable. If you wish your code to be compatible with
- any arbitrary log adapter then you should follow the advice given above
+ any arbitrary log adapter, then you should follow the advice given above
for pre-1.0.4 releases.</p>
</subsection>
</section>
@@ -340,10 +339,10 @@ In addition to the logging methods, the following are provided for code guards:
The <code>commons-logging.jar</code> file includes the JCL API, the default
<code>LogFactory</code> implementation and thin-wrapper <code>Log</code>
implementations for
-<a href="https//logging.apache.org/log4j/docs/index.html">Log4J</a>,
-<a href="https//avalon.apache.org/logkit/index.html">Avalon LogKit</a>,
+<a href="https://logging.apache.org/log4j/docs/index.html">Log4J</a>,
+<a href="https://avalon.apache.org/logkit/index.html">Avalon LogKit</a>,
the Avalon Framework's logging infrastructure,
-JDK 1.4, as well as an implementation of JDK 1.4 logging APIs (JSR-47) for
+java.util.logging, as well as an implementation of java.util.logging APIs (JSR-47) for
pre-1.4 systems.
</p>
<p>
@@ -606,10 +605,10 @@ invokes:
Instead JCL caches the
<code>LogFactory</code> implementation created as a result of the discovery
process and uses the cached factory to return <code>Log</code> objects.
-Since in J2EE and similar multi-classloader environments, the result of the
+Since in JEE and similar multi-classloader environments, the result of the
discovery process can vary depending on the thread context classloader
(e.g. one webapp in a web container may be configured to use Log4j and
-another to use JDK 1.4 logging), JCL internally caches the
+another to use java.util.logging), JCL internally caches the
<code>LogFactory</code> instances in a static hashtable, keyed by classloader.
</p>
<p>
@@ -624,18 +623,13 @@ classloader (and thus to all the classes loaded by it) will be
held in <code>LogFactory</code>'s static hashtable.
</p>
<p>
-Beginning with JCL 1.1, <code>LogFactory</code> caches factory implementations in a
+<code>LogFactory</code> caches factory implementations in a
"WeakHashtable". This class is similar to <code>java.util.WeakHashMap</code> in
that it holds a <code>WeakReference</code> to each key (but a strong reference
to each value), thus allowing classloaders to be GC'd even if
<code>LogFactory.release()</code> is never invoked.
</p>
<p>
-Because <code>WeakHashtable</code> depends on JDK 1.3+ features, it is dynamically
-loaded depending on the JVM version; when commons-logging is run on java versions
-prior to 1.3 the code defaults to a standard Hashtable instead.
- </p>
- <p>
If a custom LogFactory implementation is used, however, then a
<code>WeakHashtable</code> alone can be insufficient to allow garbage collection
of a classloader without a call to <code>release</code>. If the abstract class
@@ -735,8 +729,8 @@ for details.
<p>
JCL is distributed with a very simple <code>Log</code> implementation named
<code>org.apache.commons.logging.impl.SimpleLog</code>. This is intended to be a minimal
-implementation and those requiring a fully functional open source logging system are
-directed to <a href='https//logging.apache.org/log4j'>Log4J</a>.
+implementation. Developers requiring a fully functional open source logging system are
+directed to <a href='https://logging.apache.org/log4j'>Log4J</a>.
</p>
<p>
<code>SimpleLog</code> sends all (enabled) log messages,