Hi Piyush, Indeed the move to 1.0 was made too early, I didn't expect the initial design to be so impacted by feed-back and comments... In order to attempt to compensate, we'll have a series of 1.0 RC releases, see: http://www.restlet.org/roadmap
Best regards, Jerome > -----Message d'origine----- > De : Piyush Purang [mailto:[EMAIL PROTECTED] > Envoyé : jeudi 17 août 2006 10:54 > À : [email protected] > Objet : Re: API design review > > Hi Jerome, > > +1 for the move. > > One fact that troubles me is that we are already at/near version 1. > Isn't that a tad too soon? > > Please see my inline comments. > > On 8/16/06, Jerome Louvel <[EMAIL PROTECTED]> wrote: > > Following the recent questions and suggestions from Piyush > Purang, I've > > started reviewing and refactoring the API to make it more > inline with the > > current best practices. I'm basing my work on the following > guide lines: > > > > 1) Java API Design Guidelines by Eamonn McManus > > http://www.artima.com/weblogs/viewpost.jsp?thread=142428 > > > > 2) How to Design a Good API and Why it Matters by > Joshua Bloch > > http://lcsd05.cs.tamu.edu/slides/keynote.pdf > > > > 3) How To Design a (module) API > > http://openide.netbeans.org/tutorial/api-design.html > > > > The next beta release (b18) is moving along pretty well and > already contains > > many improvements in this area: > > - All member variables are now private instead of protected. When > > necessary, we provide protected accessor methods for subclasses > > +10 > > > - There is now a clear dependency between API packages. > The only one > > exception to the rule is the org.restlet.Factory class. The result > > dependency tree is: > > org.restlet.component > > +- org.restlet.connector > > +- org.restlet > > +- org.restlet.data > > +1 > > > - Most interfaces are gone, even Restlet, Filter, etc. But > don't worry they > > were replaced by equivalent classes. The advantage is > simplicity and > > extensibility (riskier to add methods to interfaces without > breaking code, > > unless you force people to use a base class). The only two > survivors are > > Resource and Representation, but I'm still considering this :) > > Hmmm I am not so sure about this move. I will have to play with the > API. I like interfaces. And I still am sceptical about Representation > extending Resource :) > > Do we really need to call that class Chainer :) how about > RestletChain ? > > > - Factorized the enumeration and related classes in > org.restlet.data into a > > single class with static constants. This vastly reduces the > number of > > artifacts to learn and deal with. > > I have to review them. > > I just looked at the Protocol class. So everytime restlet supports a > new protocol someone needs to update 1. the constants and 2. the > create method. Not Good. And why does Protocol extend MetaData ? > > > Here are the other things I'm considering: > > - Add an org.restlet.util (or helper) package with all the > wrapper and > > abstract classes, plus the EmptyValue class. > > +1 for org.restlet.util > > -1 EmptyValue do we really really need a marker interface, > maybe there > is some method that all Value objects must implement? > > +1 to moving wrapper and abstract classes iff the package > dependencies look like > > org.restlet.component > +- org.restlet.connector > +- org.restlet > +- org.restlet.data > +-org.restlet.util > > > - Make the Restlet class and subclasses generic again (for Call > > subclasses). > > No Comment Yet (NCY) > > > - Make the Preference class generic (for Metadata > subclasses) and remove > > all the other *Pref classes which add nothing more than > casting to the > > correct Metadata subclass. > > NCY > > > - Adding an org.restlet.spi package and put the Factory > class in it, but > > hide it from the Javadocs. > > +20 :) -1 hiding it in the Javadocs > > > - Make all classes, except those intended to be > subclasses, as final. Which > > ones? > > Hmmm ... usually immutable classes are very good candidates and > classes that only act as data stores .. > > > - Make classes whose instances don't need to be modified > as immutable > > (members are final). > > +1 > > So those were my first votes and comments. On the whole it is a very > encouraging step to be reviewing the API now rather than after 1.0 > final is out. > > Cheers > Piyush > >
