FWIW, another interesting API doc is from Eliotte Rusty Harrold
regarding XOM:
http://xom.nu/designprinciples.xhtml
Some of the points are specific to XML/DOM stuff, but some are very
useful to keep in mind.
Jerome Louvel wrote:
> ...
- All member variables are now private instead of protected. When
necessary, we provide protected accessor methods for subclasses
Great!
> ...
- 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 :)
I like that you took the findNext() out of Restlet and stuck it into
Chainer. And I think Resource and Representation can probably be made
into abstract classes pretty easily.
- 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.
This is much better!
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.
I think keeping the abstract classes inline with that they're based on
(e.g., Represesentation + AbstractRepresentation in the same package) is
a good idea. Separating them can make it difficult for new people to
find them, unless they have a nifty IDE (like IDEA or Eclipse) that
lists easily all the known implementations.
- Make the Restlet class and subclasses generic again (for Call
subclasses).
Not sure what this means.
- 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.
Cool.
- Adding an org.restlet.spi package and put the Factory class in it, but
hide it from the Javadocs.
Ok.
- Make all classes, except those intended to be subclasses, as final. Which
ones?
This is trickier. You might want to let the API stabilize a bit and see
what people actually do subclass before going down this path.
- Make classes whose instances don't need to be modified as immutable
(members are final).
Great! Immutability makes dealing with concurrency much easier.
Any feed-back? For the most adventurous, there is a new snapshot with the
latest changes from SVN:
I'm in the process of refreshing and rebuilding, and I'll see what
changes are necessary in the sample app.
Chris
--
Chris Winters ([EMAIL PROTECTED])
Lead Software Developer
Vocollect Healthcare Systems
CONFIDENTIAL, PRIVILEGED COMMUNICATION: This e-mail is private and
intended for the addressee(s) only. It may contain privileged and/or
confidential information. If you have received it in error you are not
authorized to disseminate it in any manner; please delete it and any
copies and reply to the sender that it was misdirected.
