首先先看一下HTTP中定义的响应码及其意义:
响应码
|
含义
|
100
|
继续
|
101
|
分组交换协议
|
200
|
OK
|
201
|
被创建
|
202
|
被采纳
|
203
|
非授权信息
|
204
|
无内容
|
205
|
重置内容
|
206
|
部分内容
|
300
|
多选项
|
301
|
永久地传递
|
302
|
找到
|
303
|
参见其他
|
304
|
未改动
|
305
|
使用代理
|
307
|
暂时重定向
|
400
|
错误请求
|
401
|
未授权
|
402
|
要求付费
|
403
|
禁止
|
404
|
未找到
|
405
|
不允许的方法
|
406
|
不被采纳
|
407
|
要求代理授权
|
408
|
请求超时
|
409
|
冲突
|
410
|
过期的
|
411
|
要求的长度
|
412
|
前提不成立
|
413
|
请求实例太大
|
414
|
请求URL太大
|
415
|
不支持的媒体类型
|
416
|
无法满足的请求范围
|
417
|
失败的预期
|
500
|
内部错误
|
501
|
未被使用
|
502
|
网关错误
|
503
|
不可用的服务
|
504
|
网关超时
|
505
|
HTTP版本未被支持
|
一、成功
从 200 到 399 为成功码,表示请求处理成功。
如果方法返回值不为null,则返回码是 200;如果返回值为 null 或者为 void,则返回码为 204,表示无内容。
二、错误
从 400 到 599 表示处理错误。
例如 404表示网页未找着;如果请求的期望的返回交换类型不对,则返回 406,表示不可接爱;如果请求的方法未找着,则返回 405,表示方法不允许,这个返回结果对于HEAD和OPTIONS请求方法例外,对于HEAD会试图去查找能处理相同URI的GET方法;对于OPTION,会返回一些自动生成的信息。
三、复杂的响应
对于不能简单处理的返回信息,则可以返回javax.ws.rs.core.Response对象:
public abstract class Response {
public abstract Object getEntity();
public abstract int getStatus();
public abstract MultivaluedMap<String, Object> getMetadata();
...
}
Response对象不能直接创建,需要通过javax.ws.rs.core.Response.ResponseBuilder来创建:
public abstract class Response {
...
public static ResponseBuilder status(Status status) {...}
public static ResponseBuilder status(int status) {...}
public static ResponseBuilder ok() {...}
public static ResponseBuilder ok(Object entity) {...}
public static ResponseBuilder ok(Object entity, MediaType type) {...}
public static ResponseBuilder ok(Object entity, String type) {...}
public static ResponseBuilder ok(Object entity, Variant var) {...}
public static ResponseBuilder serverError() {...}
public static ResponseBuilder created(URI location) {...}
public static ResponseBuilder noContent() {...}
public static ResponseBuilder notModified() {...}
public static ResponseBuilder notModified(EntityTag tag) {...}
public static ResponseBuilder notModified(String tag) {...}
public static ResponseBuilder seeOther(URI location) {...}
public static ResponseBuilder temporaryRedirect(URI location) {...}
public static ResponseBuilder notAcceptable(List<Variant> variants) {...}
public static ResponseBuilder fromResponse(Response response) {...}
...
}
ResponseBuilder是一个用来创建单个Response实例的工厂类, 首先将要创建的response对象的状态存起来,最后当状态设置完成了,就使用builder去初始化Response:
public static abstract class ResponseBuilder {
public abstract Response build();
public abstract ResponseBuilder clone();
public abstract ResponseBuilder status(int status);
public ResponseBuilder status(Status status) {...}
public abstract ResponseBuilder entity(Object entity);
public abstract ResponseBuilder type(MediaType type);
public abstract ResponseBuilder type(String type);
public abstract ResponseBuilder variant(Variant variant);
public abstract ResponseBuilder variants(List<Variant> variants);
public abstract ResponseBuilder language(String language);
public abstract ResponseBuilder language(Locale language);
public abstract ResponseBuilder location(URI location);
public abstract ResponseBuilder contentLocation(URI location);
public abstract ResponseBuilder tag(EntityTag tag);
public abstract ResponseBuilder tag(String tag);
public abstract ResponseBuilder lastModified(Date lastModified);
public abstract ResponseBuilder cacheControl(CacheControl cacheControl);
public abstract ResponseBuilder expires(Date expires);
public abstract ResponseBuilder header(String name, Object value);
public abstract ResponseBuilder cookie(NewCookie... cookies);
}
例如:
@Path("/textbook")
public class TextBookService {
@GET
@Path("/restfuljava")
@Produces("text/plain")
public Response getBook() {
String book = ...;
ResponseBuilder builder = Response.ok(book);
builder.language("fr").header("Some-Header", "some value");
return builder.build();
}
}
四、Cookie
JAX-RS使用了一个简单的类去表示一个cookie值,它就是javax.ws.rs.core.NewCookie:
public class NewCookie extends Cookie {
public static final int DEFAULT_MAX_AGE = −1;
public NewCookie(String name, String value) {}
public NewCookie(String name, String value, String path,
String domain, String comment,
int maxAge, boolean secure) {}
public NewCookie(String name, String value, String path,
String domain, int version, String comment,
int maxAge, boolean secure) {}
public NewCookie(Cookie cookie) {}
public NewCookie(Cookie cookie, String comment,
int maxAge, boolean secure) {}
public static NewCookie valueOf(String value)
throws IllegalArgumentException {}
public String getComment() {}
public int getMaxAge() {}
public boolean isSecure() {}
public Cookie toCookie() {}
}
要返回Cookie,只需要传入它到Response中:
@GET
public Response get() {
NewCookie cookie = new NewCookie("key", "value);
ResponseBuilder builder = Response.ok("hello", "text/plain");
return builder.cookies(cookie).build();
}
五、状态类别
除了直接写数据外,JAX-RS定义了一个状态值的枚举类别:
public enum Status {
OK(200, "OK"),
CREATED(201, "Created"),
ACCEPTED(202, "Accepted"),
NO_CONTENT(204, "No Content"),
MOVED_PERMANENTLY(301, "Moved Permanently"),
SEE_OTHER(303, "See Other"),
NOT_MODIFIED(304, "Not Modified"),
TEMPORARY_REDIRECT(307, "Temporary Redirect"),
BAD_REQUEST(400, "Bad Request"),
UNAUTHORIZED(401, "Unauthorized"),
FORBIDDEN(403, "Forbidden"),
NOT_FOUND(404, "Not Found"),
NOT_ACCEPTABLE(406, "Not Acceptable"),
CONFLICT(409, "Conflict"),
GONE(410, "Gone"),
PRECONDITION_FAILED(412, "Precondition Failed"),
UNSUPPORTED_MEDIA_TYPE(415, "Unsupported Media Type"),
INTERNAL_SERVER_ERROR(500, "Internal Server Error"),
SERVICE_UNAVAILABLE(503, "Service Unavailable");
public enum Family {
INFORMATIONAL, SUCCESSFUL, REDIRECTION,
CLIENT_ERROR, SERVER_ERROR, OTHER
}
public Family getFamily()
public int getStatusCode()
public static Status fromStatusCode(final int statusCode)
}
每个Status的值都关联的到一个特定HTTP的返回值族,这个族由Status.Family标识。例如 100范围的值被认识是信息性的;200范围的是成功;300范围的也是成功,但是被重定向的;400是client错误;500是服务器错误。
Response.status()和ResponseBuilder.status()都接受一个Status值,例如:
@DELETE
Response delete() {
...
return Response.status(Status.GONE).build();
}
六、javax.ws.rs.core.GenericEntity
当处理Response的返回对象(entity)时,如果是一个类似于MessageBodyWriter这样的支持泛型的对象,则问题来了: isWriteable()方法需要有泛弄的信息。然后不幸的是java的泛型信息只存在编译时,不存在运行时,因此没有一个简单的方法可以得到在运行时得到泛型的信息,因此MessageBodyWriter不知道如何输出对象。
为了解决这个问题,JAX-RS提供了一个帮助类 javax.ws.rs.core.GenericEntity 。例如:
@GET
@Produces("application/xml")
public Response getCustomerList() {
List<Customer> list = new ArrayList<Customer>();
list.add(new Customer(...));
GenericEntity entity = new GenericEntity<List<Customer>>(list){};
return Response.ok(entity);
}
GenericEntity也是一个泛型模板,只需要将输出entity的泛型信息加到它上,并且把对象做为一个参数传入即可。
七、javax.ws.rs.WebApplicationException
WebApplicationException是一个内置、非检测异常,支持传入Response对象或者状态码:
public class WebApplicationException extends RuntimeException {
public WebApplicationException() {...}
public WebApplicationException(Response response) {...}
public WebApplicationException(int status) {...}
public WebApplicationException(Response.Status status) {...}
public WebApplicationException(Throwable cause) {...}
public WebApplicationException(Throwable cause,
Response response) {...}
public WebApplicationException(Throwable cause, int status) {...}
public WebApplicationException(Throwable cause,
Response.Status status) {...}
public Response getResponse() {...]
}
当JAX-RS碰到一个WebApplicationException抛出时,它就捕获这个异常,调用它的getResponse()方法去获取Response,发回给client端。 如果应用以一个状态码或者Response初始化了WebApplicationException,则这个状态码或者Response将被用来创建真正的HTTP响应;或者,会直接返回 500, “Internal Server Error“给客户端,例如:
@Path("/customers")
public class CustomerResource {
@GET
@Path("{id}")
@Produces("application/xml")
public Customer getCustomer(@PathParam("id") int id) {
Customer cust = findCustomer(id);
if (cust == null) {
throw new WebApplicationException(Response.Status.NOT_FOUND);
}
return cust;
}
}
这里如果没找着客户,会返回404错误
八、错误匹配
应用中可能有各种各样的,来自应用或者第三方包的异常,如果仅依赖于容器提供的错误处理方式,则可能灵活度不够: 捕获这些异常,然后包装到WebApplicationException中会让人觉得相当乏味。
这里的另外一种选择就是使用javax.ws.rs.ext.ExceptionMapper,这个对象知道怎么匹配一个抛出的异常到一个Repsonse对象上:
public interface ExceptionMapper<E extends Throwable> {
Response toResponse(E exception);
}
例如对于JPA有EntityNotFoundException:
@Provider
public class EntityNotFoundMapper
implements ExceptionMapper<EntityNotFoundException> {
public Response toResponse(EntityNotFoundException e) {
return Response.status(Response.Status.NOT_FOUND).build();
}
}
注: ExceptionMapper的实现,必须加上@Provider注释
ExceptionMapper也支持异常层级关系,例如A 继承 B,如果找不到A的mapper,则会向上查找B的mapper。
最后ExceptionMapper使用JAX-RS的deployment API进行注册,可以用Application.