Ok, I admit it, I sidetracked a bit about the ClassMetaData thing. God, I wish I could develop open-source with pair-programming. Your opinions made me snap out of it and I had another go today.
So I had the Extractor <-> ant task <-> Writer model which required the ClassMetaData containing all meta-data. I just changed that to be ant task -> Extractor -> Writer and that made things A LOT easier. The "streams approach". So have a look at my latest patch posted to commons-dev, I think it's quite ok. There's some other pros with having a ClassMetaData (based on java.lang.reflect-values). For example sending it around as an argument, serializing it via RMI, and so on. There's also some optimizations that would be easier to implement if we had a ClassMetaData-object. My experience from using Nanning tells me we do need some speed from this. So I think adding a ClassMetaData/ClassAttributes/AttributeInfo/whatever is the next thing to do. The cool thing about the latest design is that we can really start experimenting with different techniques for handling attributes. To do compile-time validation, just implement a new extractor. If you want to handle some new type of marshalling (object serialization, BeanInfo-style, xml, and so on), implement a new finder/writer-pair to. And so on... Also, I'm pressing the issue about 1.0 and the schedule again: What do we want from 1.0? I'm for just having simple attributes and the pluggable API and the rest goes into releases after that. > -----Original Message----- > From: Mark Pollack [mailto:[EMAIL PROTECTED]] > Sent: den 24 november 2002 17:19 > To: 'Jon Tirsén' > Cc: [EMAIL PROTECTED] > Subject: RE: runtime attributes > > > Hi, > > I think I'm getting closer to understanding the design issues > - a whiteboard session would be so much more efficient! > > >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. > > This is not a prerequisite for our development right? > > > The interface between the Extractor <-> ant task <-> and > Writer probably isn't so important because the only people > who will really see it are implementers of the 'attributes > compile' step, not that it shouldn't be made as > straightforward as possible. I think that could be achieved > in a couple of designs, one which is more stream like, as > javadoc/qdox parser uncovers meta-data it calls appropriate > methods on an associated writer, or the javadoc/qdox parser > runs through and entire class, generates an data-object > (ClassMetaData) and then passes this off to the writer. I > don't think I can see a big difference between the two > approaches. I understand your point about the string array > weakness when describing the method parameters, I suppose > this could be replaced via a Class array, much the same way > that the reflection API is based. This is only an issue for > method parameters since everything else can be described by Strings. > > BTW, there should also be a non-ant way to call the > attributes compiler. > > > The interface between the Reader <-> Attributes (facade) <-> > Client is more important. I can imagine an Attributes API > that also does not expose 'ClassMetaData' to the client, > since the methods could be asking relatively fine-grained > questions - such as 'give me all class attributes for this > class', 'give me all field attributes for this class', etc. > The only case in the API where I could imagine the need to > expose ClassMetaData would be to give the client the ability > to ask 'give me all the attributes for this class', in which > case it has to return a meta-data object so it can iterate > through them. In some sense this is a convenience class. > Implementation wise the design has the same choices as with > how the Extractor and Writer exchange data, the reader and > the attributes(façade) can communicate either through a > shared data object, or via the reader exposing fine-grained > methods that the Attributes(façade) calls. > > The important point for me is that client runtime api should > take the java.lang.reflect classes as arguments since > everyone is used to dealing with them. Just as a point of > info, I don't think the .Net attributes api supports such a > 'return ClassMetaData' feature. > > To support such a ClassMetaData class it has to be our own > implementation and I agree it can't depend on > java.lang.reflect probably since we can't create our own > instances of Field, Method, etc to return. I bet the same > limitation applies to FieldDoc, MethodDoc classes in the javadoc api. > > <jon> > 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. </jon> > > Why are the argument names important. Can you explain > revalidation - maybe there is some nice features of using the > ClassMetaData class that I am missing... > > > Anyway, I'm a little nervous of getting sidetracked with > developing ClassMetaData. I don't think it is a bad idea - > very good from the service provider interface point of view, > but not that critical from the > end-user point of view. I'd like more emphasis right now making sure > the interfaces can support both qdoc/javadoc parsers and also > support storing/getting of more complex attributes such as > serialized objects. I think the current api has some > assumptions about the attributes being string key/string > value pairs - I'll look into this in some more detail. > > Two side questions, how does one go about contributing to the > commons area - submit patches and then someone commits the > work? I'd like to contribute as well but want to be > coordinated with everyone and not duplicate work. Also how > to you use the irc.werken.com chat site? > > How about an email summarizing the newly proposed classes, > interactions, how changing implementations works, etc. I > think we have > > Attribute (the interface for attributes - string name value > pairs - should maybe have getObject!, clients of the api > would be very aware of this attribute.) > > AttributeWriter (the interface for writing attributes - > either property/xml files, .class etc.) > > AttributeReader (read the attribute from files .class files.) > > AttributeExtractor (parses source code to get @tags, qdox, javadoc) > > Attributes (client interface to get attributes at runtime) > > ClassMetaData (Contains extracted meta-data from source files > (which is certainly string key value pairs) and from runtime > meta-data files - which could also be string key/object value > pairs. Maybe rename to begin with Attribute - > AttributeMetaData? AttributeDoc, AttributeInfo ala javabeans?) > > One other approach I had toyed with was something similar to > javabean, where a class Foo could also have an associated > class FooInfo that contains property information. In our > case this could be class Bar has a class BarMetadata which > would be searched in the implementation of the 'Attributes' > class. This is somewhere in between storing attributes in > the .class file itself and in a properties/xml file. This > approach does have some nice features I think.... > > Whew,long email! > Cheers, > Mark > > > > > > > > > > -----Original Message----- > From: Jon Tirsén [mailto:[EMAIL PROTECTED]] > Sent: Sunday, November 24, 2002 8:12 AM > To: 'Mark Pollack' > Subject: RE: runtime attributes > > > > -----Original Message----- > > From: Mark Pollack [mailto:[EMAIL PROTECTED]] > > Sent: den 22 november 2002 23:03 > > To: 'Jon Tirsén'; [EMAIL PROTECTED]; [EMAIL PROTECTED] > > Cc: [EMAIL PROTECTED]; [EMAIL PROTECTED]; > > [EMAIL PROTECTED]; '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: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
