RESTful Web Services with JRapid

23/07/2009. Christian Hein

Introduction

A Web Service is defined by the W3C as "a software system designed to support interoperable machine-to-machine interaction over a network?.

This means web services allow systems to interact in a client - server architecture. The system acting as a server offers ways for the client to execute operations. These operations may include the typical create, read, update and/ or delete actions.

As described in Wikipedia, Web services are a set of tools that can be used in a number of ways. The three most common styles of use are RPC, SOA and REST. The basic Web Services platform is XML + HTTP.

A web service may have an interface described in a machine-processable format (e.g. WSDL). Other systems interact with the Web service in a manner prescribed by its description using SOAP-messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards.

In his article on RESTful web services, Sameer Tyagi explains this subject. (REST) is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs. Web service clients that want to use these resources access a particular representation by transferring application content using a small globally defined set of remote methods that describe the action to be performed on the resource.

The service producer and service consumer have a mutual understanding of the context and content being passed along. Because there is no formal way to describe the web services interface, both parties must agree out of band on the schemas that describe the data being exchanged and on ways to process it meaningfully.

Web services in JRapid

Web applications created using JRapid are built around a RESTful controller. This means every JRapid application exposes all of its operations through RESTful web services. The AJAX client communicates with the RESTful controller through these web services.

In a JRapid generated application the RESTful controller is implemented by auto generated MainControllerAbstract class. This class registers every service in its initialization method. The MainControllerAbstract registers a service for every CRUD operation for each entity created. If other services are required, the developer may register them editing the MainController class that extends the former.

Suppose you have a JRapid application consisting of only one entity named Company as follows.

The services registered by the MainControllerAbstract class for the Company entity generate the following code.

private final static String QUERY_PATTERN = "(?:,saveas=([a-zA-Z0-9 ]+))?(?:,page(\\d+))?(?:!([^\\$]+))?(?:\\$(\\d+d?))?";

// main for Company

controller.registerXmlService(GET, "/Company" + QUERY_PATTERN, CompanyServices.class, "findPage", new DefaultMarshaller());
controller.registerXmlService(GET, "/Company/([0-9,]+)", CompanyServices.class, "find", new DefaultMarshaller(true));
controller.registerXmlService(POST, "/Company/([0-9,]+)", CompanyServices.class, "store", new DefaultMarshaller(true, "com/webservices/xml/CompanyFull.xml"));

When previewing the Company entity in the JRapid IDE you may use the quick access combo on the right upper corner of the Preview canvas to test the auto generated services for this entity.

For each entity created in a JRapid application there are three main REST services exposed as resources. Each of these services is accessed through a specific URL. We will describe some of these using the Company entity example.

http://dev2.jrapid.com/webservices/xml/Company
Lists all the companies.



 	JRapid Corp. 


 	Web Services Ltd.

http://dev2.jrapid.com/webservices/xml/Company/1
Gets or Posts the company with id equal to 1.


 	JRapid Corp. 
JRapid Way, 10x faster 
true

http://dev2.jrapid.com/webservices/xml/Company,page1!companyName=JRapid
Lists the first page of companies after applying the companyName filter with ?JRapid? as the parameter value.



 	JRapid Corp.

As the code in MainControllerAbstract shows, each of these URLs maps to a method in the corresponding services class, in this case, the CompanyServicesAbstract class.

// code for find
public Company find(String id) {
...
}

// code for store
public Object store(String id, Company voobj) {
...
}

// code for findall
public Collection findPage(String storedFilter, String page, String pattern, String order) {
?
}

Conclusions

JRapid applications enable interaction with other systems through the use of web services from ground up. The RESTful controller architecture that supports the client ? server architecture of the very application may be used as well to provide or consume services to and from other systems.

Unless a very specific protocol of communication must be addressed through the use of a more formal web service interface definition, the same auto generated services, or extensions of these, may be offered as web services.

By overwriting the existing methods or creating new ones the developer may offer more customized operations through web services.