commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jon Tirsén <>
Subject RE: runtime attributes
Date Sun, 24 Nov 2002 13:12:52 GMT
> -----Original Message-----
> From: Mark Pollack []
> Sent: den 22 november 2002 23:03
> To: 'Jon Tirsén';;
> Cc:;; 
>; 'Jakarta Commons Developers List'
> Subject: RE: runtime attributes
> Hi,
> Why just adjust the interface between the Writer and
> Extractor to be more self-describing?  It seems that qdox 
> offers enough metadata as the standard javadoc doclet as far 
> as our needs are concerened.  I agree that the coupling 
> between the two should be well defined, either if this is an 
> exchanged object between the two or qdox/javadoc indepenent 
> methods that the writer exposes to the extractor.

This is really what my point 3 was about. If we adjust the interface
between Extractor and Writer to be more self-describing we should do
that between Reader and client too, simply because we'll use the same
object/interface: ClassMetaData.  If we don't want to add two objects
for the same thing, one is used at compile-time (which has all the
Qdox/Xjavadox stuff on it) and the other is used at run-time (and has
the java.lang.reflect stuff on it).

The coupling between Reader and Writer is really implementation
dependent and not much we can do about. (some will use files, some will
use BCEL and so on)

> It seems the motivation for xjavadoc is code mutation, not
> required by us. qdox is speed which shouldn't be a concern at 
> the moment.  What features are lacking in the qdox api? I 
> don't see a need for a new javadoc parser project.  Sorry if 
> I am missing something.

The Qdox and the Xdoclet-team want to unify the parsers into a single
project. Sorry if I assumed everyone was up-to-date on this.

> The Qdox api seems to already offer access to the metadata we
> normally associate with 'java.lang.Class,Method,Field or 
> javadoc.ClassDoc,MethodDoc,FieldDoc.  That is you can drill 
> down the the qdox.JavaParameters[] of the method.  Based on 
> this we could come up with a simple self describing class to 
> pass between the Extractor and the Writer, or just have the 
> extractor call well defined writer methods (preferred way?).  
> These methods do not have to depend on the qdox api if we 
> don't want to - we can use a String array to define the 
> method parameters.  In the case of an implementation that 
> uses qdox, these would come from JavaParameters[], in the 
> case of a doclet implementation they would come from 
> MethodDoc.  In Attribj4, I changed the 'writer' interface 
> (ClassAnnotator) to accept a javadoc.MethodDoc paramter, but 
> that was before I wrote a utility class for bcel to convert 
> its method signature from the jvm way (IJ) to a string array 
> [int, long].  Actually now I realize that I should put that 
> method back to the orignal way since I never liked that 
> dependency there and I was not aware of qdox at the time.

Using a String-array or a String creates implicit contracts ("you need
to send a String in this format"). I think it's better that we use a
proper hard-typed way to do this.

Another thing is that the Extractor and the Writer is not dependent on
each-other. The Ant-task is the driver for them both, it sets up the
Extractor, extracts all meta-data and sends it to the Writer.

> I'm not sure I understand point 3, can you explain better.
> Is the exteral file that contains the metadata self 
> describing enough so that it can be extracted by an 
> AttributeReader easily?  Something like 
> attribute.class.<class tag name> = <class tag value> 
> attribute.field.<field name>.<field tag> = <field tag value> 
> attribute.method.<method name>.<method signature>.<method 
> tag> = <method tag value> This should be easy to create an
> API to read this file in the implementation of the
> AttributeReader that can take java.lang.reflect package 
> classes as arguments.  The only trick part is the method 
> signature, but that isn't that bad either.

That's what I have now.

The tricky part in the new design is the interface between Extractor <->
Ant-task <-> Writer, which is the ClassMetaData object. Another thing is
the interface between Reader <-> Attributes (facade) <-> Client. My
problem number 3 is: Do we want this interface to be the same or shall
we introduce two different ones? Shall we use ClassMetaData both for the
compile-engine and for the runtime?

I've had some thought on this and I think we should use the same. In
that case the ClassMetaData will be based on (a subset of?) the
(upcoming) Xdox-API and not on java.lang.reflect. It will be (a bit)
more work for Writer and Reader-implementors (because they have to
handle things like argument-names which is really only available at
compile-time). On the other hand I think things will be much easier
because we don't need to maintain two different object-models. Also we
can do things like revalidation at runtime and so on.

What do you think? Am I crazy to want to include this stuff at runtime?

I'm gonna have a go at this later today and see how it turns out.

To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message