Table of Contents
1.1. Maven Archetype で新しいプロジェクトを作る
1.2. 新しく作られたプロジェクトを探検する
1.3. プロジェクトを実行する
1.4. JavaEE ウェブアプリケーションを作る
1.5. Heroku に配備できるウェブアプリケーションを作る
1.6. 他の Jersey Example を探検する
以下は、２０１９年１月時点の、https://jersey.github.io/documentation/latest/getting-started.html の kanda.motohiro@gmail.com による抄訳です。GNU General Public License Version 2 only ("GPL") or the Common Development and Distribution License("CDDL") のもとで公開します。 Google site に置く都合で、原文とレイアウトなどは変わります。xml ファイルを添付するので、ご自由に mvn package 下さい。
この章は Jersey を使って RESTful なサービスを作り始める方法を、簡潔に紹介します。 ここで示す例は、軽量の Grizzly HTTP サーバーを使います。 この章が終わる頃にはあなたは、同じ機能を、Servlet 2.5 以上をサポートするサーブレット コンテナ上ならどこにでも配備することのできる JavaEE ウェブアプリケーションとして実装する方法を理解するでしょう。
Jersey プロジェクトは、 Apache Maven ソフトウェアプロジェクトビルドと管理ツールを使ってビルドされます。 Jersey プロジェクトビルドの一部として開発された全てのモジュールは、 Central Maven Repository にプッシュされます。 このため、Maven ベースのプロジェクトならどれでも、Jersey を使って作業することはとても簡単です。 全てのリリースされた（SNAPSHOT でない） Jersey への依存は、特別な maven リポジトリを設定しなくても、 ただちに Jersey モジュールを引っ張ってこられるからです。
Jersey モジュールの最新の SNAPSHOT バージョンに依存したい場合、 あなたの Maven プロジェクト pom に以下のリポジトリ設定を加える必要があります。
<repository>
<id>snapshot-repository.java.net</id>
<name>Java.net Snapshot Repository for Maven</name>
<url>https://maven.java.net/content/repositories/snapshots/</url>
<layout>default</layout>
</repository>
Jersey で作業するために最も便利な方法は、 Maven プロジェクトから始めることですから、このアプローチ でやってみましょう。 これから、Grizzly コンテナの上で動く新しい Jersey プロジェクトを作りましょう。 Jersey が提供する maven archetype を使います。 プロジェクトを作るには、以下の 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.28-SNAPSHOT
あなたの新しいプロジェクトの groupId, package そして／あるいは artifactId を修正ください。 あるいは、新しいプロジェクトの pom.xml が生成された後でそれを更新することもできます。
Jersey maven archetype を使ったプロジェクト生成が成功したら、 現在の位置に作成された、新しい simple-service プロジェクトディレクトリを見ましょう。 そのディレクトリは、標準的な Maven プロジェクトの構造を持っています。
プロジェクトのビルドと管理の設定は、プロジェクトのルートディレクトリにある pom.xml に書いてあります。
プロジェクトのソースは、 src/main/java の下にあります。
プロジェクトのテストソースは、 src/test/javaの下にあります。
com.example パッケージのソースディレクトリには、 ２つのクラスがあります。 Main クラスは、Grizzly コンテナをブートストラップすることと、 このプロジェクトの JAX-RS アプリケーションをコンテナに設定し配備する役割を果たします。 同じパッケージのもう一つのクラスは、MyResource クラスです。これが、単純な JAX-RS リソースの実装を持ちます。 こんな風です。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
package com.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!";
}
}
JAX-RS リソースは、アノテートされた POJO であり、 いわゆるリソースメソッドを提供します。 それは、そのリソースが束縛された URI パスへの HTTP 要求を処理することができます。 JAX-RS リソースの完全なガイドは、Chapter 3, JAX-RS Application, Resources and Sub-Resources を参照ください。 私達の場合、このリソースは、単一のリソースメソッドを公開します。それは、HTTP GET 要求を 処理することができ、/myresource URI パスに束縛され、 "text/plain" メディアタイプで表現される応答メッセージコンテントを 使った応答を生成することができます。 このバージョンでは、このリソースは全てのクライアント要求に、同じ "Got it!" 応答を 返します。
このスケルトンプロジェクトで生成された最後のコード部品は、MyResourceTest ユニットテストクラスであり、MyResource クラスと同じ、com.example パッケージにあります。 しかし、このユニットテストクラスは、maven プロジェクトのテストソースディレクトリ src/test/java にあります。 （簡単のため、一部のコードコメントと JUnit import は除いてあります。）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
package com.example;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import org.glassfish.grizzly.http.server.HttpServer;
...
public class MyResourceTest {
private HttpServer server;
private WebTarget target;
@Before
public void setUp() throws Exception {
server = Main.startServer();
Client c = ClientBuilder.newClient();
target = c.target(Main.BASE_URI);
}
@After
public void tearDown() throws Exception {
server.stop();
}
/**
* Test to see that the message "Got it!" is sent in the response.
*/
@Test
public void testGetIt() {
String responseMsg = target.path("myresource").request().get(String.class);
assertEquals("Got it!", responseMsg);
}
}
このユニットテストでは、テスト setUp() メソッドにおいて、 Main.startServer()への静的コールによって、 最初に Grizzly コンテナが開始され、サーバーアプリケーションが配備されます。 次に、同じテストセットアップメソッドで JAX-RS クライアントコンポーネントが作成されます。 最初に、新しい JAX-RS クライアントインスタンス c が作られ、 次に、http://localhost:8080/myapp/ （Main.BASE_URI 定数の値） に配備された私達のアプリケーションのコンテキストルートを指す JAX-RS ウェブターゲットコンポーネント がそのユニットテストクラスの target フィールドに 格納されます。 次にこのフィールドが実際のテストメソッド (testGetIt()) で使われます。
testGetIt() メソッドでは、能弁な JAX-RS Client API を使って、 /myresource URI でリスンしている MyResource JAX-RS リソースクラス に接続して、 HTTP GET 要求を送ります。 同じ能弁な JAX-RS API 発行のチェーンの一部として、 応答が、Java String 型として読まれます。 テストメソッドの２行目で、サーバから返された応答コンテント文字列は、テストアサーションの中で、 期待されるフレーズと比較されます。 JAX-RS Client API についてより詳しくは、Chapter 5, Client API の章を参照ください。
プロジェクトの中身を見たので、さあそれをテスト実行してみましょう。 そのためには、以下のコマンドをコマンドラインで実行します。
これは、このプロジェクトをコンパイルして、このプロジェクトのユニットテストを走らせます。 ビルドが終わったら、ビルドの成功を告げるこのような出力があるはずです。
Results : Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 34.527s [INFO] Finished at: Sun May 26 19:26:24 CEST 2013 [INFO] Final Memory: 17M/490M [INFO] ------------------------------------------------------------------------
さて、プロジェクトがコンパイルし、ユニットテストが合格することを確かめたので、 このアプリケーションをスタンドアロンモードで実行することができます。 そのためには、以下の maven コマンドを実行します。
アプリケーションが開始し、しばらくしてコンソールに以下の通知が見えるはずです。
May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.NetworkListener start INFO: Started listener bound to [localhost:8080] May 26, 2013 8:08:45 PM org.glassfish.grizzly.http.server.HttpServer start INFO: [HttpServer] Started. Jersey app started with WADL available at http://localhost:8080/myapp/application.wadl Hit enter to stop it...
これは、アプリケーションが開始して、その WADL 記述子が http://localhost:8080/myapp/application.wadl URL にあることを通知します。 WADL コンテントは、 curl http://localhost:8080/myapp/application.wadl コマンドをコンソールで実行するか、 お好みのブラウザで、WADL URL をタイプすれば得られます。 あなたが配備した、RESTful アプリケーションを WADL 形式で記述する XML ドキュメントが、返ってくるはずです。 WADL を使った作業についてもっと知るには、Chapter 17, WADL Support の章をチェック下さい。
この節を終わる前に試すべき最後のことは、/myresource パスに配備された 私達のリソースと通信できるか確かめることです。 同様に、ブラウザでリソース URL をタイプしても、curl を使っても良いです。
$ curl http://localhost:8080/myapp/myresource Got it!
ご覧のように、curl コマンドは、私達のリソースが送った Got it! メッセージを返しました。 curl コマンドが、応答についてより多くの情報を提供するように指定することもできます。 例えば、-i スイッチを使えば、全てのレスポンスヘッダが表示されます。
curl -i http://localhost:8080/myapp/myresource HTTP/1.1 200 OK Content-Type: text/plain Date: Sun, 26 May 2013 18:27:19 GMT Content-Length: 7 Got it!
ここでは、私達の Jersey/JAX-RS アプリケーションが返した応答メッセージの完全な内容が見えます。 それは、全ての HTTP ヘッダを含みます。 Content-Type: text/plain ヘッダは、MyResource クラスに アタッチした @Produces アノテーションの値に由来することに注意ください。
curl クライアントと、Grizzly I/O コンテナ内の Jersey 上で動いている私達のリソースの間の 通信について、もっと詳細に見たければ、 curl の提供する、多くの他のオプションとスイッチを 自由に試して下さい。 例えば、この最後のコマンドは、curl が通信全体について多くの追加の情報を出力する ようにさせます。
$ curl -v http://localhost:8080/myapp/myresource * About to connect() to localhost port 8080 (#0) * Trying ::1... * Connection refused * Trying 127.0.0.1... * connected * Connected to localhost (127.0.0.1) port 8080 (#0) > GET /myapp/myresource HTTP/1.1 > User-Agent: curl/7.25.0 (x86_64-apple-darwin11.3.0) libcurl/7.25.0 OpenSSL/1.0.1e zlib/1.2.7 libidn/1.22 > Host: localhost:8080 > Accept: */* > < HTTP/1.1 200 OK < Content-Type: text/plain < Date: Sun, 26 May 2013 18:29:18 GMT < Content-Length: 7 < * Connection #0 to host localhost left intact Got it!* Closing connection #0
WAR にパッケージして、サーブレットコンテナに配備することのできるウェブアプリケーションを作成するのは、 Section 1.1, “Maven Archetype で新しいプロジェクトを作る”で説明した処理と同様にすることができます。 Grizzly ベースの archetype に加えて、 Jersey はウェブアプリケーションスケルトンを作成するための Maven archetype も 提供します。 新しいウェブアプリケーションスケルトンプロジェクトを作成するには、 以下の Maven コマンドを、新しいプロジェクトを置くディレクトリで 実行ください。
mvn clean test
mvn exec:java
mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-webapp \
-DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false \
-DgroupId=com.example -DartifactId=simple-service-webapp -Dpackage=com.example \
-DarchetypeVersion=2.28-SNAPSHOT
Grizzly ベースのプロジェクトと同様、 あなたの新しいウェブアプリケーションプロジェクトの groupId, package そして／あるいは artifactId を修正ください。 あるいは、新しいプロジェクトの pom.xml が生成された後でそれを更新することもできます。
Jersey maven archetype を使ったプロジェクト生成が成功したら、 現在の位置に、新しい simple-service-webapp プロジェクトディレクトリができているはずです。 そのディレクトリは、以前見た、simple-service プロジェクトの内容と同様の、 標準的な Maven プロジェクトの構造を持っています。 例外は、それが、ウェブアプリケーション特有の余分のコンテントで拡張されていることです。
プロジェクトは、同じ MyResouce JAX-RS リソースクラスを持ちます。 それは、ユニットテストは持たず、前のプロジェクトで Grizzly コンテナをセットアップ するために使われた Main クラスも持ちません。 その代わりに、それは、標準 Java EE ウェブアプリケーションの web.xml 配備記述子を、 src/main/webapp/WEB-INF の下に持ちます。 このプロジェクトの最後のコンポーネントは、このアプリケーションにパッケージされ配備される MyResource リソースクラスのクライアントとしてそれを提供する index.jsp ページです。
アプリケーションをコンパイルして、 WAR にパッケージするには、以下の maven コマンドをコンソールで実行下さい。
ビルドが成功したら以下のような出力が生成されるでしょう。
Results : Tests run: 0, Failures: 0, Errors: 0, Skipped: 0 [INFO] [INFO] --- maven-war-plugin:2.1.1:war (default-war) @ simple-service-webapp --- [INFO] Packaging webapp [INFO] Assembling webapp [simple-service-webapp] in [.../simple-service-webapp/target/simple-service-webapp] [INFO] Processing war project [INFO] Copying webapp resources [.../simple-service-webapp/src/main/webapp] [INFO] Webapp assembled in [75 msecs] [INFO] Building war: .../simple-service-webapp/target/simple-service-webapp.war [INFO] WEB-INF/web.xml already added, skipping [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 9.067s [INFO] Finished at: Sun May 26 21:07:44 CEST 2013 [INFO] Final Memory: 17M/490M [INFO] ------------------------------------------------------------------------
さてこれで、パッケージされた WAR （./target/simple-service-webapp.war にあります。） を、お好みのサーブレットコンテナに配備する準備ができました。
Jersey アプリケーションを配備するには、Servlet 2.5 以上をサポートするサーブレットコンテナが必要です。 高度な機能（JAX-RS 2.0 Async Support のような）を得るには、Servlet 3.0 以上に適合するコンテナが必要です。
略
以上の節で、Jersey で何かをするアプローチを、簡潔に述べました。 Jersey と JAX-RS についてより多くを学ぶためには、Jersey User Guide の他の節を参照ください。 User Guide ではできる限り多くのことを述べるように最善の努力をしましたが、 あなたが解こうとしている問題の完全な回答を得ることのできない可能性は常にあります。 その場合は、example を探すことを考慮下さい。それは、あなたがご自分のプロジェクトで使いたいと思う 機能のそれ以上の知識とヒントを提供します。
Jersey コードベースには、いろいろな Jersey と JAX-RS の機能をどのように使うかについての 便利な例がたくさんあります。 Jersey ソースリポジトリにある、Jersey Examples の個々のコードをのぞいてみてください。 オフラインで見るために、 ここから、全ての例をバンドルしたものをダウンロードすることもできます。
mvn clean package