Restful Web services（jax-Rs）

What Are RESTful Web Services?
RESTful web services are services that are built to work best on the web. Representational State Transfer (REST) is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such as performance, scalability, and modifiability, that enable services to work best on the Web. In the REST architectural style, data and functionality are considered resources, and these resources are accessed using Uniform Resource Identifiers (URIs), typically links on the web. The resources are acted upon by using a set of simple, well-defined operations. The REST architectural style constrains an architecture to a client-server architecture, and is designed to use a stateless communication protocol, typically HTTP. In the REST architecture style, clients and servers exchange representations of resources using a standardized interface and protocol. These principles encourages RESTful applications to be simple, lightweight, and have high performance.
RESTful web services typically map the four main HTTP methods to the operations they perform : create, retrieve, update, and delete. The following table shows a mapping of HTTP methods to the operations they perform.

1、什么是Restful Web services（jax-Rs）？

Restful Web services是为网络交互的提供很好的方式。Representational State Transfer (表现状态转移)REST
是一种架构风格，指定了统一的接口和约束，为高性能，高可伸缩性和可变性的web服务提供很好的 实现支持。 
在这种架构风格中，数据和功能被认为是一种资源，可以通过统一的资源标识去访问，典型的标识如web上的链接等。
我们可以通过一系列定义好的简单的操作。
这种架构风格被设计为用无状态链接协议（如HTTP）交互的客户-服务端的架构风格，在此之下，客户端与服务端的资源的
交互使用统一的接口和协议。这些特点保证了Restful 应用程序的简单、轻量及高性能。

The following principles encourage RESTful applications to be simple, lightweight, and fast:
■ Resource identification through URI: A RESTful web service exposes a set of resources
that identify the targets of the interaction with its clients. Resources are identified by URIs,
which provide a global addressing space for resource and service discovery. See “The @Path
Annotation and URI Path Templates” on page 357 for more information.
■ Uniform interface: Resources are manipulated using a fixed set of four create, read, update,
delete operations: PUT, GET, POST, and DELETE. PUT creates a new resource, which can be then
deleted by using DELETE. GET retrieves the current state of a resource in some representation.
POST transfers a new state onto a resource. See “Responding to HTTP Resources” on
page 359 for more information.
■ Self-descriptive messages: Resources are decoupled from their representation so that their
content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG,
JSON, and others.Metadata about the resource is available and used, for example, to control
caching, detect transmission errors, negotiate the appropriate representation format, and
perform authentication or access control. See “Responding to HTTP Resources” on page 359
and “Using Entity Providers toMap HTTP Response and Request Entity Bodies” on
page 361 for more information.
■ Stateful interactions through hyperlinks: Every interaction with a resource is stateless; that
is, request messages are self-contained. Stateful interactions are based on the concept of
explicit state transfer. Several techniques exist to exchange state, such as URI rewriting,
cookies, and hidden form fields. State can be embedded in response messages to point to
valid future states of the interaction. See “Using Entity Providers toMap HTTP Response
and Request Entity Bodies” on page 361 and “Building URIs” in the JAX-RSOverview
document for more information.

Restful服务的操作接口映射主要的Http方法：create, retrieve, update, and delete，下表指出了对应的Http方法的主要含义：
HTTP Method   Operations Performed 


GET                        Get a resource 


POST                     Create a resource and other operations, as it has no defined semantics 


PUT                        Create or update a resource 


DELETE                Delete a resource 

2. How Does Jersey Fit in?
Jersey是sun公司的一个产品它很好地实现了Jax-ws。（The Java API for RESTful Web Services）.
Jersey实现了所有的在JSR-311中的注释，使得开发者使用java及jvm很容易地可以构建Restful web服务。
Jersey还实现一些没有在JSR-311中提到的其他的附加功能。
最新版本的JAX—RS API:https://jsr311.dev.java.net/nonav/javadoc/index.html

3、Demo

HelloWorld.java


import javax.ws.rs.core.Context;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.PathParam;
import javax.ws.rs.Consumes;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;


/**
 * REST Web Service
 *
 * @author zhang
 */
@Path("helloWorld")
public class HelloWorld {


    @Context
    private UriInfo context;


    /** Creates a new instance of HelloWorld */
    public HelloWorld() {
    }


    /**
     * Retrieves representation of an instance of helloWorld.HelloWorld
     * @return an instance of java.lang.String
     */
    @GET
    @Produces("text/plain")
    public String getXml() {
        //TODO return proper representation object
        return "Hello China World";
       // throw new UnsupportedOperationException();
    }


    /**
     * PUT method for updating or creating an instance of HelloWorld
     * @param content representation for the resource
     * @return an HTTP response with content of the updated or created resource.
     */
    @PUT
    @Consumes("text/plain")
    public void putXml(String content) {
        System.out.println(content);
    }
}
web.xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
             <servlet>
        <servlet-name>ServletAdaptor</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>ServletAdaptor</servlet-name>
        <url-pattern>/resources/*</url-pattern>
    </servlet-mapping>
    <session-config>
    <session-timeout>
            30
    </session-timeout>
    </session-config>
</web-app>
测试地址：http://localhost:8080/HelloWebApplication/resources/helloWorld