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

Tue, 07 Apr 2009 10:51:14 -0700

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:
 
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:
 
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"
 
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:[email protected]]
Envoyé : vendredi 3 avril 2009 07:46
À : [email protected]
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 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

Reply via email to