It's all about the answers!

Ask a question

Questions regarding IModelledRestService


Rakesh Kukkamalla (565) | asked Jul 09 '08, 4:01 p.m.
While working on my project I came accross some facts which I didnt understand quite well.

1. What does extending the service interface in common plugin with IModelledRestService mean?

2. Do we have to use IParameterWrapper to pass parameters for such services?

3. What is the difference between a service that extends IModelledRestService and one that doesnt?

Thank you.

7 answers



permanent link
Matt Lavin (2.7k2) | answered Jul 09 '08, 4:43 p.m.
FORUM MODERATOR / JAZZ DEVELOPER
The IModelledRestService is the service to implement if you would like to expose your service through a more language neutral interface. Subclasses of IModelledRestService are invoked with GET/POST through HTTP with the parameters encoded as URL parameters. That calling convention makes it easy to call the services from Javascript.

Service that subclass from just AbstractService (and don't implement IModelledRestService) are easily called from a Java client and the wire-format between the client and server is hidden by the Jazz transport/service execution code.

For IModelledRestServices, you do need to pass parameters through the IParameterWrapper class. The reason for that is because Java reflection is used to map URL parameters to fields in the IParameterWrapper class, but it is not possible to reflect the name of the normal Java method arguments.

permanent link
Bill Higgins (4562323) | answered Jul 09 '08, 10:46 p.m.
JAZZ DEVELOPER
Just to give a bit of history, when we started Jazz the initial focus was on enabling the Eclipse client. To do this we created an RPC-style interface where you could make Java method calls in the Eclipse and our service infrastructure would automagically serialize the service invocation request and response using a serialization format that was very specific to our Java/EMF software stack.

When we started work on the Jazz web UI and decided to use Ajax, we quickly realized that we needed a different web services story, since it wasn't feasible to write JavaScript code that could marshall/demarshall the EMF-based RPC service messages.

So literally in the course of about a week, I fed Pat Mueller the requirements and he came up with a very simple REST-style marshalling framework - IModelledRestService, with some nice EObject to JSON marshalling provided by Balaji Krishnamachari. It's basically a "low REST" approach that expects either GET or POST methods (GET for fetches and POST for everything else, where POSTs are overloaded for any action - e.g. postDeleteFoo, postDoCoolStuff, etc.). Each modeled REST service method returns an EObject, which is automagically marshalled into a simple JSON equivalent (which is very easy for the Ajax UI to understand, since JSON's pretty much "native" to JavaScript). As Matt mentioned, you also have the option of sending in an IParameterWrapper object as a parameter, where IParameterWrapper objects are simple "structs" (to use C terminology) that contain public properties that map to request parameters. The nice thing is that the request parameters are automatically converted from strings to whatever type you specify for the IParameterWrapper property (i.e. Strings, Booleans, Integers, etc.)

For Team Concert 1.0, IModelledRestService and IParameterWrapper are used almost exclusively by web clients (Eclipse client code tends to use the RPC-style services), such as the Work Items web UI. So if you want to see some usage examples, look at the *.web projects (for service requests) and the *.service projects for service implementations. E.g. com.ibm.team.workitem.web and com.ibm.team.workitem.service.

Surprisingly, even though we did the IModelledRestService stuff in a matter of weeks in early 2006, it's held up very well - it powers ~ 95% of the data transfer for all of the Team Concert 1.0 web clients. Over time, other people came to appreciate the power and flexibility that a simple REST-style web service interface provides. Because of this we've made REST a technological focus for post-Team Concert 1.0, in the form of the concrete Jazz REST Services work and more broadly the Open Services for Lifecycle Collaboration work. So while IModelledRestService has served us very well, the current thinking is that the Jazz REST Service stuff will become the primary style of REST interaction for the Jazz Platform in the future.

So if you're looking for some near-term REST goodness from Team Concert 1.0, IModelledRestService is a good way to go. But if you want to build on the strategic REST technology, I recommend you take a close look at JRS.

Below are some other docs that may shed light on this topic. Please write back if you have additional questions.

Ajax and REST, Part 1: Advantages of the Ajax/REST architectural style for immersive Web applications (moi)
http://www.ibm.com/developerworks/xml/library/wa-ajaxarch/

The Highs and Lows of REST (Ryan Tomayko)
http://lesscode.org/2006/03/19/high-low-rest/

A brief history of the Jazz Team Server interface: Our journey from a J2EE server towards a RESTful server (James Branigan)
https://jazz.net/blog/index.php/2008/02/15/a-brief-history-of-the-jazz-server-interface-our-journey-from-a-j2ee-server-towards-a-restful-server/

The Jazz REST Services (JRS) charter:
https://jazz.net/wiki/bin/view/Main/JRSCharter

Open Services for Lifecycle Collaboration:
http://jazz.net/open-services/

- Bill Higgins
Jazz Web UI Team

permanent link
Vibha Sinha (1643610) | answered Jul 10 '08, 1:26 a.m.
Hello Bill,

I have modeled some services using ITeamModelledRestService. However, the serialization it returns is xml based with a SOAP envelope. How could I make it return back the JSON serialization ?

Thanks
- Vibha

permanent link
Bill Higgins (4562323) | answered Jul 10 '08, 10:07 a.m.
JAZZ DEVELOPER
Hello Bill,

I have modeled some services using ITeamModelledRestService. However, the serialization it returns is xml based with a SOAP envelope. How could I make it return back the JSON serialization ?

Thanks
- Vibha


Sorry, I should have mentioned this. You have to send a "text/json" Accept header. See:

com.ibm.team.repository.web/resources/transport/TeamServerClient.js

... search for "text/json"

permanent link
Todd Lainhart (40611) | answered Jul 10 '08, 10:12 a.m.
FORUM MODERATOR / JAZZ DEVELOPER
To get back JSON, your Accept header must contain "text/json". Note
however that the response will still be wrapped in SOAP-ish wrapper.

Bill neglected to note that in 1.0 there is another variant of REST
services that are arguably more RESTful than the modelled REST services.
Plain JSON (without SOAP wrappers) is marshalled, and the URIs don't
need to contain reflective service names and wrapped parameters. While
the majority of Jazz REST services are "modelled", a number are not and
use the idiom described in the Wiki topic below:

https://jazz.net/wiki/bin/view/Main/JazzRESTServicesV1

-- Todd (Jazz Team)


vssinha wrote:
Hello Bill,

I have modeled some services using ITeamModelledRestService. However,
the serialization it returns is xml based with a SOAP envelope. How
could I make it return back the JSON serialization ?

Thanks
- Vibha

permanent link
Rakesh Kukkamalla (565) | answered Jul 10 '08, 1:22 p.m.
One more question I have is that if a service implements IModelledRestService the only way to send parameters to the sevice is through th IParameterWrapper. But the IParameterWrapper has restrictions regarding what kinda parameters can be passed.

I tried to send a ITeamAreaHandle inside a IParameterWrapper and it didnt work. Can you throw some light on how to deal with this. Is there a work around to pass parameters like this and still use IModelledRestService?

permanent link
Bill Higgins (4562323) | answered Jul 10 '08, 1:29 p.m.
JAZZ DEVELOPER
The pattern for this is to send in an itemId as a simple string parameter and then turn use some of the basic item-related APIs to turn this into the handle type you need.

UUID itemId = UUID.valueOf(paramWrapper.teamAreaItemId);
ITeamAreaHandle handle = ITeamArea.ITEM_TYPE.createItemHandle(itemId, null);

You can also use an identifier that's not an itemId (e.g. a work item integer ID). In this case you look up the item using a query rather than through the item handle.

If you haven't already you should really look at the Work Item modeled REST services (i.e. com.ibm.team.workitem.service.internal.rest.WorkItemRestService and related classes) for some usage examples and patterns.

One more question I have is that if a service implements IModelledRestService the only way to send parameters to the sevice is through th IParameterWrapper. But the IParameterWrapper has restrictions regarding what kinda parameters can be passed.

I tried to send a ITeamAreaHandle inside a IParameterWrapper and it didnt work. Can you throw some light on how to deal with this. Is there a work around to pass parameters like this and still use IModelledRestService?

Your answer


Register or to post your answer.