JAX-RS入门 九： 内容约定（2）

JAX-RS与Conneg

 

JAX-RS有一些用来帮助用户管理他的conneg的工具：

• 基于Accept头的方法派发
• 允许直接查看内容信息
• 用于处理多约束条件的APIs

1. 方法派发

 

前几节中，我们看到怎么使用@Produces注释来指示响应的Media Type。 JAX-RS也使用这个注释来分发请求到恰当的方法上，通过匹配最佳的请求的Accept头信息的Media Type 列表到由@Produces标注的元数据。例如：

@Path("/customers")
public class CustomerResource {

    @GET
    @Path("{id}")
    @Produces("application/xml")
    public Customer getCustomerXml(@PathParam("id") int id) {...}

    @GET
    @Path("{id}")
    @Produces("text/plain")
    public String getCustomerText(@PathParam("id") int id) {...}

    @GET
    @Path("{id}")
    @Produces("application/json")
    public Customer getCustomerJson(@PathParam("id") int id) {...}

}

这里三个方法对应的服务路径一样，但是@Produces的元数据不同。JAX-RS会基于请求信息的Accept头信息来选择恰当的处理方法，例如：

GET http://example.com/customers/1
Accept: application/json;q=1.0, application/xml;q=0.5

根据头一节的介绍，这里，Accept的数据类型的优先级为：

1. application/json
2. application/xml  

因此对这个请求，getCustomerJson()方法将被调用。

 

2. JAXB与Conneg

 

之前的章节里介绍了怎么通过使用JAXB来实现从java对象到xml或者json的映射。而通过在JAX-RS中使用conneg，我们也可以实现一个可以服务于这两种格式的方法，例如：

@Path("/service")
public class MyService {

    @GET
    @Produces({"application/xml", "application/json"})
    public Customer getCustomer(@PathParam("id") int id) {...}

}

3. 复杂的内容协议

 

有时候，简单的Accept头与@Produces之间的映射可能不足以解决问题，服务于同一路径的不同的JAX-RS方法可能需要处理不同的Media Type、Language、Encoding等等。 不幸的是JAX-RS并没有提供类似于@ProduceLanguages或者@ProduceEncodings注释。相反，我们必须实现自己的头信息查找方法，或者是使用JAX-RS API管理复杂的Conneg。接下来分别介绍这两种方式。

 

        > 查看Accept头

在之前的章节里介绍过javax.ws.rs.core.HttpHeaders接口。这个接口包含了预处理的与Http请求相关的Conneg信息：

public interface HttpHeaders {

    public List<MediaType> getAcceptableMediaTypes();
    public List<Locale> getAcceptableLanguages();
    ...

}

getAcceptableMediaTypes()得到包含定义在HTTP请求的Accept头信息的Media Type列表，其中的项被解析成一个个javax.ws.rs.core.MediaType对象，并且这个列表已经是基于其中的"q"值（显式或隐式的）排序的。

 

getAcceptableLanguages()处理HTTP请求的Accept-Language头信息，其中的项已经被解析成一个个java.util.Locale对象。并且和上面的MediaType一样，已经是根据"q"值有序的了。

 

通过使用@javax.ws.rs.core.Context注释来注入HttpHeaders对象。例如：

@Path("/myservice")
public class MyService {

    @GET
    public Response get(@Context HttpHeaders headers) {
        MediaType type = headers.getAcceptableMediaTypes().get(0);
        Locale language = headers.getAcceptableLanguages().get(0);
        Object responseObject = ...;
        Response.ResponseBuilder builder = Response.ok(responseObject, type);
        builder.language(language);
        return builder.build();
    }

}

        > variant处理

 

JAX-RS也提供了API用来处理当你有多个Media Type、Language或Encoding集的情况。通过使用javax.ws.rs.core.Request和javax.ws.rs.core.Variant类来处理这些复杂的匹配。首先看Variant类：

package javax.ws.rs.core.Variant
public class Variant {

    public Variant(MediaType mediaType, Locale language, String encoding) {...}

    public Locale getLanguage() {...}

    public MediaType getMediaType() {...}

    public String getEncoding() {...}

}

Variant类就是一个简单的包含Media Type，Language和Encoding的结构。它表示一个简单的你JAX-RS资源方法所支持的集合。然后通过在Request接口中设置一列这个类的对象来进行交互：

package javax.ws.rs.core.Request
public interface Request {

    Variant selectVariant(List<Variant> variants) throws IllegalArgumentException;
    ...

}

其中selectVariant()方法里设置的就是JAX-RS方法中支持的一列Variant对象。它会检查请求中的Accept、Accept-Language和Accept-Encoding头，然后把它们和Variant列表进行比较，找到最匹配的请求的Variant对象。如果没有符合的对象，则返回null。例如：

@Path("/myservice")
public class MyService {
    @GET
    Response getSomething(@Context Request request) {

        List<Variant> variants = new ArrayList();
        variants.add(new Variant(new MediaType("application/xml"),"en", "deflate"));
        variants.add(new Variant(new MediaType("application/xml"),"es", "deflate"));
        variants.add(new Variant(new MediaType("application/json"),"en", "deflate"));
        variants.add(new Variant(new MediaType("application/json"),"es", "deflate"));
        variants.add(new Variant(new MediaType("application/xml"),"en", "gzip"));
        variants.add(new Variant(new MediaType("application/xml"),"es", "gzip"));
        variants.add(new Variant(new MediaType("application/json"),"en", "gzip"));
        variants.add(new Variant(new MediaType("application/json"),"es", "gzip"));

        // Pick the variant
        Variant v = request.selectVariant(variants);
        Object entity = ...; // get the object you want to return
        ResponseBuilder builder = Response.ok(entity);
        builder.type(v.getMediaType()).language(v.getLanguage()).header("Content-Encoding", v.getEncoding());

        return builder.build();
    }
}

这里花了很多代码去提供所支持的Variant。也有更好的方法去做自动选择，JAX-RS提供了javax.ws.rs.core.Variant.VariantBuilder类用来创建这些复杂的选择器：

public static abstract class VariantListBuilder {
    public static VariantListBuilder newInstance() {...}

    public abstract VariantListBuilder mediaTypes(MediaType... mediaTypes);

    public abstract VariantListBuilder languages(Locale... languages);

    public abstract VariantListBuilder encodings(String... encodings);

    public abstract List<Variant> build();

    public abstract VariantListBuilder add();
}

它支持使用Builder的模式来创建variant列表。例如重写前面的例子：

@Path("/myservice")
public class MyService {

    @GET
    Response getSomething(@Context Request request) {
        Variant.VariantBuilder vb = Variant.VariantBuilder.newInstance();
        vb.mediaTypes(new MediaType("application/xml"),
                new MediaType("application/json"))
                .languages(new Locale("en"), new Locale("es"))
                .encodings("deflate", "gzip");

        List<Variant> variants = vb.build();
        // Pick the variant
        Variant v = request.selectVariant(variants);
        Object entity = ...; // get the object you want to return
        ResponseBuilder builder = Response.ok(entity);
        builder.type(v.getMediaType())
                .language(v.getLanguage())
                .header("Content-Encoding", v.getEncoding());
        return builder.build();
    }
}

通过调用VariantBuilder的mediaTypes()、languages()和encodings()方法设置可能的值，最后调用build()方法，它会生成一个Variant列表，包含所有可能的组合。

 

VariantBuilder也支持多个不同的Variant集体，通过使用VariantBuilder.add()方法可以分隔和定义不同的Variant集。例如：

 

Variant.VariantBuilder vb = Variant.VariantBuilder.newInstance();
vb.mediaTypes(new MediaType("application/xml"),new MediaType("application/json"))
        .languages(new Locale("en"), new Locale("es"))
        .encodings("deflate", "gzip")
        .add()
        .mediaTypes(new MediaType("text/plain"))
        .languages(new Locale("en"), new Locale("es"), new Locale("fr"))
        .encodings("compress");

 上例中VariantBuilder创建了两组Variant，最后builder后就是这两组的合集。

 

现实中使用Request.selectVariant()方法的例子并不多。首先，content encoding在JAX-RS并不是一个很容易处理的东西，如果你想灵活的处理content encoding，你最好是自己去处理所有的流。大多数JAX-RS的实现应该都自动支持了GZIP。

 

其次，多数JAX-RS的服务都会根据@Produces注释和Accept头信息自动处理响应的Media Type。

 

4. URI模式约定

 

Conneg是一个很强大的HTTP特性。问题是有的客户端，特别是浏览器并不支持它。例如Firefox浏览器的Accept头信息被硬编码为：

 

text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

如果你希望访问的是JSON数据，那可能就失败了。

 

一个常用的解决此类问题的方法就是把Conneg信息内嵌在URI中，而不是使用Accept头，例如：

/customers/en-US/xml/3323
/customers/3323.xml.en-US

内容信息以分隔的路径或文件名后缀被嵌在URI中。上例中，客户端要求的是XML格式，英文的信息。在JAX-RS中可以如下实现：

 

@Path("/customers/{id}.{type}.{language}")
@GET
public Customer getCustomer(@PathParam("id") int id,
            @PathParam("type") String type,
            @PathParam("language") String language) {...}

在JAX-RS规范完成之前，围绕着文件名后缀的使用确实被定义为规范的一部分。不幸的是，专业组不同意这个特性的整个语义定义，因此它还是被删除了。很多JAX-RS的实现仍然支持这个特性，因此了解它是怎么工作的还是很重要的。

 

规范定义和很多JAX-RS实现现在的工作方式是在文件后缀， Media Type和Language之间定义一个映射关系。xml后缀映射到application/xml；en后缀映射到en-US。当一个请求来了，JAX-RS实现就会提取后缀，并使用这个信息作为Conneg的数据，替换任何传入的Accept或Accept-Language头。例如：

@Path("/customers")
public class CustomerResource {

    @GET
    @Produces("application/xml")
    public Customer getXml() {...}

    @GET
    @Produces("application/json")
    public Customer getJson() {...}

}

如果请求为 GET /customers.json ，刚JAX-RS实现会提取.json后缀，并把它从请求路径中移除。然后它会查找匹配json的映射。假设是 application/json ，然后这个信息，而不是Accept头，不会被使用，最后getJson()方法就会被调用。