欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

Restlet实战(十八)Restlet如何产生WADL

程序员文章站 2022-07-03 20:52:54
...

现在究竟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