Jersey 2.23.2用户指南：Maven项目创建与RESTful服务开发

jersey

guide

需积分: 9 130 浏览量更新于2024-07-20 收藏 2.93MB PDF 举报

身份认证购VIP最低享 7 折!

30元优惠券

Jersey User Guild 是一份详细的用户手册，专注于 Jersey 2.23.2 版本，这是一个流行的 Java 实现的 RESTful Web Services 框架，用于构建 Java Enterprise Edition (Java EE) 应用程序。这份文档提供了一个结构化的指南，旨在帮助开发人员从头开始学习和掌握 Jersey 的使用。 **1. Getting Started** 章节详细介绍了如何使用 Maven 架构模式创建新项目，引导读者探索新项目的结构，并演示如何运行应用。对于初学者，这里有步骤指导如何在 Heroku 上部署一个 Web 应用，这有助于了解 Jersey 在实际部署环境中的应用。 **2. Modules and Dependencies** 这部分内容涵盖了 Jersey 与 Java SE 的兼容性，以及如何管理和使用框架所需的依赖项。它列举了不同场景下的使用案例，例如基于 Servlet 的 Glassfish 应用、服务器端应用程序、客户端应用程序，以及在支持的容器上运行的服务器端应用。此外，还列出了 Jersey 框架的主要模块列表，为开发者提供了清晰的模块划分和选择依据。 **3. JAX-RS Application, Resources, and Sub-Resources** 这部分核心内容围绕 JAX-RS 应用、资源类以及子资源的定义展开。讲解了如何使用 `@Path` 注解来指定资源路径，以及如何通过 `@GET`, `@PUT`, `@POST`, 和 `@DELETE` 方法处理 HTTP 请求。`@Produces` 和 `@Consumes` 被用来指定资源的响应类型和请求内容类型。参数注解如 `@*Param` 用于处理请求参数，而子资源的管理则涉及到资源类的生命周期管理和依赖注入规则。`@Context` 的用法也在此处介绍，它允许在资源类中获取上下文信息。此外，还讨论了程序式资源模型的设计。 **4. Application Deployment and Runtime Environments** 最后一部分着重于应用的部署和运行环境。这部分介绍了如何将 Jersey 应用部署到不同的运行时环境，包括服务器配置、部署策略以及在生产环境中的性能优化和错误处理。这部分内容对理解 Jersey 如何在实际应用中运作至关重要。 Jersey User Guild 是一个全面的教程，适合希望通过 Jersey 构建 RESTful API 的开发人员，无论是初次接触 Jersey 还是希望提升现有技能的开发者，都能从中获得丰富的实践指导和理论知识。通过阅读和实践这份手册，开发者可以熟练掌握 Jersey 的核心概念和技术，从而构建高效、可扩展的 Web 服务。

资源详情

资源推荐

Security
oauth1-client Module that adds an OAuth 1 support to Jersey client.
oauth1-server Module that adds an OAuth 1 support to Jersey server
oauth1-signature OAuth1 signature module
oauth2-client Module that adds an OAuth 2 support to Jersey client
Table  2.10. Je rsey Examples
Jersey Examples
additional-bundle OSGi Helloworld Webapp - additional bundle
alternate-version-bundle OSGi Helloworld Webapp - alternate version bundle
assemblies Jersey examples shared assembly types.
bean-validation-webapp Jersey Bean Validation (JSR-349) example.
bookmark Jersey Bookmark example.
bookmark-em Jersey Bookmark example using EntityManager.
bookstore-webapp Jersey MVC Bookstore example.
bundle OSGi HttpService example bundle
cdi-webapp Jersey CDI example.
clipboard Jersey clipboard example.
clipboard-programmatic Jersey programmatic resource API clipboard example.
declarative-linking Declarative Hyperlinking - Jersey Sample
entity-filtering Jersey Entity Data Filtering Example.
entity-filtering-security Jersey Entity Data Filtering Security Example.
entity-filtering-selectable Jersey Entity Data Filtering Selectable Example.
exception-mapping Jersey example showing exception mappers in action.
extended-wadl-webapp Extended WADL example.
feed-combiner-java8-webapp Jersey Web Application (Servlet) examples parent POM.
flight-management-webapp Jersey Flight Management Demo Web Application Example
freemarker-webapp Jersey Freemarker example.
functional-test Jersey examples
functional-test OSGi HttpService example
groovy Groovy Jersey
helloworld Jersey annotated resource class "Hello world" example.
helloworld-benchmark Jersey "Hello World" benchmark example.
helloworld-netty Jersey "Hello world" example on Netty container.
helloworld-programmatic Jersey programmatic resource API "Hello world" example.
helloworld-pure-jax-rs Example using only the standard JAX-RS API's and the lightweight HTTP server bundled in JDK.
helloworld-spring-annotations Spring 3 Integration Jersey Example
helloworld-spring-webapp Spring 3 Integration Jersey Example
helloworld-webapp Jersey annotated resource class "Hello world" example.
helloworld-weld Jersey annotated resource class "Hello world" example with Weld support.
http-patch
Jersey example for implementing generic PATCH support via JAX-RS reader interceptor. Taken from Gerard Davison's blog entry:
http://kingsfleet.blogspot.co.uk/2014/02/transparent-patch-support-in-jax-rs-20.html
http-trace Jersey HTTP TRACE support example.
https-clientserver-grizzly Jersey HTTPS Client/Server example on Grizzly.
https-server-glassfish Jersey HTTPS server on GlassFish example.
java8-webapp Java 8 Types WebApp Example.
jaxb Jersey JAXB example.
jaxrs-types-injection Jersey JAX-RS types injection example.
jersey-ejb Jersey Web Application (Servlet) examples parent POM.
json-jackson Jersey JSON with Jackson example.
json-jackson1 Jersey JSON with Jackson 1.x example.
json-jettison Jersey JSON with Jettison JAXB example.
json-moxy Jersey JSON with MOXy example.
json-processing-webapp Jersey JSON-P (JSR 353) example.
json-with-padding Jersey JSON with Padding example.
lib-bundle OSGi Helloworld Webapp - lib bundle
managed-beans-webapp Jersey Managed Beans Web Application Example.
managed-client Jersey managed client example.
managed-client-simple-webapp Jersey Web Application (Servlet) examples parent POM.
managed-client-webapp Jersey managed client web application example.
monitoring-webapp Jersey Web Application (Servlet) examples parent POM.
multipart-webapp Jersey Multipart example.
oauth-client-twitter Twitter client using OAuth 1 support for Jersey that retrieves Tweets from the home timeline of a registered Twitter account.
oauth2-client-google-webapp Google API data retrieving example using OAuth2 for authentication and authorization
osgi-helloworld-webapp Jersey examples
osgi-http-service OSGi HttpService example
reload Jersey resource configuration reload example.
rx-client-java8-webapp Jersey Reactive Client Extension (Java8) WebApp Example.

rx-client-webapp Jersey Reactive Client Extension WebApp Example.
server-async Jersey JAX-RS asynchronous server-side example.
server-async-managed Jersey JAX-RS asynchronous server-side example with custom Jersey executor providers.
server-async-standalone Standalone Jersey JAX-RS asynchronous server-side processing example.
server-async-standalone-client Standalone Jersey JAX-RS asynchronous server-side processing example client.
server-async-standalone-webapp Standalone Jersey JAX-RS asynchronous server-side processing example web application.
server-sent-events Jersey Server-Sent Events example.
servlet3-webapp Jersey Servlet 3 example with missing servlet-class in the web.xml file
shortener-webapp Jersey Shortener Webapp (MVC + Bean Validation).
simple-console Jersey Simple Console example
sparklines Jersey examples
sse-item-store-webapp Jersey SSE-based item store example.
sse-twitter-aggregator Jersey SSE Twitter Message Aggregator Example.
system-properties-example Jersey system properties example.
tone-generator Jersey examples
war-bundle OSGi Helloworld Webapp WAR bundle
webapp-example-parent Jersey Web Application (Servlet) examples parent POM.
xml-moxy Jersey XML MOXy example.
Jersey Examples
Chapter 3. JAX-RS Application, Resources and Sub-Resources
Table  of Contents
3.1. Root Resource Classes
3.1.1. @Path
3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods)
3.1.3. @Produces
3.1.4. @Consumes
3.2. Parameter Annotations (@*Param)
3.3. Sub-resources
3.4. Life-cycle of Root Resource Classes
3.5. Rules of Injection
3.6. Use of @Context
3.7. Programmatic resource model
This chapter presents an overview of the core JAX-RS concepts - resources and sub-resources.
The JAX-RS 2.0.1 JavaDoc can be found online here.
The JAX-RS 2.0.1 specification draft can be found online here.
3.1. Root Resource Classes
Root resource classes are POJOs (Plain Old Java Objects) that are annotated with @Path have at least one method annotated with @Path or a resource
method designator annotation such as @GET, @PUT, @POST, @DELETE. Resource methods are methods of a resource class annotated with a resource
method designator. This section shows how to use Jersey to annotate Java objects to create RESTful web services.
The following code example is a very simple example of a root resource class using JAX-RS annotations. The example code shown here is from one of the
samples that ships with Jersey, the zip file of which can be found in the maven repository here.
Example 3.1. Simple hello world root resource class
Let's look at some of the JAX-RS annotations used in this example.
3.1.1. @Path
The @Path annotation's value is a relative URI path. In the example above, the Java class will be hosted at the URI path /helloworld. This is an extremely
simple use of the @Path annotation. What makes JAX-RS so useful is that you can embed variables in the URIs.
URI path templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a
request based on the substituted URI. Variables are denoted by curly braces. For example, look at the following @Path annotation:
In this type of example, a user will be prompted to enter their name, and then a Jersey web service configured to respond to requests to this URI path template
will respond. For example, if the user entered their username as "Galileo", the web service will respond to the following URL:
http://example.com/users/Galileo
To obtain the value of the username variable the @PathParam may be used on method parameter of a request method, for example:
Example 3.2. Specifying URI path paramete r
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package org.glassfish.jersey.examples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
 
@Path("helloworld")
public class HelloWorldResource {
    public static final String CLICHED_MESSAGE = "Hello World!";
 
@GET
@Produces("text/plain")
    public String getHello() {
        return CLICHED_MESSAGE;
    }
}
@Path("/users/{username}")

If it is required that a user name must only consist of lower and upper case numeric characters then it is possible to declare a particular regular expression,

which overrides the default regular expression, "[^/]+", for example:

In this type of example the username variable will only match user names that begin with one upper or lower case letter and zero or more alpha numeric

characters and the underscore character. If a user name does not match that a 404 (Not Found) response will occur.

A @Path value may or may not begin with a '/', it makes no difference. Likewise, by default, a @Path value may or may not end in a '/', it makes no difference,

and thus request URLs that end or do not end in a '/' will both be matched.

3.1.2. @GET, @PUT, @POST, @DELETE, ... (HTTP Methods)

@GET, @PUT, @POST, @DELETE and @HEAD are resource method designator annotations defined by JAX-RS and which correspond to the similarly

named HTTP methods. In the example above, the annotated Java method will process HTTP GET requests. The behavior of a resource is determined by which

of the HTTP methods the resource is responding to.

The following example is an extract from the storage service sample that shows the use of the PUT method to create or update a storage container:

Example 3.3. PUT method

By default the JAX-RS runtime will automatically support the methods HEAD and OPTIONS, if not explicitly implemented. For HEAD the runtime will invoke the

implemented GET method (if present) and ignore the response entity (if set). A response returned for the OPTIONS method depends on the requested media

type defined in the 'Accept' header. The OPTIONS method can return a response with a set of supported resource methods in the 'Allow' header or return a

WADL document. See wadl section for more information.

3.1.3. @Produces

The @Produces annotation is used to specify the MIME media types of representations a resource can produce and send back to the client. In this example,

the Java method will produce representations identified by the MIME media type "text/plain". @Produces can be applied at both the class and method levels.

Here's an example:

Example 3.4. Specifying output MIME type

The doGetAsPlainText method defaults to the MIME type of the @Produces annotation at the class level. The doGetAsHtml method's @Produces

annotation overrides the class-level @Produces setting, and specifies that the method can produce HTML rather than plain text.

If a resource class is capable of producing more that one MIME media type then the resource method chosen will correspond to the most acceptable media

type as declared by the client. More specifically the Accept header of the HTTP request declares what is most acceptable. For example if the Accept header is

"Accept: text/plain" then the doGetAsPlainText method will be invoked. Alternatively if the Accept header is " Accept: text/plain;q=0.9,

text/html", which declares that the client can accept media types of "text/plain" and "text/html" but prefers the latter, then the doGetAsHtml method will be

invoked.

More than one media type may be declared in the same @Produces declaration, for example:

Example 3.5. Using multiple output MIME types

The doGetAsXmlOrJson method will get invoked if either of the media types "application/xml" and "application/json" are acceptable. If both are equally

acceptable then the former will be chosen because it occurs first.

Optionally, server can also specify the quality factor for individual media types. These are considered if several are equally acceptable by the client. For

example:

Example 3.6. Server-side content negotiation

@Path("/users/{username}")

public class UserResource {

@GET

@Produces("text/xml")

public String getUser(@PathParam("username") String userName) {

...

}

1 @Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")

@PUT

public Response putContainer() {

System.out.println("PUT CONTAINER " + container);

URI uri = uriInfo.getAbsolutePath();

Container c = new Container(container, uri.toString());

Response r;

if (!MemoryStore.MS.hasContainer(c)) {

r = Response.created(uri).build();

} else {

r = Response.noContent().build();

}

MemoryStore.MS.createContainer(c);

return r;

}

@Path("/myResource")

@Produces("text/plain")

public class SomeResource {

@GET

public String doGetAsPlainText() {

...

}

@GET

@Produces("text/html")

public String doGetAsHtml() {

...

}

@GET

@Produces({"application/xml", "application/json"})

public String doGetAsXmlOrJson() {

...

}

In the above sample, if client accepts both "application/xml" and "application/json" (equally), then a server always sends "application/json", since

"application/xml" has a lower quality factor.

The examples above refers explicitly to MIME media types for clarity. It is possible to refer to constant values, which may reduce typographical errors, see the

constant field values of MediaType.

3.1.4. @Consumes

The @Consumes annotation is used to specify the MIME media types of representations that can be consumed by a resource. The above example can be

modified to set the cliched message as follows:

Example 3.7. Specifying input MIME type

In this example, the Java method will consume representations identified by the MIME media type "text/plain". Notice that the resource method returns void. This

means no representation is returned and response with a status code of 204 (No Content) will be returned to the client.

@Consumes can be applied at both the class and the method levels and more than one media type may be declared in the same @Consumes declaration.

3.2. Parameter Annotations (@*Param)

Parameters of a resource method may be annotated with parameter-based annotations to extract information from a request. One of the previous examples

presented the use of @PathParam to extract a path parameter from the path component of the request URL that matched the path declared in @Path.

@QueryParam is used to extract query parameters from the Query component of the request URL. The following example is an extract from the sparklines

sample:

Example 3.8. Query parameters

If a query parameter "step" exists in the query component of the request URI then the "step" value will be extracted and parsed as a 32 bit signed integer and

assigned to the step method parameter. If "step" does not exist then a default value of 2, as declared in the @DefaultValue annotation, will be assigned to the

step method parameter. If the "step" value cannot be parsed as a 32 bit signed integer then a HTTP 404 (Not Found) response is returned. User defined Java

types such as ColorParam may be used, which as implemented as follows:

Example 3.9. Custom Jav a type for consuming request parameters

In general the Java type of the method parameter may:

1. Be a primitive type;

2. Have a constructor that accepts a single String argument;

3. Have a static method named valueOf or fromString that accepts a single String argument (see, for example, Integer.valueOf(String) and

java.util.UUID.fromString(String));

4. Have a registered implementation of javax.ws.rs.ext.ParamConverterProvider JAX-RS extension SPI that returns a

javax.ws.rs.ext.ParamConverter instance capable of a "from string" conversion for the type. or

5. Be List<T>, Set<T> or SortedSet<T>, where T satisfies 2 or 3 above. The resulting collection is read-only.

Sometimes parameters may contain more than one value for the same name. If this is the case then types in 5) may be used to obtain all values.

If the @DefaultValue is not used in conjunction with @QueryParam and the query parameter is not present in the request then value will be an empty collection

@GET

@Produces({"application/xml; qs=0.9", "application/json"})

public String doGetAsXmlOrJson() {

...

}

@POST

@Consumes("text/plain")

public void postClichedMessage(String message) {

// Store the message

}

@Path("smooth")

@GET

public Response smooth(

@DefaultValue("2") @QueryParam("step") int step,

@DefaultValue("true") @QueryParam("min-m") boolean hasMin,

@DefaultValue("true") @QueryParam("max-m") boolean hasMax,

@DefaultValue("true") @QueryParam("last-m") boolean hasLast,

@DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,

@DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,

@DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) {

...

}

public class ColorParam extends Color {

public ColorParam(String s) {

super(getRGB(s));

}

private static int getRGB(String s) {

if (s.charAt(0) == '#') {

try {

Color c = Color.decode("0x" + s.substring(1));

return c.getRGB();

} catch (NumberFormatException e) {

throw new WebApplicationException(400);

}

} else {

try {

Field f = Color.class.getField(s);

return ((Color)f.get(null)).getRGB();

} catch (Exception e) {

throw new WebApplicationException(400);

}

forList, Set or SortedSet, null for other object types, and the Java-defined default for primitive types.

The @PathParam and the other parameter-based annotations, @MatrixParam, @HeaderParam, @CookieParam, @FormParam obey the same rules as

@QueryParam. @MatrixParam extracts information from URL path segments. @HeaderParam extracts information from the HTTP headers. @CookieParam

extracts information from the cookies declared in cookie related HTTP headers.

@FormParam is slightly special because it extracts information from a request representation that is of the MIME media type "application/x-www-form-

urlencoded" and conforms to the encoding specified by HTML forms, as described here. This parameter is very useful for extracting information that is

POSTed by HTML forms, for example the following extracts the form parameter named "name" from the POSTed form data:

Example 3.10. Processing POSTed HTML form

If it is necessary to obtain a general map of parameter name to values then, for query and path parameters it is possible to do the following:

Example 3.11. Obtaining ge neral map of URI path and/or query parameters

For header and cookie parameters the following:

Example 3.12. Obtaining ge neral map of header paramete rs

In general @Context can be used to obtain contextual Java types related to the request or response.

Because form parameters (unlike others) are part of the message entity, it is possible to do the following:

Example 3.13. Obtaining ge neral map of form parameters

I.e. you don't need to use the @Context annotation.

Another kind of injection is the @BeanParam which allows to inject the parameters described above into a single bean. A bean annotated with @BeanParam

containing any fields and appropriate *param annotation(like @PathParam) will be initialized with corresponding request values in expected way as if these

fields were in the resource class. Then instead of injecting request values like path param into a constructor parameters or class fields the @BeanParam can

be used to inject such a bean into a resource or resource method. The @BeanParam is used this way to aggregate more request parameters into a single

bean.

Example 3.14. Example of the bean which will be used as @BeanParam

Example 3.15. Injection of MyBeanParam as a method parameter:

The example shows aggregation of injections @PathParam, @QueryParam @MatrixParam and @HeaderParam into one single bean. The rules for injections

inside the bean are the same as described above for these injections. The @DefaultValue is used to define the default value for matrix parameter

matrixParam. Also the @Encoded annotation has the same behaviour as if it were used for injection in the resource method directly. Injecting the bean

parameter into @Singleton resource class fields is not allowed (injections into method parameter must be used instead).

@BeanParam can contain all parameters injections injections (@PathParam, @QueryParam, @MatrixParam, @HeaderParam, @CookieParam,

@FormParam). More beans can be injected into one resource or method parameters even if they inject the same request values. For example the following is

possible:

@POST

@Consumes("application/x-www-form-urlencoded")

public void post(@FormParam("name") String name) {

// Store the message

}

@GET

public String get(@Context UriInfo ui) {

MultivaluedMap<String, String> queryParams = ui.getQueryParameters();

MultivaluedMap<String, String> pathParams = ui.getPathParameters();

}

@GET

public String get(@Context HttpHeaders hh) {

MultivaluedMap<String, String> headerParams = hh.getRequestHeaders();

Map<String, Cookie> pathParams = hh.getCookies();

}

@POST

@Consumes("application/x-www-form-urlencoded")

public void post(MultivaluedMap<String, String> formParams) {

// Store the message

}

public class MyBeanParam {

@PathParam("p")

private String pathParam;

@MatrixParam("m")

@Encoded

@DefaultValue("default")

private String matrixParam;

@HeaderParam("header")

private String headerParam;

private String queryParam;

public MyBeanParam(@QueryParam("q") String queryParam) {

this.queryParam = queryParam;

}

public String getPathParam() {

return pathParam;

}

...

}

@POST

public void post(@BeanParam MyBeanParam beanParam, String entity) {

final String pathParam = beanParam.getPathParam(); // contains injected path parameter "p"

...

}

剩余145页未读，继续阅读

Hyman行之

粉丝: 13
资源: 70

Jersey 2.23.2用户指南：Maven项目创建与RESTful服务开发

synplify使用指导

Jboss Portal User Guild

UVM1.1User Guild

discord中client.get_guild 什么意思

discord.py 添加频道

let m_allGuildMsg = {}加值

python discord

create discord bot in javascript which count members online

discord API接口

写出显示每个门派年龄第二大的人的sql语句

discord欢迎机器人Python代码

Stwórz bota do discorda w języku javascript który będzie liczył osoby które są online

discord.py 获取频道列表

discord py 如何多个频道发消息

discord.py==1.7.3 如何获取频道信息

怎么实现想要跳转到 Discord 的某个特定频道或服务器

好像没有editChatPermissions方法啊

最新资源