dev@jsr311.java.net

Re: JSR311: EntityProvider Syntax Clarifcation

From: Ryan J. McDonough <ryan_at_damnhandy.com>
Date: Fri, 2 Nov 2007 17:50:34 -0400

My apologies for the multiple posts of my first message. GMails IMAP
appears to be very flakey. But I think I got it now. So the proper
syntax for this class would be:

@Provider
@Contract
@ConsumeMime("image/jpg,image/png,image/gif")
@ProduceMime("image/jpg,image/png,image/gif")
public class ImageEntityProvider implements EntityProvider<IIOImage> {

        public IIOImage readFrom(Class<IIOImage> type,
                                                         MediaType mediaType,
                                                         MultivaluedMap<String, String> httpHeaders,
                                                         InputStream entityStream) throws IOException {...}

        public void writeTo(IIOImage image,
                                            MediaType mediaTypes,
                                            MultivaluedMap<String, Object> httpHeaders,
                                            OutputStream entityStream) throws IOException {...}

        public boolean supports(Class<?> type) {...}


Now I were using Jersey as an implementation, the
AbstractTypeEntityProvider class would be annotated by an @Contract
annotation. If ImageEntityProvider extended,
AbstractTypeEntityProvider then ImageEntityProvider would not need to
be marked with @Contract? I'm still a bit fuzzy on the need for
@Contract both and @Provider. Couldn't @Provider just be sufficient?

Ryan-


On Nov 2, 2007, at 10:58 AM, Marc Hadley wrote:

> On Nov 2, 2007, at 9:55 AM, Ryan J. McDonough wrote:
>
>> As I read through some the spec and some of the Jersey code, I am
>> not clear on how the proper syntax on how to create a custom
>> EntityProvider. To help clarify my understanding, I have some code
>> below for a theoretical ImageEntityProvider which would be able to
>> render an Image representation. Based on what I have read so far,
>> this is my understanding so far on how to implement it:
>>
>> @Provider
>> public class ImageEntityProvider implements
>> EntityProvider<IIOImage> {
>> @ConsumeMime("application/xml,image/jpg,image/png,image/gif")
>> public IIOImage readFrom(Class<IIOImage> type,
>> MediaType mediaType,
>> MultivaluedMap<String, String> httpHeaders,
>> InputStream entityStream)
>> throws IOException {...}
>> @ProduceMime("image/jpg,image/png,image/gif")
>> public void writeTo(IIOImage image,
>> MediaType mediaTypes,
>> MultivaluedMap<String, Object> httpHeaders,
>> OutputStream entityStream)
>> throws IOException {...}
>>
> Move the ConsumeMime and ProduceMime to the class as you show
> below, you also need to add the supports method. The supports
> method allows an entity provider to support entities based on
> criteria other than the class of the entity. E.g. the JAXB provider
> is declared as "implements EntityProvider<Object>" but only
> supports classes annotated with @XmlRootElement.
>
>> The spec also mentions the use of the @Contract annotation, but
>> I'm not clear on the proper usage or the specific functionality
>> it provides. In regards to the @ProduceMime and @ConsumeMime
>> annotations, is it also possible to be able to annotate the
>> provider this way?
>>
>> @Provider
>> @ProduceMime("image/jpg,image/png,image/gif")
>> @ConsumeMime("application/xml,image/jpg,image/png,image/gif")
>> public class ImageEntityProvider implements
>> EntityProvider<IIOImage> {
>>
>> public IIOImage readFrom(Class<IIOImage> type,
>> MediaType mediaType,
>> MultivaluedMap<String, String> httpHeaders,
>> InputStream entityStream)
>> throws IOException {...}
>>
>> public void writeTo(IIOImage image,
>> MediaType mediaTypes,
>> MultivaluedMap<String, Object> httpHeaders,
>> OutputStream entityStream)
>> throws IOException {...}
>>
>>
>> I'm just trying to clarify how this all should work in practice as
>> it seems a bit vague at the moment. Is this syntax correct?
>>
> Exactly. Support for @Provider isn't yet implemented in Jersey
> which instead uses files in jersey/src/impl/META-INF/services to
> discover providers. The plan is that the JSR 311 runtime will scan
> for classes annotated with @Contract and @Provider to remove the
> need for such static configuration files. @Contract identifies an
> interface/abstract class for which providers are expected (e.g.
> EntityProvider), this corresponds to the name of the files
> currently in jersey/src/impl/META-INF/services. @Provider
> identifies classes that implement one or more interfaces/abstract
> classes annotated with @Contract and this corresponds to an entry
> in one of the files in jersey/src/impl/META-INF/services.
>
> Hope that makes it a little clearer.
>
> Marc.
>
>
> ---
> Marc Hadley <marc.hadley at sun.com>
> CTO Office, Sun Microsystems.
>
>
> ---------------------------------------------------------------------
> To