REST, JAX-RS 入門 の編集履歴

nishikawa が 2015-05-26 05:41 に編集

--- Ver.3	2015-04-25 08:24:11+09:00
+++ Ver.4	2015-05-26 05:41:40+09:00
@@ -10,7 +10,7 @@
 * 制約された統一インターフェイス (A uniform, constrained interface)
 * 表現指向 (Representation-oriented)
 * ステートレスな通信 (Communicate statelessly)
-* アプリケーション状態エンジンとしてのハイパーメディア (Hypermedia As The Engine Of Applicati on State, HATEOAS)
+* アプリケーション状態エンジンとしてのハイパーメディア (Hypermedia As The Engine Of Application State, HATEOAS)
 
 これらの原則に従った Web システムは「RESTful なシステム」と呼ばれます。
 

tomoda が 2015-04-25 08:24 に編集

--- Ver.2	2015-04-25 08:22:09+09:00
+++ Ver.3	2015-04-25 08:24:11+09:00
@@ -171,7 +171,7 @@
 
 ### `@Consumes`, `@Produces`
 
-HTTP メソッドアノテーションとともに `@Consume`, `@Produces` アノテーションを指定することにより、リクエスト・レスポンスで用いる HTTP Content-Type を JAX-RS に示すことができます。例えば次の例では `application/xml` の GET リクエストを処理するメソッドと、`application/xml` の POST リクエストを受け付けて `application/xml` のレスポンスを返すメソッドの定義例です。
+HTTP メソッドアノテーションとともに `@Consume`, `@Produces` アノテーションを指定することにより、リクエスト・レスポンスで用いる HTTP Content-Type を JAX-RS に示すことができます。例えば次の例では `application/xml` の GET レスポンスを返すメソッドと、`application/xml` の POST リクエストを受け付けて `application/xml` のレスポンスを返すメソッドの定義例です。
 
 ```java
 @GET
@@ -189,9 +189,6 @@
     :
 }
 ```
-
-
-@javax.ws.rs.Produces アノテーションを使って getCustomer() をアノテートする。このアノテーションは、GET レスポンスで用いる HTTP Content-Type を JAX-RS に示す。このケースでは HTTP Content-Type は application/xml になる。
 
 
 ## リソース

tomoda が 2015-04-25 08:22 に編集

--- Ver.1	2015-04-25 07:06:12+09:00
+++ Ver.2	2015-04-25 08:22:09+09:00
@@ -152,6 +152,10 @@
 }
 ```
 
+## JAX-RS が提供するアノテーション
+
+RESTful サービスのクラスを構築する前に、JAX-RS が提供するアノテーションの一部を紹介します。
+
 
 ## HTTP メソッドのバインド
 
@@ -165,6 +169,169 @@
 
 当然これらのアノテーションはメソッドに対して指定することになります。なお、1 つのメソッドに対しては 1 つの HTTP メソッドアノテーションしか適用できません。
 
-
-
-
+### `@Consumes`, `@Produces`
+
+HTTP メソッドアノテーションとともに `@Consume`, `@Produces` アノテーションを指定することにより、リクエスト・レスポンスで用いる HTTP Content-Type を JAX-RS に示すことができます。例えば次の例では `application/xml` の GET リクエストを処理するメソッドと、`application/xml` の POST リクエストを受け付けて `application/xml` のレスポンスを返すメソッドの定義例です。
+
+```java
+@GET
+@Produces("application/xml")
+public StreamingOutput getItem(String id) {
+    :
+    :
+}
+
+@POST
+@Consumes("application/xml")
+@Produces("application/xml")
+public Response postItem(Item item) {
+    :
+    :
+}
+```
+
+
+@javax.ws.rs.Produces アノテーションを使って getCustomer() をアノテートする。このアノテーションは、GET レスポンスで用いる HTTP Content-Type を JAX-RS に示す。このケースでは HTTP Content-Type は application/xml になる。
+
+
+## リソース
+
+`@javax.ws.rs.Path` というアノテーションによってリソースを定義できます。このアノテーションは、クラス、またはメソッドに指定可能です。
+
+クラスを `@Path("/items")` のようにアノテートすることによって「ルートリソース」を定義できます。
+
+「サブリソース」を返すリソースのメソッドを `@Path` アノテートすることによってサブリソースのファクトリメソッドを定義できます。このようなメソッドは「サブリソースロケータ」と呼ばれます。
+
+また、HTTP メソッドアノテーションとともに `@Path` アノテーションを使用することによって特定のサブリソースに対するメソッドを定義できます。
+
+
+### テンプレートパラメータ
+
+`@Path("{id}") ` のように指定することによって、名前付きのワイルドカードパターン (「/」 (スラッシュ) を含まない文字列) を指定できます。このアノテーションが `@Path("/items")` と指定されたクラスのサブリソースロケータに指定されていた場合、`/items/foo` のような URI を処理します。
+
+また、正規表現を使用することもできます。上記の例で `@Path("{id : \\d+}")` というアノテーションを指定した場合、`/items/42` のような URI だけを処理します。
+
+
+## リソースクラスの例
+
+これまでのことを踏まえて、Items, Item を処理するためのリソースクラスを構築してみます。
+
+```java
+@Path("/Items")
+public class ItemsResource {
+
+    static Items items = new Items();
+
+    @Context
+    private UriInfo context;
+
+    /**
+     * Creates a new instance of ItemsResource
+     */
+    public ItemsResource() {
+    }
+
+    /**
+     * Retrieves representation of an instance of bar.ItemsResource
+     * @return an instance of data.Items
+     */
+    @GET
+    @Produces("application/xml")
+    public Items getXml() {
+        System.out.printf("get all items\n");
+        return items;
+    }
+
+    /**
+     * POST method for creating an instance of ItemResource
+     * @param content representation for the new resource
+     * @return an HTTP response with content of the created resource
+     */
+    @POST
+    @Consumes("application/xml")
+    @Produces("application/xml")
+    public Response postXml(Item content) {
+        items.addItem(content);
+        System.out.printf("add item: %s\n", content);
+        return Response.created(context.getAbsolutePath()).build();
+    }
+
+    /**
+     * DELETE method for creating an instance of ItemResource
+     * @return an HTTP response with content of the created resource
+     */
+    @DELETE
+    @Produces("application/xml")
+    public Response deleteXml() {
+        items.deleteAllItem();
+        System.out.printf("delete all items\n");
+        return Response.created(context.getAbsolutePath()).build();
+    }
+
+    /**
+     * Sub-resource locator method for {id}
+     */
+    @Path("{id}")
+    public ItemResource getItemResource(@PathParam("id") String id) {
+        return ItemResource.getInstance(id);
+    }
+}
+```
+
+```java
+public class ItemResource {
+
+    private String id;
+
+    /**
+     * Creates a new instance of ItemResource
+     */
+    private ItemResource(String id) {
+        this.id = id;
+    }
+
+    /**
+     * Get instance of the ItemResource
+     */
+    public static ItemResource getInstance(String id) {
+        // The user may use some kind of persistence mechanism
+        // to store and restore instances of ItemResource class.
+        return new ItemResource(id);
+    }
+
+    /**
+     * Retrieves representation of an instance of bar.ItemResource
+     * @return an instance of data.Item
+     */
+    @GET
+    @Produces("application/xml")
+    public Item getXml() {
+        Item item = ItemsResource.items.getItem(id);
+        System.out.printf("get item: %s\n", item);
+        return item;
+    }
+
+    /**
+     * PUT method for updating or creating an instance of ItemResource
+     * @param content representation for the resource
+     * @return an HTTP response with content of the updated or created resource.
+     */
+    @PUT
+    @Consumes("application/xml")
+    public void putXml(Item content) {
+        content.setId(id);
+        System.out.printf("put item: %s\n", content);
+        ItemsResource.items.setItem(content);
+    }
+
+    /**
+     * DELETE method for resource ItemResource
+     */
+    @DELETE
+    public void delete() {
+        System.out.printf("delete item: %s\n", id);
+        ItemsResource.items.deleteItem(id);
+    }
+}
+```
+

tomoda が 2015-04-25 07:06 に投稿