Jersey - RESTfulなWebサービスのフレームワーク

Jerseyは、JavaでRESTfulなWebサービスを開発するためのフレームワークである。JerseyはJAX-RSをサポートしていて、JAX-RSのリファレンス実装ともなっている。

JerseyでRESTfulなWebサービスを作成する

JerseyでRESTfulなWebサービスを開発するには、次のものが必要になる。

Pleiades All in One (Java Full Edition)にはJDKとTomcatが含まれているので、簡単に開発環境を構築できる。また、Mavenを使うとJerseyを自動的にダウンロードできるうえ、プロジェクトの雛形を作成することができる。MavenもPleiades All in One (Java Full Edition)に含まれているので、今回はこれを使用する。

  1. Eclipseを起動する。
  2. Java EEパースペクティブを表示する。
    Java EEパースペクティブ
    Figure 1. Java EEパースペクティブ
  3. [ファイル]メニューを開いて、[新規] - [Maven プロジェクト]をクリックする。
    Maven プロジェクト
    Figure 2. Maven プロジェクト
  4. [新規Maven プロジェクト]ダイアログが表示されてロケーションの選択を求められるので、そのまま[次へ]ボタンをクリックする。
    新規Maven プロジェクト
    Figure 3. 新規Maven プロジェクト
  5. アーキタイプの選択を求められるので、[アーキタイプの追加]ボタンをクリックする。
    アーキタイプの選択
    Figure 4. アーキタイプの選択
  6. [アーキタイプの追加]ダイアログが表示されるので、各プロパティを入力して[完了]ボタンをクリックする。
    項目
    アーキタイプ・グループID org.glassfish.jersey.archetypes
    アーキタイプ・アーティファクトID jersey-quickstart-webapp
    アーキタイプ・バージョン 最新のバージョン(Maven Repositoryで確認する)
    リポジトリーurl 空欄のままでよい
    アーキタイプの追加
    Figure 5. アーキタイプの追加
  7. アーキタイプを選択して、[次へ]ボタンをクリックする。
    アーキタイプの選択
    Figure 6. アーキタイプの選択
  8. アーキタイプ・パラメータの指定を求められるので、各パラメータを入力して[完了]ボタンをクリックする。
    アーキタイプ・パラメーターの指定
    Figure 7. アーキタイプ・パラメーターの指定
  9. 指定した名前で新規Mavenプロジェクトが作成される。このとき、MyResource.javaやindex.jsp、pom.xmlなどのファイルも作成され、自動的にビルドが始まる。

    MyResource.java:

    package com.fc2web.itref.jersey_example;
    
    import javax.ws.rs.GET;
    import javax.ws.rs.Path;
    import javax.ws.rs.Produces;
    import javax.ws.rs.core.MediaType;
    
    /**
    * Root resource (exposed at "myresource" path)
    */
    @Path("myresource")
    public class MyResource {
    
      /**
       * Method handling HTTP GET requests. The returned object will be sent
       * to the client as "text/plain" media type.
       *
       * @return String that will be returned as a text/plain response.
       */
      @GET
      @Produces(MediaType.TEXT_PLAIN)
      public String getIt() {
          return "Got it!";
      }
    }

    index.jsp:

    <html>
      <body>
        <h2>Jersey RESTful Web Application!</h2>
        <p><a href="webapi/myresource">Jersey resource</a>
        <p>Visit <a href="http://jersey.java.net">Project Jersey website</a>
        for more information on Jersey!
      </body>
    </html>

    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.fc2web.itref</groupId>
      <artifactId>jersey-example</artifactId>
      <packaging>war</packaging>
      <version>0.0.1-SNAPSHOT</version>
      <name>jersey-example</name>
    
      <build>
        <finalName>jersey-example</finalName>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>2.5.1</version>
            <inherited>true</inherited>
            <configuration>
              <source>1.7</source>
              <target>1.7</target>
            </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-core</artifactId>
          <!-- use the following artifactId if you don't need servlet 2.x compatibility -->
          <!-- 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>
      <properties>
        <jersey.version>2.21</jersey.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
      </properties>
    </project>
  10. プロジェクトでエラーが発生しても、「javax.servlet.http.HttpServletが見つからない」というものなら問題ない。
    ビルドエラー
    Figure 8. ビルドエラー
  11. [サーバー]ビューを開き、[使用可能なサーバーがありません。このリンクをクリックして新規サーバーを作成してください]リンクをクリックする。
    サーバー ビュー
    Figure 9. サーバー ビュー
  12. 作成するサーバーのタイプを聞かれるので、任意のバージョンのTomcatを選択して、[次へ]ボタンをクリックする。
    新規サーバーの定義
    Figure 10. 新規サーバーの定義
  13. 追加するリソースを聞かれるので、作成したプロジェクトを選択して「追加」ボタンをクリックする。
    追加および除去
    Figure 11. 追加および除去
  14. [構成済み]に追加されるので、[完了]ボタンをクリックする。
    追加および除去
    Figure 12. 追加および除去
  15. 作成したサーバーを右クリックしてコンテキストメニューを表示させ、[開始]をクリックする。
    コンテキストメニュー
    Figure 13. コンテキストメニュー
  16. Webブラウザで「http://localhost:8080/jersey-example/」を表示する。
    Webブラウザ
    Figure 14. Webブラウザ
  17. 「Jersey Resorce」リンクをクリックする。
  18. 結果が表示される。
    結果の表示
    Figure 15. 結果の表示

WebサービスのレスポンスをJSON形式で返す

上記のWebサービスのレスポンスをJSON形式で返すよう修正する例を示す。

Mavenのpom.xmlを修正して、dependenciesに次の依存関係を追加する。pom.xmlは直接編集してもよいし、pom.xmlを選択してから右クリックしてコンテキストメニューから[Maven] - [依存関係の追加]をクリックしてもよい。

<dependency>
  <groupId>javax.xml.bind<groupId>
  <artifactId>jaxb-api</artifactId>
  <version>2.3.0</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson<artifactId>
</dependency>

社員を表すリソースとしてEmployeeをPOJOクラスで作成する。

package com.fc2web.itref.jersey_example;

/*
* 社員
*/
public class Employee {

  /** 番号 */
  public int no;

  /** 氏名 */
  public String name;

  /**
   * コンストラクタ
   * @param no 番号
   * @param name 氏名
   */
  public Employee(int no, String name) {
      this.no = no;
      this.name = name;
  }
}

リソースクラスを次のように修正する。

JavaのPOJOクラスであるEmployeeからJSON文字列への変換は自動的にやってくれるので、明示的に変換処理を記述する必要はない。

package com.fc2web.itref.jersey_example;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

/**
* Root resource (exposed at "myresource" path)
*/
@Path("myresource")
public class MyResource {

  /**
   * Method handling HTTP GET requests. The returned object will be sent
   * to the client as "application/json" media type.
   *
   * @return Employee that will be returned as a application/json response.
   */
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public String getIt() {
      Employee employee = new Employee(1, "Muto Ayami");
      return employee;
  }
}

Webブラウザで「http://localhost:8080/jersey-example/」を表示する。

「Jersey Resorce」リンクをクリックする。

WebブラウザにJSON文字列が表示される。

{"no":1,"name":"Muto Ayami"}

Mavenリポジトリ

Jerseyに関するMavenリポジトリを次の表に示す。

groupId artifactId 説明
org.glassfish.jersey jersey-bom Jersey Bill of Materials (BOM)
org.glassfish.jersey.containers jersey-container-servlet-core Jersey core Servlet 2.x implementation
org.glassfish.jersey.media jersey-media-json-jackson Jersey JSON Jackson (2.x) entity providers support module

Jackson

JacksonはJSONをパースするJavaライブラリである。JavaのオブジェクトをJSONに変換したり、JSONの文字列を受け取ってJavaのオブジェクトに変換できる。

JAR

JAR 説明
jackson-core-n.n.n.jar Jackson Core
jackson-dataind-n.n.n.jar Jackson Databind
jackson-annotations-n.n.n.jar Jackson Annotations

Maven

Mavenのpom.xml

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>2.9.2</artifactId>
</dependency>

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.9.2</artifactId>
</dependency>

<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotasions -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <version>2.9.2</artifactId>
</dependency>