Spring Restful WebサービスのJSON、Jackson、およびクライアントプログラムを使用した例

Springは最も広く使用されているJava EEフレームワークの一つです。以前、Spring MVCを使用してJavaベースのWebアプリケーションを作成する方法を見てきました。今日は、Spring MVCを使用してSpringのRestful Webサービスを作成し、Restクライアントでテストする方法を学びます。最後に、SpringのRestTemplate APIを使用してSpringのRestful Webサービスを呼び出す方法についても説明します。

SpringのREST

私たちは最新バージョンのSpring 4.0.0.RELEASEを使用し、Spring Jackson JSONの統合を利用して、RESTコールのレスポンスでJSONを送信します。このチュートリアルは、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.journaldev</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>

このファイルには、すべてのWebコンポーネントに表示される共有リソースが含まれています。私たちはシンプルな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.journaldev.spring.controller" />
	
</beans:beans>

ほとんどの部分は自動生成され、ボイラープレートの構成が含まれています。ただし、注目すべき重要な点は、アノテーションベースの構成をサポートするannotation-driven要素と、RequestMappingHandlerAdapterのmessageConvertersにMappingJackson2HttpMessageConverterを追加することです。これにより、Jackson APIが実行され、JSONをJava Beansに変換し、その逆も行います。この構成を使用することで、リクエストボディにはJSONを使用し、レスポンスではJSONデータを受け取ることができます。

Spring RESTモデルクラス

単純なPOJOクラスを作成しましょう。これは、私たちのRESTful Webサービスメソッドの入力および出力として機能します。

package com.journaldev.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;
	}
	
	
}

注目すべき重要な点は、JavaのDate型からJSON形式への変換およびその逆にDateSerializerクラスを使用するための@JsonSerializeアノテーションの使用です。

Spring Restfulウェブサービスのエンドポイント

以下のRESTウェブサービスのエンドポイントを持っています。

これらのURIを文字列定数として定義するクラスがあります。

package com.journaldev.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ウェブサービスのコントローラークラス

EmployeeControllerクラスは、上記で言及されたすべてのウェブサービスのエンドポイントを公開します。クラスのコードを見て、それぞれのメソッドについて詳しく学びましょう。

package com.journaldev.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.journaldev.spring.model.Employee;

/**
 * Handles requests for the Employee service.
 */
@Controller
public class EmployeeController {
	
	private static final Logger logger = LoggerFactory.getLogger(EmployeeController.class);
	
	//従業員を格納するためのマップ、理想的にはデータベースを使用するべきです
	Map empData = new HashMap();
	
	@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 getAllEmployees() {
		logger.info("Start getAllEmployees.");
		List emps = new ArrayList();
		Set 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でサーバーが設定されている場合、サーバーで実行してデプロイすることもできます。私はWizTools RestClientを使用してREST呼び出しを行っていますが、Chrome拡張機能のPostmanも使用できます。以下のスクリーンショットは、アプリケーションによって公開されたREST APIの異なる呼び出しとその出力を示しています。ヘルスチェック – ダミー従業員の取得REST呼び出し 従業員の作成POST REST呼び出し: リクエストのContent-Typeが “application/json”に設定されていることを確認してください。そうでない場合、HTTPエラーコード415が返されます。 従業員の取得REST呼び出し 従業員の削除REST呼び出し すべての従業員の取得REST呼び出し

Spring Rest クライアントプログラム

Restクライアントは、私たちのRest Webサービスをテストするのに役立ちますが、ほとんどの場合、プログラムを介してRestサービスを呼び出す必要があります。これらのメソッドを簡単に呼び出すためにSpringのRestTemplateを使用できます。以下は、RestTemplate APIを使用してアプリケーションのrestメソッドを呼び出す単純なプログラムです。

package com.journaldev.spring;

import java.util.LinkedHashMap;
import java.util.List;

import org.springframework.web.client.RestTemplate;

import com.journaldev.spring.controller.EmpRestURIConstants;
import com.journaldev.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();
		// JSONコンバーターはリスト内のオブジェクトの型を知らないため、
		//デフォルトのJSONオブジェクトタイプLinkedHashMapに変換します。
		List 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メソッドを呼び出す場合、LinkedHashMapを使用する必要があります。これは、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

もう1つのポイントは、RestTemplateのputメソッドには応答オブジェクトを設定するオプションがないことです。PUTメソッドはサーバーに何かを保存するために使用されるべきであり、単純なHTTP 200ステータスコードで十分です。

Spring Restful Webサービスプロジェクトのダウンロード

それがSpring Restful webアプリケーションチュートリアルのすべてです。上記のリンクからサンプルプロジェクトをダウンロードして、さらに試してみて、より多くを学んでください。 更新：XMLおよびJSONの両方をサポートする同様の例を提供するための多くのリクエストがあったため、このアプリケーションをSpring REST XML JSON Exampleで拡張しました。XMLおよびJSONのリクエストとレスポンスの両方をサポートするためのSpringフレームワークの美しさと、これを達成するのがどれほど簡単かを確認するために、それを参照することを強くお勧めします。

完全なプロジェクトは、GitHubリポジトリからダウンロードできます。