Siphalor/tweed5-commons-logging
1
0
Fork 0
Code Activity

Remove references to very old JDK and commons logging versions (#201)

Browse Source 
* remove referencs to very old JDK and commons logging versions

* fix urls

* commas

* runon

* redundancy

* comma
This commit is contained in:
Elliotte Rusty Harold
2024-01-26 08:12:45 -05:00
committed by GitHub
parent 9965147aa8
commit ff386ee307
1 changed files with 23 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
src/site/xdoc/guide.xml
View File

@@ -103,30 +103,29 @@ a specific logging implementation.
<p> <p>
<strong>Warning:</strong> implementations for older logging backends such as <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://logging.apache.org/log4j/1.2/">Log4j 1.2</a>,
<a href="https//avalon.apache.org">Avalon LogKit</a> and <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. <a href="https://javalogging.sourceforge.net">Lumberjack</a> are also provided, although they are disabled by default.
</p> </p>
<p> <p>
Familiarity with high-level details of the relevant Logging implementations is presumed. Familiarity with high-level details of the relevant Logging implementations is presumed.
</p> </p>
</section> </section>
<section name="Quick Start"> <section name="Quick Start">
<p> <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 In most cases, including the (full) <code>commons-logging.jar</code> in the classpath
should result in JCL configuring itself in a reasonable manner. 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! need to do any configuration of JCL at all!
</p><p> </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 <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 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. and will report any configuration problems that prevent that system being used.
</p> </p>
<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 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 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 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> <li>
<p> <p>
Look for a configuration attribute of this factory named 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 pre-1.0 versions of this API, an attribute
<code>org.apache.commons.logging.log</code> is also consulted). <code>org.apache.commons.logging.log</code> is also consulted).
</p> </p>
@@ -185,17 +184,17 @@ way of explicitly selecting a Log implementation.
<li> <li>
Look for a system property named Look for a system property named
<code>org.apache.commons.logging.Log</code> (for backwards <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). <code>org.apache.commons.logging.log</code> is also consulted).
</li> </li>
<li> <li>
If the <code>java.logging</code> module is available, use If the <code>java.logging</code> module is available, use
the corresponding wrapper class 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>
<li> <li>
Fall back to the default simple logging wrapper 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> </li>
</ol> </ol>
<p> <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. logging toolkit being used. Please consult the documentation for the chosen logging system.
</p> </p>
<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 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 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 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 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 implementation. When writing library code this issue is of course not relevant as the calling application
is responsible for handling such issues. 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. 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" 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 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 member must <i>not</i> be declared static. The use of "static" should therefore
be avoided in code within any "library" type project. be avoided in code within any "library" type project.
</p> </p>
@@ -316,7 +315,7 @@ In addition to the logging methods, the following are provided for code guards:
<subsection name="Serialization Issues"> <subsection name="Serialization Issues">
<p>Prior to release 1.0.4, none of the standard Log implementations were <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 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 that member to be transient and to ensure that the value is restored on
deserialization. The recommended approach is to define a custom deserialization. The recommended approach is to define a custom
readObject method on the class which reinitializes that member.</p> 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> library) is not Serializable for technical reasons.</p>
<p>Custom Log implementations not distributed with commons-logging may <p>Custom Log implementations not distributed with commons-logging may
or may not be Serializable. If you wish your code to be compatible with 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> for pre-1.0.4 releases.</p>
</subsection> </subsection>
</section> </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 The <code>commons-logging.jar</code> file includes the JCL API, the default
<code>LogFactory</code> implementation and thin-wrapper <code>Log</code> <code>LogFactory</code> implementation and thin-wrapper <code>Log</code>
implementations for implementations for
<a href="https//logging.apache.org/log4j/docs/index.html">Log4J</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>, <a href="https://avalon.apache.org/logkit/index.html">Avalon LogKit</a>,
the Avalon Framework's logging infrastructure, 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. pre-1.4 systems.
</p> </p>
<p> <p>
@@ -606,10 +605,10 @@ invokes:
Instead JCL caches the Instead JCL caches the
<code>LogFactory</code> implementation created as a result of the discovery <code>LogFactory</code> implementation created as a result of the discovery
process and uses the cached factory to return <code>Log</code> objects. 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 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 (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. <code>LogFactory</code> instances in a static hashtable, keyed by classloader.
</p> </p>
<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. held in <code>LogFactory</code>'s static hashtable.
</p> </p>
<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 "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 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 to each value), thus allowing classloaders to be GC'd even if
<code>LogFactory.release()</code> is never invoked. <code>LogFactory.release()</code> is never invoked.
</p> </p>
<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 If a custom LogFactory implementation is used, however, then a
<code>WeakHashtable</code> alone can be insufficient to allow garbage collection <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 of a classloader without a call to <code>release</code>. If the abstract class
@@ -735,8 +729,8 @@ for details.
<p> <p>
JCL is distributed with a very simple <code>Log</code> implementation named 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 <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 implementation. Developers requiring a fully functional open source logging system are
directed to <a href='https//logging.apache.org/log4j'>Log4J</a>. directed to <a href='https://logging.apache.org/log4j'>Log4J</a>.
</p> </p>
<p> <p>
<code>SimpleLog</code> sends all (enabled) log messages, <code>SimpleLog</code> sends all (enabled) log messages,