3、restlet 2.3 用户指南（三）框架

原文链接：http://restlet.com/technical-resources/restlet-framework/guide/2.3

以下翻译，以直译方式为主，内容主要针对目前应用最为广泛的基于 Java 的服务器端的开发与应用，并修复原文中涉及到的代码 bug 。

PS：下文中resources、representation、RESTful 等属于一组相关的领域内专有名词，不便翻译。其中 resources 可以理解为“资源”。representation 可以理解为“表现层对象”。RESTful 可以理解为基于 REST 理念或架构的框架和应用。

测试环境：

Mac OS X Yosemite Version 10.10.4 

IntelliJ IDEA 14.app

jdk1.8.0_51.jdk

maven 3.3.3
 
 

  
  

 
 

3 框架

3.1 介绍

restlet 框架由两个主要部分组成。首先是 restlet API，这个 API 支持 REST 和 HTTP 的概念，可以减轻客户端和服务端的调用处理。这个API 受 restlet 引擎的支持并可打成一个简单的 jar 包（org.restlet.jar）

这种 API 与执行实现的分离结构，类似于，servlet API 与jetty、tomcat 等 web 容器的分离，JDBC API 与具体的 JDBC 驱动的分离。

3.2 REST 架构概览

让我们后退一点，先从 REST 角度考虑一个典型的 web 架构。在下面的图表中，端口（小方块）表示连接器，这些连接器提供了由用大方块表示的两两组件之间的通讯。连线表示当前通讯所使用的特定协议（例如 HTTP、SMPT）。

注意，任意数目的客户端和服务器端连接器可以归属于同一个组件。例如 web Server B，既有一个服务端的连接器去应答由 User Agent 组件发出的请求，也有多个客户端连接器来向 web Server A 和 Mail Server 组件发送请求。

3.3 restlet 架构概览

restlet 框架不仅可以支持标准的 REST 架构，除此之外，还提供了一组类，可以极大地简化了在单个 JVM 中多个应用的部署。restlet 的目标是提供一个 RESTful 、便于移植的、灵活的 API 来替代现存的 servlet API。在下图中，我们能看到使用了三种类型的 restlet 来处理复杂的情形。组件可以管理多个虚拟主机和应用。

虚拟主机支持灵活的配置方式，例如，多个域名可以共享同一个 IP 地址，或者一个域名通过多个 IP 地址来做到负载均衡。最终，我们通过应用程序来管理一组相关的 restlet、resources 以及 representations 。补充说明，在不同的 restlet 实现以及不同的虚拟主机之间，这些应用程序需要确保能够便于移植和支持重新配置。并且，这些应用程序需要能提供一些重要的服务，例如，记录访问日志，自动解析请求实体、可配置的状态页设置等等。

为了阐述这些类的作用，我们举一个简单的例子。我们创建一个 restlet 组件，然后加入 HTTP server connector 并且监听将要链接的服务器的 8182 端口，接着创建一个 ServerResource 并将其加入到组件的默认虚拟主机中。这个默认的主机可以捕获任何的请求内容，这些请求内容并没有导入到一个声明好的虚拟主机之中（详细内容参考 Component.hosts 的属性）。在后面的例子中，我们也将会介绍应用类的使用。注意，到目前为止你在控制台中是看不到任何访问日志的。

完整代码如下：

import org.restlet.Component;
import org.restlet.data.Protocol;
import org.restlet.resource.Get;
import org.restlet.resource.ServerResource;

/**
 * Created by HEAVEN on 7/31/15.
 */
public class Test extends ServerResource {
    public static void main(String[] args) throws Exception {
        // Create a new Restlet component and add a HTTP server connector to it
        Component component = new Component();
        component.getServers().add(Protocol.HTTP, 8182);
        // Then attach it to the local host
        component.getDefaultHost().attach("/trace", Test.class);
        // Now, let's start the component!
        // Note that the HTTP server connector is also automatically started.
        component.start();
    }

    @Get("txt")
    public String toString() {
        // Print the requested URI path
        return "Resource URI  : " + getReference() + '\n' + "Root URI      : "
                + getRootRef() + '\n' + "Routed part   : "
                + getReference().getBaseRef() + '\n' + "Remaining part: "
                + getReference().getRemainingPart();
    }
}

（PS：运行后，控制台输出信息如下：）

Mac OS X Yosemite Version 10.10.4 ... 

Load ...

(~~)

Starting the internal [HTTP/1.1] server on port 8182

2015-07-3121:19:590:0:0:0:0:0:0:1- - 8182 GET /trace - 200 148 056 

http://localhost:8182 

Safari/537.36 -

现在，在浏览器中输入：http://localhost:8182/trace/abc/def?param=123 我们测试一下，在浏览器中下面是你将要看到的结果：

    Resource URI  : http://localhost:8182/trace/abc/def?param=123
    Root URI      : http://localhost:8182/trace
    Routed part   : http://localhost:8182/trace
    Remaining part: /abc/def?param=123

（PS：运行后，控制台输出信息如下：）

Mac OS X Yosemite Version 10.10.4 ... 

Load ...

(~~)

Starting the internal [HTTP/1.1] server on port 8182

2015-07-31 21:20:10 0:0:0:0:0:0:0:1 - - 8182 GET /trace/abc/def param=123 200 184 0 62http://localhost:8182

Safari/537.36 -

3.4 持久化层

restlet 框架尽管完全不可预知你所想要采用的持久化技术，但由于有着众多的成功案例，我们有信心你将不会在这一领域受到限制。

从 restlet 的角度出发，有一个基础性的设计理念，就是将你的由组件组成的应用，继承 org.restlet.resource.Resource 这个类。而那些子类用于管理输入的请求处理。对于每一个请求，都将会创建一个 resource 子类的实例来处理，这样也确保了你不必关心你的应用程序的并发访问的问题。

当你的 resource 类被实例化后，它将必须暴露他的 representations （通过 HEAD，GET 方法），来用于执行存储（PUT 方法）、导入（POST 方法）、删除（DELETE 方法）representations的操作。在构建期间，基于你的 resource ID 以及请求的参数或者属性，你将可以把持久层关联起来，从而支持逻辑处理或者返回 resource 的 representations 。

3.5 表现层

与 servlet API 相比，restlet API 并没有像 JSP 之类的辅助 API。替代方式是，我们选择了一个相同的设计方案开放给所有的表现层技术。这种开放性体现在用于响应实体的 representation 类之中。

更具体的来说，我们提供了三种流行模板技术的集成技术： XSLT, FreeMarker and Apache Velocity 。并且，集成 Facelets 已经由第三方完成，它将能够轻易的兼容其他任何可复用的模板技术。

关于功能扩展的设计理念是使用 TemplateRepresentation ，这个模板表现对象使用一个模板文档的数据结构来生成。