JAX-RS入门 三 :细节
2016-06-30 17:28
267 查看
转自:http://liugang594.iteye.com/blog/1495634
一、若希望一个Java类能够处理REST请求,则这个类必须至少添加一个@Path("/")的annotation;对于方法,这个annotation是可选的,如果不添加,则继承类的定义。
二、一个方法上只有添加了某个Http Method的annotation,例如@GET,才有资格处理请求。
三、@Path里的值可以是一个复杂的表达式,例如@Path("{id}") ,其中 {id}表达式代码了一个模板参数;一个模板参数是一个定义在@Path里的通配符,它以 { 开始,中间是一堆字母和数字的混合串(不能包含 / 字符),以} 结尾。又如: @Path("{firstName}-{lastName}") .
四、@Path也支持正则表达式,例如: @Path("{id: \\d+}") ,其中 \\d+ 表示一个数字。格式为: A : B
五、可以自定http method的annotation,具体参考已经有的实现,例如@GET的实现:
Java代码
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod(HttpMethod.GET)
public @interface GET {
}
其中HttpMethod的实现为:
Java代码
@Target({ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface HttpMethod {
/**
* HTTP GET method
*/
public static final String GET="GET";
/**
* HTTP POST method
*/
public static final String POST="POST";
/**
* HTTP PUT method
*/
public static final String PUT="PUT";
/**
* HTTP DELETE method
*/
public static final String DELETE="DELETE";
/**
* HTTP HEAD method
*/
public static final String HEAD="HEAD";
/**
* HTTP OPTIONS method
*/
public static final String OPTIONS="OPTIONS";
/**
* Specifies the name of a HTTP method. E.g. "GET".
*/
String value();
}
因此,可以如下自定义新的http 请求方法:
Java代码
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {
}
注:请不要试图重写HttpMethod annotation。
六、Path的优先级规则
首先检查匹配的字符的个数,匹配的个数越多越优先
其次检查内嵌的模板表达式的个数,个数越多越优先
最后是非缺省模板表达式的个数;缺省模板即未定义正则表达式的模板
例如以下顺利:
Java代码
1 /customers/{id}/{name}/address
2 /customers/{id : .+}/address
3 /customers/{id}/address
4 /customers/{id : .+}
如果以上匹配不能解决你的问题,那多半是因为你的设计过于复杂,需要重新审视。
七、允许、保留和需要转意的字符
所以有 a-z、A-Z、0-9 都被允许
所有: _-!.~'()* 都被允许
所有: ,;:$&+=?/[]@ 都是保留字符 (需要转意)
所有其他字符需要用 % 进行转意;格式为 %HH (%加两个十六进制数)
注:如果Path中uri的表达式包含有需要转意的字符,JAX-RS会自动进行转意;否则会视之为已经进行了URL的encoding。
八、Matrix Param
Matrix Param是一个嵌在URI字符串中的name-value对,例如:
http://example.cars.com/mercedes/e55;color=black/2006
Matrix Param用于修饰特定的片段,如上修饰e55片段;不同于Query Param,用于修饰整个URI资源。
Matrix Param不出现在@Path的表达式中,例如以上URI对应的@Path的表达式可能是:@Path("/e55/{year}")。
但是可以用@MatrixParam annotation来取得Matrix Param的值,例如:@MatrixParam("color")
九、Subresource Locators
Subresources Locators是指一个指定了@Path annotation,但未指定HttpMethod的annotation,例如@GET,的Java方法。这个方法返回一个含有JAX-RS annotation的REST Service对象,这个对象知道怎么去分发剩余的请求。
例如:
Java代码
@Path("/customers")
public class CustomerDatabaseResource {
@Path("{database}-db")
public CustomerResource getDatabase(@PathParam("database") String db) {
// find the instance based on the db parameter
CustomerResource resource = locateCustomerResource(db);
return resource;
}
protected CustomerResource locateCustomerResource(String db) {
...
}
}
其中CustomerResource可能是:
Java代码
public class CustomerResource {
private Map<Integer, Customer> customerDB =
new ConcurrentHashMap<Integer, Customer>();
private AtomicInteger idCounter = new AtomicInteger();
@POST
@Consumes("application/xml")
public Response createCustomer(InputStream is) {
...
}
@GET
@Path("{id}")
@Produces("application/xml")
public StreamingOutput getCustomer(@PathParam("id") int id) {
...
}
@PUT
@Path("{id}")
@Consumes("application/xml")
public void updateCustomer(@PathParam("id") int id, InputStream is) {
...
}
}
因为CustomerResource 并不打算做一个Service暴露,所以在类上没有添加@Path的annotation。
十、完全动态分发
所谓完全分发,就是实现类可以是任意类,例如上面的CustomerDatabaseResource的getDatabase()方法的实现可以改为:
Java代码
@Path("/customers")
public class CustomerDatabaseResource {
protected CustomerResource europe = new CustomerResource();
protected FirstLastCustomerResource northamerica =
new FirstLastCustomerResource();
@Path("{database}-db")
public Object getDatabase(@PathParam("database") String db) {
if (db.equals("europe")) {
return europe;
}
else if (db.equals("northamerica")) {
return northamerica;
}
else return null;
}
}
这里返回值是一个Object,已经不再局限于CustomerResource类了。JAX-RS会检查这个实例,以决定怎么分发请求。
一、若希望一个Java类能够处理REST请求,则这个类必须至少添加一个@Path("/")的annotation;对于方法,这个annotation是可选的,如果不添加,则继承类的定义。
二、一个方法上只有添加了某个Http Method的annotation,例如@GET,才有资格处理请求。
三、@Path里的值可以是一个复杂的表达式,例如@Path("{id}") ,其中 {id}表达式代码了一个模板参数;一个模板参数是一个定义在@Path里的通配符,它以 { 开始,中间是一堆字母和数字的混合串(不能包含 / 字符),以} 结尾。又如: @Path("{firstName}-{lastName}") .
四、@Path也支持正则表达式,例如: @Path("{id: \\d+}") ,其中 \\d+ 表示一个数字。格式为: A : B
五、可以自定http method的annotation,具体参考已经有的实现,例如@GET的实现:
Java代码
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod(HttpMethod.GET)
public @interface GET {
}
其中HttpMethod的实现为:
Java代码
@Target({ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface HttpMethod {
/**
* HTTP GET method
*/
public static final String GET="GET";
/**
* HTTP POST method
*/
public static final String POST="POST";
/**
* HTTP PUT method
*/
public static final String PUT="PUT";
/**
* HTTP DELETE method
*/
public static final String DELETE="DELETE";
/**
* HTTP HEAD method
*/
public static final String HEAD="HEAD";
/**
* HTTP OPTIONS method
*/
public static final String OPTIONS="OPTIONS";
/**
* Specifies the name of a HTTP method. E.g. "GET".
*/
String value();
}
因此,可以如下自定义新的http 请求方法:
Java代码
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {
}
注:请不要试图重写HttpMethod annotation。
六、Path的优先级规则
首先检查匹配的字符的个数,匹配的个数越多越优先
其次检查内嵌的模板表达式的个数,个数越多越优先
最后是非缺省模板表达式的个数;缺省模板即未定义正则表达式的模板
例如以下顺利:
Java代码
1 /customers/{id}/{name}/address
2 /customers/{id : .+}/address
3 /customers/{id}/address
4 /customers/{id : .+}
如果以上匹配不能解决你的问题,那多半是因为你的设计过于复杂,需要重新审视。
七、允许、保留和需要转意的字符
所以有 a-z、A-Z、0-9 都被允许
所有: _-!.~'()* 都被允许
所有: ,;:$&+=?/[]@ 都是保留字符 (需要转意)
所有其他字符需要用 % 进行转意;格式为 %HH (%加两个十六进制数)
注:如果Path中uri的表达式包含有需要转意的字符,JAX-RS会自动进行转意;否则会视之为已经进行了URL的encoding。
八、Matrix Param
Matrix Param是一个嵌在URI字符串中的name-value对,例如:
http://example.cars.com/mercedes/e55;color=black/2006
Matrix Param用于修饰特定的片段,如上修饰e55片段;不同于Query Param,用于修饰整个URI资源。
Matrix Param不出现在@Path的表达式中,例如以上URI对应的@Path的表达式可能是:@Path("/e55/{year}")。
但是可以用@MatrixParam annotation来取得Matrix Param的值,例如:@MatrixParam("color")
九、Subresource Locators
Subresources Locators是指一个指定了@Path annotation,但未指定HttpMethod的annotation,例如@GET,的Java方法。这个方法返回一个含有JAX-RS annotation的REST Service对象,这个对象知道怎么去分发剩余的请求。
例如:
Java代码
@Path("/customers")
public class CustomerDatabaseResource {
@Path("{database}-db")
public CustomerResource getDatabase(@PathParam("database") String db) {
// find the instance based on the db parameter
CustomerResource resource = locateCustomerResource(db);
return resource;
}
protected CustomerResource locateCustomerResource(String db) {
...
}
}
其中CustomerResource可能是:
Java代码
public class CustomerResource {
private Map<Integer, Customer> customerDB =
new ConcurrentHashMap<Integer, Customer>();
private AtomicInteger idCounter = new AtomicInteger();
@POST
@Consumes("application/xml")
public Response createCustomer(InputStream is) {
...
}
@GET
@Path("{id}")
@Produces("application/xml")
public StreamingOutput getCustomer(@PathParam("id") int id) {
...
}
@PUT
@Path("{id}")
@Consumes("application/xml")
public void updateCustomer(@PathParam("id") int id, InputStream is) {
...
}
}
因为CustomerResource 并不打算做一个Service暴露,所以在类上没有添加@Path的annotation。
十、完全动态分发
所谓完全分发,就是实现类可以是任意类,例如上面的CustomerDatabaseResource的getDatabase()方法的实现可以改为:
Java代码
@Path("/customers")
public class CustomerDatabaseResource {
protected CustomerResource europe = new CustomerResource();
protected FirstLastCustomerResource northamerica =
new FirstLastCustomerResource();
@Path("{database}-db")
public Object getDatabase(@PathParam("database") String db) {
if (db.equals("europe")) {
return europe;
}
else if (db.equals("northamerica")) {
return northamerica;
}
else return null;
}
}
这里返回值是一个Object,已经不再局限于CustomerResource类了。JAX-RS会检查这个实例,以决定怎么分发请求。
相关文章推荐
- 深入分析 Java 中的中文编码问题
- HttpClient在HTTP协议接口测试中的使用
- oracle扩展表空间以及清空临时表
- Word神操作,不只是快捷键
- srs之时间戳矫正算法(混合单增算法,mix_correct to ensure timestamp monotonically increase)
- Scala:日期和时间
- Presentation与自定义Dialog的使用
- Linux SSH远程文件/目录传输命令scp
- 实例指导你 利用控制台(cmd) 完成github中项目管理
- 如何运行NodeJS程序
- ROS中订阅两个消息,发布一个数据。
- 二叉树的下一个节点(中序)
- 解决Andriod全屏时软键盘出现不能把原来的布局给顶上去的方法
- JAX-RS入门 二 :运行
- 深入浅出 - Android系统移植与平台开发(五)- 编译Android源码
- Hive知识点笔记-影印版
- 爬虫技术(2)--抓取网页java代码实现
- Unity3D异步加载游戏场景
- 【那些年遇到过的面试题】traceroute和tracert有什么区别
- CentOS7配置samba共享服务