On Tue, Jan 20, 2009 at 3:21 PM, Jerome Louvel <[email protected]>
wrote:
> The other way would be to automatically generate Java source code based on
> those annotations to hard code the dispatching. But I'm not sure you want to
> go on this road which seems slippery to me, especially under Java 5 where it
> would require using the additional 'apt' tool.
>
No, I didn't mean to suggest that.
> So, if we are back using runtime annotations, there is no particular type
> safety in play:
>
> Representation representXml();
>
> would be as good (and even more compact) as:
>
> @Variant("xml")
> Representation toXml();
>
> or if you want to be more explicit about the mediatype:
>
> @Variant("text/xml")
> Representation toXml();
>
> I really prefer the simplicity of the first option. It is a naming style
> close the the JavaBean getter and setter methods, which are widely used and
> accepted.
>
I haven't tried to flesh it out, but I was thinking along these lines
(adopting Rhett's comment about names):
@RepresentsVariant(type=XmlMediaType.class, lang=FrenchLanguage.class)
Representation toXml();
where XmlMediaType extends MediaType and FrenchLanguage extends Language.
But even without the type-safety aspect, I think there are two advantages to
having something like this, with string arguments:
@RepresentsVariant(type="application/xml", lang="fr-FR")
Representation toXml();
instead of the simpler and more compact:
Representation representXmlFr();
Advantage 1 is that the former doesn't restrict you to the extension
mapping, as illustrated.
Advantage 2 is that code comprehension tools are more likely to be able to
work with the former than the latter, which relies on a convention outside
of the get/set/is bean conventions.
In addition, I think that it is easier to understand what the former is
doing, even though the latter appears to be simpler. A casual reader might
not realize that this method name is special, whereas it's hard to miss with
the annotation.
--tim
On Tue, Jan 20, 2009 at 3:21 PM, Jerome Louvel <[email protected]>wrote:
> Hi Tim,
>
> Thanks for the frank feed-back.
>
> I do like type safety-ness very much but I don't see how the usage of
> annotations would help here. My understanding is that there are two ways to
> deal with annotations:
>
> 1. At compile time, using 'javac' (Java 6) or 'apt' (Java 5)
> 2. At runtime, if the annotation have been properly preserved
>
> In our case, we need extra info to be able to properly guess the variants
> and dispatch the resource thread to the matching method. This extra info can
> be either based on a method name convention or on a runtime annotation, but
> the dispatching has to be done dynamically, using Java reflection.
>
> The other way would be to automatically generate Java source code based on
> those annotations to hard code the dispatching. But I'm not sure you want to
> go on this road which seems slippery to me, especially under Java 5 where it
> would require using the additional 'apt' tool.
>
> So, if we are back using runtime annotations, there is no particular type
> safety in play:
>
> Representation representXml();
>
> would be as good (and even more compact) as:
>
> @Variant("xml")
> Representation toXml();
>
> or if you want to be more explicit about the mediatype:
>
> @Variant("text/xml")
> Representation toXml();
>
> I really prefer the simplicity of the first option. It is a naming style
> close the the JavaBean getter and setter methods, which are widely used and
> accepted.
>
> Regarding the definitive inclusion in Restlet 1.2, it can be fully changed
> or reverted while we are in the milestone phase. Once we reach 1.2 RC1
> however, those changes will become final, unless a serious security issue
> occurs.
>
> So, we could play with the new feature for a while and see how other users
> react. Meanwhile, we can definitely continue the debate!
>
> Best regards,
> Jérôme Louvel
> --
> Restlet ~ Founder and Lead developer ~ http://www.restlet.org
> Noelios Technologies ~ Co-founder ~ http://www.noelios.com
>
>
> ------------------------------
> *De :* [email protected] [mailto:[email protected]] *De la part de* Tim
> Peierls
> *Envoyé :* vendredi 16 janvier 2009 17:10
> *À :* [email protected]
> *Objet :* Re: media type adaptor
>
> While this is undeniably convenient, it deserves more thought and
> discussion before accepting as part of 1.2. I don't think it's a good
> idea as it stands.
> Item 35 of Josh Bloch's Effective Java (2nd edition) is "Prefer annotations
> to naming patterns". One of the great strengths of Java is its type-safety,
> an important reason why Java is such a good choice for production web
> services. Naming patterns rely on conventions that are invisible to the
> compiler; they throw away the opportunity to enforce typing rules at compile
> time. The use of metadata (annotations), by contrast, lets the compiler work
> for you by catching type problems early.
>
> I'm talking specifically about using method-level annotations instead of
> method naming patterns in the case of Resource methods related to variant
> representations. I'm not trying to take this line of reasoning any farther.
> For example, while I'm not crazy about allow* and handle*, at least that's
> in Handler, not Resource, and even there Restlet *does* define the standard
> methods (Get/Put/Post/Delete/Head/Options) explicitly.
>
> --tim
>
> On Fri, Jan 16, 2009 at 9:05 AM, Jerome Louvel
> <[email protected]>wrote:
>
>> To illustrate the new feature, here is the test resource class that I
>> used in the unit test:
>>
>> *public* *class* AutoDetectResource *extends* Resource {
>>
>> * public* Representation representXml() {
>> * return* *new* StringRepresentation("<root>test</root>",
>> MediaType.*TEXT_XML*);
>> }
>>
>> * public* Representation representHtmlEn() {
>> *return* *new* StringRepresentation("<html>test EN</html>",
>> MediaType.*TEXT_HTML*);
>> }
>>
>> * public* Representation representHtmlFr() {
>> *return* *new* StringRepresentation("<html>test FR</html>",
>> MediaType.*TEXT_HTML*);
>> }
>>
>> }
>> No need in this case to override the constructor, to update the variants'
>> list or to manually handle the dispatching!
>>
>>
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1041732
