[Wtp-wst-dev] WTP Server Core API meeting summary

[Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>]

Oct. 25-27: I traveled to Toronto to work on WTP Server Core APIs and meet 
with the committers at IBM. On Monday morning, I met up with Arthur Ryman 
and Tim Deboer. We agreed on the importance of developing use cases for 
the server core. David Williams had started a use case document the 
preceding week, and we decided to expand on that with the goal of having 
an improved document by the end of Wednesday that we could circulate to 
others. Along with use cases, we also wanted to push on understanding and 
writing down key concepts and roles in the server core API, and get into 
more specific areas of how to solve various problems in the current API.
The rest of Monday, and all day Tuesday and Wednesday, Tim and I spent 
locked in a conference room. We started with end user use cases. As we 
listed and worked through use cases, we naturally drilled down to the 
design and API. Tim patiently enlightened me to the requirements and 
history that led to the current design. I offered suggestions about 
possible simplifications, alternate API designs, and general API hygiene. 
After discussing about a dozen end user use cases, we switched to 4 SPI 
use cases. I half jokingly characterized our discussion as "finding out 
how deep the rabbit hole goes". The answer: remarkably deep.
Where did we end up? On one hand, both Tim and I felt our meeting was 
productive for both of us. I learned a lot about the domain and about why 
the current API is put together the way it is. Tim says he came away with 
a better appreciation of what will be involved in making the APIs platform 
quality.
I would now characterize the existing server core API this way: the server 
core API is feature-rich and provides a lot of essential function. While 
it would have been nice to be starting with something simpler, the 
features exposed in the API are generally there for good reasons. We 
should be able to reduce the API "surface area" somewhat, but the end 
result will still be large and somewhat complex. The challenge will be to 
explain the design to others, to make the functionality that is there 
sustainable and easily useable, and to write adequate specifications that 
capture what each of the API elements are supposed to do.
While we did write down and work through the use cases, the write-up is 
not particularly satisfying (the current version is in CVS). I'm not 
entirely sure why I now feel this way, but it's likely because so much of 
what we talked about was not directly touched on from the use cases 
themselves. This make the priority on having a document that explains the 
key concepts and interactions. I'm going to work on this next, and get a 
draft out for discussion in time for next Thursday's Server Tools API 
e-meeting.
There are various areas of the API that need to be reworked; e.g., 
publishing; working copies; delegates. Much of this is best done on paper. 
As we come across an interesting API problem area, we'll write up a note 
to circulate for comments.
One key area that we discussed at length was how to concentrate and 
minimize the assumptions that the server core API make on the whereabouts 
and layout of modules. This is fundamental to allowing more flexible ways 
of laying out modules in projects. I'm writing up some notes and will get 
a draft out in time for next Thursday's e-meeting.
---Jim des Rivieres