![RESTとは
●
HTTPを用いた簡易的なRPC
– クライアントはサービスを呼び出すために、手続きに対しHTTPリク
エストする（例：検索、追加）
– URIに動詞が含まれることが多い(例：deleteXxx)
– GETやPOSTが用いられることが多い
– 例：Amazon API
GET
http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[AWS アクセスキー ID]&
AssociateTag=[Associate Tag]&
Operation=CartClear&
CartId=[Cart ID]&
HMAC=[URL-encoded HMAC]
6](https://image.slidesharecdn.com/beginning-javaee6-15-120703141543-phpapp01/85/Beginning-Java-EE-6-7-bje_study-6-320.jpg)
Beginning Java EE 6 勉強会(7) #bje_study
- 1. Beginning Java EE 6 勉強会(7) -RESTful Webサービス(JAX-RS)- 担当者：ikeyat 2012/07/04
- 2. アンケート • REST知ってますか？ – 知らない – 聞いたことがある – 使ったことがある – 人に説明することができる 2
- 3. INDEX ● REST ● JAX-RS 3
- 4. REST
- 5. RESTとは ● Webサービスのアーキテクチャスタイルの一つ – 仕様や実装ではない – もちろんプロトコルでもない（SOAPはプロトコル） ● 二つの意味で使用されている – HTTPを用いた簡易的なRPC – Roy Fieldingが提唱するWebサービスアーキテクチャスタイル 5
- 6. RESTとは ● HTTPを用いた簡易的なRPC – クライアントはサービスを呼び出すために、手続きに対しHTTPリク エストする（例：検索、追加） – URIに動詞が含まれることが多い(例：deleteXxx) – GETやPOSTが用いられることが多い – 例：Amazon API GET http://ecs.amazonaws.com/onca/xml? Service=AWSECommerceService& AWSAccessKeyId=[AWS アクセスキー ID]& AssociateTag=[Associate Tag]& Operation=CartClear& CartId=[Cart ID]& HMAC=[URL-encoded HMAC] 6
- 7. RESTとは ● Roy Fieldingが提唱するWebサービスアーキテク チャスタイル – クライアントはサービスを呼び出すために、リソースに対しHTTPリ クエストする（例：本、カテゴリ） – URIは名詞である(例：book、books、categories) – リソースに対する手続きの種類はCRUDで、HTTPのメソッドで指定 する（GET/POST/PUT/DELETE） – 本書ではこちらに従う DELETE http://www.apress.com/books/1023 7
- 8. RESTとは ● Roy Fielding式RESTを学ぶ上で必要な知識=We b – リソースとURI – 表現 – HTTP ● メソッド ● コンテンツ・ネゴシエーション ● ステータスコード ● キャッシュ 8
- 9. Web ● リソース – 参照もしくは操作の対象となるサーバ上のオブジェクト。 – 例： ● Apress社のJavaに関する書籍のリスト ● 書籍『The Definitive Guide to Grails』 ● Ola Biniの経歴 ● URI – Web上のリソースを特定する識別子。内容が分かるような文字列にするとよい。 – 例： ● http://www.apress.com/book/catalog ● http://www.weather.com/weather/2008?location=Paris ● http://www.flickr.com/explore/interesting/2009/01/01 9
- 10. Web ● 表現 – リソースをクライアントで扱う際の形式。 ● 例：テキスト、HTML、XML、JSON、JPG画像、PDF – 必要に応じて、一つのリソースに対し複数の表現を用意することも ある。 ● 例：書籍一覧のHTML、書籍一覧CSV – クライアントが表現を選択する方法 ● URIを拡張子などで分ける方法 – http://xxxxxx/xxx/books.html – http://xxxxxx/xxx/books.csv ● コンテンツ・ネゴシエーションを使用する方法（後述） 10
- 11. Web ● HTTP リクエスト例 レスポンス例 HTTP/1.1 200 OK Date: Mon, 23 Feb 2009 07:28:09 GMT Server: Apache/2.0.63 (Unix) PHP/5.2.6 GET /book/catalog?category=32 HTTP/1.1 Set-Cookie: XX=YYYYYY User-Agent: xxxxxx Expires: Thu, 19 Nov 1981 08:52:00 GMT Host: www.apress.com Cache-Control: no-store, no-cache, … Accept: */* Pragma: no-cache Transfer-Encoding: chunked Content-Type: text/html <!DOCTYPE HTML> <html> <head> <GETの場合は空> <title> <body> ... 11
- 12. Web ● HTTP ステータスコード リクエスト例 メソッド レスポンス例 HTTP/1.1 200 OK Date: Mon, 23 Feb 2009 07:28:09 GMT Server: Apache/2.0.63 (Unix) PHP/5.2.6 GET /book/catalog?category=32 HTTP/1.1 Set-Cookie: XX=YYYYYY User-Agent: xxxxxx Expires: Thu, 19 Nov 1981 08:52:00 GMT Host: www.apress.com Cache-Control: no-store, no-cache, … Accept: */* コンテンツ Pragma: no-cache ネゴシエーション Transfer-Encoding: chunked Content-Type: text/html <!DOCTYPE HTML> <html> <head> <GETの場合は空> <title> <body> ... 12
- 13. Web ● メソッド – リソースに対する操作の種類。主にGET/POST/PUT/DELETEを 用いる。 メソッド CRUD リソース変化 HTTP本体 GET R なし なし リソースの返却を要 求する POST C あり あり リソースの新規作成 を要求する PUT U あり あり リソースの更新を要 求する DELETE D あり なし リソースの削除を要 求する 他にもHEAD/TRACE/OPTIONS/CONNECTがあります 13
- 14. Web ● コンテンツ・ネゴシエーション – 使用可能な「表現」が複数存在する時に、最適な表現を選択する プロセス。 – クライアントはHTTPリクエストヘッダで要求する表現を指定できる。 サーバはこれに応じた表現を返却するのが望ましい。 ● Accept：コンテンツ・タイプ ● Accept-Charset：文字コード ● Accept-Encoding：エンコード ● Accept-Language：言語 14
- 15. Web ● コンテンツ・タイプ – text/html – text/plain – image/gif, image/jpeg, image/png – text/xml, application/xml – application/json 15
- 16. Web ● ステータスコード – 1xx：情報を示す。リクエストを受信しプロセスを継続。 – 2xx：処理の精巧を示す。リクエストを正しく受信し、理解。 ● 200 OK – 3xx：リダイレクトを示す。リクエストを完了するために更なる操作が 必要。 ● 301 Moved Permanently – 4xx：クライアントエラーを示す。リクエストに不適切な構文が含ま れる、もしくはリクエストを満たすことができない。 ● 404 Not Found – 5xx：サーバーエラーを示す。サーバーは有効なリクエストに対し実 行できない。 ● 500 Internal Server Error 16
- 17. RESTとは ● （話戻って）RESTアーキテクチャスタイルとは – 統一インタフェース ● HTTP(GET/POST/PUT/DELETEおよびステータスコード)に準拠 する（=URIさえ分かれば利用できる） – アドレス指定 ● アプリケーションが扱う情報をアドレス（URI）で指定できるようにす る – 連結性 ● 関連するリソース同士をURIでリンクさせる ● 例：CDリソースの中にアーティスト情報がある場合、その名前だけ でなくURIも含める – ステートレス ● リソースの状態はサーバで管理 ● アプリケーションの状態はクライアントで管理 17
- 18. RESTとは ● 連結性の例 <cd> <title>Ella and Louis</title> <year ref=”http://music.com/year/1956”>1956</year> <artist ref=”http://music.com/artists/123”>Ella Fitzgerald</artist> <artist ref=”http://music.com/artists/456”>Louis Armstrong</artist> <link rel=”self” type=”text/json” href=”http://music.com/album/789” /> <link rel=”self” type=”text/xml” href=”http://music.com/album/789” /> <link rel=”http://music.com/album/comments” type=”text/xml” href=” http://music.com/album/789/comments” /> </cd> 18
- 19. RESTとは ● メリット – クライアントとサービスの結びつきが弱い – スケーラビリティ性 ● ステートレス ● HTTPキャッシュ ● コンパクトな電文（JSON） – 1HTTPリクエストで簡潔（SOAPはWSDL取るので2リクエスト） ● デメリット – 透過的に扱えない – プロトコルがHTTPに限定 – SOAPにあるようなWS-*（WS-Security,etc...）標準が無い 19
- 20. JAX-RS
- 21. JAX-RS ● JAX-RS1.1 – JavaでRESTfulなWebサービスを開発するためのAPI仕様 – JavaEE6に導入 – アノテーションを利用 ● ローカルBeanインタフェースもしくはインタフェースなしBean に適用可能 – サーバサイドのみ – 永続性マネージャ、データソース、EJBなどのDI可能 ● 実装 – Jersey (Sun) : GlassFish3に搭載 – Apache CXF – RESTeasy (JBoss) 21
- 22. JAX-RS ● （参考）JAX-RS2.0（JavaEE7） – クライアントAPI – FiltersとHandlers – BeanValidationを用いたパラメータの検証機能 – 非同期処理（クライアント側でFutureオブジェクトを返す） – 優れた接続ネゴシエーション https://blogs.oracle.com/arungupta/entry/jax_rs_2_0_earlyより 22
- 23. Java EE 6の全体像 http://www.slideshare.net/takakiyo/jjuc-ccc-2010-spring よ り拝借 23
- 24. JAX-RS ● JAX-RSモデル – リソースを表すPOJOクラスに@javax.ws.rs.Pathアノテーションを 付加。 – リソースクラスのメソッドに@GET/@POST/@PUT/@DELETEア ノテーションを付加し、各操作の処理を記述する。 – EJB機能を利用する場合はステートレスセッションBeanに@Pathを 付加。 www.apress.com GET http://www.apress.com/book @Path(“/book”) public class BookResource { @GET @Produces(“text/plain”) 200 OK public String getBookTitle() { H2G2 return “H2G2”; } } 24
- 25. JAX-RSモデル ● URI定義 – @Pathでコンテキストルートからの相対パスを指定。 – クラスに付加した@PathのURIはルートリソース ● 例：/items – ルートリソースのメソッドに@Pathを付加し、小リソースの操作を記 述することも可能。 ● 例：/items/books – URI構文に変数を埋め込むことも可能。@PathParamで参照。 ● 例：/items/{itemid} @Path(“/items”) public class ItemResource { @GET GET /items public List<Item> get...() {...} @GET @Path(“/{itemid}”) public Item get...( GET /items/1234 @PathParam(“itemid”) String itemid) {...} } 25
- 26. JAX-RSモデル ● パラメータの抽出 アノテーション 取得元 説明 例 @PathParam URI @Pathで指定したURIテンプレー @PathParam(“itemId”) トパラメータ @QueryParam URI URIクエリパラメータ（?以降の @QueryParam(“zip”) xxx=yyy） @MatrixParam URI URIの;で区切られたパラメータ @MatrixParam(“author”) （.../books;author=hoge） @CookieParam Cookie Cookieの値 @CookieParam(“sessioni d”) @HeaderParam HTTP リクエストHTTPヘッダの値 @HeaderParam(“Content -Type”) ヘッダ @FormParam リクエス HTMLフォームからのパラメータ @FormParam(“password ”) ト本文 @DefaultValue(“デフォルト値”)でデフォルト値の設定が可能 26
- 27. JAX-RSモデル ● コンテンツタイプの使用と生成 – リクエストのコンテンツタイプに応じて呼び出すメソッドを振り分け る→@Consumes – リクエストのAcceptに応じて呼び出すメソッドを振り分ける→@Pr oduces @Path(“/items”) @Produces(MediaType.TEXT_PLAIN) public class CustomerResource { @GET public String getAsPlainText() {...} Accept: text/plain @GET @Produces(MediaType.TEXT_HTML) Accept: text/html public String getAsHtml() {...} @GET @Produces(MediaType.Application_JSON) Accept: application/json public List<Customer> getAsJson() {…} @PUT @Consumes(MediaType.Application_XML) Content-Type: application/xml public Response createCustomer(InputStream is) {...} } 27
- 28. JAX-RSモデル ● エンティティプロバイダ – HTTP本体（JSONやXML等）をJavaオブジェクトに変換、もしくはその 逆を行うマッピングサービス。 – デフォルトでXMLやJSON用（JAXBElement）のプロバイダは用意さ れているので、通常は自作する必要はない。(JAXB/BadgerFishアダ プタ) @Provider @Consumes(MediaType.APPLICATION_XML) public class CustomerReader implements MessageBodyReader<Customer> { @Override public boolean isReadable(...) {…} @Override public Customer readFrom(..., InputStream inputStream) {…} } @Provider @Produces(MediaType.TEXT_PLAIN) public class CustomerWriter implements MessageBodyWriter<Customer> { @Override public boolean isWritable(...) {…} @Override public void writeTo(Customer customer, ..., OutputStream outputStream) {…} } 28
- 29. JAX-RSモデル ● エンティティプロバイダ（続き） @Path(“/customers”) GET public class CustomerResource { @GET Accept: XML public List<Customer> get...() {...} @GET XML @Path(“/{customerid}”) CustomerをXMLにwriteTo public Customer get...( するMessageBodyWriter @PathParam(“customerid”) String customerId, @QueryParam(“zip”) String zip) {…} POST CustomerをXMLからreadFrom @POST Accept: XML するMessageBodyReader public Response create...( +XML @QueryParam(“zip”) String zip, Customer customer) {…} （デフォルトの）XML出力 @PUT MessageBodyWriter public Response update...( XML JAXBElement<Customer>) {...} } 29
- 30. JAX-RSモデル ● HTTPメソッド – publicメソッドに@GET/@POST/@PUT/@DELETEを付加すると リソースメソッドとなる。 – リソースメソッドはvoid、ResponseもしくはJava型を返却。Java型 の場合はエンティティプロバイダによってXMLやJSONに変換され る。 @Path(“/customers”) Public class CustomerResource { @GET Public List<Customer> getListOfCustomers() {…} @POST @Consumes(MediaType.APPLICATION_XML) public Response createCustomer(JAXBElement<Customer> element) {…} @PUT @Path(“/{customerid}”) @Consumes(MediaType.APPLICATION_XML) public Response updateCustomer(@PathParam(“customerid”) String customerId, JAXBElement<Customer> element) {…} @DELETE @Path(“/{customerid}”) public void deleteCustomer(@PathParam(“customerid”) String customerId) {…} } 30
- 31. JAX-RSモデル ● コンテキスト情報 – @Contextにより各種情報（下記）を属性もしくはメソッド引数にイ ンジェクションできる。 コンテキスト情報 属性 引数 説明 HttpHeaders ○ リクエストHTTPヘッダの各種値の取得 httpHeaders.getAcceptableLanguages() // Accept-Language値 UriInfo ○ ○ リソースのURI情報 uriInfo.getAbsolutePathBuilder() // 自リソースの絶対パスURIビルダー Request ○ HTTPメソッドの種類、キャッシュ関連情報 request.getMethod() // HTTPメソッド SecurityContext ○ ○ セキュリティ関連情報の取得 secureContext.isSecure() // HTTPSか否か Providers ○ ○ エンティティプロバイダや例外マッピングプロバイダの取得 providers.getMessageBodyWriter(...) // マッチするエンティティプロバイダ（Writer）の取得 31
- 32. JAX-RSモデル ● Response – メタ情報をクライアントに返却したい場合にbuildして返却する。 ● ステータスコード（デフォルトだと200 OK） – POST/PUTの正常時に201 Createdを返却するよう変更 – エラーコード返却するよう変更（後述） ● Location（URI） –POST/PUTの正常時に作成・修正リソースのURI ● レスポンスHTTP本体 @POST public Response createNewBook(JAXBElement<Book> bookJaxb) { ... URI bookUri = uriInfo.getAbsolutePathBuilder().path( Book.getId().toString()).build(); // 返却メタ情報：ステータスコード201 Created、かつLocation=生成リソースのURI return Response.created(bookUri).build(); } 32
- 33. JAX-RSモデル ● 例外処理 – エラーステータスコードを充てたResponseを引数にしてWebApplicatio nExceptionをスロー // HTTP本体にメッセージを付けてステータスコード400を返却 throw new WebApplicationException( Response.status(400).entity(“Id must be a positive integer!”).build()); // 404 NotFound throw new WebApplicationException(Response.Status.NOT_FOUND); – 例外マッピングプロバイダを使用れば、任意の非チェック例外をWebAppli cationExceptionにチェインできる。 @Provider Public class EntityNotFoundMapper implements ExceptionMapper<javax.persistence.EntityNotFoundException> { Public Response toResponse(EntityNotFoundException ex) { return Response.status(404).entity(ex.getMessage()).build()); } – いずれにも該当しないの非チェック例外はServletまでスローされつづけ、 ServletコンテナがInternalServerError500を返却する。 33
- 34. JAX-RSモデル ● RESTサービスのパスの設定 – Jerseyに渡すURLパターンを設定する。 // ${コンテキストルート/rs/以下のURIがリクエストされたらRESTとみなし、Jerseyに渡す} @ApplicationPath(“rs”) public class ApplicationConfig extends Application { } 34
- 35. JAX-RSモデル ● ライフサイクル（EJB） – JAX-WS（SOAP）と同じ 存在しない状態 @PostConstruct @PreDestroy 準備状態 メソッド呼び出し 35
- 36. 演習 ● ソースコードを熟読（ex14.BookResource14） ● ビルド＋デプロイ ● cURLでGET/POST/DELETE ● リクエストのAcceptやContent-Typeを変えてみ る ● PUT（Bookの修正）に対応させる ※リクエスト文はソースコードにコメントで書かれ ているのでcopy&pasteしてください 36
- 37. 演習 ● 修正 – JSONArrayが見つからないエラーが発生する場合は、chapter15 配下pom.xmlに以下のリポジトリを追加する。 <dependency> <groupId>org.codehaus.jettison</groupId> <artifactId>jettison</artifactId> <version>1.3.1</version> </dependency> – NetBeansでdeployした場合のURIは”chapter15/rs/14/book s”になります。 – おまけで用意されているManagedBeanは腐っています。 ● 動かしたい場合は頑張ってください。 37
- 38. SOAP or REST? ● REST と SOAP ではどちらが優れていますか ● セキュリティについて、SOAP は REST より優れているのではありませんか ● トランザクションについてはどちらが優れていますか ● 相互運用性について、SOAP は相互運用性が考慮されており、REST よりも優 れているのではありませんか ● メタデータについてはどうでしょう。REST の相互運用性が高いとしても、REST には WSDL が存在せず、WSDL が存在しなければサービスを呼び出すクライ アント側プロキシを生成できないため、使いにくくありませんか ● HTTP 以外のトランスポートを使用するにはどうすればよいでしょう ● ここまでの答えをまとめると、REST はインターネットに接続しているアプリケー ションに適し、SOAP はエンタープライズ アプリケーションに適していることにな りますか 続きはhttp://msdn.microsoft.com/ja-jp/magazine/dd942839.aspx 38