原文链接: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
2 初窥
2.1 第一个服务器
让我们看看 restlet 框架是如何监听客户端的请求以及如何应答的。我们将使用内置的 Restlet HTTP server connector 作为连接器(当然也可以选择使用类似的基于 jetty 的连接器)并返回一个简单的 String representation ——“Hello world”。注意这个 FirstServerResource 类需要继承有 restlet API 提供的 org.restlet.resource.ServerResource 基础类。
( PS:如果是 maven 项目,pom 加入如下依赖信息即可引入 restlet 的相关依赖。可以看到 restlet 并不在 maven 的中央仓库中。当然,推荐将 restlet 的仓库加入 nexus 等私服进行管理。但是 restlet 的仓库索引不是 publish index,所以无法将索引下载到本地,也因此无法在 IDE 中直接搜索,需要在远程仓库搜索相应的依赖信息进行手工录入)
<repositories> <repository> <id>maven-restlet</id> <name>Restlet repository</name> <url>http://maven.restlet.com</url> </repository> </repositories> <properties> <restlet-version>2.3.4</restlet-version> </properties> <dependencies> <dependency> <groupId>org.restlet.jse</groupId> <artifactId>org.restlet</artifactId> <version>${restlet-version}</version> </dependency> <dependency> <groupId>org.restlet.jse</groupId> <artifactId>org.restlet.ext.jackson</artifactId> <version>${restlet-version}</version> </dependency> </dependencies> ( PS:官网上的例子,使用 toString 的方法需要在注解中需要补充加入@get("txt"),否则将会提示 document is empty 的错误(源码显示,默认使用了 json 格式封装输出,从而导致错误)。改为StringRepresentation或者补充完成即可)
完整代码如下:
import org.restlet.Server; import org.restlet.data.Protocol; import org.restlet.representation.StringRepresentation; import org.restlet.resource.Get; import org.restlet.resource.ServerResource; /** * Created by HEAVEN on 7/31/15. */ public class FirstServerResource extends ServerResource { public static void main(String[] args) throws Exception { // Create the HTTP server and listen on port 8182 new Server(Protocol.HTTP, 8182, FirstServerResource.class).start(); } /* @Get public StringRepresentation helloWorld() { return new StringRepresentation("hello, world!"); } */ @Get("txt") public String toString() { return "hello, world!"; } } (PS:运行后,控制台输出信息如下:) Mac OS X Yosemite Version 10.10.4 ... Load ... JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/bin/java -Didea.launcher.port=7538 "-Didea.launcher.bin.path=/Applications/IntelliJ IDEA 14.app/Contents/bin" -Dfile.encoding=UTF-8 -classpath "${JAVA_HOME}/lib/ant-javafx.jar: ${JAVA_HOME}/lib/dt.jar: ${JAVA_HOME}/lib/javafx-mx.jar: ${JAVA_HOME}/lib/jconsole.jar: ${JAVA_HOME}/lib/packager.jar: ${JAVA_HOME}/lib/sa-jdi.jar: ${JAVA_HOME}/lib/tools.jar: ${JAVA_HOME}/jre/lib/charsets.jar: ${JAVA_HOME}/jre/lib/deploy.jar: ${JAVA_HOME}/jre/lib/javaws.jar: ${JAVA_HOME}/jre/lib/jce.jar: ${JAVA_HOME}/jre/lib/jfr.jar: ${JAVA_HOME}/jre/lib/jfxswt.jar: ${JAVA_HOME}/jre/lib/jsse.jar: ${JAVA_HOME}/jre/lib/management-agent.jar: ${JAVA_HOME}/jre/lib/plugin.jar: ${JAVA_HOME}/jre/lib/resources.jar: ${JAVA_HOME}/jre/lib/rt.jar: ${JAVA_HOME}/jre/lib/ext/cldrdata.jar: ${JAVA_HOME}/jre/lib/ext/dnsns.jar: ${JAVA_HOME}/jre/lib/ext/jfxrt.jar: ${JAVA_HOME}/jre/lib/ext/localedata.jar: ${JAVA_HOME}/jre/lib/ext/nashorn.jar: ${JAVA_HOME}/jre/lib/ext/sunec.jar: ${JAVA_HOME}/jre/lib/ext/sunjce_provider.jar: ${JAVA_HOME}/jre/lib/ext/sunpkcs11.jar: ${JAVA_HOME}/jre/lib/ext/zipfs.jar: /Users/HEAVEN/IdeaProjects/restletSample/restletGuideSample/target/classes: ${MAVEN_REPOSITORY}/org/restlet/jse/org.restlet/2.3.4/org.restlet-2.3.4.jar: ${MAVEN_REPOSITORY}/org/restlet/jse/org.restlet.ext.jackson/2.3.4/org.restlet.ext.jackson-2.3.4.jar: ${MAVEN_REPOSITORY}/com/fasterxml/jackson/core/jackson-core/2.4.4/jackson-core-2.4.4.jar: ${MAVEN_REPOSITORY}/com/fasterxml/jackson/core/jackson-annotations/2.4.4/jackson-annotations-2.4.4.jar: ${MAVEN_REPOSITORY}/com/fasterxml/jackson/core/jackson-databind/2.4.4/jackson-databind-2.4.4.jar: ${MAVEN_REPOSITORY}/com/fasterxml/jackson/dataformat/jackson-dataformat-csv/2.4.4/jackson-dataformat-csv... ${MAVEN_REPOSITORY}/com/fasterxml/jackson/dataformat/jackson-dataformat-smile/2.4.4/jackson-dataformat-smi... ${MAVEN_REPOSITORY}/com/fasterxml/jackson/dataformat/jackson-dataformat-xml/2.4.4/jackson-dataformat-xml... ${MAVEN_REPOSITORY}/com/fasterxml/jackson/dataformat/jackson-dataformat-yaml/2.4.4/jackson-dataformat-yaml... ${MAVEN_REPOSITORY}/com/fasterxml/jackson/module/jackson-module-jaxb-annotations/2.4.4/jackson-module-jaxb... ${MAVEN_REPOSITORY}/com/fasterxml/jackson/module/jackson-module-jsonSchema/2.4.4/jackson-module-jsonSchema... ${MAVEN_REPOSITORY}/org/codehaus/woodstox/woodstox-core-asl/4.3.0/woodstox-core-asl-4.3.0.jar: ${MAVEN_REPOSITORY}/javax/xml/stream/stax-api/1.0-2/stax-api-1.0-2.jar: ${MAVEN_REPOSITORY}/org/codehaus/woodstox/stax2-api/3.1.4/stax2-api-3.1.4.jar: ${MAVEN_REPOSITORY}/org/yaml/snakeyaml/1.13/snakeyaml-1.13.jar: ${MAVEN_REPOSITORY}/log4j/log4j/1.2.17/log4j-1.2.17.jar:${MAVEN_REPOSITORY}/junit/junit/4.12/junit-4.12.jar: ${MAVEN_REPOSITORY}/org/hamcrest/hamcrest-core/1.3/hamcrest-core-1.3.jar: /Applications/IntelliJ IDEA 14.app/Contents/lib/idea_rt.jar" com.intellij.rt.execution.application.AppMain com.simon.framework.restletGuideSample.FirstServerResource Starting the internal [HTTP/1.1] server on port 8182 2015-07-31 20:10:51 0:0:0:0:0:0:0:1 - - 8182 GET http://localhost:8182 Safari/537.36 -
如果你运行这段代码并且启动了你的服务器,那么你可以打开 web 浏览器并登入 http://localhost:8182 。事实上,任意的 URI 都是生效的,例如登入:http://localhost:8182/test/tutorial 。 注意,如果你在不同的机器上测试你的服务器,你需要用 IP 地址或者已经定义好的主机名字来替换“localhost”。
到目前为止,通过 ServerResource ,我们已经向你展示了 restlet API 最上层的抽象应用情况。但随着我们的脚步向前,你将会发现,这个类是受到广泛的 Java API 支持的,所有的 REST 和 HTTP 概念都映射到一组Java 类、接口和注解之中。