RE: Restlet 1.2 M2 released

[Jerome Louvel]

Hi Tim,
 
Your idea of optionally verifying annotations values with an annotation
processor is excellent. I've updated the spec and the RFE to keep track of
your suggestion.
 
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 : tpeie...@gmail.com [mailto:tpeie...@gmail.com] De la part de Tim
Peierls
Envoyé : mercredi 8 avril 2009 18:08
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released


Jerome,

I like the compactness of what you are proposing. My concern is orthogonal
to this, however, and I apologize if I'm making too much of a fuss over this
one point:

Relying exclusively on string values in annotations raises the possibility
of spelling errors that are not detected at compile time and might in fact
not be detected at all. In a complex system, the fact that one URI isn't
generating or accepting exactly the set of representations you thought it
did might go unnoticed for a very long time.

Providing String constants would cut down on a lot of errors, but you still
want users to be able to roll their own combinations, and the minute they do
that, all bets are off.

I threw out a few ideas of a how one might use enum and/or class values
instead of strings as annotation parameters, but I only scratched the
surface. I'm sure it would be possible to devise a scheme where those who
wanted the compile-time checking could get it, and those who didn't could
use the compact string formulations.

Another approach that might appeal to you more is to use annotation
processors to examine the string values at compile-time to parse and
validate them against a registry of known elements that would also be built
by annotation processors. Those who don't care about such things could
happily skip the annotation processor step and just trust that their
spelling is right. Those who do care would get compile-time validation.

--tim


On Tue, Apr 7, 2009 at 12:48 PM, Jerome Louvel 
wrote:


What I would like to be able to do is express potentially complex variants
with a compact syntax as annotation values. By complex variants, I mean
variants like "JSON and UTF-8 and English-US" or like "JSON or XML, and
English-US or French-FR".

The design that I'd like to implement for 1.2 M3 is based on extension names
solely and a couple of operators:

*   

'|' for a logical OR (ex: application/json or text/xml =>
"json|xml")
*   

'*' for the cartesian product between variant dimensions (ex:
"json|xml * en|fr")
*   

'+' for a logical AND (ex: JSON and UTF-8 => "json+utf8")
*   

':' to separate return variant from input parameter entity
characteristics

You can find a bit more details on this page, paragraph "Annotation
parameter":
http://wiki.restlet.org/developers/172-restlet/226-restlet.html

Also, it isn't allowed to use full media types values such as "text/xml" as
it would potentially conflict with our variants grammar and lead to very
verbose values. 

Otherwise, I'm considering adding an Extension class that would contain
String constants for various extensions declared by default in the
MetadataService:

*   

Extension.EN : "en" -> English language
*   Extension.XML : "xml" -> "text/xml" media type 

*   


Extension.CSS : "css"
*   

etc.


Would that design be a good balance between all our design concerns/goals?

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1730515

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

ICATION_TEX);
    addExtension("tif", MediaType.IMAGE_TIFF);
    addExtension("tiff", MediaType.IMAGE_TIFF);
    addExtension("tsv", MediaType.TEXT_TSV);
    addExtension("txt", MediaType.TEXT_PLAIN, true);
    addExtension("ulw", MediaType.AUDIO_BASIC);
    addExtension("vm", Encoding.VELOCITY);
    addExtension("vrml", MediaType.MODEL_VRML);
    addExtension("vxml", MediaType.APPLICATION_VOICEXML);
    addExtension("wadl", MediaType.APPLICATION_WADL);
    addExtension("wav", MediaType.AUDIO_WAV);
    addExtension("wrl", MediaType.MODEL_VRML);
    addExtension("xht", MediaType.APPLICATION_XHTML);
    addExtension("xhtml", MediaType.APPLICATION_XHTML);
    addExtension("xls", MediaType.APPLICATION_EXCEL);
    addExtension("xlsx", MediaType.APPLICATION_MSOFFICE_XLSX);
    addExtension("xlsm", MediaType.APPLICATION_MSOFFICE_XLSM);
    addExtension("xltx", MediaType.APPLICATION_MSOFFICE_XLTX);
    addExtension("xltm", MediaType.APPLICATION_MSOFFICE_XLTM);
    addExtension("xlsb", MediaType.APPLICATION_MSOFFICE_XLSB);
    addExtension("xlam", MediaType.APPLICATION_MSOFFICE_XLAM);
    addExtension("xml", MediaType.TEXT_XML);
    addExtension("xml", MediaType.APPLICATION_XML);
    addExtension("xsd", MediaType.APPLICATION_W3C_SCHEMA);
    addExtension("xslt", MediaType.APPLICATION_W3C_XSLT);
    addExtension("xul", MediaType.APPLICATION_XUL);
    addExtension("z", MediaType.APPLICATION_COMPRESS);
    addExtension("zip", MediaType.APPLICATION_ZIP);



Rémi Dewitte wrote:
Why not making it optional ? As for me, I quite like
extension names and would keep it enabled because it makes uri
comprehensives. Examples
  http://server/path/resource?media=xml
  http://server/path/resource?media=json
  http://server/path/resource?media=xls
Easy to guess or try the others for an end user.
  
Cheers,
Rémi
  
  On Wed, Apr 8, 2009 at 19:52, Tal Liron <tal.li...@threecrickets.com>
wrote:
  

Then
perhaps TunnelService shouldn't be using extension names, either. ;)


Sure,
let's get more feedback. I just want to point out that this is a matter
of taste and clarity rather than any technical issue. As for my taste,
tou haven't managed to change it, yet.


I
think things are very clear to you because you've been swimming in
Restlet for years, but for new users, who will try to wrap their mind
around how to write a Resource and even what exactly a Resource is,
will be confused by the introduction of what appear to be
filename extensions. The reason is that actual, real filename
extensions are always part of the mix, whether as files existing on the
filesystem or in the resource's URI. (Even worse, Restlet uses the word
"extension" to refer to its plugin system -- there's one more layer of
potential confusion here.)



The
more I think about it, the more I think that shortcuts should be
optional, and that the full, complete MIME type should be used, especially
in the tutorials. Clarity should come above everything. If the
technical issue is that the "/" character is used by the grammar, then
perhaps we need a better grammar that treats "/" as part of the lexical
item.


This
is an important issue. I really hope other Restlet users will chime in
to express their opinion on this matter. Like Jerome, I'm very willing
to be convinced that my position creates more problems than it solves!





-Tal



Jerome Louvel wrote:


  Tal,
   
  The
MetadataService isn't restricted at all to
mapping filename extensions. As I pointed out previously, it is already
used by the TunnelService to customize client preferences, which has
nothing to do with files. From where do you get this impression? Maybe
we could clarify some documentation?
   
  Regarding
the @Get("jpg | jpeg | jpe"): first it
should allowed, maybe generating a log/warning about the redundancy.
Then proper examples and documentation will help clarifying this edge
case. I really don't see any design issue here. Quite on the opposite,
I even see advantages of using a single consistent registry.
   
  Probably
we should give this more time to
mature, and wait for further feed-back. As always, if proven wrong, I'm
always happy to change my mind.
  
  
   
  
  Best regards,
Jerome Louvel
--
  Restlet ~ Founder and Lead developer ~ http://www.restlet.org
  Noelios Technologies ~ Co-founder ~ http://www.noelios.com
  
  
   
   
  
  
  De : Tal Liron
[mailto:t

Re: Restlet 1.2 M2 released

[Tim Peierls]

Jerome,

I like the compactness of what you are proposing. My concern is orthogonal
to this, however, and I apologize if I'm making too much of a fuss over this
one point:

Relying exclusively on string values in annotations raises the possibility
of spelling errors that are not detected at compile time and might in fact
not be detected at all. In a complex system, the fact that one URI isn't
generating or accepting exactly the set of representations you thought it
did might go unnoticed for a very long time.

Providing String constants would cut down on a lot of errors, but you still
want users to be able to roll their own combinations, and the minute they do
that, all bets are off.

I threw out a few ideas of a how one might use enum and/or class values
instead of strings as annotation parameters, but I only scratched the
surface. I'm sure it would be possible to devise a scheme where those who
wanted the compile-time checking could get it, and those who didn't could
use the compact string formulations.

Another approach that might appeal to you more is to use annotation
processors to examine the string values at compile-time to parse and
validate them against a registry of known elements that would also be built
by annotation processors. Those who don't care about such things could
happily skip the annotation processor step and just trust that their
spelling is right. Those who do care would get compile-time validation.

--tim


On Tue, Apr 7, 2009 at 12:48 PM, Jerome Louvel wrote:

>  What I would like to be able to do is express potentially complex
> variants with a compact syntax as annotation values. By complex variants, I
> mean variants like "JSON and UTF-8 and English-US" or like "JSON or XML, and
> English-US or French-FR".
>
> The design that I'd like to implement for 1.2 M3 is based on extension
> names solely and a couple of operators:
>
>- '|' for a logical OR (ex: application/json or text/xml => "json|xml")
>- '*' for the cartesian product between variant dimensions (ex:
>"json|xml * en|fr")
>- '+' for a logical AND (ex: JSON and UTF-8 => "json+utf8")
>- ':' to separate return variant from input parameter entity
>characteristics
>
> You can find a bit more details on this page, paragraph "Annotation
> parameter":
> http://wiki.restlet.org/developers/172-restlet/226-restlet.html
>
> Also, it isn't allowed to use full media types values such as "text/xml" as
> it would potentially conflict with our variants grammar and lead to very
> verbose values.
>
> Otherwise, I'm considering adding an Extension class that would contain
> String constants for various extensions declared by default in the
> MetadataService:
>
>- Extension.EN : "en" -> English language
>- Extension.XML : "xml" -> "text/xml" media type
>-  Extension.CSS : "css"
>- etc.
>
>  Would that design be a good balance between all our design
> concerns/goals?
>

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1598602

Re: Restlet 1.2 M2 released [throw previous email away]

[Rémi Dewitte]

Why not making it optional ? As for me, I quite like extension names and
would keep it enabled because it makes uri comprehensives. Examples
http://server/path/resource?media=xml
http://server/path/resource?media=json
http://server/path/resource?media=xls
Easy to guess or try the others for an end user.

Cheers,
Rémi

On Wed, Apr 8, 2009 at 19:52, Tal Liron  wrote:

>  Then perhaps TunnelService shouldn't be using extension names, either. ;)
>
>
>  Sure, let's get more feedback. I just want to point out that this is a
> matter of taste and clarity rather than any technical issue. As for my
> taste, tou haven't managed to change it, yet.
>
>
>  I think things are very clear to you because you've been swimming in
> Restlet for years, but for new users, who will try to wrap their mind around
> how to write a Resource and even what exactly a Resource is, will be
> confused by the introduction of *what appear to be* filename extensions.
> The reason is that actual, real filename extensions are always part of the
> mix, whether as files existing on the filesystem or in the resource's URI.
> (Even worse, Restlet uses the word "extension" to refer to its plugin system
> -- there's one more layer of potential confusion here.)
>
>
>  The more I think about it, the more I think that shortcuts should be
> optional, and that the full, complete MIME type should be used, *
> especially* in the tutorials. Clarity should come above everything. If the
> technical issue is that the "/" character is used by the grammar, then
> perhaps we need a better grammar that treats "/" as part of the lexical
> item.
>
>
>  This is an important issue. I really hope other Restlet users will chime
> in to express their opinion on this matter. Like Jerome, I'm very willing to
> be convinced that my position creates more problems than it solves!
>
>
>  -Tal
>
>
>   Jerome Louvel wrote:
>
> Tal,
>
> The MetadataService isn't restricted at all to mapping filename extensions.
> As I pointed out previously, it is already used by the TunnelService to
> customize client preferences, which has nothing to do with files. From where
> do you get this impression? Maybe we could clarify some documentation?
>
> Regarding the @Get("jpg | jpeg | jpe"): first it should allowed, maybe
> generating a log/warning about the redundancy. Then proper examples and
> documentation will help clarifying this edge case. I really don't see any
> design issue here. Quite on the opposite, I even see advantages of using a
> single consistent registry.
>
> Probably we should give this more time to mature, and wait for further
> feed-back. As always, if proven wrong, I'm always happy to change my mind.
>
>  Best regards,
> Jerome Louvel
> --
> Restlet ~ Founder and Lead developer ~ http://www.restlet.org
> Noelios Technologies ~ Co-founder ~ http://www.noelios.com
>
>
>
>  --
> *De :* Tal Liron 
> [mailto:tal.li...@threecrickets.com]
>
> *Envoyé :* mardi 7 avril 2009 20:35
> *À :* discuss@restlet.tigris.org
> *Objet :* Re: Restlet 1.2 M2 released [throw previous email away]
>
>  I like the idea of having a default Extension for each MediaType, which
> means that they are all mappable.
>
> I understand the multiple uses of the word Extension, but my problem is the
> multiple uses of Extension itself in Restlet. :) The MetadataService really
> is used for mapping filename extensions, not only for parsing MediaTypes. I
> just feel uncomfortable about this mix of uses. Specifically, consider that
> the filename extensions use requires that have a many-to-one mapping of
> MediaTypes. For an example of how this can confuse users, a user might think
> that they need to do this in order to "fully" support all requests for JPEG
> format:
>
> @Get("jpg | jpeg | jpe")
>
> Those three extensions are indeed registered right now in MetadataService.
> However, they all point to MediaType.IMAGE_JPEG, and this is superfluous.
> So, somewhere in the documentation it must be emphasized to the user that we
> are not referring to filename extensions here, but rather the MIME types,
> and that only one Extension would be enough. I feel that this kind of
> awkward explanation can be easily avoided with a one-to-one mapping of
> shortcuts, and a separate registry to handle filename extension one-to-many
> mapping. Separate uses, separate mechanisms.
>
> -Tal
>
> Jerome Louvel wrote:
>
> Tal,
>
> It's really a matter of terminology, so it's hard to rationalize the
> choice. I know that "extension" is often synonymous of "file extension" b

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

Then
perhaps TunnelService shouldn't be using extension names, either. ;)


Sure,
let's get more feedback. I just want to point out that this is a matter
of taste and clarity rather than any technical issue. As for my taste,
tou haven't managed to change it, yet.


I
think things are very clear to you because you've been swimming in
Restlet for years, but for new users, who will try to wrap their mind
around how to write a Resource and even what exactly a Resource is,
will be confused by the introduction of what appear to be
filename extensions. The reason is that actual, real filename
extensions are always part of the mix, whether as files existing on the
filesystem or in the resource's URI. (Even worse, Restlet uses the word
"extension" to refer to its plugin system -- there's one more layer of
potential confusion here.)




The
more I think about it, the more I think that shortcuts should be
optional, and that the full, complete MIME type should be used, especially
in the tutorials. Clarity should come above everything. If the
technical issue is that the "/" character is used by the grammar, then
perhaps we need a better grammar that treats "/" as part of the lexical
item.


This
is an important issue. I really hope other Restlet users will chime in
to express their opinion on this matter. Like Jerome, I'm very willing
to be convinced that my position creates more problems than it solves!



-Tal








Jerome Louvel wrote:


  
  
  
  Tal,
   
  The MetadataService isn't restricted at all to
mapping filename extensions. As I pointed out previously, it is already
used by the TunnelService to customize client preferences, which has
nothing to do with files. From where do you get this impression? Maybe
we could clarify some documentation?
   
  Regarding the @Get("jpg | jpeg | jpe"): first it
should allowed, maybe generating a log/warning about the redundancy.
Then proper examples and documentation will help clarifying this edge
case. I really don't see any design issue here. Quite on the opposite,
I even see advantages of using a single consistent registry.
   
  Probably we should give this more time to
mature, and wait for further feed-back. As always, if proven wrong, I'm
always happy to change my mind.
  
  
   
  
  
  Best regards,
Jerome Louvel
--
  Restlet ~ Founder and Lead developer ~ http://www.restlet.org
  Noelios Technologies ~ Co-founder ~ http://www.noelios.com
  
  
   
   
  
  
  De : Tal Liron
[mailto:tal.li...@threecrickets.com] 
  Envoyé : mardi 7 avril 2009 20:35
  À : discuss@restlet.tigris.org
  Objet : Re: Restlet 1.2 M2 released [throw previous email away]
  
  
  I like the idea of having a default Extension
for each MediaType, which means that they are all mappable.
  
I understand the multiple uses of the word Extension, but my problem is
the multiple uses of Extension itself in Restlet. :) The
MetadataService really is used for mapping filename extensions, not
only for parsing MediaTypes. I just feel uncomfortable about this mix
of uses. Specifically, consider that the filename extensions use
requires that have a many-to-one mapping of MediaTypes. For an example
of how this can confuse users, a user might think that they need to do
this in order to "fully" support all requests for JPEG format:
  
@Get("jpg | jpeg | jpe")
  
Those three extensions are indeed registered right now in
MetadataService. However, they all point to MediaType.IMAGE_JPEG, and
this is superfluous. So, somewhere in the documentation it must be
emphasized to the user that we are not referring to filename extensions
here, but rather the MIME types, and that only one Extension would be
enough. I feel that this kind of awkward explanation can be easily
avoided with a one-to-one mapping of shortcuts, and a separate registry
to handle filename extension one-to-many mapping. Separate uses,
separate mechanisms.
  
-Tal
  
Jerome Louvel wrote:
  

Tal,
 
It's really a matter of terminology, so it's
hard to rationalize the choice. I know that "extension" is often
synonymous of "file extension" but it doesn't have to. If you look at
WordNet definition of the "extension" word, you should feel more
comfortable about using it as an equivalent to "shortcut":
http://wordnetweb.princeton.edu/perl/webwn?s=extension
 
The advantage of this terminology is that it
maps directly to the "file extension" concept which is widely known,
but is more generic: you need to update your mental mapping for this
word, not always easy ;). We already use it in the TunnelService to
customize the "Accept" header value via the URIs or in the Reference
class to manipulate them (see getExtensions() method). I realize that
there is some documentation and clarification work to be done, but I
don't think it is misleading as 

RE: Restlet 1.2 M2 released [throw previous email away]

[Jerome Louvel]

Dave,

The interest in extensions is that they provide compact shortcuts for media
types/languages/encodings/character sets. It is easy to remember "json",
harder to remember about "application/json", and I'm not talking about the
media type for Web forms.

So, it's really about usability and clarity of the resulting source code. My
view is that annotations shouldn't become too prominent when used, they
should be kept a simple as possible, like the standard @Override,
@Deprecated or @SuppressWarnings annotations. 

I prefer coding in Java instead of a pseudo-annotation language. It's also a
matter of taste and obviously those preferring extensive use of annotations
will be happy with JAX-RS (that we also support as a Restlet extension). 

Regarding the annotation value syntax, it isn't fixed yet and I'm looking
for feed-back. We should progressively implement it to make sure it
corresponds to real use cases. At least we have a target design that we can
refer to.

How would your annotations look if we were using string arrays or several
annotations? How would you express common cases like POST accepting either
entity with either XML or JSON as media type and in either English or French
as language, and returning XML or JSON depending on the input media type?

Regarding the comparison to JAX-RS, I agree that it will be inevitable.
Let's look at it right now :)


With JAX-RS API:


@GET 
@Produces("application/x-www-form-urlencoded")
public String toString() {
   return ...;
}

With Restlet API:
-

@Get("form")
public String toString() {
   return ...;
}


With JAX-RS API:


@PUT
@Consumes({"application/json", "application/xml",
"application/x-www-form-urlencoded"})
@Produces({"text/plain"})
public String store(String value) 
{ 
   ... 
}

With Restlet API:
-

@Put("txt:json|xml|form")
public String store(String value) 
{ 
   ... 
}


Note that there are other very significant differences between both APIs,
like for dealing with routing (URI/path mapping to resources). I just
covered the variant description aspect.
 
Best regards,
Jerome Louvel
--
Restlet ~ Founder and Lead developer ~ http://www.restlet.org
Noelios Technologies ~ Co-founder ~ http://www.noelios.com


-Message d'origine-----
De : David Fogel [mailto:carrotsa...@gmail.com] 
Envoyé : mardi 7 avril 2009 20:42
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw previous email away]

Hi Jerome-

I don't know, this whole extension thing sounds strange to me.  Why replace
a well-defined, standardized namespace for media-types (e.g.
"text/html" etc) with a new, ad-hoc, non-standard namespace like this
extension stuff?

I don't think that the goal of "compactness" is a good justification for
this!

I think I understand that you want to support other variant metadata like
language and character-set, but those, too, have standardized namespaces!

I think it's important to be _very_ cautious about introducing new text
string grammars- most of the time it would be better to use java language
syntax instead.  The challenge here is that you're trying to squeeze a lot
of structured metadata into an annotation value.  That certainly narrows the
options available.  But maybe you could use a more straightforward array of
Strings?  or have multiple annotations?
Or perhaps it would be better to  require the user to define more than one
method to split apart the variant options, even if those methods call the
same implementation?

I'm just not feeling confident that this solution is going to feel elegant
when it's done.  And it might be a good idea to keep in mind that whatever
you end up with here will likely get frequently compared to JAX-RS.  And
jax-rs's story here, although perhaps less flexible, may end up seeming
simpler.

-Dave Fogel

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=15815
89

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1596334

RE: Restlet 1.2 M2 released [throw previous email away]

[Jerome Louvel]

Tal,
 
The MetadataService isn't restricted at all to mapping filename extensions.
As I pointed out previously, it is already used by the TunnelService to
customize client preferences, which has nothing to do with files. From where
do you get this impression? Maybe we could clarify some documentation?
 
Regarding the @Get("jpg | jpeg | jpe"): first it should allowed, maybe
generating a log/warning about the redundancy. Then proper examples and
documentation will help clarifying this edge case. I really don't see any
design issue here. Quite on the opposite, I even see advantages of using a
single consistent registry.
 
Probably we should give this more time to mature, and wait for further
feed-back. As always, if proven wrong, I'm always happy to change my mind.
 
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 : Tal Liron [mailto:tal.li...@threecrickets.com] 
Envoyé : mardi 7 avril 2009 20:35
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw previous email away]


I like the idea of having a default Extension for each MediaType, which
means that they are all mappable.

I understand the multiple uses of the word Extension, but my problem is the
multiple uses of Extension itself in Restlet. :) The MetadataService really
is used for mapping filename extensions, not only for parsing MediaTypes. I
just feel uncomfortable about this mix of uses. Specifically, consider that
the filename extensions use requires that have a many-to-one mapping of
MediaTypes. For an example of how this can confuse users, a user might think
that they need to do this in order to "fully" support all requests for JPEG
format:

@Get("jpg | jpeg | jpe")

Those three extensions are indeed registered right now in MetadataService.
However, they all point to MediaType.IMAGE_JPEG, and this is superfluous.
So, somewhere in the documentation it must be emphasized to the user that we
are not referring to filename extensions here, but rather the MIME types,
and that only one Extension would be enough. I feel that this kind of
awkward explanation can be easily avoided with a one-to-one mapping of
shortcuts, and a separate registry to handle filename extension one-to-many
mapping. Separate uses, separate mechanisms.

-Tal

Jerome Louvel wrote: 

Tal,
 
It's really a matter of terminology, so it's hard to rationalize the choice.
I know that "extension" is often synonymous of "file extension" but it
doesn't have to. If you look at WordNet definition of the "extension" word,
you should feel more comfortable about using it as an equivalent to
"shortcut":
http://wordnetweb.princeton.edu/perl/webwn?s=extension
 
The advantage of this terminology is that it maps directly to the "file
extension" concept which is widely known, but is more generic: you need to
update your mental mapping for this word, not always easy ;). We already use
it in the TunnelService to customize the "Accept" header value via the URIs
or in the Reference class to manipulate them (see getExtensions() method). I
realize that there is some documentation and clarification work to be done,
but I don't think it is misleading as a term.
 
Regarding the "application/www-form-urlencoded" media type, the solution is
simply to add a common extension mapping for it. This is now available in
SVN trunk as the "form" extension. If it wasn't available by default, you
could just specify it yourself at application start:
 
getMetadataService().addExtension("form",
MediaType.APPLICATION_WWW_FORM);
 
One way to guarantee that each metadata has a matching extension would be to
add an "extension" property to the Metadata class. We could then update the
MetadataService to simplify the mapping:
 
getMetadataService().addExtension(MediaType.APPLICATION_WWW_FORM);
 
In some way, the metadata service would become a registry of all available
metadata. We could add a MetadataService#registry property of type
"Metadata", resulting in this code:
 

getMetadataService().getRegistry().add(MediaType.APPLICATION_WWW_FORM);
 
Regarding the failure, I believe I did mention that the goal is to have full
parsing/validation of the annotation value string with proper warning
message. So your concern will definitely be addressed!

 

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 : Tal Liron [mailto:tal.li...@threecrickets.com] 
Envoyé : mardi 7 avril 2009 19:51
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw p

RE: Restlet 1.2 M2 released [throw previous email away]

[Jerome Louvel]

Hi Paul,
 
I agree with your comment, the knowledge of Restlet specific extensions
shouldn't be required by the clients.
 
Actually, the TunnelService already allows you to specify the full media
type name or character set or language. Therefore, "/myPath?media=text/xml"
will work.
 
In the annotation case, the usage of extensions is purely internal to
Restlet and doesn't have to be exposed or known by clients. This is even
orthogonal to the TunnelService feature.
 
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 : Paul Austin [mailto:mail-li...@revolsys.com] 
Envoyé : mardi 7 avril 2009 20:25
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw previous email away]


Jerome,

I would be happy if users can choose to either use the "extensions" or the
mime-type where the extension is currently used. Consider a web service
which is designed to be used either from a web browser when the media=
parameter is used or from a Java client where the accept header can be set.
In the documentation for this web service it would be useful to be able to
list only the mime types. Rather than saying, if you use the media parameter
use the keyword xhtml or if you use the accept header use
application/xhtml+xml.

Another thing to consider is if you describe your service using WADL you
would be using the mime types so the client using the media= parameter would
need to know the mapping to/from mime type to media type. i.e. you need a
public extensions registry.

Just some thoughts,
Paul

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1594388

RE: Restlet 1.2 M2 released [throw previous email away]

[Jerome Louvel]

Tal,
 
It's really a matter of terminology, so it's hard to rationalize the choice.
I know that "extension" is often synonymous of "file extension" but it
doesn't have to. If you look at WordNet definition of the "extension" word,
you should feel more comfortable about using it as an equivalent to
"shortcut":
http://wordnetweb.princeton.edu/perl/webwn?s=extension
 
The advantage of this terminology is that it maps directly to the "file
extension" concept which is widely known, but is more generic: you need to
update your mental mapping for this word, not always easy ;). We already use
it in the TunnelService to customize the "Accept" header value via the URIs
or in the Reference class to manipulate them (see getExtensions() method). I
realize that there is some documentation and clarification work to be done,
but I don't think it is misleading as a term.
 
Regarding the "application/www-form-urlencoded" media type, the solution is
simply to add a common extension mapping for it. This is now available in
SVN trunk as the "form" extension. If it wasn't available by default, you
could just specify it yourself at application start:
 
getMetadataService().addExtension("form",
MediaType.APPLICATION_WWW_FORM);
 
One way to guarantee that each metadata has a matching extension would be to
add an "extension" property to the Metadata class. We could then update the
MetadataService to simplify the mapping:
 
getMetadataService().addExtension(MediaType.APPLICATION_WWW_FORM);
 
In some way, the metadata service would become a registry of all available
metadata. We could add a MetadataService#registry property of type
"Metadata", resulting in this code:
 
getMetadataService().getRegistry().add(MediaType.APPLICATION_WWW_FORM);
 
Regarding the failure, I believe I did mention that the goal is to have full
parsing/validation of the annotation value string with proper warning
message. So your concern will definitely be addressed!
 
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 : Tal Liron [mailto:tal.li...@threecrickets.com] 
Envoyé : mardi 7 avril 2009 19:51
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw previous email away]



Thanks for joining the discussion, Jerome, we were getting a bit ridiculous
in trying to second guess your intentions. :) It makes sense to me to use
simple strings for referring to media types, and your examples are
definitely elegant. But I have to again say that using filename extension
names is bizarre, and would confuse users. What do filename extensions have
to do with this particular use case?




Related to this is that, indeed, not all MediaTypes have filename
extensions, so they can't even be used with the current annotation system.
Case in point: "application/w-www-form-urlencoded", a very standard MIME
type that browsers send from form submits. I can see wanting to return such
representations for proxy/robot applications.





Perhaps we can call it MetadataService.getShortcut()? And register names for
all media types, which may be similar to but not dependent on filename
extensions? (The above, for example, could be shortcutted as "form".) I
think "shortcut" is a generic enough term that it can be used throughout
Restlet without confusion. In fact, anywhere that a full MIME type string is
accepted, we could allow shortcuts to be used instead.





I hope you address another point I raised -- that ServerResource should fail
somewhere with an exception in case the annotation's configuration string is
invalid. For example, a media type extension unrecognized by MetadatService.
Right now, anything is accepted cheerfully and the user has no clue as to
what went wrong. @Get("wtf") slides through. I've tested this. :)





-Tal



Jerome Louvel wrote:


Hi all,
 
As I tried to explain in reply to Tim's alternative design
(http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447
<http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1579
830> &dsMessageId=1579830) the goal for the annotation value is to go beyond
a simple declaration of the mediatype or language or character set or
encoding expected. Instead we want to be able to express full variants,
either as a logical AND between several metadata dimensions or as a
Cartesian product between various alternatives for each dimension.
 
The only way I see to support the expression of those variants is to have a
custom string-based grammar. See reply to Tim or this page for details:
http://wiki.restlet.org/developers/172-restlet/226-restlet.html
 
Now, I agree with you guys that we should fa

Re: Restlet 1.2 M2 released [throw previous email away]

[Paul Austin]

Jerome,

I would be happy if users can choose to either use the "extensions" or the
mime-type where the extension is currently used. Consider a web service
which is designed to be used either from a web browser when the media=
parameter is used or from a Java client where the accept header can be set.
In the documentation for this web service it would be useful to be able to
list only the mime types. Rather than saying, if you use the media parameter
use the keyword xhtml or if you use the accept header use
application/xhtml+xml.

Another thing to consider is if you describe your service using WADL you
would be using the mime types so the client using the media= parameter would
need to know the mapping to/from mime type to media type. i.e. you need a
public extensions registry.

Just some thoughts,
Paul

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1581398

Re: Restlet 1.2 M2 released [throw previous email away]

[David Fogel]

Hi Jerome-

I don't know, this whole extension thing sounds strange to me.  Why
replace a well-defined, standardized namespace for media-types (e.g.
"text/html" etc) with a new, ad-hoc, non-standard namespace like this
extension stuff?

I don't think that the goal of "compactness" is a good justification for this!

I think I understand that you want to support other variant metadata
like language and character-set, but those, too, have standardized
namespaces!

I think it's important to be _very_ cautious about introducing new
text string grammars- most of the time it would be better to use java
language syntax instead.  The challenge here is that you're trying to
squeeze a lot of structured metadata into an annotation value.  That
certainly narrows the options available.  But maybe you could use a
more straightforward array of Strings?  or have multiple annotations?
Or perhaps it would be better to  require the user to define more than
one method to split apart the variant options, even if those methods
call the same implementation?

I'm just not feeling confident that this solution is going to feel
elegant when it's done.  And it might be a good idea to keep in mind
that whatever you end up with here will likely get frequently compared
to JAX-RS.  And jax-rs's story here, although perhaps less flexible,
may end up seeming simpler.

-Dave Fogel

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1581589

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

I like the idea of having a default Extension for
each MediaType, which means that they are all mappable.

I understand the multiple uses of the word Extension, but my problem is
the multiple uses of Extension itself in Restlet. :) The
MetadataService really is used for mapping filename extensions, not
only for parsing MediaTypes. I just feel uncomfortable about this mix
of uses. Specifically, consider that the filename extensions use
requires that have a many-to-one mapping of MediaTypes. For an example
of how this can confuse users, a user might think that they need to do
this in order to "fully" support all requests for JPEG format:

@Get("jpg | jpeg | jpe")

Those three extensions are indeed registered right now in
MetadataService. However, they all point to MediaType.IMAGE_JPEG, and
this is superfluous. So, somewhere in the documentation it must be
emphasized to the user that we are not referring to filename extensions
here, but rather the MIME types, and that only one Extension would be
enough. I feel that this kind of awkward explanation can be easily
avoided with a one-to-one mapping of shortcuts, and a separate registry
to handle filename extension one-to-many mapping. Separate uses,
separate mechanisms.

-Tal

Jerome Louvel wrote:

  
  
  Tal,
   
  It's really a matter of terminology, so it's
hard to rationalize the choice. I know that "extension" is often
synonymous of "file extension" but it doesn't have to. If you look at
WordNet definition of the "extension" word, you should feel more
comfortable about using it as an equivalent to "shortcut":
  http://wordnetweb.princeton.edu/perl/webwn?s=extension
   
  The advantage of this terminology is that it
maps directly to the "file extension" concept which is widely known,
but is more generic: you need to update your mental mapping for this
word, not always easy ;). We already use it in the TunnelService to
customize the "Accept" header value via the URIs or in the Reference
class to manipulate them (see getExtensions() method). I realize that
there is some documentation and clarification work to be done, but I
don't think it is misleading as a term.
   
  Regarding the "application/www-form-urlencoded"
media type, the solution is simply to add a common extension mapping
for it. This is now available in SVN trunk as the "form" extension. If
it wasn't available by default, you could just specify it yourself at
application start:
   
      getMetadataService().addExtension("form",
MediaType.APPLICATION_WWW_FORM);
   
  One way to guarantee that each metadata has a
matching extension would be to add an "extension" property to the
Metadata class. We could then update the MetadataService to simplify
the mapping:
   
     
getMetadataService().addExtension(MediaType.APPLICATION_WWW_FORM);
   
  In some way, the metadata service would become a
registry of all available metadata. We could add a
MetadataService#registry property of type "Metadata", resulting in this
code:
   
  
     
getMetadataService().getRegistry().add(MediaType.APPLICATION_WWW_FORM);
  
   
  Regarding the failure, I believe I did mention
that the goal is to have full parsing/validation of the annotation
value string with proper warning message. So your concern will
definitely be addressed!
  
  
   
  
  
  Best regards,
Jerome Louvel
--
  Restlet ~ Founder and Lead developer ~ http://www.restlet.org
  Noelios Technologies ~ Co-founder ~ http://www.noelios.com
  
  
   
   
  
  
  De : Tal Liron
[mailto:tal.li...@threecrickets.com] 
  Envoyé : mardi 7 avril 2009 19:51
  À : discuss@restlet.tigris.org
  Objet : Re: Restlet 1.2 M2 released [throw previous email away]
  
  
  Thanks
for joining the discussion, Jerome, we were getting a bit ridiculous in
trying to second guess your intentions. :) It makes sense to me to use
simple strings for referring to media types, and your examples are
definitely elegant. But I have to again say that using filename
extension names is bizarre, and would confuse users. What do filename
extensions have to do with this particular use case?
  
  
  Related
to this is that, indeed, not all MediaTypes have filename extensions,
so they can't even be used with the current annotation system. Case in
point: "application/w-www-form-urlencoded",
a very standard MIME type that browsers send from form submits. I can
see wanting to return such representations for proxy/robot applications.
  
  
  
  Perhaps
we can call it MetadataService.getShortcut()? And register names for
all media types, which may be similar to but not dependent on filename
extensions? (The above, for example, could be shortcutted as "form".) I
think "shortcut" is a generic enough term that it can be used
throughout Restlet without confusion. In fact, anywhere that a full
MIME type string is accep

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

Thanks
for joining the discussion, Jerome, we were getting a bit ridiculous in
trying to second guess your intentions. :) It makes sense to me to use
simple strings for referring to media types, and your examples are
definitely elegant. But I have to again say that using filename
extension names is bizarre, and would confuse users. What do filename
extensions have to do with this particular use case?


Related
to this is that, indeed, not all MediaTypes have filename extensions,
so they can't even be used with the current annotation system. Case in
point: "application/w-www-form-urlencoded",
a very standard MIME type that browsers send from form submits. I can
see wanting to return such representations for proxy/robot applications.



Perhaps
we can call it MetadataService.getShortcut()? And register names for
all media types, which may be similar to but not dependent on filename
extensions? (The above, for example, could be shortcutted as "form".) I
think "shortcut" is a generic enough term that it can be used
throughout Restlet without confusion. In fact, anywhere that a full
MIME type string is accepted, we could allow shortcuts to be used
instead.


 



I
hope you address another point I raised -- that ServerResource should
fail somewhere with an exception in case the annotation's configuration
string is invalid. For example, a media type extension unrecognized by
MetadatService. Right now, anything is accepted cheerfully and the user
has no clue as to what went wrong. @Get("wtf") slides through. I've
tested this. :)



-Tal




Jerome Louvel wrote:


  
  
  Hi all,
   
  As I tried to explain in reply to Tim's
alternative design (http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1579830)
  the goal for the annotation value is to go beyond a simple
declaration of the mediatype or language or character set or encoding
expected. Instead we want to be able to express full variants, either
as a logical AND between several metadata dimensions or as a Cartesian
product between various alternatives for each dimension.
   
  The only way I see to support the _expression_ of
those variants is to have a custom string-based grammar. See reply to
Tim or this page for details:
  http://wiki.restlet.org/developers/172-restlet/226-restlet.html
   
  Now, I agree with you guys that we should
facilitate the life of developers and guide them as much as possible
instead of having them guess the supported strings. That's why I
proposed a new Extension class that would contain string constants,
resulting, for simple cases, in annotations like this:
   
  @Get(Extension.XML)
  public String toString();
   
  A more complex case, where a method can process
a POST of an XML or a JSON document:
   
  @Post(Extension.XML + "|" + Extension.JSON)
  public String accept(Representation entity);
   
  In
this case, the advantage of constants over raw string starts to
diminish. This version looks better to me:
   
  
  @Post("xml | json")
  public String accept(Representation entity);
  
   
  Also,
in order to prevent confusion between our own delimiters and the
delimiters of MIME types, I have based the current design solely on
extensions, as short-cuts to full metadata. This is an internal
convention used by Restlet, based on its MetadataService and not
exposed to outside clients. 
   
  BTW,
I'm not sure about allowing special characters as extension names as
suggested by Tal as it could conflict with the suggested annotation
value grammar. MetadataService could support other types of shortcuts
such as enumerations but I don't see the need yet.
   
  To
address Dave's concerns, the MetadataService is the master of the
extension registry in a Restlet application. We don't depend at all on
OS conventions or configuration. The default/common extensions are
declared in this method:
  http://www.restlet.org/documentation/snapshot/api/org/restlet/service/MetadataService.html#addCommonExtensions()
   
  Another
thing I want to do for 1.2 M3 is to add full validation for annotation
values (based on the suggested grammar). That would have helped Dave
catching his issue with "text/html" vs. "html" more quickly. I've added
a note about that in the related RFE:
   
  "Facilitate
Resource to Representation mapping"
  http://restlet.tigris.org/issues/show_bug.cgi?id=303
  
  
   
  
  
  Best regards,
Jerome Louvel
--
  Restlet ~ Founder and Lead developer ~ http://www.restlet.org
  Noelios Technologies ~ Co-founder ~ http://www.noelios.com
  
  
   
  
  
  
  De : Tal Liron
[mailto:tal.li...@threecrickets.com] 
  Envoyé : vendredi 3 avril 2009 07:46
  À : discuss@restlet.tigris.org
  Objet : Re: Restlet 1.2 M2 released [throw previous email away]
  
  
  Hi
David,
  
  
  I
agree that filename extensions are not the best way to go here, but I
see nothing wrong wi

RE: Restlet 1.2 M2 released [throw previous email away]

[Jerome Louvel]

Hi all,
 
As I tried to explain in reply to Tim's alternative design
(http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447
<http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1579
830> &dsMessageId=1579830) the goal for the annotation value is to go beyond
a simple declaration of the mediatype or language or character set or
encoding expected. Instead we want to be able to express full variants,
either as a logical AND between several metadata dimensions or as a
Cartesian product between various alternatives for each dimension.
 
The only way I see to support the expression of those variants is to have a
custom string-based grammar. See reply to Tim or this page for details:
http://wiki.restlet.org/developers/172-restlet/226-restlet.html
 
Now, I agree with you guys that we should facilitate the life of developers
and guide them as much as possible instead of having them guess the
supported strings. That's why I proposed a new Extension class that would
contain string constants, resulting, for simple cases, in annotations like
this:
 
@Get(Extension.XML)
public String toString();
 
A more complex case, where a method can process a POST of an XML or a JSON
document:
 
@Post(Extension.XML + "|" + Extension.JSON)
public String accept(Representation entity);
 
In this case, the advantage of constants over raw string starts to diminish.
This version looks better to me:
 
@Post("xml | json")
public String accept(Representation entity);
 
Also, in order to prevent confusion between our own delimiters and the
delimiters of MIME types, I have based the current design solely on
extensions, as short-cuts to full metadata. This is an internal convention
used by Restlet, based on its MetadataService and not exposed to outside
clients. 
 
BTW, I'm not sure about allowing special characters as extension names as
suggested by Tal as it could conflict with the suggested annotation value
grammar. MetadataService could support other types of shortcuts such as
enumerations but I don't see the need yet.
 
To address Dave's concerns, the MetadataService is the master of the
extension registry in a Restlet application. We don't depend at all on OS
conventions or configuration. The default/common extensions are declared in
this method:
http://www.restlet.org/documentation/snapshot/api/org/restlet/service/Metada
taService.html#addCommonExtensions()
 
Another thing I want to do for 1.2 M3 is to add full validation for
annotation values (based on the suggested grammar). That would have helped
Dave catching his issue with "text/html" vs. "html" more quickly. I've added
a note about that in the related RFE:
 
"Facilitate Resource to Representation mapping"
http://restlet.tigris.org/issues/show_bug.cgi?id=303
 
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 : Tal Liron [mailto:tal.li...@threecrickets.com] 
Envoyé : vendredi 3 avril 2009 07:46
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released [throw previous email away]



Hi David,




I agree that filename extensions are not the best way to go here, but I see
nothing wrong with supporting them in addition to MIME types. As for
supporting MIME types, it seems we already have a facility in Restlet via
MediaType.valueOf():




http://www.restlet.org/documentation/1.2/api/org/restlet/data/MediaType.html
#valueOf(java.lang.String)





If this simple support is added to ServerResource, then it would be possible
to annotate as so:

@Get(MediaType.APPLICATION_JSON.toString()

A tad verbose, but precise and efficient.

Also, I've noticed no error if you use an unsupported extension. I think we
should have an exception thrown if we try to write something like
@Get("fishburger")! Unless a valid MediaType is found, I think it best the
ServerResource fail.

-Tal




David Fogel wrote:


But it's not clear to me why this code should use the

"MetadataService" at all.  The mapping of file extensions to

MediaTypes is one of the web's irritating but hard to avoid dirty

shameful secrets.  The only time we should stoop so low as to base a

MediaType calculation on an extension name is if we have no other

choice- in fact, we only have to do this when we DONT have real

metadata available!



If I am writing a restful web service, and I want to deliver a

representation with a mediatype of "image/jpeg", then that's what I

should have to put in the @Get annotation- not "jpg" or "jpeg" or

"JPG" or any other of the random 3 or 4-letter filename extensions

that someone, somewhere, sometime happened to associate (in their

anemic filesystem) with that mediatype.



(If I sound grumpy it might be beca

RE: Restlet 1.2 M2 released

[Jerome Louvel]

Hi Tim,
 
Thanks for your proposition. It makes me realize that I didn't explain my
design goals well enough.
 
What I would like to be able to do is express potentially complex variants
with a compact syntax as annotation values. By complex variants, I mean
variants like "JSON and UTF-8 and English-US" or like "JSON or XML, and
English-US or French-FR". 
 
The design that I'd like to implement for 1.2 M3 is based on extension names
solely and a couple of operators:

*   

'|' for a logical OR (ex: application/json or text/xml =>
"json|xml")
*   

'*' for the cartesian product between variant dimensions (ex:
"json|xml * en|fr")
*   

'+' for a logical AND (ex: JSON and UTF-8 => "json+utf8")
*   

':' to separate return variant from input parameter entity
characteristics

You can find a bit more details on this page, paragraph "Annotation
parameter":
http://wiki.restlet.org/developers/172-restlet/226-restlet.html
 
Also, it isn't allowed to use full media types values such as "text/xml" as
it would potentially conflict with our variants grammar and lead to very
verbose values. 
 
Otherwise, I'm considering adding an Extension class that would contain
String constants for various extensions declared by default in the
MetadataService:

*   

Extension.EN : "en" -> English language
*   Extension.XML : "xml" -> "text/xml" media type
*   


Extension.CSS : "css"
*   

etc.

Would that design be a good balance between all our design concerns/goals?
 
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 : Tim Peierls [mailto:tpeie...@gmail.com] 
Envoyé : jeudi 2 avril 2009 19:16
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released


On Thu, Apr 2, 2009 at 12:13 PM, Rhett Sutphin 
wrote:


On Apr 2, 2009, at 11:11 AM, Stephan Koops wrote:


Jonathan Hall schrieb:

> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.


Would it work to change MediaType from class to an enum? That could work,
but I'm not sure


This would sacrifice the ability to create new MediaTypes in applications
which use the framework.




I proposed using Class as the annotation parameter
type, but Jerome said (in
http://n2.nabble.com/New-resource-API-design-tt2348626.html#a2400409):


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.


A lot of the time, the standard metadata constants provided by Restlet are
all you need, so what about allowing both enums for standard metadata and a
way of specifying custom metadata that is more verbose but also type-safe?
There's a way to do this that still allows simple (but unsafe) string
metadata. It would let you say things like:

@Get(media=APPLICATION_ALL_XML) 
@Get(charsets={US_ASCII, ISO_8859_1}) 
@Get(userMedia=MyCustomMediaType.class)

in addition to the string forms. Here's a code sketch:

enum StdMediaType {
DEFAULT(MediaType.ALL),
ALL(MediaType.ALL),
APPLICATION_ALL(MediaType.APPLICATION_ALL),
APPLICATION_ALL_XML(MediaType.APPLICATION_ALL_XML),
// etc.
;

public boolean isDefault() { return this == DEFAULT; }
public MediaType mediaType() { return mediaType; }

StdMediaType(MediaType mediaType) { this.mediaType = mediaType; }
private final MediaType mediaType;
}

enum StdCharacterSet {
DEFAULT(CharacterSet.DEFAULT),
ALL(CharacterSet.ALL),
ISO_8859_1(CharacterSet.ISO_8859_1),
US_ASCII(CharacterSet.US_ASCII),
// etc.
;

public boolean isDefault() { return this == DEFAULT; }
public CharacterSet mediaType() { return mediaType; }

StdCharacterSet(CharacterSet mediaType) { this.mediaType = mediaType; }
private final CharacterSet mediaType;
}

enum StdEncoding { /* similarly */ }

enum StdLanguage { /* similarly */ }


@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Get {

/**
* Representable media types specified either via extension names or full
* MIME type.
*/
String[] value() default "*/*";

/**
* Representable standard media types.
*/
StdMediaType[] media() default StdMediaType.DEFAULT;

/**
* Representable user (nonstandard) media types, specified by custom subclass
of MediaType.
*/
Class[] userMedia() default {};

/**
* Representable standard character sets.
*/
StdCharacterSe

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

Hi
David,


I
agree that filename extensions are not the best way to go here, but I
see nothing wrong with supporting them in addition to MIME types. As
for supporting MIME types, it seems we already have a facility in
Restlet via MediaType.valueOf():


http://www.restlet.org/documentation/1.2/api/org/restlet/data/MediaType.html#valueOf(java.lang.String)





If this simple support is added to ServerResource,
then it would be possible to annotate as so:

@Get(MediaType.APPLICATION_JSON.toString()

A tad verbose, but precise and efficient.

Also, I've noticed no error if you use an unsupported extension. I
think we should have an exception thrown if we try to write something
like @Get("fishburger")! Unless a valid MediaType is found, I think it
best the ServerResource fail.

-Tal







David Fogel wrote:


  But it's not clear to me why this code should use the
"MetadataService" at all.  The mapping of file extensions to
MediaTypes is one of the web's irritating but hard to avoid dirty
shameful secrets.  The only time we should stoop so low as to base a
MediaType calculation on an extension name is if we have no other
choice- in fact, we only have to do this when we DONT have real
metadata available!

If I am writing a restful web service, and I want to deliver a
representation with a mediatype of "image/jpeg", then that's what I
should have to put in the @Get annotation- not "jpg" or "jpeg" or
"JPG" or any other of the random 3 or 4-letter filename extensions
that someone, somewhere, sometime happened to associate (in their
anemic filesystem) with that mediatype.

(If I sound grumpy it might be because I just spent quite a while with
a debugger trying to figure out why my new ServerResource subclass
wasn't working, and it turns out it's because I was using "text/html"
instead of "htm" or whatever. :-) )

So, I vote for explicit mediatypes.  and maybe we also need to be able
to specify charsets too?   Hmm, maybe that's not useful for content
negotiation, not sure.

-Dave Fogel

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1528590
  

Re: Restlet 1.2 M2 released [throw previous email away]

[David Fogel]

But it's not clear to me why this code should use the
"MetadataService" at all.  The mapping of file extensions to
MediaTypes is one of the web's irritating but hard to avoid dirty
shameful secrets.  The only time we should stoop so low as to base a
MediaType calculation on an extension name is if we have no other
choice- in fact, we only have to do this when we DONT have real
metadata available!

If I am writing a restful web service, and I want to deliver a
representation with a mediatype of "image/jpeg", then that's what I
should have to put in the @Get annotation- not "jpg" or "jpeg" or
"JPG" or any other of the random 3 or 4-letter filename extensions
that someone, somewhere, sometime happened to associate (in their
anemic filesystem) with that mediatype.

(If I sound grumpy it might be because I just spent quite a while with
a debugger trying to figure out why my new ServerResource subclass
wasn't working, and it turns out it's because I was using "text/html"
instead of "htm" or whatever. :-) )

So, I vote for explicit mediatypes.  and maybe we also need to be able
to specify charsets too?   Hmm, maybe that's not useful for content
negotiation, not sure.

-Dave Fogel

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1528590

Re: Restlet 1.2 M2 released [throw previous email away]

[Rickard Öberg]

Stephan Koops wrote:
> Stephan Koops schrieb:
>> Jonathan Hall schrieb:
>>   
>>> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.  
>>> 
>> Would it work to change MediaType from class to an enum? That could 
>> work, but I'm not sure
> 
> While sending the email I remembered: You can't add new MediaTypes this 
> way, so we could forget my previous idea.

That depends on how you define the annotation. If it is
@interface Get
{
   Enum value();
}

it is fine, since then you can use any enum. Which is better than "any 
string", since then you get the confusion of "Should I use 'xml' 'XML' 
'text/xml' or what?". With Enum as baseline you at least have to look at 
what someone, somewhere, has defined.

/Rickard

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1527503

Re: Restlet 1.2 M2 released [throw previous email away]

[Tal Liron]

The
MetadataService is what you're talking about. It translates between
strings and other useful dimensions (in this case, MediaType
instances). Right now, though, it only supports "extensions" as the
strings, which mean to be filename extensions. So that's why we have
"txt" as the shorthand for MediaType.TEXT_PLAIN.


It
seems a good idea to me to change MetadataService to support other
kinds of shortcuts. In fact, as others have pointed out, it should be
desirable to have the actual full MIME type as a shortcut.


-Tal




Paul Austin wrote:

An alternative would be to have a MimeType class  which
had String constant values for all the common MediaTypes, then you
would only need to use strings if you had a non common media type.
  
One other thing I've noticed that in some places the mime type is
shortened (e.g. xml instead of text/xml). Is it possible to use the
full mime type across the API if required?
  
Paul
  
  On Thu, Apr 2, 2009 at 9:13 AM, Stephan
Koops 
wrote:
  Stephan
Koops schrieb:
> Jonathan Hall schrieb:
>
>> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.
>>
> Would it work to change MediaType from class to an enum? That could
> work, but I'm not sure

While sending the email I remembered: You can't add new MediaTypes this
way, so we could forget my previous idea.

best regards
  Stephan

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520779
  
  
  

Re: Restlet 1.2 M2 released

[Tim Peierls]

On Thu, Apr 2, 2009 at 12:13 PM, Rhett Sutphin wrote:

> On Apr 2, 2009, at 11:11 AM, Stephan Koops wrote:
>
>> Jonathan Hall schrieb:
>
> > Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.
>
>
>>  Would it work to change MediaType from class to an enum? That could work,
>> but I'm not sure
>
>
> This would sacrifice the ability to create new MediaTypes in applications
> which use the framework.
>


I proposed using Class as the annotation parameter
type, but Jerome said (in
http://n2.nabble.com/New-resource-API-design-tt2348626.html#a2400409):

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.


A lot of the time, the standard metadata constants provided by Restlet are
all you need, so what about allowing both enums for standard metadata and a
way of specifying custom metadata that is more verbose but also
type-safe? There's a way to do this that still allows simple (but unsafe)
string metadata. It would let you say things like:

@Get(media=APPLICATION_ALL_XML)
@Get(charsets={US_ASCII, ISO_8859_1})
@Get(userMedia=MyCustomMediaType.class)

in addition to the string forms. Here's a code sketch:

enum StdMediaType {
DEFAULT(MediaType.ALL),
ALL(MediaType.ALL),
APPLICATION_ALL(MediaType.APPLICATION_ALL),
APPLICATION_ALL_XML(MediaType.APPLICATION_ALL_XML),
// etc.
;

public boolean isDefault() { return this == DEFAULT; }
public MediaType mediaType() { return mediaType; }

StdMediaType(MediaType mediaType) { this.mediaType = mediaType; }
private final MediaType mediaType;
}

enum StdCharacterSet {
DEFAULT(CharacterSet.DEFAULT),
ALL(CharacterSet.ALL),
ISO_8859_1(CharacterSet.ISO_8859_1),
US_ASCII(CharacterSet.US_ASCII),
// etc.
;

public boolean isDefault() { return this == DEFAULT; }
public CharacterSet mediaType() { return mediaType; }

StdCharacterSet(CharacterSet mediaType) { this.mediaType = mediaType; }
private final CharacterSet mediaType;
}

enum StdEncoding { /* similarly */ }

enum StdLanguage { /* similarly */ }


@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Get {

/**
 * Representable media types specified either via extension names or
full
 * MIME type.
 */
String[] value() default "*/*";

/**
 * Representable standard media types.
 */
StdMediaType[] media() default StdMediaType.DEFAULT;

/**
 * Representable user (nonstandard) media types, specified by custom
subclass of MediaType.
 */
Class[] userMedia() default {};

/**
 * Representable standard character sets.
 */
StdCharacterSet[] charsets() default StdCharacterSet.DEFAULT;

/**
 * Representable user (nonstandard) media types, specified by custom
subclass of CharacterSet.
 */
Class[] userCharsets() default {};

// Similarly for encodings, languages
}

--tim

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1521391

Re: Restlet 1.2 M2 released [throw previous email away]

[Paul Austin]

An alternative would be to have a MimeType class  which had String constant
values for all the common MediaTypes, then you would only need to use
strings if you had a non common media type.

One other thing I've noticed that in some places the mime type is shortened
(e.g. xml instead of text/xml). Is it possible to use the full mime type
across the API if required?

Paul

On Thu, Apr 2, 2009 at 9:13 AM, Stephan Koops  wrote:

> Stephan Koops schrieb:
> > Jonathan Hall schrieb:
> >
> >> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.
> >>
> > Would it work to change MediaType from class to an enum? That could
> > work, but I'm not sure
>
> While sending the email I remembered: You can't add new MediaTypes this
> way, so we could forget my previous idea.
>
> best regards
>   Stephan
>
> --
>
> http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520779
>

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520903

Re: Restlet 1.2 M2 released

[Rhett Sutphin]

On Apr 2, 2009, at 11:11 AM, Stephan Koops wrote:

> Jonathan Hall schrieb:
>> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.
>>
> Would it work to change MediaType from class to an enum? That could
> work, but I'm not sure

This would sacrifice the ability to create new MediaTypes in  
applications which use the framework.

Rhett

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520788

Re: Restlet 1.2 M2 released [throw previous email away]

[Stephan Koops]

Stephan Koops schrieb:
> Jonathan Hall schrieb:
>   
>> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.  
>> 
> Would it work to change MediaType from class to an enum? That could 
> work, but I'm not sure

While sending the email I remembered: You can't add new MediaTypes this 
way, so we could forget my previous idea.

best regards
   Stephan

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520779

Re: Restlet 1.2 M2 released

[Stephan Koops]

Jonathan Hall schrieb:
> Shame you can't have @Get(MediaType.TEXT_HTML). I don't know.
>   
Would it work to change MediaType from class to an enum? That could 
work, but I'm not sure

best regard
  Stephan

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520761

Re: Restlet 1.2 M2 released

[Jonathan Hall]

Really need that full annotation syntax working to test it out ;0)

Regarding that, it does seem odd to have  @Get("xml")  but use 
MediaType.TEXT_XML in the code.

@Get("TEXT_XML") ? Shame you can't have @Get(MediaType.TEXT_HTML). I 
don't know.



Jerome Louvel wrote:
> Hi Jonathan,
>
> We would be quite happy to get your feed-back, positive or not :)
>  
> Best regards,
> Jerome Louvel
> --
> Restlet ~ Founder and Lead developer ~ http://www.restlet.org
> Noelios Technologies ~ Co-founder ~ http://www.noelios.com
>  
>
> -Message d'origine-
> De : Jonathan Hall [mailto:jonrh...@gmail.com] 
> Envoyé : mercredi 1 avril 2009 18:08
> À : discuss@restlet.tigris.org
> Objet : Re: Restlet 1.2 M2 released
>
> Excellent! I'm looking forward to seeing if the new Resource API simplifies
> development.
>
>
> Jerome Louvel wrote:
>   
>> Hi all,
>>  
>> The second 1.2 milestone is out! 
>>  
>> A complete coverage is available in our blog:
>> http://blog.noelios.com/2009/04/01/restlet-12-m2-released/ 
>> <http://blog.noelios.com/2009/01/23/restlet-12-m2-released/>
>>  
>> Best regards,
>> Jérôme 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/>
>> 
>
> --
> http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=15083
> 71
>
> --
> http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1508861
>
>

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1520632

RE: Restlet 1.2 M2 released

[Jerome Louvel]

Hi Jonathan,

We would be quite happy to get your feed-back, positive or not :)
 
Best regards,
Jerome Louvel
--
Restlet ~ Founder and Lead developer ~ http://www.restlet.org
Noelios Technologies ~ Co-founder ~ http://www.noelios.com
 

-Message d'origine-
De : Jonathan Hall [mailto:jonrh...@gmail.com] 
Envoyé : mercredi 1 avril 2009 18:08
À : discuss@restlet.tigris.org
Objet : Re: Restlet 1.2 M2 released

Excellent! I'm looking forward to seeing if the new Resource API simplifies
development.


Jerome Louvel wrote:
> Hi all,
>  
> The second 1.2 milestone is out! 
>  
> A complete coverage is available in our blog:
> http://blog.noelios.com/2009/04/01/restlet-12-m2-released/ 
> <http://blog.noelios.com/2009/01/23/restlet-12-m2-released/>
>  
> Best regards,
> Jérôme 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/>

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=15083
71

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1508861

Re: Restlet 1.2 M2 released

[Jonathan Hall]

Excellent! I'm looking forward to seeing if the new Resource API 
simplifies development.


Jerome Louvel wrote:
> Hi all,
>  
> The second 1.2 milestone is out! 
>  
> A complete coverage is available in our blog:
> http://blog.noelios.com/2009/04/01/restlet-12-m2-released/ 
> 
>  
> Best regards,
> Jérôme Louvel
> --
> Restlet ~ Founder and Lead developer ~ http://www.restlet.org 
> 
> Noelios Technologies ~ Co-founder ~ http://www.noelios.com 
> 

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1508371

Restlet 1.2 M2 released

[Jerome Louvel]

Hi all,
 
The second 1.2 milestone is out! 
 
A complete coverage is available in our blog:
http://blog.noelios.com/2009/04/01/restlet-12-m2-released/
 
 
Best regards,
Jérôme Louvel
--
Restlet ~ Founder and Lead developer ~  
http://www.restlet.org
Noelios Technologies ~ Co-founder ~  
http://www.noelios.com

--
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1508219