My understanding is that there are two distinct sets of classes in the SPIs, those that are designed for specialisation by the extension provider and those that are designed to have their methods invoked by extension provider code calls. I believe that these sets are truly distinct, i.e. the intersect of these sets is the empty set. It feels like a useful piece of information to give the extension programmer. Do you think that there are hybrid classes that make the intersect non-empty?
Kelvin. On Fri, Apr 16, 2010 at 7:53 AM, ant elder <[email protected]> wrote: > On Thu, Apr 15, 2010 at 1:38 PM, kelvin goodson <[email protected]> > wrote: >> On Thu, Apr 15, 2010 at 1:00 PM, Simon Laws <[email protected]> >> wrote: >>> On Thu, Apr 15, 2010 at 12:47 PM, kelvin goodson >>> <[email protected]> wrote: >>>> I've added a reporting section to the top level build, so that I could >>>> add a custom javadoc tag "tuscany.extension.spi" [1]. I used this tag >>>> because there are more than one type of spi in the code (witness >>>> core.spi) >>>> >>>> I had to tweak the maxmemory of the maven javadoc plugin in order for >>>> mvn javadoc:aggregate to work from the modules directory. The output >>>> of this can be seen at [2] . >>>> >>>> Of note is the ImplementationImpl class documentation, which uses the >>>> custom javadoc tag at the class level. I think it is good to >>>> distinguish between tuscany code that is intended for use by extension >>>> or by calling methods direct. So far I've just added a comment in this >>>> example to say that the extension developer would be expected to >>>> derive from this class. I'm not sure if I'm happy with simply >>>> applying a documentation convention -- still thinking about it -- >>>> comments welcome. >>>> >>>> Kelvin. >>>> >>>> [1] http://svn.apache.org/viewvc?rev=934365&view=rev >>>> [2] http://people.apache.org/~kelvingoodson/SCA2.x/jdoc/ >>>> >>> >>> Looking good kelvin. A couple of things. >>> >>> We have >>> >>> Module >>> Package >>> Interface or Class >>> >>> I suspect that not all interfaces or classes in a package are SPIs. >>> Even after the various re-organizations there have been in 2.x. I may >>> be wrong but I'd continue adding the annotations at the >>> Class/Interface level and we'll have to do some analysis after the >>> first pass to see if anything needs to be moved. >>> >>> As for the annotation itself. My concern is whether we'll remember >>> what text can come after it. >>> >>> @tuscany.extension.spi By Inheritance >>> >>> I assume that you can put anything in place of "By Inheritance" and it >>> will be reproduced in the Javadoc. Maybe this is OK. However do the >>> annotations give us any extra facilities over and above being able to >>> grep for them in the code. If grep is the thing then we should >>> probably turn the "By Inheritance" part into part of the annotation. >> >> thanks Simon, I took a little look around to see if there was some >> means of providing an enumerated set of variants of a given tag, but >> I can't find anything, so I guess the dot notation can be extended to >> include the means by which the spi programmer uses the code. We could >> have >> >> tuscany.spi.extension.(inherit | inheritfrom | specialize) >> and >> tuscany.spi.extension.(client | asclient) >> >> I think I favour tuscany.spi.extension.inheritfrom and >> tuscany.spi.extension.asclient, as it would seem less ambiguous to a >> novice tuscany extender. >> >> I note that I have naturally veered towards switching from >> tuscany.extension.spi.* to tuscany.spi.extension.* - and I think this >> lends itself better towards categorising other spis in the future. >> >> Kelvin. >> >>> >>> Simon >>> >>> -- >>> Apache Tuscany committer: tuscany.apache.org >>> Co-author of a book about Tuscany and SCA: tuscanyinaction.com >>> >> > > I may have missed this earlier in the thread but what are (inherit | > inheritfrom | specialize) and (client | asclient) for? And do we > really need that level of detail, i'd worry it would quite quickly get > out of date. > > ...ant >
