JAX-RS：Java RESTful Web服务开发指南（2.1版）

需积分: 9 168 浏览量更新于2024-07-17 收藏 443KB PDF 举报

Java RESTful Web Services (JAX-RS) 是一套Java标准API，它为遵循Representational State Transfer (REST)架构风格的Web服务开发提供了规范。JAX-RS 2.1 Public Review版本于2017年4月18日发布，旨在简化Java开发者在构建RESTful应用时的工作流程。 1. **介绍**: - **状态与目标**: JAX-RS定义了Java开发人员在构建RESTful服务时所需的一致性和标准化方法。它假设读者对REST原则有基本了解，如资源定位、HTTP方法（GET、POST、PUT、DELETE等）以及状态转移。 - **非目标**: JAX-RS不是用来替代现有框架或库的，而是提供一种可扩展的方式来实现REST，它不强制特定的编程模型或ORM框架。 2. **应用配置**: - **配置选项**：开发者可以选择在Java SE环境中部署服务，或者通过Servlet容器（如Tomcat）或其他的部署平台实现。不同的容器可能有不同的配置需求。 - **验证与发布**: 服务的验证可以基于Java SE的内置机制，也可以在Servlet容器或特定容器提供的机制上进行。出版和部署可能涉及配置URL映射和资源类的注册。 3. **资源管理**: - **资源类**：资源类是JAX-RS的核心，它们代表了RESTful API中的实体。生命周期管理和环境设置是资源类的基础，包括构造函数用于初始化资源实例。 - **字段和属性**：字段表示资源的状态，而Bean Properties则用于数据交换，通常通过HTTP请求和响应进行。 - **资源方法**：核心的HTTP方法（GET、POST、PUT、DELETE等）在资源类中定义，每个方法对应一个特定的REST操作。参数处理、返回类型、异常处理和HTTP方法如HEAD和OPTIONS的特殊处理都被详细规定。 - **URI模板**：用于动态生成URL路径，支持子资源的声明。 - **媒体类型能力**：允许声明资源支持的数据格式，例如JSON或XML。 - **注解继承**：为了代码复用，注解可以通过继承机制传递，简化了配置。 4. **匹配请求到资源方法**: - JAX-RS提供了一套规则来决定如何根据HTTP请求找到合适的资源方法，这涉及到路径参数、查询参数和HTTP方法的匹配。总结来说，JAX-RS是一个强大的工具包，帮助Java开发者创建符合REST原则的Web服务。它通过API规范了资源的创建、配置、请求处理和响应生成过程，使得开发RESTful服务更加模块化和统一。通过遵循其约定和术语，开发者可以更轻松地在各种部署环境中构建和维护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 April 18, 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.

April 18, 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.

April 18, 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 April 18, 2017

剩余97页未读，继续阅读

Greggu

粉丝: 0
资源: 1

JAX-RS：Java RESTful Web服务开发指南（2.1版）

Java 调用Http Rest接口 例子说明2

java restFull及示例和Maven.rar

用java代码写一个下载pdf的restfull api接口

RESTFull风格是什么

springboot实现restfull风格

android 最简单restfull

RestFull架构是什么

delphi TIdHTTPServer restfull api

restfull风格请求方式

restfull api开发规范

最新资源

Java 调用Http Rest接口例子说明2