JAX-RS 2.1终稿：Java RESTful Web Services API详解

需积分: 24 6 浏览量更新于2024-07-17 收藏 451KB PDF 举报

JAX-RS (Java API for RESTful Web Services) 2.1规范最终版是于2017年7月13日发布的英文文档，该规范定义了Java平台上的RESTful Web服务接口的标准，以支持基于HTTP的REST（Representational State Transfer）风格的API设计。JAX-RS是一个用于构建RESTful Web服务的Java标准，它允许开发人员通过注解和编程模型来定义和实现Web服务端点。 1. **介绍**： - **规范状态**：JAX-RS 2.1是最终版本，这意味着它包含了该领域的最新稳定特性，旨在提供统一和可扩展的方式来处理RESTful服务。 - **目标**：规范的主要目标包括易于使用、灵活性、跨平台兼容性和安全性。它旨在简化Web服务开发，减少代码复杂性，并确保不同容器之间的互操作性。 - **非目标**：JAX-RS不关注特定的实现细节，如具体HTTP协议的底层处理，而是关注API的设计和行为。 2. **应用**： - **配置**：JAX-RS允许开发人员通过XML或注解配置应用，包括指定资源类、路径映射、媒体类型支持等。 - **验证**：规范规定了如何处理请求和响应的验证，包括客户端和服务器端的校验机制。 - **发布**：支持在Java SE、Servlet容器和其它类型的Web容器中部署和运行RESTful服务。 3. **资源管理**： - **资源类**：资源类是服务的核心，它们遵循一定的生命周期管理和环境依赖。构造器用于初始化资源实例，字段和bean属性提供了数据存储和访问。 - **方法与操作**： - **可见性**：资源方法的可见性必须明确，通常使用公共方法暴露接口。 - **参数**：方法可以接受GET、POST、PUT、DELETE等HTTP方法的参数，类型和处理方式符合REST原则。 - **返回类型**：方法的返回值可以是任何类型，包括资源对象或表示结果的JSON/HTML等。 - **异常处理**：需要处理可能抛出的异常，并提供合适的HTTP响应。 - **HEAD和OPTIONS**：HEAD方法支持资源状态获取而无需实际数据，OPTIONS用于查询支持的HTTP方法和其他特性。 - **URI模板**：通过URI模板进行资源路径的动态匹配，支持子资源的表示。 - **媒体类型能力**：声明资源对特定媒体类型的支持，如JSON、XML等。 - **注解继承**：利用注解继承机制，简化重复的配置和增强代码复用。 - **请求匹配**：JAX-RS规范定义了如何根据HTTP方法和URI模板找到相应的资源方法。 JAX-RS 2.1规范详细规定了如何在Java平台上设计、实现和使用RESTful Web服务，为开发者提供了一套清晰的编程模型和标准化的交互接口，有助于构建高性能、易于维护的API。通过理解和遵循这些规则，开发人员可以创建一致且可扩展的RESTful解决方案。

Chapter 2. Applications

type of endpoint required. An implementation MAY support zero or more endpoint types of any desired

type.

How the resulting endpoint class instance is used to publish the application is outside the scope of this

speciﬁcation.

2.3.1.1 JAX-WS

An implementation that supports publication via JAX-WS MUST support createEndpoint with an end-

point type of javax.xml.ws.Provider. JAX-WS describes how a Provider based endpoint can be

published in an SE environment.

2.3.2 Servlet

A JAX-RS application is packaged as a Web application in a .war ﬁle. The application classes are packaged

in WEB-INF/classes or WEB-INF/lib and required libraries are packaged in WEB-INF/lib. See the

Servlet speciﬁcation for full details on packaging of web applications.

It is RECOMMENDED that implementations support the Servlet 3 framework pluggability mechanism to

enable portability between containers and to avail themselves of container-supplied class scanning facilities.

When using the pluggability mechanism the following conditions MUST be met:

• If no Application subclass is present, JAX-RS implementations are REQUIRED to dynamically

add a servlet and set its name to

javax.ws.rs.core.Application

and to automatically discover all root resource classes and providers which MUST be packaged with

the application. Additionally, the application MUST be packaged with a web.xml that speciﬁes a

servlet mapping for the added servlet. An example of such a web.xml ﬁle is:

1 <web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"

2 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

3 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

4 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

5 <servlet>

6 <servlet-name>javax.ws.rs.core.Application</servlet-name>

7 </servlet>

8 <servlet-mapping>

9 <servlet-name>javax.ws.rs.core.Application</servlet-name>

10 <url-pattern>/myresources/

</url-pattern>

11 </servlet-mapping>

12 </web-app>

• If an Application subclass is present:

– If there is already a servlet that handles this application. That is, a servlet that has an initialization

parameter named

javax.ws.rs.Application

whose value is the fully qualiﬁed name of the Application subclass, then no additional con-

ﬁguration steps are required by the JAX-RS implementation.

8 JAX-RS July 13, 2017

2.3. Publication

– If no servlet handles this application, JAX-RS implementations are REQUIRED to dynami-

cally add a servlet whose fully qualiﬁed name must be that of the Application subclass. If

the Application subclass is annotated with @ApplicationPath, implementations are RE-

QUIRED to use the value of this annotation appended with ”/*” to deﬁne a mapping for the added

server. Otherwise, the application MUST be packaged with a web.xml that speciﬁes a servlet

mapping. For example, if org.example.MyApplication is the name of the Application

subclass, a sample web.xml would be:

1 <web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"

2 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

3 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

4 http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

5 <servlet>

6 <servlet-name>org.example.MyApplication</servlet-name>

7 </servlet>

8 <servlet-mapping>

9 <servlet-name>org.example.MyApplication</servlet-name>

10 <url-pattern>/myresources/

</url-pattern>

11 </servlet-mapping>

12 </web-app>

When an Application subclass is present in the archive, if both Application.getClasses

and Application.getSingletons return an empty collection then all root resource classes and

providers packaged in the web application MUST be included and the JAX-RS implementation is

REQUIRED to discover them automatically by scanning a .war ﬁle as described above. If either

getClasses or getSingletons returns a non-empty collection then only those classes or single-

tons returned MUST be included in the published JAX-RS application.

The following table summarizes the Servlet 3 framework pluggability mechanism:

Condition Action Servlet Name web.xml

No Application

subclass

Add servlet javax.ws.rs.core.Application Required for servlet mapping

Application sub-

class handled by ex-

isting servlet

(none) (already deﬁned) Not required

Application sub-

class not handled by

existing servlet

Add servlet Subclass name If no @ApplicationPath

then required for servlet map-

ping

Table 2.1: Summary of Servlet 3 framework pluggability cases

If not using the Servlet 3 framework pluggability mechanism (e.g. in a pre-Servlet 3.0 container), the

servlet-class or filter-class element of the web.xml descriptor SHOULD name the JAX-RS

implementation-supplied servlet or ﬁlter class respectively. The Application subclass SHOULD be iden-

tiﬁed using an init-param with a param-name of javax.ws.rs.Application.

Note that the Servlet 3 framework pluggability mechanism described above is based on servlets and not

ﬁlters. Applications that prefer to use an implementation-supplied ﬁlter class must use the pre-Servlet 3.0

conﬁguration mechanism.

July 13, 2017 JAX-RS 9

Chapter 3

Resources

Using JAX-RS a Web resource is implemented as a resource class and requests are handled by resource

methods. This chapter describes resource classes and resource methods in detail.

3.1 Resource Classes

A resource class is a Java class that uses JAX-RS annotations to implement a corresponding Web resource.

Resource classes are POJOs that have at least one method annotated with @Path or a request method desig-

nator.

3.1.1 Lifecycle and Environment

By default a new resource class instance is created for each request to that resource. First the constructor (see

Section 3.1.2) is called, then any requested dependencies are injected (see Section 3.2), then the appropriate

method (see Section 3.3) is invoked and ﬁnally the object is made available for garbage collection.

An implementation MAY offer other resource class lifecycles, mechanisms for specifying these are outside

the scope of this speciﬁcation. E.g. an implementation based on an inversion-of-control framework may

support all of the lifecycle options provided by that framework.

3.1.2 Constructors

Root resource classes are instantiated by the JAX-RS runtime and MUST have a public constructor for which

the JAX-RS runtime can provide all parameter values. Note that a zero argument constructor is permissible

under this rule.

A public constructor MAY include parameters annotated with one of the following: @Context, @Header-

Param, @CookieParam, @MatrixParam, @QueryParam or @PathParam. However, depending on the

resource class lifecycle and concurrency, per-request information may not make sense in a constructor. If

more than one public constructor is suitable then an implementation MUST use the one with the most

parameters. Choosing amongst suitable constructors with the same number of parameters is implementation

speciﬁc, implementations SHOULD generate a warning about such ambiguity.

Non-root resource classes are instantiated by an application and do not require the above-described public

constructor.

July 13, 2017 JAX-RS 11

Chapter 3. Resources

3.2 Fields and Bean Properties

When a resource class is instantiated, the values of ﬁelds and bean properties annotated with one the follow-

ing annotations are set according to the semantics of the annotation:

@MatrixParam Extracts the value of a URI matrix parameter.

@QueryParam Extracts the value of a URI query parameter.

@PathParam Extracts the value of a URI template parameter.

@CookieParam Extracts the value of a cookie.

@HeaderParam Extracts the value of a header.

@Context Injects an instance of a supported resource, see chapters 10 and 11 for more details.

Because injection occurs at object creation time, use of these annotations (with the exception of @Context)

on resource class ﬁelds and bean properties is only supported for the default per-request resource class

lifecycle. An implementation SHOULD warn if resource classes with other lifecycles use these annotations

on resource class ﬁelds or bean properties.

A JAX-RS implementation is only required to set the annotated ﬁeld and bean property values of instances

created by its runtime. Objects returned by sub-resource locators (see Section 3.4.1) are expected to be

initialized by their creator.

Valid parameter types for each of the above annotations are listed in the corresponding Javadoc, however in

general (excluding @Context) the following types are supported:

1. Types for which a ParamConverter is available via a registered ParamConverterProvider. See

Javadoc for these classes for more information.

2. Primitive types.

3. Types that have a constructor that accepts a single String argument.

4. Types that have a static method named valueOf or fromString with a single String argument

that return an instance of the type. If both methods are present then valueOf MUST be used unless

the type is an enum in which case fromString MUST be used

5. List<T>, Set<T>, or SortedSet<T>, where T satisﬁes 1, 3 or 4 above.

The DefaultValue annotation may be used to supply a default value for some of the above, see the Javadoc

for DefaultValue for usage details and rules for generating a value in the absence of this annotation and

the requested data. The Encoded annotation may be used to disable automatic URI decoding for @Matrix-

Param, @QueryParam, and @PathParam annotated ﬁelds and properties.

A WebApplicationException thrown during construction of ﬁeld or property values using any of the

5 steps listed above is processed directly as described in Section 3.3.4. Other exceptions thrown during

construction of ﬁeld or property values using any of the 5 steps listed above are treated as client errors: if the

ﬁeld or property is annotated with @MatrixParam, @QueryParam or @PathParam then an implementation

Due to limitations of the built-in valueOf method that is part of all Java enumerations, a fromString method is often

deﬁned by the enum writers. Consequently, the fromString method is preferred when available.

12 JAX-RS July 13, 2017

剩余101页未读，继续阅读

gaoyangcool

粉丝: 0

JAX-RS 2.1终稿：Java RESTful Web Services API详解

JavaWeb服务SOAP(jax-ws)和REST(jax-rs)规范

JAX-RS方式的RESTful Web Service开发

JAX-RS之rest接口实例

JAX-RS异常处理机制：构建零故障RESTful服务的关键技术

JAX-RS并发控制：管理并发请求与负载平衡的高级技巧

JAX-RS与Spring Boot集成：简化RESTful服务部署的快捷途径

JAX-RS服务文档化：使用Swagger自动生成API文档的完美实践

JAX-RS自定义媒体类型：框架扩展与复杂数据格式支持全攻略

【JAX-RS与Jersey框架入门】：构建RESTful API的Java解决方案

JAX-RS多部分文件上传处理：支持大文件传输的Web服务构建技术

最新资源