Jersey the RESTful Web Services in Java

Jersey 是一个JAX-RS的实现, JAX-RS即Java API for RESTful Web Services, 支持按照表述性状态转移(REST)架构风格创建Web服务. REST 中最重要的概念是资源(resources)，使用Global ID (通常使用 URI)标识. 客户端应用程序使用 HTTP 方法 GET/ POST/ PUT/ DELETE 操作资源或资源集. RESTful Web 服务是使用 HTTP 和 REST 原理实现的 Web 服务. 通常, RESTful Web 服务应该定义以下方面:

Web 服务的基/根 URI，比如 http://host/<appcontext>/resources
支持 MIME 类型的响应数据，包括 JSON/XML/ATOM 等等
服务支持的操作集合, 例如 POST, GET, PUT 或 DELET.

JAX-RS 提供一个部署检测的抽象类Application用于声明根资源和提供对应的类, 在支持Servlet 3.0及以上的容器上, 可以不需要web.xml来部署. 仅需要在某个class上使用@ApplicationPath, 并扩展Application

@ApplicationPath("/*")
public class MyApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<Class<?>>();
        s.add(HelloWorldResource.class);
        return s;
    }
    ...
}

而Jersey提供了自己实现的方式, 可以更便利地使用其高级特性

@ApplicationPath("resources")
public class MyApplication extends ResourceConfig {
    public MyApplication() {
        packages("org.foo.rest;org.bar.rest");
    }
}

此时要在pom.xml中添加 failOnMissingWebXml 以免构建中出现丢失web.xml的错误

<plugins>
    ...
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.3</version>
        <configuration>
            <failOnMissingWebXml>false</failOnMissingWebXml>
        </configuration>
    </plugin>
    ...
</plugins>

在MyApplication()的初始化方法中,

packages("com.aa.bb", "com.aa.cc");可以提供多个用于自动扫描的包路径. 这些路径下, 就是标注了 @Path, @Produces, @GET等信息的资源类.

register()方法用于注册各种组件

使用Maven创建一个Jersey项目:

mvn archetype:generate -DarchetypeGroupId=org.glassfish.jersey.archetypes -DarchetypeArtifactId=jersey-quickstart-webapp -DarchetypeVersion=2.22. -DinteractiveMode=false -DgroupId=com.nz -DartifactId=longinus -Dpackage=com.nz

如果要使用上面的servlet 3.0特性不带web.xml启动, 需要修改下pom.xml

注意里面的这段话

        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet-core</artifactId>
            <!-- use the following artifactId if you don't need servlet 2.x compatibility -->
            <!-- artifactId>jersey-container-servlet</artifactId -->
        </dependency>

需要去掉和servlet 2.x的兼容, 然后就能以不带web.xml的形式启动了

        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
        </dependency>

最后的pom.xml是这样的

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 
    <modelVersion>4.0.0</modelVersion>
 
    <groupId>com.rockbb</groupId>
    <artifactId>foobar</artifactId>
    <packaging>war</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>foobar</name>
 
    <properties>
        <jersey.version>2.22.1</jersey.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
 
    <build>
        <finalName>foobar</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.3</version>
                <inherited>true</inherited>
                <configuration>
                    <source>1.7</source>
                    <target>1.7</target>
                    <encoding>${project.build.sourceEncoding}</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <configuration>
                    <encoding>${project.build.sourceEncoding}</encoding>
                </configuration>
            </plugin>
            <plugin>
                            <groupId>org.apache.maven.plugins</groupId>
                            <artifactId>maven-war-plugin</artifactId>
                            <version>2.3</version>
                            <configuration>
                                <failOnMissingWebXml>false</failOnMissingWebXml>
                            </configuration>
                        </plugin>
        </plugins>
    </build>
 
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.glassfish.jersey</groupId>
                <artifactId>jersey-bom</artifactId>
                <version>${jersey.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
 
    <dependencies>
        <dependency>
            <groupId>org.glassfish.jersey.containers</groupId>
            <artifactId>jersey-container-servlet</artifactId>
        </dependency>
        <!-- uncomment this to get JSON support
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-moxy</artifactId>
        </dependency>
        -->
    </dependencies>
</project>

jersey常用注解解释：           

Annotation	作用	说明
@GET	查询请求	相当于数据库的查询数据操作
@POST	插入请求	相当于数据库的插入数据操作
@PUT	更新请求	相当于数据库的更新数据操作
@DELETE	删除请求	相当于数据的删除数据操作
@Path	uri路径	定义资源的访问路径，client通过这个路径访问资源。比如：@Path("user")
@Produces	指定返回MIME格式	资源按照那种数据格式返回，可取的值有：MediaType.APPLICATION_XXX。比如：@Produces(MediaType.APPLICATION_XML)
@Consumes	接受指定的MIME格式	只有符合这个参数设置的请求再能访问到这个资源。比如@Consumes("application/x-www-form-urlencoded")
@PathParam	uri路径参数	写在方法的参数中，获得请求路径参数。比如：@PathParam("username")  String userName
@QueryParam	uri路径请求参数	写在方法的参数中，获得请求路径附带的参数。比如：@QueryParam("desc")  String desc
@DefaultValue	设置@QueryParam参数的默认值	如果@QueryParam没有接收到值，就使用默认值。比如：@DefaultValue("description") @QueryParam("desc") String desc
@FormParam	form传递的参数	接受form传递过来的参数。比如：@FormParam("name")  String userName
@BeanParam	通过Bena的形式传递参数	接受client传递的bean类型的参数，同时这个bean可以在属性上配置@FormParam用以解决client的属性名称和bean的属性名称不一致的问题。比如：@BeanParam  User user
@Context	获得一些系统环境信息	通过@Context可以获得以下信息：UriInfo、ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse和HttpHeaders等
@XmlRootElement	将bean转换为xml	如果要讲bean以xml或json的格式返回，必须要这个注解。比如： @XmlRootElement public class User｛...｝
@XmlElements
@XmlElement