Restlet官方文檔翻譯

1、第1章 java Restletrestlet是java框架中用于開發(fā)RESTful風(fēng)格的web應(yīng)用程序的框架。在restlet中，我們可以方便的使用Router來管理URI。一個HTTP請求包含一個URI來標(biāo)識要訪問的資源。這個信息被存儲在Request.resourceRef屬性中，并作為我們路由請求的基礎(chǔ)。我們的第一個目標(biāo)是找目標(biāo)資源，它可以是一個ServerResource類及其對象或ServerResource類的子類及其對象。如果使用類而不是對象，則在有請求到來并路由成功（匹配route成功）之后，會自動實例化該類。在Router類中有一個attach()方法，它需要兩個參數(shù)，一個

2、是URI模版，一個是ServerResource。attach()方法會創(chuàng)建相應(yīng)的routes，以便在有請求到來時進行匹配。在使用Router時，我們不必關(guān)心HTTP請求的Method，因為我們只需要在Resource類中使用注解（比如：put，post等），Router就會自動根據(jù)HTTP請求中的Method，去調(diào)用有著相應(yīng)注解的方法。1.1 Restlet概述Restlet框架由兩個重要部分組成：Restlet API和Restlet Engine 。Restlet API是支持REST的API，并能處理來自用戶側(cè)和服務(wù)器側(cè)應(yīng)用程序的調(diào)用。Restlet API的后端是Restlet En

3、gine，這兩部分都在包中。在API和實現(xiàn)之間的區(qū)別，類似Servlet API和Web contatiners（Jetty或Tomcat）或JDBC API和具體的JDBC drivers之間的區(qū)別。Restlet框架既是客戶框架也是服務(wù)器框架。比如，Restlet能使用HTTP client connector去操作遠(yuǎn)程資源。在REST中的一個connector是來保證兩個組件之間正常通信的軟件元素，通常由網(wǎng)絡(luò)協(xié)議實現(xiàn)。Restlet提供幾個基于已有開源項目的client connectors實現(xiàn)。在connectors一章中，列出了所有可用的client和server connector

4、s，并解釋了如何去使用和配置。/ Create the client resourceClientResource resource = new ClientResource("");/ Customize the referrer propertyresource.setReferrerRef("");/ Write the response entity on the consoleresource.get().write(System.out);現(xiàn)在，我們想要知道Restlet框架如何監(jiān)聽客戶請求和相應(yīng)。我們

5、將用Internal Restlet HTTP服務(wù)器connector，并返回一個簡單的字符串表示“hello, world”。public class Part03 extends ServerResource public static void main(String args) throws Exception / Create the HTTP server and listen on port 8182 new Server(Protocol.HTTP, 8182, Part03.class).start(); Get public String toString() return

6、 "hello, world" 如果運行這個代碼和啟動你的服務(wù)器，你能打開一個Web 瀏覽器，并登錄http:/localhost:8182。事實上，任何URI都能正常工作，嘗試使用http:/localhost:8182/test/tutorial。注意，如果你從另一臺機器測試你的服務(wù)器，你需要替換“l(fā)ocalhost”。1.2 REST架構(gòu)概述讓我們從REST的角度來考慮典型的web架構(gòu)。這下圖中，ports表示connector，links表示具體的協(xié)議（HTTP，SMTP等）。1.3 Components，virtual hosts和applications除了支持

7、標(biāo)準(zhǔn)REST軟件架構(gòu)之外，Restlet 框架也提供一個可以極大簡化在一個JVM內(nèi)部駐留多個應(yīng)用程序的類集。目標(biāo)是提供RESTful、portable和更靈活的選擇來替代已有Servlet API。在下圖中，我們能看到Restlets提供了三個類型來管理這些復(fù)雜情形。Components能管理幾個Virtual Hosts和Applications。Virutal Hosts支持靈活的配置，比如，幾個域名共享相同IP地址，或者相同域名被負(fù)載均衡到幾個不同的IP地址。最后，我們用Applications來管理相關(guān)Restlets、Resources和Representations的集合。除此之外

8、，Applications被確保能在不同的Restlet實現(xiàn)和不同的Virual Hosts上portable和reconfigurable。除此之外，他們也提供像訪問日志、請求實體的自動編碼、可配置狀態(tài)頁設(shè)置等等的重要服務(wù)。為了說明這些類，我們使用一個簡單的例子。在這里我們創(chuàng)建一個Component，然后增加一個HTTP服務(wù)器Connector到它上面，并監(jiān)聽在端口8182。然后我們創(chuàng)建一個簡單的trace Restlet，并把它增加到Component的默認(rèn)Virtual Host上。默認(rèn)host會抓住任何還沒有路由到一個聲明VirtualHost的請求（看Component.hosts屬

9、性）。在之后的例子中，我們也引入Application類的用法。注意現(xiàn)在還沒有任何的訪問日志顯示在終端上。public class Part05 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

10、, 8182); / Then attach it to the local host component.getDefaultHost().attach("/trace", Part05.class); / Now, let's start the component! / Note that the HTTP server connector is also automatically started. component.start(); Get public String toString() / Print the requested URI path r

11、eturn "Resource URI : " + getReference() + 'n' + "Root URI : " + getRootRef() + 'n' + "Routed part : " + getReference().getBaseRef() + 'n' + "Remaining part: " + getReference().getRemainingPart();現(xiàn)在，我們通過在Web瀏覽器上輸入t:8182/trace/abc/def?pa

12、ram=123來測試。得到的結(jié)果如下：Resource URI : http:/localhost:8182/trace/abc/def?param=123Root URI : http:/localhost:8182/traceRouted part : http:/localhost:8182/traceRemaining part: /abc/def?param=123 1.4 Serving static files你的Web應(yīng)用程序會提供像Javadocs一樣的靜態(tài)頁面嗎？如果有，不需要建立一個Apache服務(wù)器，使用Directory類即可。/ URI of the root di

13、rectory.public static final String ROOT_URI = "file:/c:/restlet/docs/api/"./ Create a componentComponent component = new Component();component.getServers().add(Protocol.HTTP, 8182);component.getClients().add(Protocol.FILE);/ Create an applicationApplication application = new Application()

14、Override public Restlet createInboundRoot() return new Directory(getContext(), ROOT_URI); ;/ Attach the application to the component and start itcomponent.getDefaultHost().attach(application);component.start();為了運行這個例子，你需要指明ROOT_URI的有效值，在這里，它是被設(shè)置成file:/c:/restlet/docs/api/。注意不需要額外的配置，如果想要自定義在文件擴展和元數(shù)

15、據(jù)之間的映射，或如果想要指明一個index名，就需要使用Application的metadataservice屬性。1.5 Access logging能夠適當(dāng)?shù)赜涗沇eb應(yīng)用程序的活動是一個常見需求。Restlet Components默認(rèn)知道如何去生成類似Apache的日志，或者可以自定義。通過充分利用建立在JDK上的日志系統(tǒng)，可以像配置任意標(biāo)準(zhǔn)JDK日志一樣配置logger。為了充分配置日志，需要通過設(shè)置系統(tǒng)屬性聲明一個配置文件：System.setProperty("java.util.logging.config.file", "/your/path/l

16、ogging.config");配置文件格式請參見：1.6 Displaying error pages另外一個常見需求是自定義狀態(tài)頁。1.7 引導(dǎo)對敏感資源的訪問如果需要確保對一些Restlets的訪問 的安全，有幾個方法可用。一個通用的方法是依靠cookies來識別客戶（或客戶會話），并檢查違反應(yīng)用程序聲明的用戶ID和會話ID來決定接入是否應(yīng)該被授予。Restlets通過Request或Response中的Cookie和CookieSetting 對象來支持cookie。也有另外一種基于標(biāo)準(zhǔn)HTTP認(rèn)證機制的方法。Restlet Engine當(dāng)前接收證書并放到Basic HTTP

17、 scheme中，證書也可以被送到Amazon Web Service Scheme。當(dāng)接收到一個調(diào)用，開發(fā)者能通過ChallengeAuthenticator filter來使用在中有效且分析過的證書。Filters是一類具體的Restlets，它能在喚醒之前預(yù)處理一個調(diào)用，并附著在Restlet上，或者在附著的Restlet對調(diào)用返回之后處理調(diào)用。如果你熟悉Servlet AI，這個概念有點類似Filter接口?？匆韵碌睦樱覀?nèi)绾涡薷闹暗睦觼泶_保訪問的安全：/ Create a simple password verifierMapVerifier verifier = new M

18、apVerifier();verifier.getLocalSecrets().put("scott", "tiger".toCharArray();/ Create a GuardChallengeAuthenticator guard = new ChallengeAuthenticator( getContext(), ChallengeScheme.HTTP_BASIC, "Tutorial");guard.setVerifier(verifier);/ Create a Directory able to return a

19、deep hierarchy of filesDirectory directory = new Directory(getContext(), ROOT_URI);directory.setListingAllowed(true);guard.setNext(directory);return guard;注意認(rèn)證和授權(quán)決定可以通過繼承自Authenticator（比如ChallengeAuthenticator）和Authorizer抽象類的filters來自定義。我們在這簡單設(shè)置一個用戶和密碼。為了測試，我們需要使用客戶側(cè)Restlet API。/ Prepare the request

20、ClientResource resource = new ClientResource("http:/localhost:8182/");/ Add the client authentication to the callChallengeScheme scheme = ChallengeScheme.HTTP_BASIC;ChallengeResponse authentication = new ChallengeResponse(scheme, "scott", "tiger");resource.setChallengeR

21、esponse(authentication);/ Send the HTTP GET requestresource.get();if (resource.getStatus().isSuccess() / Output the response entity on the JVM console resource.getResponseEntity().write(System.out); else if (resource.getStatus() .equals(Status.CLIENT_ERROR_UNAUTHORIZED) / Unauthorized access System.

22、out .println("Access authorized by the server, check your credentials"); else / Unexpected status System.out.println("An unexpected status was returned: " + resource.getStatus();你能改變被測試client發(fā)送的用戶ID或密碼來檢查來自服務(wù)器的返回。記住在啟動你的client之前，先啟動之前的Restlet服務(wù)器。注意如果從另外一臺機器上測試你的服務(wù)器，你需要替換“l(fā)ocalhos

23、t”。1.8 URI重寫和重定向Restlet框架的另外一個優(yōu)勢是對cool URIs的支持。第一個有效工具是Redirector，它可以把一個cool URI重寫到另一個URI，并遵循自動化重定向。它也支持多個重定向類型，通過client/browser的外部重定向和為類似代理行為的connector重定向。在以下例子中，我們將定義一個對我們網(wǎng)站（命名為“”）的基于google的搜索服務(wù)。“/search”URI識別搜索服務(wù)，通過“kwd”參數(shù)接收一些關(guān)鍵字。/ Create a root routerRouter router = new Router(getConte

24、xt();/ Create a Redirector to Google search serviceString target = "Redirector redirector = new Redirector(getContext(), target, Redirector.MODE_CLIENT_TEMPORARY);/ While routing requests to the redirector, extract the "kwd" query/ parameter. For instance :/ http:/localhost:8182/searc

25、h?kwd=myKeyword1+myKeyword2/ will be routed to/ Extractor extractor = new Extractor(getContext(), redirector);extractor.extractQuery("keywords", "kwd", true);/ Attach the extractor to the routerrouter.attach("/search", extractor);注意Redirector只需要三個參數(shù)。第一個是parent上下文。第二個是定義

26、URI應(yīng)該如何被重寫，基于URI模版。第三個參數(shù)定義重定向類型，在這里我們選擇客戶重定向。我們也依靠Router類來從原始請求中抽取查詢參數(shù)“kwd”。如果參數(shù)被找到，它被復(fù)制進名叫“keywords”的請求屬性，并準(zhǔn)備在當(dāng)格式化它的目標(biāo)URIs時被Redirector使用。1.9 Routers和分層URIs除了重定向，我們有另外一個工具來管理cool URIs，即Routers。他們是一類具體的Restlet并且有一些其他Restlets（比如Finders和Filters）能附著在他們上面，并且能自動代表基于一個URI模版的調(diào)用。通常，你將設(shè)置一個Router作為你應(yīng)用程序的root。下

27、面我們向解釋如何處理以下URI模式：/docs/ to display static files/users/user to display a user account/users/user/orders to display the orders of a particular user/users/user/orders/order to display a specific order事實上這些URIs包含可變部分（在accolades之間），并且沒有使用在典型Web container中很難處理的文件擴展。在這里，你僅僅需要使用URI模版把目標(biāo)Restlets附著到一個Router上

28、。在運行時，最佳匹配請求URI的規(guī)則將接收調(diào)用，并能喚醒附著在它上面的Restlet。同時，請求中的屬性映射將隨著URI模版變量的值而被自動更新?？匆韵碌拇a實現(xiàn)，在真實的應(yīng)用程序中，你將可能要創(chuàng)建分離的子類來代替匿名的。/ Create a root routerRouter router = new Router(getContext();/ Attach a guard to secure access to the directoryGuard guard = new Guard(getContext(), ChallengeScheme.HTTP_BASIC, "Restl

29、et tutorial");guard.getSecrets().put("scott", "tiger".toCharArray();router.attach("/docs/", guard);/ Create a directory able to expose a hierarchy of filesDirectory directory = new Directory(getContext(), ROOT_URI);guard.setNext(directory);/ Create the account hand

30、lerRestlet account = new Restlet() Override public void handle(Request request, Response response) / Print the requested URI path String message = "Account of user "" + request.getAttributes().get("user") + """ response.setEntity(message, MediaType.TEXT_PLAIN)

31、; ;/ Create the orders handlerRestlet orders = new Restlet(getContext() Override public void handle(Request request, Response response) / Print the user name of the requested orders String message = "Orders of user "" + request.getAttributes().get("user") + """

32、; response.setEntity(message, MediaType.TEXT_PLAIN); ;/ Create the order handlerRestlet order = new Restlet(getContext() Override public void handle(Request request, Response response) / Print the user name of the requested orders String message = "Order "" + request.getAttributes().g

33、et("order") + "" for user "" + request.getAttributes().get("user") + """ response.setEntity(message, MediaType.TEXT_PLAIN); ;/ Attach the handlers to the root routerrouter.attach("/users/user", account);router.attach("/users/user/

34、orders", orders);router.attach("/users/user/orders/order", order);注意routing假設(shè)請求包含一個能識別一個目標(biāo)資源的絕對目標(biāo)URI。在請求處理期間，在routers分層中的每一層，資源的基本URI都會被更新。這解釋了為什么routers的默認(rèn)行為是只匹配剩余URI部分的開始，而不是全部。在這種情形中，你也許想要改變默認(rèn)模式，通過在Router上的“defaultMatchingMode”屬性可以很容易做到這一點，或者修改與被Router.attach()方法創(chuàng)建的route相關(guān)的模版的“matc

35、hingMode”屬性。對于這些模式，你能用Template.MODE_EQUALS或Template.MODE_STARTS_WITH常數(shù)。請注意變量的值是直接從URI中抽取，因此沒有百分百解碼，為了實現(xiàn)這個任務(wù)，看看Reference#decode(String)方法。1.10 Reaching target Resources在之前的例子中，我們充分利用框架的靈活routing特征來路由請求，同時從目標(biāo)URI中抽取感興趣的內(nèi)容。但是，我們不關(guān)心請求方法，也不關(guān)心客戶偏好，會忽略掉客戶期待的響應(yīng)設(shè)置。我們?nèi)绾芜B接我們的Restlet資源與后端系統(tǒng)呢？到目前為止，我們介紹了比傳統(tǒng)Servlet API的更好的特征?？偨Y(jié)下來，一個請求包含能識別目標(biāo)資源的URI。這個信息被存儲在Request.resourceRef屬性中，并且正如我們所看到的那樣，它作為路由的基礎(chǔ)。所以，處理請求時的第一個目標(biāo)是找到在框架中的目標(biāo)資源，這是一個ServerResource類的實例或更準(zhǔn)確的說是ServerResource類的子類的實例。為了幫助我們完成這個任務(wù)，我們能使用Finder（Restlet的子類），它從參數(shù)中獲取一個ServerResource類，并且會在有請求到達時自動實例化它。資源將動態(tài)分發(fā)調(diào)用到（1）匹配上被注解的方法（2）預(yù)定義的方法（get(