RESTful 中创建"资源"

RESTful 中所有的请求都是由资源来处理的。JAX-RS API实现的资源就是一个Java Class，这个Class被Annotated了

一个或多个Annotations; 使用JAX-RS实现的RESTful Web service是一个root resource class, 这个root resource class

 service expose后的访问的入口，该root resource class可以自己处理request,也可以由其sub-resource来处理request;

 即RESTfule 中有两种resource type: root resource class,sub-resource

 

1. Basic JAX-RS annotations

     (1) URI template syntax: URI template syntax

     (2) Specifying HTTP verbs

•      javax.ws.rs.DELETE specifies that the method maps to a DELETE.
•      javax.ws.rs.GET specifies that the method maps to a GET.
•      javax.ws.rs.POST specifies that the method maps to a POST.
•      javax.ws.rs.PUT specifies that the method maps to a PUT.
•      javax.ws.rs.HEAD specifies that the method maps to a HEAD.
  

     (3) Root resource classes

•      Class被用于Root Class需满足一下条件：
•      Class 必须被标注@Path注解；
•      Class必须有一个公共的构造函数用于运行期间调用；
•      Class中的Method至少有一个被标注HTTP verb或@Path

     例如：

package demo.hw.server;

import javax.ws.rs.DELETE;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.PUT;

import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.Response;

@Path("/customerservice/")
public class CustomerService {

	public CustomerService() {
	}

	@GET 
	public Customer getCustomer(@QueryParam("id") String id){
	}

	@DELETE
	public Response deleteCustomer(@QueryParam("id") String id){
	}

	@PUT
	public Response updateCustomer(Customer customer){
	}

	@POST
	public Response addCustomer(Customer customer){
	}

	@Path("/orders/{orderId}/") 
	public Order getOrder(@PathParam("orderId") String orderId){
	
	}
}

     (4) Resource Method

•      所有的resource method需满足一下条件：
•      必须是public;
•      必须被标准HTTP Method 注解；
•      不能有多有一个的实体参数。
  

     A. Resource Method的Paramter有两种类型：

          entity parameters;

          annotated parameters.

          例如：

@POST
@Path("disaster/monster/giant/{id}")
public void addDaikaiju(Kaiju kaiju,
@PathParam("id") String id){
}

    B. Resource Method的Return values

         void;

         any Java class for which the application has an entity provider;

         a Response object;

         a GenericEntity<T> object.

         所有的Resource Method返回一个HTTP Status Code给Request, 当返回值是void,null时，HTTP Status Code是

         200; 若返回值是除了null之外的其他值时,HTTP Status Code是204.

    (5) Sub-Resource

          有两种实现方式：

•           Sub-Resource method: 对sub-resource直接使用HTTP verb;
•           Sub-resource locator:只想一个实现了sub-resource的class.

          例如：Sub-resource methods ：标注@Path注解和HTTP verb注解，sub-resource method直接响应处理request

          中指定的HTTP verb.      

@Path("/customerservice/")
public class CustomerService {

	@Path("/orders/{orderId}/")
	@GET
	public Order getOrder(@PathParam("orderId")
	String orderId) {
	}

	@Path("/orders/{orderId}/")
	@PUT
	public Order updateOrder(@PathParam("orderId")
	String orderId, Order order) {
	}

	@Path("/orders/")
	@POST
	public Order newOrder(Order order) {
	}
}

          例如：Sub-resource locators：没有HTTP verb注解，也不直接处理request; 而是sub-resource locator返回

           一个resource class instance来处理request,同时sub-resource不能有Entity Paramters.

@Path("/customerservice/")
public class CustomerService{
	
	@Path("/orders/{orderId}/")
	public Order processOrder(@PathParam("orderId") String orderId){
	}
}

public class Order{
	
	@GET
	public Order getOrder(@PathParam("orderId") String orderId){
	
	}
	
	@PUT
	public Order updateOrder(@PathParam("orderId") String orderId,Order order){
	
	}
}

     (7) Resource selection method

     JAX-RS选择resource method 算法被分成三个阶段：

     A. Determine the root resource class;

     B. Determine the object will handle the request;

     C. Select the resource method that will handle the request.

     1. Selecting from multiple resource classes

         当有多个resource匹配reqauest URI时，resource class优先于sub-resource;当有多个resource class时按照

         下面的条件匹配：

         (1) Prefer the resource with the most literal characters in its URI template;

         (2) Prefer the resource with the most variables in its URI template

         (3) Prefer the resource with the most variables containing regular expressions.

      2.Selecting from multiple resource methods

         按照下面的条件进行匹配：

         (1) Prefer resource methods over sub-resources;

         (2) Prefer sub-resource methods over sub-resource locaters;

         (3) Prefer methods that use the most specific values in the @Consumes annotation and the @Produces

         annotation; 例如：@Consumes(text/xml) > @Consumes(text/*) > @Consumes(*/*)

         (4) Prefer methods that most closely match the content type of the request body entity; HTTP Content-Type

         property.

         (5) Prefer methods that most closely match the content type accepted as a response; HTTP Accept property.

      3.Customizing the selection process

         实现org.apache.cxf.jaxrs.ext.ResourceComparator.