Re: Restlet 1.2 M2 released

[Tim Peierls]

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=1521391