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
- 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
- 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 :)
- 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.
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.
- Make the Restlet class and subclasses generic again (for Call
subclasses).
- 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.
- Adding an org.restlet.spi package and put the Factory class in it, but
hide it from the Javadocs.
- Make all classes, except those intended to be subclasses, as final. Which
ones?
- Make classes whose instances don't need to be modified as immutable
(members are final).
Any feed-back? For the most adventurous, there is a new snapshot with the
latest changes from SVN:
http://www.restlet.org/downloads/current.zip
Best regards,
Jerome Louvel
--
Noelios Consulting
http://www.noelios.com
