dev@jsr311.java.net

RE: JSR311: The best practice to return primitive types from a RESTful service?

From: Liu, Jervis <jliu_at_iona.com>
Date: Thu, 29 Nov 2007 22:49:23 -0500

Thanks for the reply. I do agree that returning an int is indeed a fine grained style from the old RPC world, and this should be avoid if possible. However, as Stefan mentioned, whether or not an employee's age can be made a resource is really arguable, it is a design choice made by users unless the JSR-311 API formally prohibits doing so. So here is my question. As one of the goals of JSR-311 is to prompt a resource-oriented programming model [1], should not the JSR-311 spec provide a guide on how to deal with returning primitive types either through API or at least a best practice recommendation? At the moment, I see this is a hole not addressed by the spec. I can imagine once JRS-311 is getting used to build real applications, people will come out with the same question again and again, "oh, I have a java method "int getEmployeeAge(String employeeName)", how can I turn this into a restful service using JSR-311?".

Several options I have in my mind:

a). in JSR-311 section 3.1.2, "An implementation MUST include pre-packaged EntityProvider implementations for the following Java and media type combinations:", add the support for Java Primitive types:

Java primitive types All text media types (text/*).

But with an statement that returning a fine grained primitive type is not a recommended practice.

Essentially this means a JSR-311 runtime implementation needs to provide a PrimitiveEntityProvider to read and write primitive types to/from entity body using text/plain content type, same as what we do with String.

b). Do not provide any support for Java Primitive types but explicitly stated in JSR-311 section 3.1.2 that no default support for returning Java Primitive types is because this is not a recommended practice. But if users really want to do this, they really understand the design choice they have made, they can do this by registering their own PrimitiveEntityProvider on the JSR-311 container.

Thoughts?

[1]. "It was observed that an API cannot be RESTful itself, rather the applications built using the API can be RESTful. There was general agreement that the API should lead in a certain direction where developers would 'naturally' build RESTful applications." - Meeting Minutes April 24th, 2007. https://jsr311.dev.java.net/

Cheers,
Jervis



> -----Original Message-----
> From: Stefan Tilkov [mailto:stefan.tilkov_at_innoq.com]
> Sent: 20071130 1:53
> To: dev_at_jsr311.dev.java.net
> Subject: Re: JSR311: The best practice to return primitive types from a
> RESTful service?
>
> On Nov 29, 2007, at 10:18 AM, Liu, Jervis wrote:
>
> > It is mentioned in JSR-311 section 3.1.2 that "An implementation MUST
> > include pre-packaged EntityProvider implementations for the following
> > Java and media type combinations: java.lang.String All text media
> > types
> > (text/*).". However I don't see any places in the spec mentions about
> > the conversion between a Java primitive types and an entity body. It
> > is
> > a common use case that I want to map my SQL "select employee _age
> from
> > employee where employee _name='john'" to a java method "int
> > getEmployeeAge(String employeeName)" then expose this as a RESTful
> > service. Is this the correct way to do REST, or I am still having my
> > head in a Service-oriented world instead of resource-oriented?
>
> It's questionable whether an employee's age should be a resource in
> itself, but that's a design decision. Nothing unRESTful about it.
>
>
> > Anyway,
> > let's say my use case is indeed valid, in this case what content
> > type I
> > shall use to return an int type so that the client can make sense of?
> >
>
> text/plain if you return the characters "27". Some other content type
> if you use a binary representation; I'm not sure which one would be
> applicable and would actually cause less problems. Text seems fine
> here from POV.
>
>
> > Shall I return int using content type "text/*"? In the case of
> > returning
> > String, as long as the client knows the returned content type is text,
> > it should always be able to marshal the response body to a String
> > without making any further assumptions. However this does not work for
> > int type. If only information I have on the client side is the content
> > type "text/*", it would be impossible for me to make sense of the
> > response, is it a int type, is it a double type? I simply do not know.
> >
>
> That's a typical trade off, similarly to using application/xml: You
> have said that it's XML (or text/plain), which means that an client
> capable of handling this can work with it (which is good). You don't
> get any more information (which is bad). Make your own choice ;-)
>
> Stefan
> --
> Stefan Tilkov, http://www.innoq.com/blog/st/
>
>
> > Or maybe, return an int using "text/*" is not a good practice in the
> > RESTful world, using "application/xml" would be better. Can I say
> > exposing a java method whose signature is " int getEmployeeAge(String
> > employeeName)" is not a good practice, you should always wrap the
> > result
> > in a Java object instead, e.g., like " Employee getEmployeeAge(String
> > employeeName)"? Or maybe, the JSR-311 runtime can go a little bit
> > fancy,
> > for example, it can generate a wrapper automatically on top of java
> > primitive types so that the returned result is a valid an xml doc.
> >
> > Any thoughts would be highly appreciated. And should not JSR-311 spec
> > include a section to describe how to do the conversion between a Java
> > primitive types and an entity body?
> >
> > Thanks,
> > Jervis Liu
> >
> > ----------------------------
> > IONA Technologies PLC (registered in Ireland)
> > Registered Number: 171387
> > Registered Address: The IONA Building, Shelbourne Road, Dublin 4,
> > Ireland
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> > For additional commands, e-mail: dev-help_at_jsr311.dev.java.net
> >
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net

----------------------------
IONA Technologies PLC (registered in Ireland)
Registered Number: 171387
Registered Address: The IONA Building, Shelbourne Road, Dublin 4, Ireland