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 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 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)
<http://www.restlet.org/documentation/1.2/api/org/restlet/data/MediaType.htm
l#valueOf%28java.lang.String%29>
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
<http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1528
590> &dsMessageId=1528590
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1596015
