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 <rh...@detailedbalance.net>
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<? extends MediaType> 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<? extends MediaType>[] userMedia() default {};
/**
* Representable standard character sets.
*/
StdCharacterSet[] charsets() default StdCharacterSet.DEFAULT;
/**
* Representable user (nonstandard) media types, specified by custom subclass
of CharacterSet.
*/
Class<? extends CharacterSet>[] userCharsets() default {};
// Similarly for encodings, languages
}
--tim
------------------------------------------------------
http://restlet.tigris.org/ds/viewMessage.do?dsForumId=4447&dsMessageId=1579830
