JAX-RS入門 八： HTTP響應

 

首先先看一下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.