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
À : discuss@restlet.tigris.org
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
