返回信息给Consumer

return four types of Java constructs:

• common Java types return basic information with HTTP return codes determined by the JAX-RS runtime;
• JAXB objects return complex information with HTTP return codes determined by the JAX-RS runtime;
• JAX-RS Response objects return complex information with a programmatically determined HTTP return  status.    The Response object also allows HTTP headers to be specified;
• JAX-RS GenericEntity objects return complex information with HTTP return codes determined by the JAX-RS runtime. The GenericEnitity object provides more information to the runtime components serializing the data.

1. Returning plain Java constructs

     通常情况下，resource class返回一个标准的Java Type, 一个JAXB对象，或者任何的对象(应用程序有对应的Entity

     Provider)；在这种情况下，运行环境将使用返回的对象来决定MIME type信息，运行环境也决定使用适合的HTTP

     Code发送给Consumer.

     (1) Returnable types: 可以是null或者是：Java 原生类型，Java原生类型的Numbet representations， JAXBObject.

     (2) MIME types: 运行环境决定返回Entiy 的MIME type首先检查resource method 和 resource class的@Produce

     注解；如果找到一个，将使用注解中指定的MIME type，如果没有找到，将依赖与Entity Provider来决定适合的

     MIME Type.默认情况下，运行环境分配MIME Type按照下面的方式进行：

•      Java primitives 和她们的Number representations被赋予MIME Type:application/octet-stream;
•      JAXB objects被赋予MIME Type:application/xml.

     (3) Response codes

     如果resource method完成处理时没有抛出异常并且返回了Plain Java Constructs时，运行环境将自动设置response

     status code:

•      204(No Content)—the resource method's return type is void
•      204(No Content)—the value of the returned entity is null
•      200(OK)—the value of the returned entity is not null
  

2. Basics of building responses

    Response  Object 包装了返回给Consumer的Entity，该对象使用ResponseBuilder工厂类进行实例化。

    获取Reponse Builder: 有两种方法：

    (1) 使用Response类的静态方法：

import javax.ws.rs.core.Response;

Response r = Response.ok().build();

    (2) 使用ResponseBuilderImpl类

import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(200);
Response r = builder.build();

3. Creating responses for common use cases

     (1) Creating responses for successful requests

     例如：下面的例子返回HTTP Status 200并包含一个Entity:Customer:

import javax.ws.rs.core.Response;
import demo.jaxrs.server.Customer;

Customer customer = new Customer("Jane", 12);
return Response.ok(customer).build();

     如果希望返回值是200，但没有Content,可以使用Response.noContent() method：    

import javax.ws.rs.core.Response;

return Response.noContent().build();

     (2) Creating responses for redirection

     Response Class 提供了method用于处理redirection response statuses：

     A. 303 See Other：当request resource需要用久的重定向consumer至一个新的resource时，使用Response类的

     seeOther() method;

     B. 304 Not Modified：当request resource没有改变时，使用notModified() method;

import javax.ws.rs.core.Response;

return Response.notModified().build();

     C. 307 Temporary Redirect：当request resource需要引导consumer至一个新的resource，但是想consumer继续

     使用这个resource来处理未来的request时，使用temporaryRedirect() method.

     (3) Creating responses to signal errors

     Response Class提供了类处理两个基本的Error:

     A. serverError()(): Status of 500 Internal Server Error;

     B. notAcceptable()(java.util.List<javax.ws.rs.core.Variant> variants): 创建一个Reponse，有406 Status Code和一

     个Entity(包含a list of acceptable resource types).

import javax.ws.rs.core.Response;

return Response.serverError().build();

4. Handling more advanced responses

    (1) Adding custom headers

import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.header("username", "joe");
Response r = builder.build();

     (2) Adding a cookie

import javax.ws.rs.core.Response;
import javax.ws.rs.core.NewCookie;

NewCookie cookie = new NewCookie("username", "joe");
Response r = Response.ok().cookie(cookie).build();

     (3) Setting the response status

import javax.ws.rs.core.Response;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.status(404);
Response r = builder.build();

     (4) Setting cache control directives

import javax.ws.rs.core.Response;
import javax.ws.rs.core.CacheControl;
import org.apache.cxf.jaxrs.impl.ResponseBuilderImpl;

CacheControl cache = new CacheControl();
cache.setNoCache(true);
ResponseBuilderImpl builder = new ResponseBuilderImpl();
builder.cacheControl(cache);
Response r = builder.build();

5. Returning entities with generic type information

    如果应用程序需要更多的控制返回对象的MIME Type或者Entity Provider序列化Reponse, JAX-RS类

    javax.ws.rs.core.GenericEntity<T>提供了更细粒度的控制。

    Creating a GenericEntity<T> object

    有两种方法：

    A. 使用将被包装的Entity来创建GenericEntity<T>的子类：

import javax.ws.rs.core.GenericEntity;

List<String> list = new ArrayList<String>();

GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};
Response response = Response.ok(entity).build();

     B. 使用Entity的Generic Type信息直接创建Instance:

import javax.ws.rs.core.GenericEntity;

AtomicInteger result = new AtomicInteger(12);

GenericEntity<AtomicInteger> entity = new GenericEntity<AtomicInteger>(result,
result.getClass().getGenericSuperclass());
Response response = Response.ok(entity).build();