Arquitectura del Framework

As stated in the REST references provided in the previous section, the HTTP URL concept is central to the REST architectural style. Also, REST organizes its processing units as resources, and each resource is mapped to a particular URL reference. As URLs are global - each organization maintains its own set of URLs under its domain - this provides REST a universal addressing scheme, but this apparently trivial consideration simplifies a lot of the complexities found in a typical web services scenario.

NOTE: This section is extracted from the tutorial. For the complete explanations please refer there.

As REST architecture's organization is mainly based in URL hierarchies, it is important to know which parts of an URL map with which facilities of the java servlet API. The following URLs represent different resources in a REST hierarchy:

• http://example.com/forum/topics that represents the topics in a forum application.
• http://example.com/forum/topics/234 that represents a single topic in a forum application.
• http://example.com/forum/topics/234/comments that represents comments on a single topic ( in the same forum application ).
• http://example.com/forum/topics/234/comments/34 that represents a single comment of a given topic.

From a Java Servlet API implementation perspective, parts that form the previous URLs will be mapped to a resource as shown in the following image ( at least in a Cetia4 implementation ).

This means that in Cetia4 Framework, all requests starting from a given level will be attended by a single servlet, although from a REST perspective these different URLs represent different resources. Moreover, each of these URLs may be accessed using different HTTP methods: GET, POST, PUT, DELETE; and also different query strings and parameters of these different types of requests may result in different behavior. A good part of the tutorial deals explicitly in how the framework manages to do this in an easy and convenient way, from the simplest cases to the more elaborated ones.

Cetia4's servlets are subclasses of com.acsinet_solutions.cetia4.controller.rest.RestServlet class, which in turn extends javax.servlet.http.HttpServlet.

RestServlet is an abstract class which implements doGet(), doPost(), doPut() and doDelete() methods, and enables the facilities in the framework.

Cetia4 REST Framework uses an approach to attend requests similar to the one present in the standard Java Portlet specification. In this model, requests are divided in two types: render requests and action requests. In Cetia4 render requests answer GET HTTP method requests; and action requests answer POST, PUT and DELETE HTTP method requests.

Render requests are attended in REST servlets by render methods. Render methods can attend both web browser based requests that are answered with HTML or XHTML markup, and web service requests that are answered with XML markup. Render methods in a Cetia4 REST servlet ( which extends RestServlet ) are not inherited from the parent class. Instead, they are discovered at class initialization using the standard Java Reflection API. That means that those methods must adhere to a convention in order to be discovered and used. The most simple render method that can be created on a Cetia4 REST servlet is the one that is shown in the following code:

package com.example.forum.controller;
import com.acsinet_solutions.cetia4.controller.rest.RestServlet;
import com.acsinet_solutions.cetia4.controller.RenderContext;
public class TopicsServlet extends RestServlet
{
  public String render( RenderContext context )
  {
   return "display_topics";
  }
}

A render method can be recognized because it starts with the "render" prefix, and returns a java.lang.String value. Parameters of a render method are dynamic in nature, but commonly will receive at least an argument of type com.acsinet_solutions.cetia4.controller.RenderContext. In a servlet environment, this class can be viewed as a generic holder for standard servlet request, response and config objects ( javax.servlet.http.HttpServletRequest, and so on ). RenderRequest offers convenience methods to access functionality of those servlet specific objects in a generic way.

The render method returns a java.lang.String instance as it return value. This value will point to the view that will display the response to the client. It can be an absolute path value ( starting with a '/' ), or a relative path value. A relative path value - like the one in the previous code example "display_topics" - references a file in a default directory with a default extension. The default directory is dependent on the servlet's name, and starts by default with the path "/WEB-INF/html" for traditional web requests ( as oposed to a web service request ), and then a directory with the REST servlet name.

The previously created render() method will answer GET requests for the basic resource of the servlet; that is, it will answer requests for the URL http://example.com/forum/topics, but it won't answer GET requests of any of it's sub-resources such as http://example.com/forum/topics/234 or http://example/forum/topics/235/comments. How to answer these other types of requests is covered in the tutorial document.

The render method defined above can be used also for a web service request; one request that expects XML as a response format. This can be easily accomplished using the same relative path facility that was explained previously. In case of a web service request, a different view is selected; for the same example as before, the default directory now is placed before /WEB-INF/xml ( instead of /WEB-INF/html ) and the default prefix is .jspx ( because now we are generating XML files ). So, for the same code example, the view file in this case will be /WEB-INF/xml/topics/display_topic.jspx.

Cetia4 framework recognizes between a traditional web request and a web service request based on the HTTP Accept header. An Accept HTTP header of value "text/html" or that contains "html" anywhere in it will be answered in a traditional web way ( and thus the /WEB-INF/html view will be called ); on contrast, an Accept HTTP header of value "application/xml" or "text/xml" will be answered in a web service way ( and thus the /WEB-INF/xml view will be called ). So, it is very important for web service client to set this header appropriately, or the request may not be answered as desired.

Copyright © ACSINET S.A. de C.V. 2000 - 2007 Derechos Reservados. Java™ is a trademark of Sun Microsystems in the United States and/or other countries All other products and services are trademarks of their respective owners.