Restlet实战（十八）Restlet如何产生WADL

现在究竟REST是否需要WADL这种东西，有很多争论，有人说不需要，给出的理由是，如果客户端根据WADL来编写了客户端，那将来服务改变了怎么办；有人说需要，但是基于特定的形式，比如APP。众说纷纭吧。

 

先不管了。看看Restlet里面是如何支持WADL的。Restlet里提供了一组类：WadlComponent, WadlApplication, WadlResource等，如果想了解的更多，可以到org/restlet/ext/wadl下查看。

 

转入正题，要想我们的基于Restlet的Web提供Wadl，首先需要改变Resource类，之前每个Resource类都继承于org.restlet.resource.Resource类, 现在要改为使其继承org.restlet.ext.wadl.WadlResource, 而此类中有五个新的方法describeGet, describePut, describePost, describeDelete, describeOptions对应描述GET, PUT, POST, DELETE, OPTIONS。

 

下面我们在describeGet, describePost, describeDelete添加一些描述信息:

 

    @Override
    protected void describeGet(MethodInfo info) {
        info.setIdentifier("customer");
        info.setDocumentation("To retrieve details of a specific customer");

        RepresentationInfo repInfo = new RepresentationInfo(MediaType.TEXT_XML);
        repInfo.setXmlElement("customer");
        repInfo.setDocumentation("XML representation of the current customer.");
        info.getResponse().getRepresentations().add(repInfo);

        FaultInfo faultInfo = new FaultInfo(Status.CLIENT_ERROR_NOT_FOUND,
                "customer not found");
        faultInfo.setIdentifier("customerError");
        faultInfo.setMediaType(MediaType.TEXT_HTML);
        info.getResponse().getFaults().add(faultInfo);
    }

 

    @Override
    protected void describePost(MethodInfo info) {
        info.setDocumentation("Update or create the current customer.");

        RepresentationInfo repInfo = new RepresentationInfo(
                MediaType.APPLICATION_WWW_FORM);
        ParameterInfo param = new ParameterInfo("name", ParameterStyle.PLAIN,
                "Name of the customer");
        repInfo.getParameters().add(param);
        param = new ParameterInfo("description", ParameterStyle.PLAIN,
                "Description of the customer");
        repInfo.getParameters().add(param);
        repInfo.getStatuses().add(Status.SUCCESS_OK);
        repInfo.getStatuses().add(Status.SUCCESS_CREATED);

        repInfo.setDocumentation("Web form.");
        info.getRequest().getRepresentations().add(repInfo);

    }

 

    @Override
    protected void describeDelete(MethodInfo info) {
        info.setDocumentation("Delete the current customer.");

        RepresentationInfo repInfo = new RepresentationInfo();
        repInfo.setDocumentation("No representation is returned.");
        repInfo.getStatuses().add(Status.SUCCESS_NO_CONTENT);
        info.getResponse().getRepresentations().add(repInfo);
    }

 

简要说明一下DescribeGet方法里面的设置：

info.setIdentifier("customer"); 是为Get方法在wadl里设定一个唯一id值

info.setDocumentation()是设定文档的名称（描述）

而

RepresentationInfo repInfo = new RepresentationInfo(MediaType.TEXT_XML);
        repInfo.setXmlElement("customer");
        repInfo.setDocumentation("XML representation of the current customer.");
        info.getResponse().getRepresentations().add(repInfo);

 是设定表述的相关内容，如返回的表述的类型是基于XML的形式。

 

另外可以定义出错信息，通过FaultInfo：

FaultInfo faultInfo = new FaultInfo(Status.CLIENT_ERROR_NOT_FOUND,
                "Customer not found");
        faultInfo.setIdentifier("customerError");
        faultInfo.setMediaType(MediaType.TEXT_HTML);
        info.getResponse().getFaults().add(faultInfo);

 

接下来，测试一下上述代码，看看最终的Wadl是什么样子：

 

首先启动服务，然后编写客户端如下：

 

        Reference appUri = new Reference("http://localhost:8080/restlet/resources/customers/1");
        // The URI of the resource "list of items".
        Reference itemsUri = new Reference(appUri, "items");

        Client client = new Client(Protocol.HTTP);

        // Displays the WADL documentation of the application
        client.options(appUri).getEntity().write(System.out);

 

如果所有的代码没有问题，则会有Wadl内容输出：

 

<?xml version="1.0" standalone="yes"?>
<?xml-stylesheet type="text/xsl" href="wadl_documentation.xsl"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
   <resources>
      <resource path="/customers/1">
         <method name="DELETE">
            <doc>Delete the current customer.</doc>
            <request/>
            <response>
               <representation status="204">
                  <doc>No representation is returned.</doc>
               </representation>
            </response>
         </method>
         <method id="customer" name="GET">
            <doc>To retrieve details of a specific customer</doc>
            <request/>
            <response>
               <representation mediaType="text/xml" element="customer">
                  <doc>XML representation of the current customer.</doc>
               </representation>
               <fault id="customerError" mediaType="text/html" status="404">
                  <doc>customer not found</doc>
               </fault>
            </response>
         </method>
         <method name="POST">
            <doc>Update or create the current customer.</doc>
            <request>
               <representation mediaType="application/x-www-form-urlencoded" status="200 201">
                  <doc>Web form.</doc>
                  <param style="plain" name="name">
                     <doc>Name of the customer</doc>
                  </param>
                  <param style="plain" name="description">
                     <doc>Description of the customer</doc>
                  </param>
               </representation>
            </request>
            <response/></method>
      </resource>
   </resources>
</application>

 

对照这个输出，然后回头看看我们在CustomerResource里面的描述设定，是不是清楚了很多。

 

一个在线的分析和描述Wadl的工具网站：http://tomayac.de/rest-describe/latest/RestDescribe.html