目的和综述

1. 实现JAX-RS API规范，提供固定周期的发布；
2. 提供扩展Api提供自定义的开发功能；
3. 更简单的使用java开发RESFull应用

仅仅core-common and core-client可以使用java6，其他模块需要使用java7

使用maven创建

创建一个直接执行的空工程

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.24

创建一个可以打包为war的空工程mvn clean package

mvn archetype:generate -DarchetypeArtifactId=jersey-heroku-webapp -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false -DgroupId=com.example -DartifactId=simple-heroku-webapp -Dpackage=com.example -DarchetypeVersion=2.24

jersey 范例

https://github.com/jersey/jersey/tree/2.24/examples

配置资源

• @Path 配置资源的相对路径,路径前后无所谓有没有‘/’
  • @Path("/users")
  • @Path("/users/{username}") 传入参数
  • @Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}") 限制参数路径格式
• @GET, @PUT, @POST, @DELETE, @HEAD, ... (HTTP Methods)
  • 默认支持HEAD,OPTIONS请求
  • HEAD请求会忽略返回的结果
  • OPTIONS 方法可以根据请求头的Accept字段返回对应结果
• @Produces设置请求返回的MIME类型
  • 放在类上，代表本类默认没有@Produces类型的都使用默认类型
  • 范例@Produces("text/html")， @Produces({"application/xml", "application/json"})；
• @Consumes 可接受的类型
• @*Param 参数注解

  • @QueryParam 从Url请求上请求的参数

    @Path("smooth")
    @GET
    public Response smooth(
        @DefaultValue("2") @QueryParam("step") int step,
        @DefaultValue("true") @QueryParam("max-m") boolean hasMax,
        @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) {
        ...
    }
    

    • 参数类型要求
      1. 为基础类型；
      2. 有一个参数类型为String构造函数；
      3. 有一个Strig参数的静态方法，名称为valueOf、fromString；
      4. 实现接口javax.ws.rs.ext.ParamConverterProvider;
      5. 类型为List<T>, Set<T> or SortedSet<T>, 且T类型满足第2、3条；

  • 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 从MIME类型为 "application/x-www-form-urlencoded"的请求中提取参数。

    @POST
    @Consumes("application/x-www-form-urlencoded")
    public void post(@FormParam("name") String name) {
        // Store the message
    }
    

  • @BeanParam 将所有参数转换成一个Bean

    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"
        ...
    }
    

  • 可以使用@Context注入HttpHeaders, Request, UriInfo, SecurityContext.

获取所有参数

~~~
@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
}
~~~

子资源

@Path("/item")
public class ItemResource {
    @Context UriInfo uriInfo;
 
    @Path("content")
    public ItemContentResource getItemContentResource() {
        return new ItemContentResource();
    }
 
    @GET
    @Produces("application/xml")
        public Item get() { ... }
    }
}
 
public class ItemContentResource {
 
    @GET
    public Response get() { ... }
 
    @PUT
    @Path("{version}")
    public void put(@PathParam("version") int version,
                    @Context HttpHeaders headers,
                    byte[] in) {
        ...
    }
}

默认资源类都是prototype,当使用@Singleton时可以控制为案例

资源文件定义可以通过继承Application实现

*  ResourceConfig默认实现

使用java spi方式查找META-INF/services/中提供的实现