Hi Tim,
Thanks for the feed-back!
The usage of string parameters for the annotation was really more driven by
a desire to keep the annotations usage simple and compact than to follow
JAX-RS. For JAX-RS compatibility, we already have a nice extension :-)
However, I like your idea of using more formal annotation parameters, but
using MediaType subclasses seems overkill. I wish we could pass MediaType
instances like we already have defined as annotation parameters...
Also, in addition to a media type, a variant can also be composed of a
character set, a list of encodings and even a list of languages, that would
result in a rather verbose annotation.
That's where I like the idea of leveraging our MetadataService and its
mapping from short extension names to metadata, like "atom" to the
"application/atom+xml". The MetadataService is easily extensible to declare
new mappings:
getMetadataService().addExtension("es", Language.SPANISH);
Also, all those marker subclasses would crowd the Javadocs and give some
impression that the same artifact is defined in several places/ways, ex:
MediaType.ATOM and AtomType.
Maybe we could restrict the value we use in annotations to the declared
extension names in the MetadataService, significantly reducing the risk of
typing issues?
Best regards,
Jerome Louvel
--
Restlet ~ Founder and Lead developer ~ <http://www.restlet.org/>
http://www.restlet.org
Noelios Technologies ~ Co-founder ~ <http://www.noelios.com>
http://www.noelios.com
_____
De : [email protected] [mailto:[email protected]] De la part de Tim
Peierls
Envoyé : mercredi 18 février 2009 19:29
À : [email protected]
Objet : New resource API design
On Wed, Feb 18, 2009 at 12:09 PM, Jerome Louvel <[email protected]>
wrote:
Did you have a chance to check the updated resource API design?
http://wiki.restlet.org/developers/172-restlet/226-restlet.html
It looks good to me. My only concern is that in the attempt to be consistent
with JAX-RS, you're giving up an opportunity for more compile-time checking.
If the annotation parameter type for @Get, @Post, @Put was something like
Class<? extends MediaType>
instead of
String[]
it would cut down on the bugs related to typos in those parameters. You
could provide common variants as subclasses of MediaType and let users
provide their own. As a fallback to the other style, you could have a
special subclass that uses an optional String[] parameter to convey the
media type(s).
Using those ideas, one could rewrite the example on the refactoring page as:
@Get(AtomType.class)
public Feed toAtom() {
// ...
return null;
}
@Get(XmlApplicationType.class)
public Representation toXml() {
// ...
return null;
}
@Post(XmlType.class)
public Representation accept(Document entity) {
// ...
return null;
}
@Put(StringArrayType.class, type="atom") // fallback to String[] style
public void storeAtom(Feed feed) {
// ...
}
@Put(XmlApplicationType.class)
public void storeXml(InputStream stream) {
// ...
}
@Delete
public void removeAll() {
// ...
}
I bet most people would want to know at compile-time that they'd written
@Put(XmlAplicationType.class) instead of learning at run-time (if ever) that
they'd written @Put("application/custom_xml") (See the underscore instead of
the plus sign? I would probably miss it.)
I'm not sure why JAX-RS didn't do this in the first place. Any idea why
they went with easily mistyped string values as arguments to the
annotations?
--tim
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1244114
