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