53173ea247
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@371168 13f79535-47bb-0310-9956-ffa450edef68
197 lines
9.0 KiB
Plaintext
197 lines
9.0 KiB
Plaintext
<!--
|
|
|
|
Copyright 2005,2006 The Apache Software Foundation.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
|
|
$Id$
|
|
|
|
Commons Logging Package
|
|
Version 1.1.0
|
|
Release Notes
|
|
|
|
INTRODUCTION:
|
|
============
|
|
|
|
This release of Jakarta Commons Logging (JCL) is a maintenance release, with a
|
|
few new configuration features but no major changes in services provided.
|
|
|
|
This release introduces significant changes in the way that discovery of
|
|
logging implementations occurs, and how errors are handled. A number of
|
|
problems that have troubled users in past releases (particularly the
|
|
"Log4JLogger does not implement Log" problem) will hopefully be
|
|
significantly reduced or cured.
|
|
|
|
This release is 100% compatible with existing code that calls
|
|
commons-logging. There are some incompatibilities with code that extends
|
|
commons-logging, for example to implement custom logging adapters. See
|
|
the compatibility section for details.
|
|
|
|
For further details, please see the Jakarta Commons Logging website:
|
|
http://jakarta.apache.org/commons/logging.
|
|
|
|
For the very latest news, hints, FAQs etc. please see the
|
|
Jakarta Commons Logging wiki site:
|
|
http://wiki.apache.org/jakarta-commons/Logging
|
|
|
|
== New Features ==
|
|
|
|
* Jarfiles now have release-numbers embedded in the names, for easier management.
|
|
|
|
* New jarfile commons-logging-adapters-xxx.jar is now provided. This can be
|
|
used to resolve class cast conflicts where parts of commons-logging are
|
|
deployed via different classloaders.
|
|
|
|
* New internal diagnostics feature. If commons-logging is behaving in an
|
|
unexpected manner, you can now set system property
|
|
org.apache.commons.logging.diagnostics.dest
|
|
to the value STDOUT, STDERR or a filename. As commons-logging initialises
|
|
itself for each new contextClassLoader it detects, useful information will
|
|
be output about which logging library is bound to and why.
|
|
|
|
* JCL now prefers to "make a best attempt" in problem scenarios rather than
|
|
report an error and fail to initialise. New configurable attributes
|
|
ALLOW_FLAWED_HIERARCHY, ALLOW_FLAWED_DISCOVERY and ALLOW_FLAWED_CONTEXT are
|
|
provided to control startup behavior. The default values for these are all
|
|
true, meaning that commons-logging attempts to recover from bad logging
|
|
configuration situations by finding *some* logger to use even when it isn't
|
|
quite the one that might be expected. This will significantly reduce the
|
|
occurrence of the dreaded LogConfigurationException on application/webapp
|
|
startup at the cost of slightly more ambiguity about where output will go.
|
|
In cases where no logging output is generated or wanted (which is the case
|
|
99% of the time) this is definitely a more convenient approach. Users who
|
|
cannot figure out where logging went or why it went to an unexpected
|
|
destination can enable diagnostics to find out, or set the ALLOW_FLAWED_
|
|
settings to false to force LogConfigurationException to be thrown as in
|
|
earlier releases.
|
|
|
|
* Fix for the problem where memory was not being released under some circumstances
|
|
when a webapp was undeployed. An internal change fixes some situations where
|
|
that occurs (by using weak references); this requires no action on the part of
|
|
users of this library. In addition, a utility class ServletContextCleaner is
|
|
provided in the jarfile which is expected to resolve this problem in all
|
|
situations; however it is necessary for an application to define this class as
|
|
a ServletContextListener in the web.xml in order for this to be invoked.
|
|
|
|
* Prioritised commons-logging.properties files. A file with the name
|
|
"commons-logging.properties" placed in the classpath can be used to set
|
|
various JCL configuration options. In previous releases, the first
|
|
such file found in the classpath was used to configure JCL. Now, each file
|
|
can have an entry "priority", and the file with the highest priority is used.
|
|
Where two files have equal priority, the first one in the classpath is used;
|
|
this maintains backwards compatibility.
|
|
|
|
* New feature to disable loading of logging classes via the thread context
|
|
classloader (TCCL), on a per-webapp basis. Simply putting an entry
|
|
"use_tccl=false" in a commons-logging.properties file will ensure that
|
|
all classes used for logging are loaded via the same classloader that
|
|
loads the LogFactory class. This resolves any "class cast" issues with
|
|
JCL, though at the price of losing some control over logging configuration.
|
|
|
|
* The log4j logging adapter now supports the TRACE level (added to log4j 1.2.12).
|
|
Formerly, any calls to log.trace were output at the log4j debug level.
|
|
|
|
* Better behaviour for systems with null classloaders (generally embedded systems).
|
|
|
|
== Incompatibilities ==
|
|
|
|
There are no changes for code that calls LogFactory or Log methods. This means
|
|
that any application which is a simple "user" of the JCL library can safely
|
|
upgrade to this version.
|
|
|
|
All changes to JCL configuration are backwards compatible.
|
|
|
|
Classes Log4JCategoryLog and Log4jFactory have been removed; these were both
|
|
deprecated in the 1.0.3 release (April 2003).
|
|
|
|
For code that extends the JCL LogFactoryImpl class, the isXXXAvailable methods
|
|
in org.apache.commons.logging.impl.LogFactoryImpl are no longer called during
|
|
discovery by that class. Therefore classes which subclass LogFactoryImpl and
|
|
override those methods will not have their methods called. This is a pretty
|
|
unusual thing to do, so it isn't expected that any apps will actually be
|
|
affected by this.
|
|
|
|
Previous releases of commons-logging-api.jar contained the Jdk14Logger class;
|
|
this has now been removed. If your application needs this jar, then instead of
|
|
upgrading to commons-logging-api-1.1.jar, upgrade to commons-logging-1.1.jar.
|
|
|
|
== Dependencies ==
|
|
|
|
Commons-logging has no mandatory dependencies.
|
|
|
|
Java 1.2 and later are supported. It may be possible to use this release with
|
|
java 1.1 but this has not been tested; the unit tests certainly don't run on
|
|
that version.
|
|
|
|
== Distributed jarfiles ==
|
|
|
|
File commons-logging-nn.jar is the one most people will want. It provides the
|
|
base implementation and adapters to a number of popular logging libraries.
|
|
|
|
File commons-logging-adapters-nn.jar includes only the adapters to various
|
|
concrete logging libraries. When commons-logging-nn.jar or
|
|
commons-logging-api-nn.jar is deployed in a container classpath, then this
|
|
adapters-only jarfile should be deployed in the webapp, not the complete JCL
|
|
distribution. This ensures that the core Log/LogFactory classes are only
|
|
deployed via one classloader, thus avoiding "Log4JLogger does not implement Log"
|
|
and similar problems.
|
|
|
|
File commons-logging-api-nn.jar provides no adapters to external logging
|
|
libraries, just the internally implemented SimpleLog and NoOpLog classes. This
|
|
jarfile may be used as a declared dependency for projects that care about
|
|
"transitive dependencies" and can't handle jarfiles such as commons-logging-nn.jar
|
|
which have "optional" dependencies depending on how they are used. In addition,
|
|
this jarfile can be useful for "rebundlers" of JCL who recompile the source-code
|
|
but who may not be able to recompile against the full set of supported adapters;
|
|
such projects should be able to at least recreate an equivalent of this jarfile.
|
|
|
|
== General Notes ==
|
|
|
|
The jakarta commons project has migrated to the Subversion version control system
|
|
(previously, CVS was used). There should be no effect on users of the JCL
|
|
library, but obviously the process of examining the latest source code, and of
|
|
creating patches for JCL has now changed. Please see the jakarta commons
|
|
website for details (http://jakarta.apache.org/commons).
|
|
|
|
== Bugs Fixed ==
|
|
|
|
* 31597: problem where log4j adapter was in parent classloader but log4j.jar was
|
|
in child classloader led to failure to initialise logging has been
|
|
fixed.
|
|
|
|
* 31710, 10825: commons-logging now works better in systems where getClassLoader
|
|
returns null. This essentially means embedded systems.
|
|
|
|
* 31818: workaround for bug in java1.2 compiler; code now compiles under 1.2
|
|
|
|
* Log4JCategoryLog has been removed from the main distribution jar; it has been
|
|
deprecated for a long while. Replacement class Log4JLogger should be a completely
|
|
transparent replacement for all commons-logging users.
|
|
|
|
* package.html files are no longer present in the jarfiles, removing nuisance
|
|
javadoc warnings when building javadoc for apps using jcl.
|
|
|
|
* In several cases, LogConfigurationException objects were being wrapped in
|
|
other LogConfigurationException objects. These have (hopefully) all been
|
|
fixed.
|
|
|
|
DEPRECATIONS:
|
|
============
|
|
|
|
(These are carried forward from Version 1.0.4)
|
|
|
|
[LogSource] Previously deprecated, replaced by LogFactory.
|
|
|