#Restlet 2.3 指南

---

#1. Restlet概述

Restlet框架由两个主要部分构成。首先，一部分是"Restlet API"，是一个中立的，支持REST概念，并能促进客户端、服务器端应用程序的调用处理机制的API。这个API由Restlet引擎支持，而且Restlet API和Restlet Engine现在都封装在一个单独的JAR文件中("org.restlet.jar")。 这样的API和实现的分离关系有点类似于Servlet API和Web容器(比如Jetty或者Tomcat)的关系，也类似于JDBC API和JDBC驱动包的关系。

#2. 获取一个网页的内容

正如我们在导论论文中提到的，Restlet框架既是客户端框架，同时也是服务器端框架。比如说，Restlet可以很容易通过它的HTTP客户端连接器(connector)处理远程资源。一个REST的连接器是其软件的一个组成部分，能够提供不同组件(Component)之间交流的功能，通常通过实现一个网络协议的一端来实现这个功能。Restlet提供了多种基于现存的开源项目的连接器的实现。连接器部分列出了所有可用的客户端、服务器端连接器并解释了应该如何使用和配置它们。

下面我们将获取一个已经存在资源内容的表达(Representation)并把它输出到JVM的控制台里：

// Outputting the content of a Web page
new ClientResource("http://restlet.org").get().write(System.out);

请注意：上述例子使用了简化的方式，通过ClientResource类来发出调用。如果你需要多线程或者需要加强对其的控制，你可以直接操作客户端连接器类对象或者请求对象(Request)。下面的例子告诉我们如何对客户端请求进行一些设置，例如引用地址。它(配置)也可以是你在回应中希望得到的语言或者媒体类型。

// Create the client resource
ClientResource resource = new ClientResource("http://restlet.org");// Customize the referrer property
resource.setReferrerRef("http://www.mysite.org");// Write the response entity on the console
resource.get().write(System.out);

3. 监听浏览器请求

现在，我们想看看Restlet框架如何监听浏览器请求并回复的。我们会使用内部的Restlet HTTP服务器连接器(当然我们可以使用Jetty这些服务器)并返回一个简单的字符串资源的表达："hello, world"字符串。注意：Part03类继承了由Restlet提供的基类ServerResource类：

public class Part03 extends ServerResource {public static void main(String[] args) throws Exception {// Create the HTTP server and listen on port 8182new Server(Protocol.HTTP, 8182, Part03.class).start();}@Getpublic String toString {return "hello, world";}
}

如果你运行这段代码，运行服务器，你可以打开一个网页浏览器并点击http://localhost:8182。实际上，任何的URI都可以，再试试http://localhost:8182/test/tutorial。注意：如果你在不同的机器上测试这个服务器(程序)，你会需要把"localhost"替换成服务器地址，如果有域名的话替换成域名。

迄今为止，我们已经通过ClientResource类和ServerResource类展示给你了Restlet API的最高层次的抽象。但随着我们继续前进，你会发现那两个类被很多API函数支持，使你能够操作所有REST功能。

4. REST结构概述

让我们回退一点，从REST角度考虑一个典型的web结构。如下图所示，小方块表现了使组件之前能够交流的连接器，组件由大盒子表现。连线描述了在实际交流中使用的特定的协议(HTTP, SMTP, 等等)。

注意：同一组件上可以有任意数目的客户端连接器和服务器连接器。比如Web Server B，具有服务器连接器用以响应从User Agent组件的请求，也具有客户端连接器，用以向Web Server A和Mail Server发送请求。

5. 组件、虚拟主机和应用程序

Restlet框架不仅可以像之前所演示的，能够支持标准的REST软件结构，而且它也提供了一系列的类，可以极大的简化在单一的一个JVM里部署多个应用程序的功能。Restlet API的目标是提供一个RESTful，易于移植，并且比现有Servlet API更加灵活的替代品。在下面的图表中，我们可以看到三种不同的Restlet用来处理如此复杂的情况。组件能够管理多个虚拟主机和应用程序。

虚拟主机可以提供灵活的配置，比如说多个域名共享一个IP，或者一个域名使用多个IP用于负载平衡。最终，我们使用应用程序们来管理一系列相关Restlet对象，资源对象，表达对象。除此之外，应用程序们要具有可移植、可重新配置的特点，即可以轻易的切换成不同的Restlet实现有不同的虚拟主机。而且，它们提供了一些重要的服务，比如记录访问日志、自动解析请求内容实体、可配置的状态页设置和其它服务！

为了解释这些类，让我们来看一个简单的例子。这里我们创建一个Component对象，然后给它添加一个HTTP服务器连接器，监听8182端口。现在我们创建一个简单的追踪请求信息用的Restlet，并把它放在这个Component默认的虚拟主机这里。这个默认的虚拟主机只是抓取所有的请求对象，并不把它们转向到一个声明好的虚拟主机对象那里(详见Component.hosts属性)。在偏后的例子，我们也引入Application类的使用。注意：现在在控制台你是看不到日志信息的。

public static void main(String[] args) throws Exception {public static void main(String[] args) throws Exception {// Create a new Restlet component and add a HTTP server connector to itComponent component = new Component();component.getServers().add(Protocol.HTTP, 8182);// Then attach it to the local hostcomponent.getDefaultHost().attach("/trace", Part05.class);// Now, let's start the component!// Note that the HTTP server connector is also automatically started.component.start();}@Getpublic String toString() {// Print the requested URI pathreturn "Resource URI  : " + getReference() + '\n' + "Root URI      : "+ getRootRef() + '\n' + "Routed part   : "+ getReference().getBaseRef() + '\n' + "Remaining part: "+ getReference().getRemainingPart();}
}

现在，我们在浏览器里输入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