A while back Raymond and I looked at what parts of the 2.x code base we'd consider constituted the SPI for Tuscany 2.x. Raymond put together a useful page [1]. This includes the packages that we think an extension developer needs to use in order to build implementation types, bindings, databindings etc. + APIs that a SCA application developer might use.
Because this SPI is exposed to users of Tuscany these are the classes we need to be careful with when we're changing them and, of course, make sure that they are commented/documented correctly/sufficiently. I wanted to come up with a speedy utility that warns when the classes we consider to the SPI classes are changed. I added a test [2] comprising a relatively simple ant script and a unit test. The ant scripts collect a list of all the classes in the SPI and runs javap on them to decompile the essence of them (class and operation signatures) and writes them all to a single file [3]. The Junit takes an MD5 of this safe file and compares it against the MD5 for the SPI file it's generated off the current code base and fails the tests if they aren't the same. Of course this is just comparing the signatures and not the semantics but that was what I was looking for in this case. As I had an ant script with a list of the SPI files in it I extended it with another simple target to create stand-alone Javadoc just for the SPI. I've put the javadoc for trunk up at [4]. I know that we have some javadoc generation configured into the poms but I don't find this particularly satisfactory as it takes an awful long time when I run it and it javadocs everything. Anyhow this isn't in the build at the moment but I'm looking for comments/suggestion about whether this is useful or not or whether I should just keep it as a utility for my personal use. Regards Simon [1] http://tuscany.apache.org/documentation-2x/tuscany-2x-extensibility-and-spis.html [2] http://svn.apache.org/repos/asf/tuscany/sca-java-2.x/trunk/testing/itest/spi/ [3] http://svn.apache.org/repos/asf/tuscany/sca-java-2.x/trunk/testing/itest/spi/spi-safe.txt [4] http://people.apache.org/~slaws/tuscany-20-spi/javadoc/ -- Apache Tuscany committer: tuscany.apache.org Co-author of a book about Tuscany and SCA: tuscanyinaction.com