Hi Alex,
1. This design was already in place for the older Finder, with the
findTarget() and createTarget() methods. The idea is that find() could
potentially reuse instances of ServerResource subclasses created by the
create() method, doing some sort of pooling.
The targetClass property points to the ServerResource subclass that must be
instantiated. I'm not sure how to describe it better in the Javadocs. Any
suggestion?
2. Good points. Here is the updated Javadocs for ServerResource:
* Base class for server-side resources. It is a full replacement for the
* deprecated {...@link Resource} class. It acts as a wrapper to a given call,
* including the incoming {...@link Request} and the outgoing {...@link
Response}.
<br>
* <br>
* It's life cycle is managed by a {...@link Finder} created either explicitly
or
* more likely implicitly when your {...@link ServerResource} subclass is
attached
* to a {...@link Filter} or a {...@link Router} via the {...@link
Filter#setNext(Class)}
* or {...@link Router#attach(String, Class)} methods for example. After
* instantiation using the default constructor, the final
* {...@link #init(Context, Request, Response)} method is invoked, setting the
* context, request and response. You can intercept this by overriding the
* {...@link #doInit()} method. Then, if the response status is still a
success,
* the {...@link #handle()} method is invoked to actually handle the call.
Finally,
* the final {...@link #release()} method is invoked to do the necessary
clean-up,
* which you can intercept by overriding the {...@link #doRelease()} method.
During
* this life cycle, if any exception is caught, then the
* {...@link #doCatch(Throwable)} method is invoked.<br>
I've also just added links from the API packages to the relevant section in
the user guide (wiki). There is already a "How to" page in the wiki that
should probably be expanded (contributors welcome):
http://wiki.restlet.org/docs_2.0/13-restlet/333-restlet/338-restlet.html
Best regards,
Jerome Louvel
--
Restlet ~ Founder and Technical Lead ~ http://www.restlet.org
Noelios Technologies ~ http://www.noelios.com
-----Message d'origine-----
De : [email protected] [mailto:[email protected]] De la part de Alex
Milowski
Envoyé : mercredi 14 avril 2010 12:19
À : [email protected]
Objet : A Couple Restlet 2.0rc2 Documentation Comments
I've been attempting to upgrade my Restlet-based projects to the latest
Restlet 2.0rc2 release. Things have been going well but I've had to resort
to inspecting the code to figure out how to properly use the API as the
javadoc seems to be insufficient.
Here's a couple of things I found a bit too terse:
1. The new Finder API is a bit confusing as to when I should override
find() versus create() (either one). Since find() calls the create()
variant without the Class<? extends ServerResource> parameter
the two methods are almost synonyms. I don't really know
when I should use which one.
I also don't quite know what the "target class" information is all
about either.
2. I've moved my code to use the ServerResource class from the
Resource class. In doing so it isn't clear from the API documentation
that if I set response facets (e.g. the status) using the direct
setter methods that they will remain as set. In fact, in certain cases,
that seems to not be the case (e.g. get() without an entity will change
a 200 to a 204).
More information about the lifecycle would be really helpful.
While I'm quite confortable searching through the code, I'm sure others
are not.
Maybe putting targeted "how to" code samples on the wiki would also
be helpful as well as back pointers from the javadoc to the online
documentation in the wiki?
Anyway, so far things are working pretty well and I haven't run into any
real issues yet.
--Alex Milowski
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=25820
36
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=2611174
