Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Received-SPF: pass (hermes.apache.org: domain of
 robertburrelldonkin@blueyonder.co.uk designates 195.188.213.5 as permitted
 sender)
Subject: Re: [logging] proposed design for 1.0.5
From: robert burrell donkin <robertburrelldonkin@blueyonder.co.uk>
To: commons-dev@jakarta.apache.org
In-Reply-To: <1116888956.3835.21.camel@localhost.localdomain>
References: <1116726876.4014.117.camel@localhost.localdomain>
	 <1116880047.4992.53.camel@knossos.elmet>
	 <1116888956.3835.21.camel@localhost.localdomain>
Content-Type: text/plain
Date: Wed, 25 May 2005 20:37:56 +0100
Message-Id: <1117049876.5005.25.camel@knossos.elmet>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On Tue, 2005-05-24 at 10:55 +1200, Simon Kitching wrote:
> On Mon, 2005-05-23 at 21:27 +0100, robert burrell donkin wrote:
> > > (b)
> > > That in addition to commons-logging.jar we distribute a
> > > "commons-logging-adapters.jar" which contains the entire contents of the
> > > "impl" subdirectory, ie all the logging adapters and the concrete
> > > LogFactory subclasses, but specifically NOT
> > >    * LogFactory
> > >    * Log
> > > 
> > > [this is along the lines of Brian's jar-refactoring proposal]
> > > 
> > > We should do away with commons-logging-api.jar; it serves no purpose.
> > 
> > -1
> > 
> > a few reasons:
> > 
> > 1. it is vital for dependency management. it is very important that JCL
> > ships a dependency free jar for compilation and dependency management.
> > the main flaw with the api is that it's too big and not viable by
> > itself. 
> 
> Sorry, I don't understand. Why can't people compile against
> commons-logging.jar?

it's not about compilation: it's about dependency management.

the full commons-logging is dependent on log4j (two versions), avalon
framework and logkit. commons-logging-api has no dependencies outside
java. introducing these additional dependencies would be a *major* issue
for automated dependency management system.
 
> > 2. it is useful for certain parent first configurations. replacing an
> > full jar with an api jar allows some parent first configurations to log
> > to log4j. 
> 
> I don't see why this would be true. What configurations does an api jar
> support that a full commons-logging.jar won't?

3 + 4 (according to the demonstration numbering) are parent first with
log4j present only in the child classloader. these must log to java.util
logging. 

11 + 12 are variations where the JCL in the parent classloader is
replaced by the api jar. now, JCL logs to log4j.

in other words, if you need log4j in the child classloader only and you
want JCL to be able to use it, it's necessary to have the api jar
(rather than the full jar) in the parent classloader.
 
> > 3. backwards compatibility. (would need a 1.1 release at least.)
> 
> I'm happy with making the next release 1.1.
> 
> It should be totally backwards-compliant anyway.

with an api jar to replace the current api jar, configurations such as
11 and 12 would be broken. this breaks symantic compatibility.

in additional, all projects depending on the api jar (only) would need
to update their dependency. 

of course, this would be permitable with a minor version change but i
feel strongly that the problems this would create for dependency and
configuration management would be too great for the gain. i would much
prefer to approach this problem through making stronger recommendations
in the documentation. 

> > > (c) 
> > > That we change the error message when multiple Log instances found, to
> > > state that child should contain -adapters.jar not full jar.
> > 
> > +1
> > 
> > we need to be confident about the diagnostics in this case before
> > recommended definite action. (i believe that some exotic classloader
> > configurations may also produce similar symptoms) i certain think that
> > the wording should be improved but would welcome a reference to
> > troubleshooting document (possibly an url?) which could provide more
> > explanation and could offer advice for the more exotic cases.
> 
> Yep, it's hard to be confident we've understood the situation completely
> until we get feedback from people in the field. But the fact that they
> can turn on diagnostics and email us the output should improve that
> situation greatly. 

+1

> As you say, we could be a bit careful about the wording of the error
> message, just in case it turns out that there are some other situations
> that trigger the same message...eg "This is probably caused by ..."

i think it'd be best for me to making adding exotic classloaders to the
demonstration a priority. (i should be able to do this over the weekend)
i think that this should allow a better understanding of diagnostics
under these conditions...

> > > > (d)
> > > That we provide the deployment instructions listed at the bottom of this
> > > email.
> > 
> > in some ways discovery deployment instructions are both needed and a
> > contradiction. discovery is supposed to guess right but sometimes it
> > needs a little help. 
> > 
> > JCL needs a troubleshooting document. (i even made a start on one a
> > while ago.) the deployment instructions/recommendations would fit very,
> > very into such a document. i like having information on the web (rather
> > than in release notes etc). not only is it easy to reference when
> > answering user questions but it's also easily indexed by search
> > engines. 
> > 
> > if this sounds like a good plan, i'll try to pull something along those
> > lines together in the next few days.
> 
> +1

i'm probably going to push this down my priority list just a little
(after those exotic classloaders). may commit a first draft sooner
rather than try to produce something a little more polished and
considered. 

- robert


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org