JSON、Jackson、およびクライアントプログラムを使用したSpringのRestful Webサービスの例
SpringはJava EEフレームワークの中でも最も広く利用されている一つです。以前は、Spring MVCを使用してJavaベースのWebアプリケーションを作成する方法を紹介しました。今日は、Spring MVCを使用してSpringのRestful Webサービスを作成し、Restクライアントでテストします。最後に、Spring RestTemplate APIを使用してSpringのRestful Webサービスを呼び出す方法についても説明します。
スプリングREST
私たちは、最新バージョンのSpring 4.0.0.RELEASEを使用し、Spring Jackson JSONの統合を利用してJSONレスポンスをRESTコールの応答として送信します。このチュートリアルは、Spring STS IDEで簡単にSpring MVCのスケルトンコードを作成し、それを拡張してRestfulアーキテクチャを実装するために開発されています。STSで新しいSpring MVCプロジェクトを作成し、最終的なプロジェクトは以下の画像のようになります。それぞれのコンポーネントを順番に見ていきます。
SpringのREST構成XMLファイル
私たちのpom.xmlファイルは以下のように見えます。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="https://maven.apache.org/POM/4.0.0" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.scdev</groupId>
<artifactId>SpringRestExample</artifactId>
<name>SpringRestExample</name>
<packaging>war</packaging>
<version>1.0.0-BUILD-SNAPSHOT</version>
<properties>
<java-version>1.6</java-version>
<org.springframework-version>4.0.0.RELEASE</org.springframework-version>
<org.aspectj-version>1.7.4</org.aspectj-version>
<org.slf4j-version>1.7.5</org.slf4j-version>
<jackson.databind-version>2.2.3</jackson.databind-version>
</properties>
<dependencies>
<!-- Jackson -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.databind-version}</version>
</dependency>
<!-- Spring -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>${org.springframework-version}</version>
<exclusions>
<!-- Exclude Commons Logging in favor of SLF4j -->
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${org.springframework-version}</version>
</dependency>
<!-- AspectJ -->
<dependency>
<groupId>org.aspectj</groupId>
<artifactId>aspectjrt</artifactId>
<version>${org.aspectj-version}</version>
</dependency>
<!-- Logging -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>${org.slf4j-version}</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<version>${org.slf4j-version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>${org.slf4j-version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.15</version>
<exclusions>
<exclusion>
<groupId>javax.mail</groupId>
<artifactId>mail</artifactId>
</exclusion>
<exclusion>
<groupId>javax.jms</groupId>
<artifactId>jms</artifactId>
</exclusion>
<exclusion>
<groupId>com.sun.jdmk</groupId>
<artifactId>jmxtools</artifactId>
</exclusion>
<exclusion>
<groupId>com.sun.jmx</groupId>
<artifactId>jmxri</artifactId>
</exclusion>
</exclusions>
<scope>runtime</scope>
</dependency>
<!-- @Inject -->
<dependency>
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<version>1</version>
</dependency>
<!-- Servlet -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.5</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet.jsp</groupId>
<artifactId>jsp-api</artifactId>
<version>2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>1.2</version>
</dependency>
<!-- Test -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.7</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-eclipse-plugin</artifactId>
<version>2.9</version>
<configuration>
<additionalProjectnatures>
<projectnature>org.springframework.ide.eclipse.core.springnature</projectnature>
</additionalProjectnatures>
<additionalBuildcommands>
<buildcommand>org.springframework.ide.eclipse.core.springbuilder</buildcommand>
</additionalBuildcommands>
<downloadSources>true</downloadSources>
<downloadJavadocs>true</downloadJavadocs>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.5.1</version>
<configuration>
<source>1.6</source>
<target>1.6</target>
<compilerArgument>-Xlint:all</compilerArgument>
<showWarnings>true</showWarnings>
<showDeprecation>true</showDeprecation>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.2.1</version>
<configuration>
<mainClass>org.test.int1.Main</mainClass>
</configuration>
</plugin>
</plugins>
</build>
</project>
今日の日付を基準にして、STSツールは私たちのためにpom.xmlファイルを生成します。ただし、私はSpring Framework、AspectJ、SLF4J、およびJacksonのバージョンを最新のものに更新しました。ほとんどの部分は共通で自動生成されますが、重要なポイントは、オブジェクトをJSONに変換したり、逆に変換するためにJacksonのJSONライブラリを依存関係に追加したことです。
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="https://java.sun.com/xml/ns/javaee"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://java.sun.com/xml/ns/javaee https://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<!-- The definition of the Root Spring Container shared by all Servlets and Filters -->
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/spring/root-context.xml</param-value>
</context-param>
<!-- Creates the Spring Container shared by all Servlets and Filters -->
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<!-- Processes application requests -->
<servlet>
<servlet-name>appServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/spring/appServlet/servlet-context.xml</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>appServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
</web-app>
このファイルは自動的に生成されており、私はその中の何も変更していません。ただし、コンテキストの設定ファイルとその場所を変更したい場合は、web.xmlファイルで行うことができます。
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="https://www.springframework.org/schema/beans"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">
<!-- Root Context: defines shared resources visible to all other web components -->
</beans>
このファイルには、すべてのウェブコンポーネントで表示される共有リソースが含まれています。私たちはシンプルなRESTサービスを開発する予定であり、そのためここでは何も変更していません。
<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="https://www.springframework.org/schema/mvc"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="https://www.springframework.org/schema/beans"
xmlns:context="https://www.springframework.org/schema/context"
xsi:schemaLocation="https://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd
https://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
https://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd">
<!-- DispatcherServlet Context: defines this servlet's request-processing infrastructure -->
<!-- Enables the Spring MVC @Controller programming model -->
<annotation-driven />
<!-- Handles HTTP GET requests for /resources/** by efficiently serving up static resources in the ${webappRoot}/resources directory -->
<resources mapping="/resources/**" location="/resources/" />
<!-- Resolves views selected for rendering by @Controllers to .jsp resources in the /WEB-INF/views directory -->
<beans:bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
<beans:property name="prefix" value="/WEB-INF/views/" />
<beans:property name="suffix" value=".jsp" />
</beans:bean>
<!-- Configure to plugin JSON as request and response in method handler -->
<beans:bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
<beans:property name="messageConverters">
<beans:list>
<beans:ref bean="jsonMessageConverter"/>
</beans:list>
</beans:property>
</beans:bean>
<!-- Configure bean to convert JSON to POJO and vice versa -->
<beans:bean id="jsonMessageConverter" class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
</beans:bean>
<context:component-scan base-package="com.scdev.spring.controller" />
</beans:beans>
ほとんどの部分は自動生成され、ボイラープレートの設定が含まれています。ただし、注釈ベースの構成をサポートするための注釈ドリブンの要素や、RequestMappingHandlerAdapterのmessageConvertersにMappingJackson2HttpMessageConverterを組み込むことにより、Jackson APIが起動し、JSONをJavaのBeansに変換するように注意する必要があります。この設定を行うことで、リクエストボディにJSONを使用し、レスポンスでJSONデータを受け取ることができます。
春のRESTモデルクラス
私たちが書く簡単なPOJOクラスは、私たちのレストフルなWebサービスメソッドの入力と出力として機能するでしょう。
package com.scdev.spring.model;
import java.io.Serializable;
import java.util.Date;
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import com.fasterxml.jackson.databind.ser.std.DateSerializer;
public class Employee implements Serializable{
private static final long serialVersionUID = -7788619177798333712L;
private int id;
private String name;
private Date createdDate;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@JsonSerialize(using=DateSerializer.class)
public Date getCreatedDate() {
return createdDate;
}
public void setCreatedDate(Date createdDate) {
this.createdDate = createdDate;
}
}
重要なポイントは、@JsonSerialize アノテーションの使用で、Javaの日付をJSON形式に変換するために DateSerializer クラスを使うこと、そしてその逆の変換も行うことです。
Spring Restful web serviceのエンドポイント
以下のREST Webサービスのエンドポイントを用意します。
| Sl. No | URI | HTTP Method | Details |
|---|---|---|---|
| 1 | /rest/emp/dummy | GET | Health Check service, to insert a dummy data in the Employees data storage |
| 2 | /rest/emp/{id} | GET | To get the Employee object based on the id |
| 3 | /rest/emps | GET | To get the list of all the Employees in the data store |
| 4 | /rest/emp/create | POST | To create the Employee object and store it |
| 5 | /rest/emp/delete/{id} | PUT | To delete the Employee object from the data storage based on the id |
私たちには、これらのURIを文字列定数として定義するクラスがあります。
package com.scdev.spring.controller;
public class EmpRestURIConstants {
public static final String DUMMY_EMP = "/rest/emp/dummy";
public static final String GET_EMP = "/rest/emp/{id}";
public static final String GET_ALL_EMP = "/rest/emps";
public static final String CREATE_EMP = "/rest/emp/create";
public static final String DELETE_EMP = "/rest/emp/delete/{id}";
}
SpringのRestfulウェブサービスのコントローラークラス
上記で説明されたすべてのWebサービスのエンドポイントは、私たちのEmployeeControllerクラスによって公開されます。クラスのコードを見て、それぞれのメソッドについて詳しく学びましょう。
package com.scdev.spring.controller;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.scdev.spring.model.Employee;
/**
* Handles requests for the Employee service.
*/
@Controller
public class EmployeeController {
private static final Logger logger = LoggerFactory.getLogger(EmployeeController.class);
//Map to store employees, ideally we should use database
Map<Integer, Employee> empData = new HashMap<Integer, Employee>();
@RequestMapping(value = EmpRestURIConstants.DUMMY_EMP, method = RequestMethod.GET)
public @ResponseBody Employee getDummyEmployee() {
logger.info("Start getDummyEmployee");
Employee emp = new Employee();
emp.setId(9999);
emp.setName("Dummy");
emp.setCreatedDate(new Date());
empData.put(9999, emp);
return emp;
}
@RequestMapping(value = EmpRestURIConstants.GET_EMP, method = RequestMethod.GET)
public @ResponseBody Employee getEmployee(@PathVariable("id") int empId) {
logger.info("Start getEmployee. ID="+empId);
return empData.get(empId);
}
@RequestMapping(value = EmpRestURIConstants.GET_ALL_EMP, method = RequestMethod.GET)
public @ResponseBody List<Employee> getAllEmployees() {
logger.info("Start getAllEmployees.");
List<Employee> emps = new ArrayList<Employee>();
Set<Integer> empIdKeys = empData.keySet();
for(Integer i : empIdKeys){
emps.add(empData.get(i));
}
return emps;
}
@RequestMapping(value = EmpRestURIConstants.CREATE_EMP, method = RequestMethod.POST)
public @ResponseBody Employee createEmployee(@RequestBody Employee emp) {
logger.info("Start createEmployee.");
emp.setCreatedDate(new Date());
empData.put(emp.getId(), emp);
return emp;
}
@RequestMapping(value = EmpRestURIConstants.DELETE_EMP, method = RequestMethod.PUT)
public @ResponseBody Employee deleteEmployee(@PathVariable("id") int empId) {
logger.info("Start deleteEmployee.");
Employee emp = empData.get(empId);
empData.remove(empId);
return emp;
}
}
簡単のため、すべての従業員のデータをHashMap empDataに保存しています。@RequestMappingアノテーションは、リクエストURIをハンドラメソッドにマッピングするために使用されます。クライアントアプリケーションがRESTメソッドを呼び出すために使用するHTTPメソッドを指定することもできます。@ResponseBodyアノテーションは、応答オブジェクトを応答ボディにマッピングするために使用されます。ハンドラメソッドによって応答オブジェクトが返されると、MappingJackson2HttpMessageConverterが応答をJSON応答に変換します。@PathVariableアノテーションは、REST URIからデータを抽出し、メソッド引数にマッピングする簡単な方法です。@RequestBodyアノテーションは、リクエストボディのJSONデータをEmployeeオブジェクトにマッピングするために使用されます。これもMappingJackson2HttpMessageConverterによるマッピングです。コードの残りは単純で自己解明です。アプリケーションはデプロイとテストの準備ができています。WARファイルとしてエクスポートし、サーブレットコンテナのWebアプリディレクトリにコピーするだけです。STSでサーバーが設定されている場合は、サーバーで実行してデプロイできます。REST呼び出しを実行するためにWizTools RestClientを使用していますが、Chrome拡張機能のPostmanも使用できます。以下のスクリーンショットは、アプリケーションによって公開されたREST APIの異なる呼び出しとその出力を示しています。ヘルスチェック – ダミー従業員の取得REST呼び出し、従業員の作成POST REST呼び出し：リクエストのContent-Typeが “application/json”に設定されていることを確認してください。そうでない場合、HTTPエラーコード415が表示されます。従業員の取得REST呼び出し、従業員の削除REST呼び出し、すべての従業員の取得REST呼び出し
春のレストクライアントプログラム
Restクライアントは、私たちのRESTウェブサービスをテストするのに適していますが、ほとんどの場合、プログラムを通じてRESTサービスを呼び出す必要があります。Spring RestTemplateを使用することで、これらのメソッドを簡単に呼び出すことができます。以下は、RestTemplate APIを使用して私たちのアプリケーションのRESTメソッドを呼び出す単純なプログラムです。
package com.scdev.spring;
import java.util.LinkedHashMap;
import java.util.List;
import org.springframework.web.client.RestTemplate;
import com.scdev.spring.controller.EmpRestURIConstants;
import com.scdev.spring.model.Employee;
public class TestSpringRestExample {
public static final String SERVER_URI = "https://localhost:9090/SpringRestExample";
public static void main(String args[]){
testGetDummyEmployee();
System.out.println("*****");
testCreateEmployee();
System.out.println("*****");
testGetEmployee();
System.out.println("*****");
testGetAllEmployee();
}
private static void testGetAllEmployee() {
RestTemplate restTemplate = new RestTemplate();
//we can't get List<Employee> because JSON convertor doesn't know the type of
//object in the list and hence convert it to default JSON object type LinkedHashMap
List<LinkedHashMap> emps = restTemplate.getForObject(SERVER_URI+EmpRestURIConstants.GET_ALL_EMP, List.class);
System.out.println(emps.size());
for(LinkedHashMap map : emps){
System.out.println("ID="+map.get("id")+",Name="+map.get("name")+",CreatedDate="+map.get("createdDate"));;
}
}
private static void testCreateEmployee() {
RestTemplate restTemplate = new RestTemplate();
Employee emp = new Employee();
emp.setId(1);emp.setName("Pankaj Kumar");
Employee response = restTemplate.postForObject(SERVER_URI+EmpRestURIConstants.CREATE_EMP, emp, Employee.class);
printEmpData(response);
}
private static void testGetEmployee() {
RestTemplate restTemplate = new RestTemplate();
Employee emp = restTemplate.getForObject(SERVER_URI+"/rest/emp/1", Employee.class);
printEmpData(emp);
}
private static void testGetDummyEmployee() {
RestTemplate restTemplate = new RestTemplate();
Employee emp = restTemplate.getForObject(SERVER_URI+EmpRestURIConstants.DUMMY_EMP, Employee.class);
printEmpData(emp);
}
public static void printEmpData(Employee emp){
System.out.println("ID="+emp.getId()+",Name="+emp.getName()+",CreatedDate="+emp.getCreatedDate());
}
}
プログラムのほとんどは理解しやすいですが、コレクションを返すRESTメソッドを呼び出す際には、JSONからオブジェクトに変換する際にEmployeeオブジェクトについて知らないため、LinkedHashMapのコレクションに変換します。LinkedHashMapからJava Beanオブジェクトに変換するためのユーティリティメソッドを作成することができます。上記のプログラムを実行すると、コンソールに以下の出力が表示されます。
ID=9999,Name=Dummy,CreatedDate=Tue Mar 04 21:02:41 PST 2014
*****
ID=1,Name=Pankaj Kumar,CreatedDate=Tue Mar 04 21:02:41 PST 2014
*****
ID=1,Name=Pankaj Kumar,CreatedDate=Tue Mar 04 21:02:41 PST 2014
*****
2
ID=1,Name=Pankaj Kumar,CreatedDate=1393995761654
ID=9999,Name=Dummy,CreatedDate=1393995761381
もう一つのポイントは、RestTemplateのPUTメソッドにはレスポンスオブジェクトを設定するオプションがないことです。PUTメソッドはサーバーに何かを保存するために使用されるべきであり、単純なHTTP 200ステータスコードで十分です。
スプリングのRestfulウェブサービスプロジェクトをダウンロードしてください。
これがSpring Restful Webアプリケーションチュートリアルのすべてです。上記のリンクからサンプルプロジェクトをダウンロードして、試してみて、さらに学びましょう。追記：XMLもサポートし、XMLとJSONの両方をサポートする同様の例を提供するための多くのリクエストがあったため、このアプリケーションをSpring REST XML JSON例として拡張しました。この例を通じて、Springフレームワークの美しさとこれを実現するための簡単さをご覧いただくことを強くお勧めします。
私たちのGitHubリポジトリから、プロジェクト全体をダウンロードすることができます。
