RESTful初探之四（Restlets）

Restlets
Restlet项目为“建立REST概念与Java类之间的映射”提供了一个轻量级而全面的框架。它可用于实现任何种类的REST式系统，而不仅仅是REST式Web服务。

The Restlet framework

Restlet application are akin to servlet applications in that they reside in a container,but in practice they are quite different in two major ways,First,Restlets use no direct notion of HTTP or its stateful manifestations such as cookies or sessions ,per se.Second,the Restlet framework is extremely lightweight.As you'll see ,a fully functional RESTful application can be built with a handful of classes that extend from a few core Restlet base classes.Configuration and deployment leverage existing container models,so you simply update the customary web.xml file and deploy a standard Web archive(WAR)file.
Restlet应用类似于servlet应用，他们都处于一个容器中。但是在实际操作中，他们在俩大方面有很大的不同：
一、Restlets没有直接的HTTP概念，也没有他自身的状态表现如cookies和sessions。
二、Restlets框架非常轻量。如你所见，一个全功能的RESTful应用只需少数几个继承自Restlet基础类的类。配置部署现有集成模式，只需简单更新通常的web.xml文件和部署一个标桩WAR文件。

For the most part,the bulk of a RESTful application built with the Restlet framework requires the use of two base classes:Application and Resource.Logically speaking,an Application instance maps URIs to Resource instances.Resource instances do the work of handling the basic CRUD commands,which are,of course ,mapped to GET,POST,PUT,and DELETE.
大部分情况下，基于Restlet框架的RESTful应用需要俩继承类：Application和Resource。从逻辑上讲，一个应用实例映射URIs到Resource实例。Resource实例支持CRUD命令操作。

The race application
You create a starting point with the Restlet framework by extending from the framework's Application class.In this class,you define Resources that respond to URIs.This definition process is done with the framework's Router class.For example,if you have a URI such as order/order_id,you need to specify which object can handle these requests.This object is an instance of the framework's Resource type.You link objects with URIs by attaching them to a Router instance,as in Listing5:

Router router = new Router(this.getContext());
router.attach("order/{order_id}", Order.class);

创建一个继承自Application的出发点。这个类中定义响应URIs的Resources，即框架的Router类实现。例如：URI order/order_id，你需要指定哪个对象来处理这个请求。这个对象是框架Resource类型的实例。对象与URIs的关联通过附加到Router实例下来实现。

So in this example, the URI order/order_id is logically mapped to an Order class (which, in turn, extends Resource).
这个例子将Order类与URI order/order_id逻辑映射起来。

Acme Racing has the four logical RESTful URIs that you've already defined - four patterns that work with various aspects of races and runners:
      * /race
      * /race/race_id
      * /race/race_id/runner
      * /race/race_id/runner/runner_id
你为Acme Racing 已经定义了四个逻辑RESTful URIs ——四种模式为各方面races和runners服务。

The behavior of each URI(such as if it works with POST,DELETE,GET,and so on)is'not important at this point.The behavior of each Resource is the job of a Resource instance; however,the Application instance is used to map these URIs to (yet-to-be-defined)Resources via a Router instance,as shown in Listing6:

public class ReceApplication extends Application{
      public RaceApplication(Context context){
       super(context);
    }
      public Restlet createRoot(){
       Router router = new Router(this.getContext());
       router.attach("/race",RacesResource.class);    
       router.attach("/race/{race_id}",RaceResource.class);
       router.attach("/race/{race_id}/runner",RaceRunnersResource.class);
       router.attach("/race/{race_id}/runner/{runner_id}",
       RaceRunnerResource.class);
       return router;
    }
}

继承自Application的实例被用来映射URIs到Resources，通过一个Router实例，如上面的代码所示。

    The base class,Application,is an abstract class.Extending classes must implement the createRoot() method.In this method, you can create a Router instance and attach Resources to URIs as i've done in List6.
Application是一个抽象类，他的子类必须实现createRoot方法，这个方法中，我们可以创建Router实例附加Resources到URIs上。

Race resources
Now that you've defined the Application instance to handle four different URI patterns,you must implement the four Resources.
Resource types in the Restlet framework are known as Restlets.They are the heart of any RESTful application developed with the Restlet framework.Unlike the Application type.the base Resource class is not abstract.It's more like a template with default behavior that you can override as needed.
现在你已经定义了四种URI模式在Application实例中。现在你必须再实现4个Resources。
Resource类型在Restlet框架中被称为Restlets。他们是Restlet框架下RESTful应用的核心。不同于Application类型，基础Resource类不是抽象的，他更想一个有默认方法的模板，你只需重写你需要的方法。

At a high level,Resource has four methods that require overriding.Not coincidentally,they map to the basic HTTP commands that are the touchstone of REST-GET,POST,PUT,DELETE.because the Resource class is nonabstract,the framework requires a paired method to be implemented for desired behavior to be invoked.For instance,if you want a particular resource to respond to DELETE requests,you would first implement the delete() method.Second, you also must implement the allowDelete() method and have this method return true(it defaults to false).By default,the corresponding PUT,POST,and DELETE allow methods return false,and the alllowGet() method return true.this means for read-only Resources,you need to override only one method(instead of two in the other three cases).You can alternatively call the setModifcation(true) in a Resource class and thus not have to override individual HTTP verb allow methods.
Resource类有四个方法需要被重写。这并非巧合。他们映射到HTTP的四种命令，是REST-GET,POST,PUT,DELETE的试金石。因为Resource类不是抽象的，REST框架需要一系列的方法去实现所期待的行为去被调用。例如，如果你想让一个指定的resource去响应一个DELETE请求，首先你要实现delete()方法，然后你必须实现allowDelete()方法并且使这个方法返回值为true。
默认情况下，相应的PUT,POST,and DELETE方法允许返回值为false，alllowGet()方法返回为ture。这意味着对于只读Resources，你只需重载一个方法（其它几种情况要俩方法）。你可以在一个resource类中选择性地访问setModifcation(true)方法，并且因此不必重写个体的HTTP动词方法。

For instance,the RacesResource is intended to respond to GET requests with XML document that describes the races in the system.Users can also create new races via this Resource type.Therefore,the RacesResource class overrides at least three methods from the Resource base class:
       *getRepresentation()
       *allowPost()
       *post()
Remember, Resources instances, by default, are read-only. Hence the allowGet() method doesn't need to be overridden.


上面讲的都是原理性的东西，下面是具体开发实例：

http://www.lifeba.org/arch/restlet_develop_jax-rs_service_1.html