Jersey 2.22.1 用户手册：REST接口开发指南

需积分: 10 66 浏览量更新于2024-07-16 收藏 2.57MB PDF 举报

Jersey 2.22.1 用户手册是一份详细的指南，专注于Java平台上的RESTful Web服务开发，特别是使用Jersey框架。Jersey是一个轻量级的Java Servlet容器，用于实现Java API for RESTful Web Services (JAX-RS)标准，为开发者提供了构建RESTful API的强大工具。该手册的结构清晰，分为几个部分： 1. **Getting Started**：这部分介绍了如何通过Maven Archetype快速创建新项目，并逐步指导读者设置环境、运行项目。包括创建Java EE web应用和将应用部署到Heroku（尽管提到Spring Boot在现代开发中的流行，但Jersey仍然是构建REST API的重要选项）。 - 新建项目：步骤包括配置Maven，创建项目骨架，以及设置基本的运行环境。 - 部署到Heroku：展示了将应用部署到云平台的过程，以便在实际环境中测试和部署。 2. **Modules and Dependencies**：讲解了Jersey框架的兼容性和依赖关系，以及不同应用场景的示例。内容涵盖了Java SE版本的支持、如何集成Jersey到项目中、以及与 Glassfish、JDK、其他容器的集成，以及常见使用案例。 - Java SE兼容性：确保Jersey能在各种Java环境上运行。 - 应用场景示例：如基于Servlet的服务器端应用、客户端应用以及在支持的容器上的部署。 3. **JAX-RS Application, Resources, and Sub-Resources**：这部分是核心内容，详细解释了如何定义和实现RESTful资源和子资源。涉及的关键概念有`@Path`注解用于指定资源路径，HTTP方法注解（如`@GET`, `@PUT`, `@POST`, `@DELETE`）控制请求处理，以及`@Produces`和`@Consumes`用于指定资源的响应类型和接受请求类型。 - 根资源类：介绍如何创建根资源类，以及如何使用参数注解（如`@PathParam`, `@QueryParam`等）来处理请求参数。 - 子资源：展示了如何组织资源层次结构，以及资源类的生命周期管理和依赖注入规则。 - `@Context`注解的使用：允许访问服务器上下文信息，增强了资源的灵活性。在阅读Jersey 2.22.1 用户手册时，开发者可以了解到如何有效地使用Jersey进行API设计，以及如何处理客户端和服务端交互。这对于理解RESTful架构和开发可维护的API至关重要。尽管Spring Boot可能更受欢迎，但对于仍在使用Jersey或者需要深入了解其特性的开发者来说，这份手册是一份宝贵的参考资料。

xvi

Preface

This is user guide for Jersey 2.22.1. We are trying to keep it up to date as we add new features. When reading

the user guide, please consult also our Jersey API documentation [https://jersey.java.net/apidocs/2.22.1/

jersey/index.html] as an additional source of information about Jersey features and API.

If you would like to contribute to the guide or have questions on things not covered in our docs, please

in the Jersey documentation, please report them by filing a new issue in our Jersey JIRA Issue Tracker

[http://java.net/jira/browse/JERSEY] under docs component. Please make sure to specify the version of

the Jersey User Guide where the error has been spotted by selecting the proper value for the Affected

Version field.

Text formatting conventions

First mention of any Jersey and JAX-RS API component in a section links to the API documentation of

the referenced component. Any sub-sequent mentions of the component in the same chapter are rendered

using a monospaced font.

Emphasised font is used to a call attention to a newly introduce concept, when it first occurs in the text.

In some of the code listings, certain lines are too long to be displayed on one line for the available page

width. In such case, the lines that exceed the available page width are broken up into multiple lines using

a '\' at the end of each line to indicate that a break has been introduced to fit the line in the page. For

example:

This is an overly long line that \

might not fit the available page \

width and had to be broken into \

multiple lines.

This line fits the page width.

Should read as:

This is an overly long line that might not fit the available page width and had to be broken into multiple lines.

This line fits the page width.

Chapter 1. Getting Started

This chapter provides a quick introduction on how to get started building RESTful services using Jersey.

The example described here uses the lightweight Grizzly HTTP server. At the end of this chapter you will

see how to implement equivalent functionality as a JavaEE web application you can deploy on any servlet

container supporting Servlet 2.5 and higher.

1.1. Creating a New Project from Maven

Archetype

Jersey project is built using Apache Maven [http://maven.apache.org/] software project build and

management tool. All modules produced as part of Jersey project build are pushed to the Central Maven

Repository [http://search.maven.org/]. Therefore it is very convenient to work with Jersey for any Maven-

based project as all the released (non-SNAPSHOT) Jersey dependencies are readily available without a

need to configure a special maven repository to consume the Jersey modules.

Note

In case you want to depend on the latest SNAPSHOT versions of Jersey modules, the following

repository configuration needs to be added to your Maven project pom:

<id>snapshot-repository.java.net</id>

<name>Java.net Snapshot Repository for Maven</name>

<url>https://maven.java.net/content/repositories/snapshots/</url>

<layout>default</layout>

</repository>

Since starting from a Maven project is the most convenient way for working with Jersey, let's now have

a look at this approach. We will now create a new Jersey project that runs on top of a Grizzly [http://

grizzly.java.net/] container. We will use a Jersey-provided maven archetype. To create the project, execute

the following Maven command in the directory where the new project should reside:

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 \

-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false \

-DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example \

-DarchetypeVersion=2.22.1

Feel free to adjust the groupId, package and/or artifactId of your new project. Alternatively,

you can change it by updating the new project pom.xml once it gets generated.

1.2. Exploring the Newly Created Project

Once the project generation from a Jersey maven archetype is successfully finished, you should see the new

simple-service project directory created in your current location. The directory contains a standard

Maven project structure:

Project build and management configuration is described in the pom.xml located in the project root

directory.

Project sources are located under src/main/java.

Getting Started

Project test sources are located under src/test/java.

There are 2 classes in the project source directory in the com.example package. The Main class is

responsible for bootstrapping the Grizzly container as well as configuring and deploying the project's JAX-

RS application to the container. Another class in the same package is MyResource class, that contains

implementation of a simple JAX-RS resource. It looks like this:

1 package com.example;

3 import javax.ws.rs.GET;

4 import javax.ws.rs.Path;

5 import javax.ws.rs.Produces;

6 import javax.ws.rs.core.MediaType;

8 /**

9 * Root resource (exposed at "myresource" path)

10 */

11 @Path("myresource")

12 public class MyResource {

14 /**

15 * Method handling HTTP GET requests. The returned object will be sent

16 * to the client as "text/plain" media type.

17 *

18 * @return String that will be returned as a text/plain response.

19 */

20 @GET

21 @Produces(MediaType.TEXT_PLAIN)

22 public String getIt() {

23 return "Got it!";

24 }

25 }

A JAX-RS resource is an annotated POJO that provides so-called resource methods that are able to handle

HTTP requests for URI paths that the resource is bound to. See Chapter 3, JAX-RS Application, Resources

and Sub-Resources for a complete guide to JAX-RS resources. In our case, the resource exposes a single

resource method that is able to handle HTTP GET requests, is bound to /myresource URI path and

can produce responses with response message content represented in "text/plain" media type. In this

version, the resource returns the same "Got it!" response to all client requests.

The last piece of code that has been generated in this skeleton project is a MyResourceTest unit test

class that is located in the same com.example package as the MyResource class, however, this unit

test class is placed into the maven project test source directory src/test/java (certain code comments

and JUnit imports have been excluded for brevity):

1 package com.example;

3 import javax.ws.rs.client.Client;

4 import javax.ws.rs.client.ClientBuilder;

5 import javax.ws.rs.client.WebTarget;

7 import org.glassfish.grizzly.http.server.HttpServer;

9 ...

11 public class MyResourceTest {

Getting Started

13 private HttpServer server;

14 private WebTarget target;

16 @Before

17 public void setUp() throws Exception {

18 server = Main.startServer();

20 Client c = ClientBuilder.newClient();

21 target = c.target(Main.BASE_URI);

22 }

24 @After

25 public void tearDown() throws Exception {

26 server.stop();

27 }

29 /**

30 * Test to see that the message "Got it!" is sent in the response.

31 */

32 @Test

33 public void testGetIt() {

34 String responseMsg = target.path("myresource").request().get(String.class);

35 assertEquals("Got it!", responseMsg);

36 }

37 }

In this unit test, a Grizzly container is first started and server application is deployed in the test setUp()

method by a static call to Main.startServer(). Next, a JAX-RS client components are created in

the same test set-up method. First a new JAX-RS client instance c is built and then a JAX-RS web target

component pointing to the context root of our application deployed at http://localhost:8080/

myapp/ (a value of Main.BASE_URI constant) is stored into a target field of the unit test class. This

field is then used in the actual unit test method (testGetIt()).

In the testGetIt() method a fluent JAX-RS Client API is used to connect to and send a HTTP GET

request to the MyResource JAX-RS resource class listening on /myresource URI. As part of the

same fluent JAX-RS API method invocation chain, a response is read as a Java String type. On the

second line in the test method, the response content string returned from the server is compared with

the expected phrase in the test assertion. To learn more about using JAX-RS Client API, please see the

Chapter 5, Client API chapter.

1.3. Running the Project

Now that we have seen the content of the project, let's try to test-run it. To do this, we need to invoke

following command on the command line:

mvn clean test

This will compile the project and run the project unit tests. We should see a similar output that informs

about a successful build once the build is finished:

Results :

Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

Getting Started

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 34.527s

[INFO] Finished at: Sun May 26 19:26:24 CEST 2013

[INFO] Final Memory: 17M/490M

[INFO] ------------------------------------------------------------------------

Now that we have verified that the project compiles and that the unit test passes, we can execute the

application in a standalone mode. To do this, run the following maven command:

mvn exec:java

The application starts and you should soon see the following notification in your console:

May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.NetworkListener start

INFO: Started listener bound to [localhost:8080]

May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.HttpServer start

INFO: [HttpServer] Started.

Jersey app started with WADL available at http://localhost:8080/myapp/application.wadl

Hit enter to stop it...

This informs you that the application has been started and it's WADL descriptor is available at http://

localhost:8080/myapp/application.wadl URL. You can retrieve the WADL content by

executing a curl http://localhost:8080/myapp/application.wadl command in your

console or by typing the WADL URL into your favorite browser. You should get back an XML document

in describing your deployed RESTful application in a WADL format. To learn more about working with

WADL, check the Chapter 17, WADL Support chapter.

The last thing we should try before concluding this section is to see if we can communicate with our

resource deployed at /myresource path. We can again either type the resource URL in the browser

or we can use curl:

$ curl http://localhost:8080/myapp/myresource

Got it!

As we can see, the curl command returned with the Got it! message that was sent by our resource.

We can also ask curl to provide more information about the response, for example we can let it display

all response headers by using the -i switch:

curl -i http://localhost:8080/myapp/myresource

HTTP/1.1 200 OK

Content-Type: text/plain

Date: Sun, 26 May 2013 18:27:19 GMT

Content-Length: 7

Got it!

Here we see the whole content of the response message that our Jersey/JAX-RS application returned,

including all the HTTP headers. Notice the Content-Type: text/plain header that was derived

from the value of @Produces [http://jax-rs-spec.java.net/nonav/2.0/apidocs/javax/ws/rs/Produces.html]

annotation attached to the MyResource class.

In case you want to see even more details about the communication between our curl client and our

resource running on Jersey in a Grizzly I/O container, feel free to try other various options and switches

剩余341页未读，继续阅读

leetooy

粉丝: 0
资源: 15

Jersey 2.22.1 用户手册：REST接口开发指南

jersey2.3.1最新参考文档api

jersey文件下载

Jersey 1.18 API CHM文档

bfopdf-2.22.1.zip

git-2.22.1.tar.gz

surefire-api-2.22.1.jar

selenium-2.22.1.tar.gz

maven-surefire-common-2.22.1.jar

maven-surefire-plugin-2.22.1.jar

prometheus-2.22.1.linux-386.tar.gz

最新资源