📄 index.xtp
字号:
<document> <header> <product>resin</product> <title>Accessing External REST Services with Resin</title> <description> <p> Resin offers simplified access to external REST-based services. This example shows how to access a subset of the flickr<sup><small>TM</small></sup> API. </p> </description> <type>tutorial</type><!-- <tutorial-startpage>demo.jsp</tutorial-startpage>--> </header> <body> <localtoc/><s1><p>Resin's Service-Oriented Architecture (SOA) allows not only easier deploymentof web services via SOAP, REST, and Hessian, but also simplified client access to external services. Traditionally, using REST services as a client requireddevelopers to write potentially complex libraries. URL construction and parsing returned XML data can often be clumsy and time-consuming to do manually.</p><p>Resin's SOA and JAXB simplify these tasks. This tutorial shows an example fora subset of the flickr<sup><small>TM</small></sup> API.</p></s1><s1 title="Files in this tutorial"><deftable><tr><td><viewfile-link file="WEB-INF/classes/example/FlickrAPI.java"/> </td><td>Interface for the hello service.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/FlickrImpl.java"/> </td><td>The main service implementation.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrResponse.java"/> </td><td>The response object that wraps specialized responses.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrPayload.java"/> </td><td>The payload of a response.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrError.java"/> </td><td>An error payload.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrGroups.java"/> </td><td>A payload of group information.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrPerson.java"/> </td><td>A payload of profile information.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrPhotos.java"/> </td><td>A payload of photo information.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/FlickrUser.java"/> </td><td>A payload of user information.</td></tr><tr><td><viewfile-link file="WEB-INF/classes/example/data/jaxb.index"/> </td><td>Lists the classes to be used by JAXB </td></tr><tr><td><viewfile-link file="WEB-INF/resin-web.xml"/> </td><td>Configures the environment</td></tr><tr><td><viewfile-link file="demo.jsp"/> </td><td>Client JSP</td></tr></deftable></s1><s1 title="Writing a REST Client"><p>Many companies now offer web services externally to be used as componentsin third-party applications. These services often have REST, SOAP, and/orXML-RPC interfaces. SOAP and XML-RPC are standards and have somewhat well-defined access methods for clients. REST on the other hand is aboutbeing able to use the properties of HTTP to design a custom interface. Thusclients are often difficult to write because each service requires specialization. Unlike the case of SOAP where WSDLs allow automated construction of client stubs, REST-based services essentially defy standardization. While Resin's SOA does not offer automated client construction, it does make the task easier. </p><p>The example in this tutorial shows how to access a subset of theflickr<sup><small>TM</small></sup> image sharing service API. This API iswell-designed and consistent which allows very clean client construction.</p></s1><s1 title="REST Client Architecture"><p></p><figure src="rest-client.png"/><p>The REST client architecture in Resin can be thought of as a stack. At thetop of the stack is the client, which calls methods on a proxy. That proxythen constructs the calls to the external REST service. Complex objects thatare sent to the service use JAXB to marshal from Java objects to XML. Therequest is then processed by the service and a response is sent. The responseis unmarshalled from XML to Java using JAXB and returned to the client bythe proxy.</p></s1><s1 title="REST Bindings"><p>A REST interface can be thought of as a binding between an HTTP requestand a method invocation. All the portions of the HTTP request (the pathinformation, the query, headers, and POSTed data) can be used to constructthe method call.</p><p>In the case of the flickr<sup><small>TM</small></sup> API, the method binding is straightforward and uses the query data almost exclusively. For example, there is a method, <code>flickr.people.findByUsername</code>, that takes two arguments, an <code>api_key</code> and a <code>username</code>. The<code>api_key</code> allows flickr<sup><small>TM</small></sup> to track and manage usage while the <code>username</code> is used to find a user's id.The method name and these two arguments are used to construct a URL to perform the REST operation: <url>http://api.flickr.com/services/rest/?method=flickr.people.findByUsername&api_key=XXX&username=foo</url>. </p><p>The data returned by the service uses a simple XML format. In this case,the service might return the following:</p><example><?xml version="1.0" encoding="utf-8" ?><rsp stat="ok"> <user nsid="12345678901@N01"> <username>foo</username> </user></rsp></example><p>The next section shows how to construct a Java client interface to construct these URLs and decode the responses.</p></s1><s1 title="Annotated Client Interface"><p>An annotated Java class or interface is used to access a REST service as a client. In this example, only JAX-WS annotations are used, so thosedevelopers already familiar with JAX-WS can leverage their experience toconstruct certain types of REST interfaces.</p><example title="FlickrAPI.java">package example;import javax.jws.*;import example.data.*;public interface FlickrAPI{ @WebMethod(operationName="flickr.people.findByEmail") public FlickrResponse findByEmail(@WebParam(name="api_key") String api_key, @WebParam(name="find_email") String find_email); @WebMethod(operationName="flickr.people.findByUsername") public FlickrResponse findByUsername(@WebParam(name="api_key") String api_key, @WebParam(name="username") String username); @WebMethod(operationName="flickr.people.getInfo") public FlickrResponse getInfo(@WebParam(name="api_key") String api_key, @WebParam(name="user_id") String user_id); @WebMethod(operationName="flickr.people.getPublicGroups") public FlickrResponse getPublicGroups(@WebParam(name="api_key") String api_key, @WebParam(name="user_id") String user_id); @WebMethod(operationName="flickr.people.getPublicPhotos") public FlickrResponse getPublicPhotos(@WebParam(name="api_key") String api_key, @WebParam(name="user_id") String user_id, @WebParam(name="extras") String extras, @WebParam(name="per_page") int per_page, @WebParam(name="page") int page);}</example><p>In this interface, there are five methods, each annotated with @WebMethod.The <code>operationName</code> field is overloaded here to give the RESTmethod name. The method parameters are all annotated with @WebParam. The<code>name</code> field gives a key name for the argument. Resin uses thisinterface to construct URLs sent to a service. By default, the method nameis sent in the query using "method" as the key. This is customizable usingthe annotations @RestMethod and @RestService, but for this example, nocustomization is needed.</p><p>When a client calls one of the methods in the interface above, Resinautomatically constructs a URL, makes the request, and decodes the response.Notice that the return value of all the methods above is FlickrResponse.This class is a JAXB-annotated class that wraps all the responses sent fromthe service. The next section shows how to construct the JAXB-annotatedclasses for easy access to response data.</p></s1><s1 title="JAXB-Annotated Response Classes"><p>Even though flickr<sup><small>TM</small></sup> uses a custom XML formatfor responses, it is easy to construct simple JAXB-annotated classes forthese responses, even without schema! First notice that the responses allhave a wrapper element, <code><rsp></code>. This wrapper is representedby a FlickrResponse object in this example.</p><example title="FlickrResponse.java">package example.data;import javax.xml.bind.annotation.*;@XmlRootElement(name="rsp")⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -