1.2.15. RESTful Webサービス

1.2.15.1. RESTful Webサービス・プロジェクトの作成

JAX-RS 1.xプロジェクトの作成

(1)新規プロジェクトから作成

図1.2.15.1-1

図1.2.15.1-2

図1.2.15.1-3

図1.2.15.1-4

図1.2.15.1-5

図1.2.15.1-6

(2)既存の動的WebプロジェクトからRESTful Webサービスへ変換

図1.2.15.1-7

図1.2.15.1-8

JAX-RS 2.0プロジェクトの作成

(1)新規プロジェクトから作成

図1.2.15.1-9

図1.2.15.1-10

図1.2.15.1-11

図1.2.15.1-12

図1.2.15.1-13

図1.2.15.1-14

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
  <display-name>RestSample</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
  </welcome-file-list>
  <servlet>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <servlet-class>com.nec.webotx.jersey2.servlet.ServletContainer</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <url-pattern>/jaxrs/*</url-pattern>
  </servlet-mapping>
</web-app>

(2)既存の動的WebプロジェクトからRESTful Webサービスへ変換

図1.2.15.1-15

図1.2.15.1-16

1.2.15.2. JAX-RSのアノテーション

1.2.15.3. ルートリソースクラス

  1 package com.nec.webotx.ws.rest.samples.helloworld.resources;
  2 
  3 import javax.ws.rs.GET;
  4 import javax.ws.rs.Produces;
  5 import javax.ws.rs.Path;
  6 
  7 // The Java class will be hosted at the URI path "/helloworld"
  8 @Path("/helloworld")
  9 public class HelloWorldResource {
 10 
 11     // The Java method will process HTTP GET requests
 12     @GET
 13     // The Java method will produce content identified by the MIME Media
 14     // type "text/plain"
 15     @Produces("text/plain")
 16     public String getClichedMessage() {
 17         // Return some cliched textual content
 18         return "Hello World";
 19     }
 20 }

ライフサイクル

• リクエストのライフサイクルと同一
  ルートリソースクラスに@Singletonや@PerSessionアノテーションが定義されていない場合、リクエスト毎に一つのインスタンスを作成します。リクエストを処理した後、そのインスタンスはJavaのガベージ・コレクション対象になります。
• Webアプリケーションのライフサイクルと同一
  ルートリソースクラスに@Singletonアノテーションを定義した場合、Webアプリケーションごとに一つのインスタンスを作成します。Webアプリケーションがガベージ・コレクションされる時、インスタンスもガベージ・コレクションされます。
• セッションのライフサイクルと同一
  ルートリソースクラスに@PerSessionアノテーションを定義した場合、一つのセッションに対して一つのインスタンスを作成します。作成したインスタンスは属性としてsessionに格納しています。セッションがガベージ・コレクションされる時、インスタンスをガベージ・コレクションされます。

コンストラクタ

• 明示的に宣言されないコンストラクタ
• パラメータを持たないコンストラクタ
• パラメータを持つコンストラクタ

@Path("ResourceTest1")
public class Resource1{
    private String query1;
    public Resource1(@Encoded @DefaultValue("abc") @QueryParam("queryParam1") String query) {
    query1 = query;
}	
@GET
@Path("/queryParam1Value")
    public String getQuery1Value() {
        return "query1=" + query1;
    }
}

フィールドおよびbeanプロパティ

private @Encoded @DefaultValue("value1") @QueryParam("id") String id;

private String property1;
@DefaultValue("10") @QueryParam("paramProperty1")
public void setProperty1(String property1) {
  this.property1 = property1;
}

リソースメソッド

@Path("resource_method")
public class ResourceMethodResource {
	@GET
	public String resourceMethod() {
		return "this is a resource method.";
	}
}

サブリソースメソッド

@Path("/resourceTest1")
public class Resource1 {
    public Resource1(){
    }
...
    @GET
    @Path("/testPathParam/{arg1}/{arg2}")
    public String listPathParam(@PathParam("arg1") String arg1,@PathParam("arg2") String arg2) {
        return "arg1="+arg1+" and arg2="+arg2;
    }
...
｝

サブリソースロケータ

@Path("/resourceTest1")
public class Resource1 {
    @Path("/testSubResourceLocator/{id}")
    public Resource1_1 getResource1_1(@PathParam("id") String id){
        return new Resource1_1(id);
    }
...
}

public class Resource1_1 {
    private String resourceID;
    public Resource1_1(String id){
        resourceID = id;
  }    
    @GET
    public String getDetails(){
        return "This resource id is "+resourceID;
    }
}

1.2.15.4. サブリソースクラス

public class Resource1_1 {
    private String resourceID;
    public Resource1_1(String id){
        resourceID = id;
  }    
    @GET
    public String getDetails(){
        return "This resource id is "+resourceID;
    }
}

ライフサイクル

コンストラクタ

フィールドおよびbeanプロパティ

リソースメソッド、サブリソースメソッドおよびサブリソースロケータ

1.2.15.5. URIテンプレート

1.2.15.6. HTTPメソッド

@GET

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

@POST

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

@PUT

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

@DELETE

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

@HEAD

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

@OPTIONS

• ルートリソースクラスのpublicメソッド
• サブリソースクラスのpublicメソッド

import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("optionsmethod")
public class OptionsMethodResource {
	@GET
	public String getHello() {
		return "hello";
	}
}

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
    <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.11 12/09/2011 10:27 AM"/>
    <grammars/>
    <resources base="http://{server-name:port}/{context-root}/{url-pattern}/">
        <resource path="optionsmethod">
            <method id="getHello" name="GET">
                <response>
                    <representation mediaType="*/*"/>
                </response>
            </method>
        </resource>
    </resources>
</application>

1.2.15.7. MIMEタイプ宣言

@Consumesアノテーション

• リソースクラス(ルートリソースクラス/サブリソースクラス): クラスレベルで@Consumesアノテーションを指定します。そのリソースクラスにある全てのリソースメソッドとサブリソースメソッドのデフォルトMIMEタイプとなります。
• (サブ)リソースメソッド：メソッドレベルで@Consumesアノテーションを指定します。そのリソースメソッドだけ有効になるリクエストのMIMEタイプです。設定の優先度は、メソッドレベルの@Consumesアノテーション > クラスレベルの@Consumesアノテーション となります。
• エンティティプロバイダ：プロバイダクラスレベルで@Consumesアノテーションを指定します。そのプロバイダが処理できるMIMEタイプとなります。

@Producesアノテーション

• リソースクラス(ルートリソースクラス/サブリソースクラス): クラスレベルで@Producesアノテーションを指定します。そのリソースクラスにある全てのリソースメソッドとサブリソースメソッドのデフォルトMIMEタイプとなります。
• (サブ)リソースメソッド：メソッドレベルで@Producesアノテーションを指定します。そのリソースメソッドだけ有効になるレスポンスのMIMEタイプです。設定の優先度は、メソッドレベルの@Producesアノテーション > クラスレベルの@Producesアノテーション となります。
• エンティティプロバイダ: プロバイダクラスレベルで@Producesアノテーションを指定します。そのプロバイダが返却するメッセージのMIMEタイプとなります。

複数なメディアタイプを指定する場合の使用例

• 下記の例では、メディアタイプ「application/xml」と「application/json」のいずれも許容される場合の例を示します。

      @GET
      Produces({"application/xml", "application/json"})
      public String doGetAsXmlOrJson() {
          ... 
      }
      

• 複数なメディアタイプを受ける場合、クライアントは、「q」パラメータとして知られている相対的な品質係数を使用してプリファレンスを示すことができます。
• 「q」パラメータの値或いはq-valueは受け入れたセットをソートするために使用されます。
• 下記の例では、クライアントは「application/xml」と「application/json」の両方を受け入れる場合、「application/xml」がより低い品質係数（「qs=0.9」）を指定されるので、サーバは常に「application/json」で送信します。

      @GET
      @Produces({"application/xml; qs=0.9", "application/json"}) 
      public String doGetAsXmlOrJson() { 
          ... 
      }
      

1.2.15.8. アノテーションの継承

• 子クラスのメソッドおよびパラメータでJAX-RS仕様のアノテーションが使用されていない場合
• 実装クラスのメソッドおよびパラメータでJAX-RS仕様のアノテーションが使用されていない場合

//インタフェース
public interface A {
    @GET
    public String getValue(@QueryParam("query") String query);
}
//インタフェースを実装するルートリソースクラス
@Path("/root/")
public class Resource implements A {
    public String getValue(String query) {…}
}

//親クラス
public class ParentClassA {
	@GET
	public String getValue(@QueryParam("query1") String query1){
		return "query1 = "+query1;
	}
}
//子クラス
@Path("/inheretance")
public class SubClass extends ParentClassA {
	public String getValue(String query){
		return query;
	}
}

public interface InterfaceA {
	@GET
	public String getValue(@PathParam("path1") String path1);
}
public interface InterfaceB {
	@GET
	public String getValue(@QueryParam("query") String query);
}
@Path("/inheretance/{path1}")
public class SubClass implements InterfaceB, InterfaceA{
	public String getValue(String param){
		return param;
	}
}

@Path("/inheretance/{path1}")
public class SubClass implements InterfaceA, InterfaceB{
	public String getValue(String param){
		return param;
	}
}

1.2.15.9. アノテーションのパラメータ

@HeaderParamアノテーション

@CookieParamアノテーション

@MatrixParamアノテーション

@QueryParamアノテーション

@PathParamアノテーション

@Contextアノテーション

javax.ws.rs.core.UriInfo

@Path("/root")
public class Resource {
  private @Context UriInfo uriInfo;
  @GET
  public String getValue() {
    String value = this.uriInfo.getQueryParameters().getFirst("query");
    return value;
  }
}

javax.ws.rs.core.HttpHeaders

@Path("/root")
public class Resource {
  private @Context HttpHeaders httpHeaders;
  @GET
  public String getValue () {
    String value = this.httpHeaders.getRequestHeader("Accept").get(0);
    return value;
  }
}

javax.ws.rs.core.Providers

@Path("/root")
public class Resource {
  private @Context Providers providers;
  @GET
  public String getValue() {
    //providersフィールドから例外マッピングプロバイダを取得します
    return this.providers.getExceptionMapper(RuntimeException.class);
  }
}

javax.ws.rs.core.SecurityContext

@Path("/root")
public class Resource {
private @Context SecurityContext securityContext;
  @GET
  public String getValue () {
    String value = "Authentication Scheme: "
        + this.securityContext.getAuthenticationScheme()
        + ", User Principal: " + this.securityContext.getUserPrincipal()
        + ", Is secure: " + this.securityContext.isSecure()
        + ", Is user in role: " + this.securityContext.isUserInRole("admin");
    return value;
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  ...
  <security-constraint>
     <web-resource-collection>
       <web-resource-name>Test Resource</web-resource-name>
       <url-pattern>/*</url-pattern>
       <http-method>GET</http-method>
     </web-resource-collection>
     <auth-constraint>
       <role-name>admin</role-name>
     </auth-constraint>
  </security-constraint>
  <login-config>
     <auth-method>BASIC</auth-method>
     <realm-name>jaxrs_server</realm-name>
  </login-config>
  <security-role>
     <role-name>admin</role-name>
  </security-role>
</web-app>

javax.ws.rs.core.HttpServletRequest

@Path("/root")
public class Resource {
  private @Context HttpServletRequest httpRequest;
  @GET
  public String getValue() {
    return this.httpRequest.getParameter("TestParam");
  }
}

javax.ws.rs.core.HttpServletResponse

@Path("/root")
public class Resource {
  private @Context HttpServletResponse httpResponse;
  @GET
  public void getValue() throws IOException {
    String entity = "Response mentioned using HttpServletResponse";
    httpResponse.setHeader("abc","xyz");
    httpResponse.getOutputStream().write(entity.getBytes());
    httpResponse.getOutputStream().flush();
    httpResponse.getOutputStream().close(); 
  }
}

javax.ws.rs.core.ServletConfig

@Path("/root")
public class Resource {
  private @Context ServletConfig config;
  @GET
  public String getValue() {
    return this.config.getInitParameter("TestParam");    
  }
}

<web-app ...>
<servlet>
<init-param>
      <param-name>TestParam</param-name>
      <param-value>TestValue</param-value>
</init-param>
……
</servlet>
</web-app>

javax.ws.rs.core.ServletContext

@Path("/root")
public class Resource {
  private @Context ServletContext context;
  @GET
  public String getValue() {
    return this.context.getInitParameter("TestParam");    
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>
  ...
  <context-param>
    <param-name>TestParam</param-name>
    <param-value>TestValue</param-value>
  </context-param>
</web-app>

javax.ws.rs.core.Request

@FormParamアノテーション

<html>
<head>
<meta http-equiv="content-type" content="text/xml;charset=utf-8">
<title> test RESTFulWebService @FromParam</title>
</head>
<body>
<form action="http://localhost:8080/WebProject1/myApplication1/testFormParam" method="post" >
<table>
<tr>
<td>FirstName:</td>
<td><input type="text" name="firstname"></td>
</tr>
<tr>
<td>Age:</td>
<td><input type="text" name="age"></td>
</tr>
</table>
<input type="submit" value="Submit" >
</form>
</body>
</html>

@Path("testFormParam")
public class FormResource {
@POST
@Consumes("application/x-www-form-urlencoded")
public String getFormString(@FormParam("firstname") String name, @FormParam("age") int age){
	return "firstname="+name+";age="+age;
	}
}

@Encodedアノテーション

@DefaultValueアノテーション

@BeanParamアノテーション

public class MyBeanParam {
    @PathParam("p")
    private String pathParam;

    @MatrixParam("m")
    @Encoded
    @DefaultValue("default")
    private String matrixParam;

    @HeaderParam("header")
    private String headerParam;

    private String queryParam;

    public MyBeanParam(@QueryParam("q") String queryParam) {
        this.queryParam = queryParam;
    }

    public String getPathParam() { 
        return pathParam; 
    }
    ...
}

@POST
public void post(@BeanParam MyBeanParam beanParam, String entity) { 
    final String pathParam = beanParam.getPathParam();
    ... 
}

1.2.15.10. エンティティパラメータ

@Path("EntityParameter")
public class EntityParameter {
	@POST
	@Path("getFileBody")
	public String getFileBody(File fileBody) throws IOException{
		BufferedReader br = new BufferedReader(new InputStreamReader(new FileInputStream(fileBody),"UTF-8"));
		String line=null;
		StringBuffer sb = new StringBuffer();
		while((line=br.readLine()) != null){
			sb.append(line);
		}
		return sb.toString();
	}
}

1.2.15.11. レスポンスの作成

内蔵エンティティプロバイダ対応するJavaの型

@Path("/inputStreamRes")
public class InputStreamResource {
	private Map<String, String> fileRecord = new HashMap<String, String>();
	public InputStreamResource() {
		fileRecord.put("id1", "ファイルパス");
	}
	@GET
	@Path("/{fileId}")
	public InputStream getInputStream(@PathParam("fileId") String fileId) {
		FileInputStream inStream = null;
		String filePath = fileRecord.get(fileId);
		if (filePath != null) {
			try {
				inStream = new FileInputStream(filePath);
			} catch (FileNotFoundException e) {
				e.printStackTrace();
			}
		}
		return inStream;
	}
}

Responseタイプ

@Path("ResponseResource")
public class ResponseResource {
    @GET
    @Path("helloworld")
    public Response getHelloWorldByResponse() {
	    String entityBody = "HelloWorld";
	    return Response.ok(entityBody, MediaType.TEXT_HTML_TYPE).build();
    }
}

カスタムエンティティプロバイダ対応するJavaの型

1.2.15.12. プロバイダ

図1.2.15.12-1

エンティティプロバイダ

• (1)リクエストボディからJavaインスタンスに変換します。
• (2)Javaのインスタンスからレスポンスボディに変換します。

内蔵エンティティプロバイダ

• javax.xml.transform.stream.StreamSource
• javax.xml.transform.sax.SAXSource
• javax.xml.transform.dom.DOMSource

カスタムエンティティプロバイダ

    カスタムMessageBodyReaderエンティティプロバイダ

  @Provider
 public class NamePasswordBeanReader implements MessageBodyReader<NamePasswordBean> {

	@Override
	public boolean isReadable(Class<?> arg0, Type arg1, Annotation[] arg2,MediaType arg3) {
		return arg0 == NamePasswordBean.class;
	}

	@Override
	public NamePasswordBean readFrom(Class<NamePasswordBean> arg0, Type arg1,Annotation[] arg2, MediaType arg3, MultivaluedMap<String, String> arg4, InputStream arg5) throws IOException, WebApplicationException {
		//NamePasswordBeanインスタンスを作成。
                ……
	}
}
 

(1)MessageBodyReaderエンティティプロバイダのマッチルール

    カスタムMessageBodyWriterエンティティプロバイダ

 @Provider
public class NamePasswordBeanWriter implements MessageBodyWriter<NamePasswordBean> {

	@Override
	public long getSize(NamePasswordBean arg0, Class<?> arg1, Type arg2,Annotation[] arg3, MediaType arg4) {
		return -1;
	}

	@Override
	public boolean isWriteable(Class<?> classType, Type arg1, Annotation[] arg2,MediaType arg3) {
		return classType == NamePasswordBean.class;
	}

	@Override
	public void writeTo(NamePasswordBean arg0, Class<?> arg1, Type arg2,Annotation[] arg3, MediaType arg4,MultivaluedMap<String, Object> arg5, OutputStream arg6) throws IOException, WebApplicationException {
		// NamePasswordBeanのインスタンスをシリアライズするロジック
     …………
	}
}
 

(1)MessageBodyWriterエンティティプロバイダのマッチルール

• (1)：HTTPレスポンスエンティティボディに対応するObjectの型を取得します。
• (2)：レスポンスのMIMEタイプを決めります。
• (3)：(1)と(2)から取得したJavaタイプとMIMEタイプをサポートするプロバイダの集合を取得します。
  マッチルールは下記に従います。
  「x/y < x/* < */*」
  特定のMIMEタイプをサポートするプロバイダは全てのMIMEタイプをサポートするプロバイダより優先マッチします。
• (4)：(3)に選択したプロバイダをソート(Sort)します。
• (5)：ソートした毎プロバイダのisWriteable()メソッドをコールし、「true」を返すプロバイダを利用します。複数のプロバイダを定義し、それらのプロバイダが全てisWriteable ()でtrueを返却する場合：
  Applicationを継承する場合サブクラスに先に追加されたプロバイダを利用します。PackagesResourceConfigとcom.nec.webotx.jersey.config.property.packagesを利用する場合、クラス名の昇順で前のプロバイダを利用します。
• (6)：いずれのプロバイダも利用できない場合は、例外が発生し、ログに「A message body writer for Java class {ユーザ実装のJavaクラス}, and Java type class {ユーザ実装のJavaクラス}, and MIME media type {MIMEタイプ} was not found」を出力します。HTTPステータスコードには500が返されます。

XML

    JAXBアノテーション

   @XmlRootElement
   public class Planet {
       public int id;
       public String name;
       public double radius;
   }
  

   @Path("planet")
   public class Resource {
   
       @GET
       @Produces(MediaType.APPLICATION_XML)
       public Planet getPlanet() {
           Planet p = new Planet();
           p.id = 1;
           p.name = "Earth";
          p.radius = 1.0;  
          return p;
      }
 }
  

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <planet>
      <id>1</id>
      <name>Earth</name>
      <radius>1.0</radius>
   </planet>
  

    JAXBElementクラス

   public class Planet {
       public int id;
       public String name;
       public double radius;
   }
  

   @Path("planet")
   public class Resource {
       @GET
       @Produces(MediaType.APPLICATION_XML)
       public JAXBElement<Planet> getPlanet() {
           Planet p = new Planet();
           p.id = 1;
           p.name = "Earth";
          p.radius = 1.0;
  
          return new JAXBElement<Planet>(new QName(“myplanet”), Planet.class, p);
      }
   }
  

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <myplanet>
        <id>1</id>
        <name>Earth</name>
        <radius>1.0</radius>
    <myplanet>
  

JSON

Caution
任意のメンバ変数がシリアライズできない場合、エラーとなり次の例外が発生します。「JsonMappingException: No serializer found for class {サブリソースロケータの情報} and no properties discovered to create BeanSerializer」。その変数を無視するのであれば、アノテーション「@JsonIgnoreProperties(value = {"hibernateLazyInitializer", "変数名"})」を使用してください。

    POJO

     <init-param>
       <param-name>
            com.nec.webotx.jersey.api.json.POJOMappingFeature
       </param-name>
       <param-value>true</param-value>
   </init-param>
  

   public class NonJAXBBean {
    public String name = "non-JAXB-bean";
    public String description = "I am not a JAXB bean, just an unannotated POJO";
    public int[] array = {1, 1, 2, 3, 5, 8, 13, 21};
   }
  

	import com.nec.webotx.jersey.api.json.JSONWithPadding;
	import javax.ws.rs.GET;
	import javax.ws.rs.Path;
	import javax.ws.rs.Produces;
	import javax.ws.rs.core.MediaType;

	@Path("/nonJAXBResource")
	public class NonJAXBBeanResource {

	    @GET 
	    @Produces({"application/javascript", MediaType.APPLICATION_JSON})
	    public JSONWithPadding getSimpleBeanJSONP() {
	        return new JSONWithPadding(new NonJAXBBean());
	    }
	}
  

  {"name":"non-JAXB-bean","description":"I am not a JAXB bean, just an unannotated POJO","array":[1,1,2,3,5,8,13,21]}
  

    JAXB

   @XmlRootElement
   public class MyJaxbBean {
     public String name;
     public int age;
         
     public MyJaxbBean() {} // JAXB needs this default constructor
   
     public MyJaxbBean(String name, int age) {
       this.name = name;
      this.age = age;
    }
 }
  

   @GET @Produces("application/json")
   public MyJaxbBean getMyBean() {
      return new MyJaxbBean("Agamemnon", 32);
   }
  

  {"name":"Agamemnon", "age":"32"}
  

   @Provider
   public class JAXBContextResolver implements ContextResolver<JAXBContext> {
   
       private JAXBContext context;
       private Class[] types = {MyJaxbBean.class};
   
       public JAXBContextResolver() throws Exception {
           this.context = 
   	  new JSONJAXBContext( 
  	    JSONConfiguration.natural().build(), types); 
      }
       
      public JAXBContext getContext(Class<?> objectType) {
          for (Class type : types) {
              if (type == objectType) {
                  return context;
              }
          }
          return null;
      }
  }
  

	   @XmlRootElement
	   public class Address {
	       public String street;
	       public String town;
	   
	       public Address(){}
	   
	       public Address(String street, String town) {
	           this.street = street;
	          this.town = town;
	      }
	  }
   

Contactクラス詳細：

	   @XmlRootElement
	   public class Contact {
	       public int id;
	       public String name;
	       public List<Address> addresses;
	   
	       public Contact() {};
	   
	      public Contact(int id, String name, List<Address> addresses) {
	          this.name = name;
	          this.id = id;
	          this.addresses = 
	  	        (addresses != null) ? new LinkedList<Address>(addresses) : null;
	      }
	 }
   

   @Path("/JAXBJSONResource")
   public class JAXBJSONResource {
	 @GET
	 @Produces("application/json")
	 public Contact getContact() {
		 Address[] addresses = new Address[]{new Address("Long Street 1", "Short Village")};
		 Contact contact = new Contact(2, "BOb", Arrays.asList(addresses));
		
		 return contact;
 	 }
   }
   

コンテキストプロバイダ詳細：

   @Provider
   public class JAXBContextResolver implements ContextResolver<JAXBContext> {
	  private JAXBContext context;
	  private Class[] types = {Contact.class};
	
	  public JAXBContextResolver() throws Exception {
		  this.context = new JSONJAXBContext(JSONConfiguration.mapped().build() // ※(1)
				 types);
	  }

	  public JAXBContext getContext(Class<?> type) {
		  for(Class supportType: types) {
			  if (type == supportType) {
				 return context;
			  }
		}
		return null;
	}
  }
   

    Mapped Notation

    { "id":"2" ,"name":"Bob","addresses":{"street":"Long Street 1","town":"Short Village"}}
   

    {"id":"2","name":"BOb","addresses":[{"street":"Long Street 1" ,"town":"Short Village"}]}
    

    {"id":2 ,"name":"BOb","addresses":{"street":"Long Street 1","town":"Short Village"}}
    

	 ...
	 @XmlAttribute
	 public int id;
	 ...
    

    {"@id":"2" ...
    

    {"contact":{"id":"2","name":"BOb","addresses":{"street":"Long Street 1" ,"town":"Short Village"}}}
    

	…
	@XmlElement(namespace="http://www.nec.cn.jersey")
	public List<Address> addresses;
	…
    

	Map<String, String> ns2json = new HashMap<String, String>();
	ns2json.put("http://www.nec.cn.jersey", "addressesNS");
	this.context = new JSONJAXBContext(
	JSONConfiguration.mapped().xml2JsonNs(ns2json).build(), types);
    

  {"id":"2","name":"BOb","addressesNS.addresses":{"street":"Long Street 1" ,"town":"Short Village"}}
    

    JSONConfiguration.mapped().xml2JsonNs(ns2json).nsSeparator(':').build()
    

    {"id":"2","name":"BOb","addressesNS:addresses":{"street":"Long Street 1","town":"Short Village"}}  
    

    Natural Notation

    {"id":2,"name":"BOb","addresses":[{"street":"Long Street 1","town":"Short Village"}]}
   

    {"contact":{"id":2,"name":"BOb","addresses":[{"street":"Long Street 1","town":"Short Village"}]}}
   

	……
	@XmlAttribute
	public int id;
	……
   

    {"id":2,"name":"BOb","addresses":[{"street":"Long Street 1","town":"Short Village"}]}
   

   {"@id":2 ,"name":"BOb","addresses":[{"street":"Long Street 1","town":"Short Village"}]}
   

    Jettison mapped Notation

     {"contact":{"id":2,"name":"BOb","addresses":{"street":"Long Street 1","town":"Short Village"}}}
    

	……
	@XmlElement(namespace="http://www.nec.cn.jersey")
	public int id;
	……
    

	Map<String, String> ns2json = new HashMap<String, String>();
	ns2json.put("http://www.nec.cn.jersey", "idNS");
	this.context = new JSONJAXBContext(
	JSONConfiguration.mappedJettison().xml2JsonNs(ns2json).build(), types);
    

    {"contact":{"idNS.id":2,"name":"BOb","addresses":{"street":"Long Street 1" ,"town":"Short Village"}}
    

    Badgerfish Notation

   {"contact":{"id":2,"name":"BOb","addresses":{"street":"Long Street 1","town":"Short Village"}}}
  

JSONObject/JSONArray

   public class Contact {
  
       public int id;
       public String name;
        
       public Contact(int id, String name) {
           this.name = name;
           this.id = id;
          
      }
  }
  

	 @Path("/JSONObject")
	 public class MyJSONObjectResource {
		@GET
		@Produces("application/json")
		public JSONObject getContact() {
			
			Contact contact = new Contact(2, "BOb");
			JSONObject jsonOb = new JSONObject();
			try {
				jsonOb.put("id", contact.id).put("name", contact.name);
			} catch (JSONException e) {
				e.printStackTrace();
			}
			return jsonOb;
		}
   }
  

  {"id":2,"name":"BOb"}
  

コンテキストプロバイダ

    @Provider
   public class JAXBContextResolver implements ContextResolver<JAXBContext> {
   
       private JAXBContext context;
       private Class[] types = {MyJaxbBean.class};
   
       public JAXBContextResolver() throws Exception {
           this.context = 
   	  new JSONJAXBContext( 
  	    JSONConfiguration.natural().build(), types); 
      }
  
      public JAXBContext getContext(Class<?> objectType) {
          for (Class type : types) {
              if (type == objectType) {
                  return context;
              }
          }
          return null;
      }
 }
   

     @Provider
     @Produces(“application/json”)
      public class JAXBContextResolver implements ContextResolver<JAXBContext> {
         ……
      }
   

コンテキストプロバイダのマッチルール

例外マッピングプロバイダ

1.2.15.13. JAX-RSクライアントAPIのサポート

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

public class UserClient {

   private static String serverUri = "http://localhost:80/WSDemo/rest";

private static void addUser() {
     User user = new User("219","山口","25");
     Client client = ClientBuilder.newClient();
     WebTarget target = client.target(serverUri + "/users");
     Response response = target.request().buildPost(Entity.entity(user, MediaType.APPLICATION_XML)).invoke();
     response.close();
}

ClientConfig clientConfig = new ClientConfig();
clientConfig.register(MyClientResponseFilter.class);
clientConfig.register(new AnotherClientFilter());
Client client = ClientBuilder.newClient(clientConfig);

WebTarget webTarget = client.target("http://example.com/rest");
WebTarget resourceWebTarget = webTarget.path("resource");		// URI "http://example.com/rest/resource"
WebTarget helloworldWebTarget = resourceWebTarget.path("helloworld");	//"http://example.com/rest/resource/helloworld".
WebTarget helloworldWebTargetWithQueryParam = helloworldWebTarget.queryParam("greeting", "Hi World!");

Invocation.Builder invocationBuilder = helloworldWebTargetWithQueryParam.request(MediaType.TEXT_PLAIN_TYPE);
invocationBuilder.header("some-header", "true");

Response response = invocationBuilder.get();

Response response = invocationBuilder.post(Entity.entity("A string entity to be POSTed", MediaType.TEXT_PLAIN));

System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));

1.2.15.14. フィルターの作成

フィルターはHttpヘッダなどリクエストとレスポンスのパラメータを変更したい場合に使用します。サーバー側のフィルターとクライアント側のフィルター、2種類に分かれています。

サーバ側のフィルター：

クライアント側のフィルター:

図1.2.15.14-1

図1.2.15.14-2

Memo
フィルターは JAX-RS 2.0 規範に定義される機能であるため、フィルター作成で選択されるプロジェクトは JAX-RS 2.0 ファセットを持つ必要があります。

図1.2.15.14-3

ContainerResponseFilter

import java.io.IOException;
import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerResponseContext;
import javax.ws.rs.container.ContainerResponseFilter;
import javax.ws.rs.core.Response;
 
public class PoweredByResponseFilter implements ContainerResponseFilter {
 
    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext)
        throws IOException { 
            responseContext.getHeaders().add("X-Powered-By", "Jersey :-)");
    }
}

ContainerRequestFilter

import java.io.IOException;
import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.SecurityContext;
 
public class AuthorizationRequestFilter implements ContainerRequestFilter {
 
    @Override
    public void filter(ContainerRequestContext requestContext)
                    throws IOException {
 
        final SecurityContext securityContext =
                    requestContext.getSecurityContext();
        if (securityContext == null ||
                    !securityContext.isUserInRole("privileged")) {
 
                requestContext.abortWith(Response
                    .status(Response.Status.UNAUTHORIZED)
                    .entity("User cannot access the resource.")
                    .build());
        }
    }
}

ClientRequestFilter

public class CheckRequestFilter implements ClientRequestFilter {
 
    @Override
    public void filter(ClientRequestContext requestContext)
                        throws IOException {
        if (requestContext.getHeaders(
                        ).get("Client-Name") == null) {
            requestContext.abortWith(
                        Response.status(Response.Status.BAD_REQUEST)
                .entity("Client-Name header must be defined.")
                        .build());
         }
    }
}

ClientResponseFilter

public class ClientResponseLoggingFilter implements ClientResponseFilter {

	@Override
	public void filter(final ClientRequestContext reqCtx,
			final ClientResponseContext resCtx) throws IOException {
		System.out.println("status: " + resCtx.getStatus());
		System.out.println("media-type: " + resCtx.getMediaType().getType());
}

1.2.15.15. インターセプターの作成

インターセプターは、入出力ストリームを通じてエンティティーの読み書き処理を行う時に使います。サーバー側とクライアント側は共通APIを利用します。
インターセプターは

• 入力ストリームをラップするReaderInterceptorと、
• 出力ストリームをラップするWriterInterceptor

図1.2.15.15-1

図1.2.15.15-2

Memo
インターセプターは JAX-RS 2.0 規範に定義される機能であるため、インターセプター作成で選択されるプロジェクトは JAX-RS 2.0 ファセットを持つ必要があります。

図1.2.15.15-3

ReaderInterceptor

public class GZIPReaderInterceptor implements ReaderInterceptor {
 
    @Override
    public Object aroundReadFrom(ReaderInterceptorContext context)
                    throws IOException, WebApplicationException {
        final InputStream originalInputStream = context.getInputStream();
        context.setInputStream(new GZIPInputStream(originalInputStream));
        return context.proceed();
    }
}

WriterInterceptor

public class GZIPWriterInterceptor implements WriterInterceptor {
 
    @Override
    public void aroundWriteTo(WriterInterceptorContext context)
                    throws IOException, WebApplicationException {
        final OutputStream outputStream = context.getOutputStream();
        context.setOutputStream(new GZIPOutputStream(outputStream));
        context.proceed();
    }
}

1.2.15.16. SpringDI機能のサポート

• Springのトランザクション管理機能(@Transactional注解を利用)
• SpringのセキュリティとAOP(aspect oriented programming)機能(@Aspect注解を利用)

• @Component
• @Service
• @Controller
• @Repository

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import org.springframework.stereotype.Component;
@Component
@Path("/")
public class SomeResource { 
    @Transactional
    @GET
    public void updateResource() {
        // ...
    }.
}

• jersey-spring3.jar

<?xml version="1.0" encoding"UTF-8"?>
<nec-web-app>
        <context-root>sse-item-store-webapp</context-root>
	<class-loader delegate="false" extra-class-path="C:/WebOTX/modules/jaxrs20.jar;C:/WebOTX/lib/jaxrs20/jersey-spring3.jar">
		<property name="overrideablejavaxpackages" value="javax.ws.rs,javax.annotation,javax.validation" />
        </class-loader>
	......
</nec-web-app>

1.2.15.17. 非同期処理

サーバ側

@Path("/resource")
public class AsyncResource {
    @GET
    public void asyncGet(@Suspended final AsyncResponse asyncResponse) {
 
        new Thread(new Runnable() {
            @Override
            public void run() {
                String result = veryExpensiveOperation();
                asyncResponse.resume(result);
            }
 
            private String veryExpensiveOperation() {
                // ... very expensive operation
            }
        }).start();
    }
}

@GET
public void asyncGetWithTimeout(@Suspended final AsyncResponse asyncResponse) {
    asyncResponse.setTimeoutHandler(new TimeoutHandler() {
 
        @Override
        public void handleTimeout(AsyncResponse asyncResponse) {
            asyncResponse.resume(Response.status(Response.Status.SERVICE_UNAVAILABLE)
                    .entity("Operation time out.").build());
        }
    });
    asyncResponse.setTimeout(20, TimeUnit.SECONDS);
 
    new Thread(new Runnable() {
 
        @Override
        public void run() {
            String result = veryExpensiveOperation();
            asyncResponse.resume(result);
        }
 
        private String veryExpensiveOperation() {
            // ... very expensive operation that typically finishes within 20 seconds
        }
    }).start();
}

クライアント側

final AsyncInvoker asyncInvoker = target().path("http://example.com/resource/")
        .request().async();
final Future<Response> responseFuture = asyncInvoker.get();
System.out.println("Request is being processed asynchronously.");
final Response response = responseFuture.get();
    // get() waits for the response to be ready
System.out.println("Response received.");

1.2.15.18. セキュリティ

SslConfigurator sslConfig = SslConfigurator.newInstance()
        .trustStoreFile("./truststore_client")
        .trustStorePassword("secret-password-for-truststore")
        .keyStoreFile("./keystore_client")
        .keyPassword("secret-password-for-keystore");
 
SSLContext sslContext = sslConfig.createSSLContext();
Client client = ClientBuilder.newBuilder().sslContext(sslContext).build();
Response response = client.target("https://example.com/resource").request().get();

HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic("user", "superSecretPassword");

HttpAuthenticationFeature feature = HttpAuthenticationFeature.basicBuilder()
    .nonPreemptive().credentials("user", "superSecretPassword").build();

1.2.15.19. Java API for JSON Processing (JSON-P)

       ClientBuilder.newClient(new ClientConfig()
             .register(JsonProcessingFeature.class)
             .property(JsonGenerator.PRETTY_PRINTING, true));
     

      public class MyApplication extends ResourceConfig {
          public MyApplication() {
              packages("com.nec.webotx.jersey.examples.jsonp.resource");
              register(LoggingFilter.class);
              property(JsonGenerator.PRETTY_PRINTING, true);
          }
      }
     

  <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
   <servlet>
     <servlet-name>com.nec.webotx.jersey.examples.jsonp.MyApplication</servlet-name>
     <servlet-class>com.nec.webotx.jersey.servlet.ServletContainer</servlet-class>
     <init-param>
         <param-name>javax.ws.rs.Application</param-name>
         <param-value>com.nec.webotx.jersey.examples.jsonp.MyApplication</param-value>
     </init-param>
     <init-param>
         <param-name>javax.json.stream.JsonGenerator.prettyPrinting</param-name>
         <param-value>true</param-value>
     </init-param>
     <load-on-startup>1</load-on-startup>
   </servlet>
   <servlet-mapping>
     <servlet-name>com.nec.webotx.jersey.examples.jsonp.MyApplication</servlet-name>
     <url-pattern>/*</url-pattern>
   </servlet-mapping>
  </web-app>
  

• Object Model API
• Streaming API

Object Model API

主なObject Model APIのクラス

      URL url = new URL("http://sample.com/example/?q=java&type=post");
      try (InputStream is = url.openStream();
          JsonReader rdr = Json.createReader(is)) {
          JsonObject obj = rdr.readObject();
          JsonArray results = obj.getJsonArray("data");
          for (JsonObject result : results.getValuesAs(JsonObject.class)) {
              System.out.print(result.getJsonObject("from").getString("name"));
              System.out.print(": ");
              System.out.println(result.getString("message", ""));
              System.out.println("-----------");
          }
     

     	{
          "data" : [
              { "from" : { "name" : "xxx", ... }, "message" : "yyy", ... },
              { "from" : { "name" : "ppp", ... }, "message" : "qqq", ... },
              ...
          ],
          ...
      }
     

Streaming API

主なStreaming APIのクラス

      URL url = new URL("https://graph.facebook.com/search?q=java&type=post");
      try (InputStream is = url.openStream();
           JsonParser parser = Json.createParser(is)) {
           while (parser.hasNext()) {
             Event e = parser.next();
             if (e == Event.KEY_NAME) {
                   switch (parser.getString()) {
                      case "name":
                          parser.next();
                         System.out.print(parser.getString());
                         System.out.print(": ");
                         break;
                     case "message":
                         parser.next();
                          System.out.println(parser.getString());
                         System.out.println("---------");
                         break;
                  }
               }
           }
       }
     

1.2.15.20. Server-Sent Events (SSE)サポート

概要

Server-Sent Events API

サーバ実装とクライアント実装

     	...
      import com.nec.webotx.jersey.media.sse.EventOutput;
      import com.nec.webotx.jersey.media.sse.OutboundEvent;
      import com.nec.webotx.jersey.media.sse.SseFeature;
      ...
      @Path("events")
      public static class SseResource {
          @GET
          @Produces(SseFeature.SERVER_SENT_EVENTS)
          public EventOutput getServerSentEvents() {
              final EventOutput eventOutput = new EventOutput();
              new Thread(new Runnable() {
                  @Override
                  public void run() {
                      try {
                          for (int i = 0; i < 10; i++) {
                              // ... code that waits 1 second
                              final OutboundEvent.Builder eventBuilder
                              = new OutboundEvent.Builder();
                              eventBuilder.name("message-to-client");
                              eventBuilder.data(String.class,
                                  "Hello world " + i + "!");
                              final OutboundEvent event = eventBuilder.build();
                              eventOutput.write(event);
                          }
                      } catch (IOException e) {
                          throw new RuntimeException(
                              "Error when writing the event.", e);
                      } finally {
                          try {
                              eventOutput.close();
                          } catch (IOException ioClose) {
                              throw new RuntimeException(
                                  "Error when closing the event output.", ioClose);
                          }
                      }
                  }
              }).start();
              return eventOutput;
          }
      }
     

      Client client = ClientBuilder.newBuilder()
        .register(SseFeature.class).build();
      WebTarget target = client.target("http://localhost:9998/events");
 
      EventInput eventInput = target.request().get(EventInput.class);
      while (!eventInput.isClosed()) {
          final InboundEvent inboundEvent = eventInput.read();
          if (inboundEvent == null) {
              // connection has been closed
              break;
          }
          System.out.println(inboundEvent.getName() + "; "
              + inboundEvent.readData(String.class));
      }
     

1.2.15.21. 異常の処理

WebApplicationException

public class NotFoundException extends WebApplicationException {
   
   /**
     * Create a HTTP 404 (Not Found) exception.
     *
     * @param message the String that is the entity of the 404 response.
     */
    public NotFoundException(String message) {
        this(message, null);
    }

    /**
     * Create a HTTP 404 (Not Found) exception.
     *
     * @param message the String that is the entity of the 404 response.exception A URI-parameter-based exception for errors with QueryParam.Contain a response with a 404 (Client error) status code.
     *  ParamException.HeaderParamException	A parameter exception for errors with HeaderParam.Contain a response with a 400 (Client error) status code.
     *  ParamException.CookieParamException	A parameter exception for errors with CookieParam.Contain a response with a 400 (Client error) status code.
     *  ParamException.FormParamException	A parameter exception for errors with FormParam.Contain a response with a 400 (Client error) status code.
     * @param notFoundUri the URI that cannot be found.
     */
    public NotFoundException(String message, URI notFoundUri) {
        super(Responses.notFound().
                entity(message).type("text/plain").build());
        this.notFoundUri = notFoundUri;
    }
}

ExceptionMapperの使用

   @Provider
   public class EntityNotFoundMapper implements
           ExceptionMapper<EntityNotFoundException> {
       public Response toResponse(EntityNotFoundException ex) {
          return Response.status(404).
               entity(ex.getMessage()).
               type("text/plain").
              build();
       }
  }
 

• Applicationを継承する場合サブクラスに先に追加されたプロバイダを利用します。
• PackagesResourceConfigとcom.nec.webotx.jersey.config.property.packagesを利用する場合、クラス名の昇順で前のプロバイダを利用します。

1.2.15.22. warファイルの構成

warファイルの構成

（凡例）

−：説明や補足事項が特にないことを示します。

ルートリソースクラスの作成

• classesディレクトリ以下
• libディレクトリ以下に含まれるJARファイル内

JAX-RS機能の配備

      package com.nec.jersey.application;
      @ApplicationPath(“resources”)
      public class MyApplication extends Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> s = new HashSet<Class<?>>();
            s.add(HelloWorldResource.class);
            return s;
        }
    }
    

    package com.nec.jersey.application;
    public class MyApplication extends PackagesResourceConfig {
        public MyApplication() {
            super("com.nec.jersey.resource;com.nec.jersey.providers");
        }
    }
    

  <web-app>
       <servlet>
           <servlet-name>Jersey Web Application</servlet-name>
           <servlet-class>
             com.nec.webotx.jersey.spi.container.servlet.ServletContainer
           </servlet-class>
           <init-param>
               <param-name>
                 com.nec.webotx.jersey.config.property.packages
               </param-name>
               <param-value>com.nec.jersey.resource;com.nec.jersey.providers</param-value>
           </init-param>
           ...
      </servlet>
      ...
  </web-app>
  

1.2.15.23. WADL

WADLの概要

使用例の説明

  @Path("wadlResource")
  public class WADLResource {
	 @GET
	 public String executeGetRequest() {
		//do something
		return "success";
	 }
	 @POST
	 public String executePostRequest() {
		//do something
		return "success";
	 }
  }
  

  <web-app ……>
     ……
    <servlet>
  	   <servlet-name>wadlTest</servlet-name>
	   <servlet-class>
         com.nec.webotx.jersey.spi.container.servlet.ServletContainer
       </servlet-class>
  	    ……
    </servlet>
    <servlet-mapping>
  	   <servlet-name>wadlTest</servlet-name>
  	   <url-pattern>/jersey/*</url-pattern>
    </servlet-mapping>
    ……
  </web-app>
  

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <application xmlns="http://wadl.dev.java.net/2009/02">
     <doc xmlns:jersey=http://jersey.java.net/ …… />
     <grammars/>
     <resources base="http://{server-name}:{port}/{context-root}/{url-pattern}/">
         <resource path="wadlResource">
             <method id="executeGetRequest" name="GET">
                <response>
                    <representation mediaType="*/*"/>
                </response>
             </method>
             <method id="executePostRequest" name="POST">
                 <response>
                     <representation mediaType="*/*"/>
                 </response>
             </method>
         </resource>
     </resources>
    </application>
  

1.2.15.24. JAX-RS 1.1/2.0の切り替え

WebOTX AS V9.4では、JAX-RS 1.1もしくはJAX-RS 2.0を利用できます。 デフォルトの環境ではJAX-RS 1.1が有効になっています。 JAX-RS 2.0に切り替える場合は、切り替え対象のドメインを停止し、管理ドメインにログインした後、 以下のコマンドを実行して下さい。

    otxadmin > login --user <管理ドメインのユーザ名> ---password <管理ドメインのパスワード> --port <管理ドメインのポート番号>
    otxadmin > install-optional-component --domain <ドメイン名> --apgroup <アプリケーショングループ名> --pgroup <プロセスグループ名> jaxrs20

    otxadmin > login --user <管理ドメインのユーザ名> ---password <管理ドメインのパスワード> --port <管理ドメインのポート番号>
    otxadmin > uninstall-optional-component  --domain <ドメイン名> --apgroup <アプリケーショングループ名> --pgroup <プロセスグループ名> jaxrs20

JAX-RSの切り替えについてのより詳しい説明は[ ドメイン構築・基本設定ガイド > 3. ドメイン > 3.2. ドメインの作成・削除 > 3.2.1. ドメインの作成 > 3.2.1.7. オプショナルコンポーネントの有効化 ] を参照して下さい。