Java RESTful

REST 服务类型

在 REST 服务中，资源类是接收 REST 请求并完成响应的核心类，而资源类是由 REST 服务的“提供者[JAX-RS 2.0 定义的 javax.ws.rs.core.Application 以及 Servlet]”来调度的。

Application 类，相当于 JAX-RS 2.0 服务的入口。作为应用的入口，Application 需要知道具体的资源文件，可以通过包扫描或直接指定类文件的方式获得．

如果 REST 服务没有自定义的 Application 子类，容器将默认生成一个javax.ws.rs.core.Application 类。

根据规范对 REST 服务场景的定义，将 REST 服务分为 4 种类型：

REST 服务类型示意图

类型一：相应的逻辑，是服务中同时不存在 Application 的子类和 Servlet 的子类。

servlet 2.x

  // pom
  <dependency>
      <groupId>org.glassfish.jersey.containers</groupId>
      <!-- jersey-container-servlet-core 不具备自动扫描资源类的功能。 -->
      <artifactId>jersey-container-servlet-core</artifactId>
  </dependency>
  
  // web.xml
  <servlet>
      <servlet-name>Jersey Web Application</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
      <init-param>
          <param-name>jersey.config.server.provider.packages</param-name>
          <param-value>com.example</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
      <servlet-name>Jersey Web Application</servlet-name>
      <url-pattern>/webapi/*</url-pattern>
  </servlet-mapping>

servlet 3.x

  // pom
  <dependency>
      <groupId>org.glassfish.jersey.containers</groupId>
      <!-- use the following artifactId if you don't need servlet 2.x compatibility -->
      <artifactId>jersey-container-servlet</artifactId>
  </dependency>
  
  // web.xml
  <servlet>
      <servlet-name>javax.ws.rs.core.Application</servlet-name>
  </servlet>
  <servlet-mapping>
      <servlet-name>javax.ws.rs.core.Application</servlet-name>
      <url-pattern>/webapi/*</url-pattern>
  </servlet-mapping>

类型二：相应的逻辑，是服务中不存在 Application 的子类，但存在 Servlet 的子类。

自定义 servlet 3.x 子类的场景

  // servlet 子类，继承自 org.glassfish.jersey.servlet.ServletContainer
  @WebServlet(
  initParams = @WebInitParam(name = "jersey.config.server.provider.packages", value = "com.example"), 
  urlPatterns = "/webapi/*", 
  loadOnStartup = 1)
  public class AirServlet extends ServletContainer {
      private static final long serialVersionUID = 1L;
  }
  
  // pom.xml
  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>2.3</version>
      <configuration>
          <failOnMissingWebXml>false</failOnMissingWebXml>
      </configuration>
  </plugin>
  
  <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>3.1.0</version>
      <scope>provided</scope>
  </dependency>
  <dependency>
      <groupId>org.glassfish.jersey.containers</groupId>
      <artifactId>jersey-container-servlet</artifactId>
  </dependency>
  
  // 无 web.xml 配置

类型三：相应的逻辑，是存在Application的子类，并定义了@ApplicationPath 注解。

servlet 2.x

   // 继承自 Application 的子类 org.glassfish.jersey.server.ResourceConfig
   @ApplicationPath("/webapi/*")
   public class AirResourceConfig extends ResourceConfig {
   
       public AirResourceConfig() {
           // 构造中提供扫描包的全名「启动后，包内资源类提供的资源路径将被映射到内存」
           packages("com.example.s2x.c3");
       }
   }
   
   // pom.xml
   <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>
   
   <dependency>
       <groupId>org.glassfish.jersey.containers</groupId>
       <artifactId>jersey-container-servlet-core</artifactId>
   </dependency>
   
   // 需要定义 web.xml ，但内容可以是“空的”，只有 web-app 的基本定义

servlet 3.x
// 继承自 Application 类
@ApplicationPath("/webapi/*")
public class AirApplication extends Application {

       @Override
       public Set<Class<?>> getClasses() {
           final Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyResource.class);
           return classes;
       }
       
   }
   
   // pom.xml
   <dependency>
       <groupId>org.glassfish.jersey.containers</groupId>
       <artifactId>jersey-container-servlet</artifactId>
   </dependency>
   
   //　可以省略 web.xml

类型四：相应的逻辑，是“一有二无”：一有是存在 Application 的子类，二无是不存在 Servlet 子类、不存在或者不允许使用 @ApplicationPath 注解。

servlet 2.x

   // 继承自 Application 类
   public class AirApplication extends Application {
       @Override
       public Set<Class<?>> getClasses() {
           final Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(MyResource.class);
           return classes;
       }
   }
   
   // web.xml
   <servlet>
       <servlet-name>Jersey Web Application</servlet-name>
       <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
       <init-param>
           <param-name>javax.ws.rs.Application</param-name>
           <param-value>com.example.AirApplication</param-value>
       </init-param>
       <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
       <servlet-name>Jersey Web Application</servlet-name>
       <url-pattern>/webapi/*</url-pattern>
   </servlet-mapping>
   
   // pom.xml
   <dependency>
       <groupId>org.glassfish.jersey.containers</groupId>
       <artifactId>jersey-container-servlet-core</artifactId>
   </dependency>

servlet 3.x

      // 继承自 Application 类
      public class AirApplication extends Application {
          @Override
          public Set<Class<?>> getClasses() {
              final Set<Class<?>> classes = new HashSet<Class<?>>();
              classes.add(MyResource.class);
              return classes;
          }
      }
      
      // web.xml
     <servlet>
          <servlet-name>com.example.AirApplication</servlet-name>
      </servlet>
      <servlet-mapping>
          <servlet-name>com.example.AirApplication</servlet-name>
          <url-pattern>/webapi/*</url-pattern>
      </servlet-mapping>
      
      // pom.xml
      <dependency>
          <groupId>org.glassfish.jersey.containers</groupId>
          <artifactId>jersey-container-servlet</artifactId>
      </dependency>