RESTful 中创建"资源"

83467014

2012-07-26

关注关注

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