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
