世俱杯 2025

　　本篇介绍这个版本中引入的新技术。这些新技术使这个平台变得更加强大，其中三个重要的新技术包括：

　　◆RESTful Web Services Java API (JAX-RS)

　　◆面向Java EE平台的上下文和依赖性注入(CDI)

　　◆Bean验证

　　本文将介绍RESTful Web Services Java API (JAX-RS)。

　　RESTful Web Services Java API (JAX-RS)

　　RESTful Web Services Java API (JAX-RS)，JSR 311让你可以迅速构建遵循REST(Representational State Transfer，表象化状态转变。参考阅读：《什么是REST》)风格软件架构的轻量级Web服务。REST中的一个重要概念是资源的存在性，每个资源都一个全局引用标识符，即URI。特别是数据和函数都被认为是可通过URI识别和访问的资源。为了操纵这些资源，网络组件，客户端和服务器通过一个标准的接口通信，如HTTP和一个组固定的动词 — GET，PUT，POST和DELETE — 交换这些资源。

　　RESTful Web服务是按照REST架构风格构建的Web服务，利用RESTful方法使用基于SOAP的技术构建Web服务已经成为一个受欢迎的选择，这都得感谢REST的轻量级特性和直接通过HTTP传输数据的能力。

　　JAX-RS为在Java中构建RESTful Web服务提供了标准化API，API提供了一组注解，以及相关的类和接口。对POJO应用注解允许你暴露Web资源，这个方法使得在Java中创建RESTful Web服务变得简单。

　　JAX-RS 1.0技术规范定稿于2008年10月，包括了一个参考实现Jersey，Java EE 6包括了这个技术规范的最新版本JAX-RS 1.1，这个版本与Java EE 6中的新特性保持一致。

　　下面我们一起来看一个使用JAX-RS构建的RESTful Web服务：

　   import javax.ws.rs.Path;
　　import javax.ws.rs.Produces;
　　import javax.ws.rs.Get;
　　import javax.ws.rs.Post;
　　import javax.ws.rs.Consumes;
　　import javax.ws.rs.core.Response;
　　import javax.ws.rs.core.MediaType;
　　import javax.ws.rs.core UriInfo;
　　import javax.ws.rs.core.UriBuilder;
　　import java.net.URI;
　　@Path ("items")
　　@Produces (MediaType.APPLICATION_XML)
　　Public class ItemsResource {
　　@Context UriInfo uriInfo;
　　@GET
　　Items listItems() {
　　Return Allitems();
　　}
　　@POST
　　@Consumes (MediaType.APPLICATION_XML)
　　Public Response create(Item item) throws ItemCreationException {
　　Item newItem = createItem(item);
　　URI newItemURI = uriInfo.getRequestUriBuilder().path(newItem.getId()).build();
　　return Response.created(newItemURI).build();
　　}
　　...
　　}

 　　在这个例子中，ItemsResource类是管理一组项目的Web服务，类中导入了JAX-RS 1.1注解，类和接口。

　　@Path注解指定了资源的相对路径，在这里是“items”，类资源URI是基于应用程序上下文的，因此，如果应用程序上下文在这个例子中是//example.com，那么类资源的URI就是//example.com/items，这意味着如果一个客户端直接请求URI //example.com/items，ItemsResource类将会执行。

　　@GET注解指定了注解的方法，这里是listItems()方法，它处理HTTP GET请求，当某个客户端直接发起对ItemsResource资源的HTTP GET请求时，JAX-RS运行时调用listItems()方法处理这个GET请求。

　　注意@Produces注解，它指定了返回给客户端的MIME媒体类型，在ItemsResource这个例子中，@Produces注解指定了MediaType.APPLICATION_XML，MediaType类是一个抽象的MIME媒体类型，MediaType.APPLICATION_XML是XML内容MIME媒体类型的抽象 — application/xml。

　　注解如@Produces建议JAX-RS自动转换某些内容类型，例如，listItems()方法返回一个Items类型的Java对象，JAX-RS自动将这个Java类型转换成application/xml MIME类型，使用这个MIME类型响应客户端的HTTP请求。注意仅当返回的类型默认是支持的才会自动转换，例如，如果Items是一个JAXB注解Bean，那么将会自动转换，但如果Items是一个POJO，你需要执行MessageBodyReader处理序列化。

　　你也可以在一个方法上指定@Produces注解，在上面的例子中，你在方法上指定的MIME类型覆盖了在类的@Produces注解中指定的MIME类型，例如，你可以象下面这样为listItems()方法指定@Produces注解：

 　@GET @Produces (MediaType.TEXT_PLAIN) Items listItems() { Return Allitems(); }

 　　JAX-RS然后会将Items Java类型转换为text/plain MIME类型，返回这种类型的内容给HTTP请求客户端。

　　@POST注解指定了注解的方法，这里是create()方法，它负责响应HTTP POST请求。在这个例子中，这个方法创建了一个新项目，然后返回一个表示它已创建了一个新项目的响应，当客户端直接向ItemsResource资源发起HTTP POST请求时，JAX-RS运行时调用create()方法处理POST请求。

　　注意@Consumes注解是在create()方法上指定的，注解指定了方法能够接受的来自客户端的MIME媒体类型。如果你在类上指定@Consumes，它适用于类中的所有方法，如果你在方法上指定@Consumes，它会覆盖你在类上指定的@Consumes注解包含的MIME类型。在这个例子中，@Consumes注解指定create()方法可接受XML内容，即MIME类型application/xml，这是从MIME类型转换到Java类型。当某个客户端在POST请求中提交XML内容时，JAX-RS调用create()方法自动将传入的XML内容转换成方法需要的Item Java类型。

　　JAX-RS也包括大量的进一步简化有关构建行为的实用类和接口，前面看到的MediaType就是这样的类，它抽象了MIME媒体类型。其它的一些类和接口是：

　　UriInfo：访问URI信息的接口，在这个例子中，@Context注解注入UriInfo接口到ItemsResource类中的uriInfo字段。

　　UriBuilder：从它们的组件构建URI的类。

　　Response：代表HTTP响应的类。

　　Response.ResponseBuilder：根据著名的Builder模式构建Response对象的类。

　　这些类和接口在下面这些语句中非常有用：

   　URI newItemURI = uriInfo.getRequestUriBuilder().path(newItem.getId()).build();
　　return Response.created(newItemURI).build();

 　　第一个语句为新项目构建一个URI，getRequestUriBuilder()方法是创建UriBuilder对象的UriInfo方法，path() 和 build()方法是为新项目一起构造URI的UriBuilder方法。

　　第二个语句为新项目创建一个返回给客户端的Response对象，created方法是一个创建Response.ResponseBuilder 对象的Response方法，build()方法是一个为新项目创建Response 对象的Response.ResponseBuilder方法，这个对象提交元数据给JAX-RS运行时构造HTTP响应。

　　这些实用类和接口隐藏了HTTP编程的许多复杂性，使用JAX-RS的另一个原因是它简化了构建RESTful Web服务，JAX-RS可以简化许多类型的Web应用程序，例如，如果你需要构建一个检查HTTP头的应用程序，JAX-RS比采用其它技术就更简单。

　　JAX-RS还有其它便捷功能，例如，JAX-RS包括大量基于参数的注解，从请求中提取信息，@QueryParam就是这样的注解，通过它你可以从请求URL中的Query组件提取查询参数，其它基于参数的注解还有@MatrixParam，它从URL路径提取信息，@HeaderParam注解从HTTP头提取信息，@CookieParam从Cookies提取信息。