このガイドでは、ハイパーメディアベースの RESTful フロントエンドを介してグラフベースのデータにアクセスするアプリケーションを作成するプロセスについて説明します。

構築するもの

Spring Data REST を使用して、Neo4j (英語) NoSQL データベースに保管されている Person オブジェクトを作成および取得できる Spring アプリケーションを作成します。Spring Data REST は、Spring HATEOAS および Spring Data Neo4j の機能を使用して、自動的に結合します。

Spring Data REST は、バックエンドデータストアとして Spring Data JPASpring Data Gemfire、および Spring Data MongoDB もサポートしていますが、このガイドでは Neo4j を扱います。

必要なもの

このガイドを完了する方法

ほとんどの Spring 入門ガイドと同様に、最初から始めて各ステップを完了するか、すでに慣れている場合は基本的なセットアップステップをバイパスできます。いずれにしても、最終的に動作するコードになります。

最初から始めるには、[ スクラッチ ] に進みます。

基本スキップするには、次の手順を実行します。

完了したときは、gs-accessing-neo4j-data-rest/complete のコードに対して結果を確認できます。

Neo4j サーバーを立ち上げる

このアプリケーションを構築する前に、Neo4j サーバーをセットアップする必要があります。

Neo4j には、フリーでインストールできるオープンソースサーバーがあります。

Homebrew がインストールされた Mac では、ターミナルウィンドウで次のように入力できます。

$ brew install neo4j

他のオプションについては、https://neo4j.com/download/community-edition/ (英語) を参照してください

Neo4j をインストールしたら、次のコマンドを実行して、デフォルト設定で Neo4j を起動できます。

$ neo4j start

次のようなメッセージが表示されます。

Starting Neo4j.
Started neo4j (pid 96416). By default, it is available at http://localhost:7474/
There may be a short delay until the server is ready.
See /usr/local/Cellar/neo4j/3.0.6/libexec/logs/neo4j.log for current status.

デフォルトでは、Neo4j のユーザー名とパスワードは neo4j と neo4j です。ただし、新しいアカウントのパスワードを変更する必要があります。これを行うには、次のコマンドを実行します。

$ curl -v -u neo4j:neo4j -X POST localhost:7474/user/neo4j/password -H "Content-type:application/json" -d "{\"password\":\"secret\"}"

これにより、パスワードが neo4j から secret に変更されます(本番環境ではしないこと!)これが完了すると、このガイドを実行する準備が整います。

Spring Initializr から開始

すべての Spring アプリケーションでは、Spring Initializr (英語) から始める必要があります。Initializr は、アプリケーションに必要なすべての依存関係をすばやく取り込む方法を提供し、多くの設定を行います。この例では、Rest リポジトリと Spring Data Neo4j の依存関係が必要です。

このリンク (英語) に従って、プロジェクトスケルトンを作成できます。

次のリストは、Maven を選択したときに作成される pom.xml ファイルを示しています。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>accessing-neo4j-data-rest</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>accessing-neo4j-data-rest</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-neo4j</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

次のリストは、Gradle を選択したときに作成される build.gradle ファイルを示しています。

plugins {
	id 'org.springframework.boot' version '2.3.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-neo4j'
	implementation 'org.springframework.boot:spring-boot-starter-data-rest'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

Neo4j へのアクセス許可

Neo4j Community エディションにアクセスするには資格情報が必要です。次のように、src/main/resources/application.properties でプロパティを設定することにより、資格情報を設定できます。

spring.data.neo4j.username=neo4j
spring.data.neo4j.password=secret

これには、デフォルトのユーザー名(neo4j)および以前に設定した新しく設定されたパスワード(secret)が含まれます。

実際の資格情報をソースリポジトリに保存しないでください。代わりに、Spring Boot のプロパティのオーバーライドを使用してランタイムで構成します。

ドメインオブジェクトを作成する

次の例(src/main/java/com/example/accessingneo4jdatarest/Person.java)に示すように、新しいドメインオブジェクトを作成して人物を提示する必要があります。

package com.example.accessingneo4jdatarest;


import org.neo4j.ogm.annotation.GeneratedValue;
import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.NodeEntity;

@NodeEntity
public class Person {

  @Id @GeneratedValue private Long id;

  private String firstName;
  private String lastName;

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }
}

Person オブジェクトには、名と姓があります。また、自動的に生成されるように構成されている ID オブジェクトもあり、そうする必要はありません。

Person リポジトリを作成する

次に、次の例(src/main/java/com/example/accessingneo4jdatarest/PersonRepository.java)が示すように、単純なリポジトリを作成する必要があります。

package com.example.accessingneo4jdatarest;

import java.util.List;

import org.springframework.data.repository.PagingAndSortingRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource(collectionResourceRel = "people", path = "people")
public interface PersonRepository extends PagingAndSortingRepository<Person, Long> {

  List<Person> findByLastName(@Param("name") String name);

}

このリポジトリはインターフェースであり、Person オブジェクトに関連するさまざまな操作を実行できます。Spring Data Commons で定義された PagingAndSortingRepositry(Javadoc) インターフェースを継承することにより、これらの操作を取得します。

実行時に、Spring Data REST はこのインターフェースの実装を自動的に作成します。次に、@RepositoryRestResource (英語) アノテーションを使用して Spring MVC に /people で RESTful エンドポイントを作成するよう指示します。

@RepositoryRestResource は、リポジトリのエクスポートには必要ありません。/persons のデフォルト値の代わりに /people を使用するなど、エクスポートの詳細を変更するためにのみ使用されます。

ここでは、lastName 値に基づいて Person オブジェクトのリストを取得するカスタムクエリも定義しました。このガイドの後半で呼び出す方法を確認できます。

アプリケーションクラスの検索

Spring Initializr を使用してプロジェクトを作成すると、アプリケーションクラスが作成されます。src/main/java/com/example/accessingneo4jdatarest/Application.java で見つけることができます。Spring Initializr はパッケージ名を連結(および大文字小文字を適切に変更)し、Application に追加してアプリケーションケース名を作成することに注意してください。この場合、次のリストに示すように、AccessingNeo4jDataRestApplication を取得します。

package com.example.accessingneo4jdatarest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@EnableTransactionManagement
@EnableNeo4jRepositories
@SpringBootApplication
public class AccessingNeo4jDataRestApplication {

  public static void main(String[] args) {
    SpringApplication.run(AccessingNeo4jDataRestApplication.class, args);
  }
}

この例では、このアプリケーションクラスに変更を加える必要はありません。

@SpringBootApplication は、次のすべてを追加する便利なアノテーションです。

  • @Configuration: アプリケーションコンテキストの Bean 定義のソースとしてクラスにタグを付けます。

  • @EnableAutoConfiguration: クラスパス設定、他の Bean、およびさまざまなプロパティ設定に基づいて Bean の追加を開始するよう Spring Boot に指示します。例: spring-webmvc がクラスパスにある場合、このアノテーションはアプリケーションに Web アプリケーションとしてフラグを立て、DispatcherServlet のセットアップなどの主要な動作をアクティブにします。

  • @ComponentScan: Spring に、com/example パッケージ内の他のコンポーネント、構成、およびサービスを探して、コントローラーを検出させるように指示します。

main() メソッドは、Spring Boot の SpringApplication.run() メソッドを使用してアプリケーションを起動します。XML が 1 行もないことに気付きましたか? web.xml ファイルもありません。この Web アプリケーションは 100% 純粋な Java であり、接続機能やインフラストラクチャの構成に対処する必要はありませんでした。

@EnableNeo4jRepositories アノテーションは、Spring Data Neo4j をアクティブにします。Spring Data Neo4j は、PersonRepository の具体的な実装を作成し、Cypher クエリ言語を使用して組み込み Neo4j データベースと通信するように構成します。

実行可能 JAR を構築する

コマンドラインから Gradle または Maven を使用してアプリケーションを実行できます。必要なすべての依存関係、クラス、およびリソースを含む単一の実行可能 JAR ファイルを構築して実行することもできます。実行可能な jar を構築すると、開発ライフサイクル全体、さまざまな環境などで、アプリケーションとしてサービスを簡単に提供、バージョン管理、およびデプロイできます。

Gradle を使用する場合、./gradlew bootRun を使用してアプリケーションを実行できます。または、次のように、./gradlew build を使用して JAR ファイルをビルドしてから、JAR ファイルを実行できます。

java -jar build/libs/gs-accessing-neo4j-data-rest-0.1.0.jar

Maven を使用する場合、./mvnw spring-boot:run を使用してアプリケーションを実行できます。または、次のように、./mvnw clean package で JAR ファイルをビルドしてから、JAR ファイルを実行できます。

java -jar target/gs-accessing-neo4j-data-rest-0.1.0.jar
ここで説明する手順は、実行可能な JAR を作成します。クラシック WAR ファイルを作成することもできます。

ロギング出力が表示されます。サービスは数秒以内に起動して実行されるはずです。

アプリケーションをテストする

アプリケーションが実行されたため、テストできます。任意の REST クライアントを使用できます。次の例では、curl という *nix ツールを使用しています。

最初に、最上位のサービスを表示します。次の例(出力あり)は、その方法を示しています。

$ curl http://localhost:8080
{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    }
  }
}

ここでは、このサーバーが提供するものを最初に垣間見ることができます。http://localhost:8080/people にある people リンクがあります。?page?size や ?sort などのオプションがあります。

Spring Data REST は、JSON 出力に HAL フォーマット (英語) を使用します。柔軟性があり、提供されるデータに隣接するリンクを提供する便利な方法を提供します。
$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

現在、要素もページも存在しないため、新しい Person を作成します。これを行うには、次のコマンドを実行します(出力とともに表示)。

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "firstName" : "Frodo",  "lastName" : "Baggins" }' http://localhost:8080/people
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/people/0
Content-Length: 0
Date: Wed, 26 Feb 2014 20:26:55 GMT
  • -i は、ヘッダーを含むレスポンスメッセージを確認できるようにします。新しく作成された Person の URI が表示されます

  • -X POST は、新しいエントリの作成に使用される POST を通知する

  • -H "Content-Type:application/json" は、ペイロードタイプに JSON オブジェクトが含まれていることをアプリケーションが認識するようにコンテンツタイプを設定する

  • -d '{ "firstName" : "Frodo", "lastName" : "Baggins" }' は送信されるデータです

前の POST 操作に Location ヘッダーが含まれていることに注意してください。これには、新しく作成されたリソースの URI が含まれます。Spring Data REST には 2 つのメソッド(RepositoryRestConfiguration.setReturnBodyOnCreate(…) および setReturnBodyOnCreate(…))もあり、作成したリソースの表現をすぐに返すようにフレームワークを構成するために使用できます。

これから、次のコマンドを実行することにより、すべてのユーザーを照会できます(出力とともに表示)。

$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

people オブジェクトには、Frodo のリストが含まれています。self リンクが含まれていることに注意してください。Spring Data REST は、Evo インフレクター (英語) ライブラリを使用して、グループ化のためにエンティティの名前を複数形にします。

次のコマンドを実行することで、個々のレコードを直接照会できます(出力とともに表示)。

$ curl http://localhost:8080/people/0
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
これは純粋に Web ベースのように見えるかもしれませんが、裏では Neo4j グラフデータベースが組み込まれています。本番環境では、おそらくスタンドアロン Neo4j サーバーに接続します。

このガイドでは、ドメインオブジェクトは 1 つだけです。ドメインオブジェクトが互いに関連しているより複雑なシステムでは、Spring Data REST は追加のリンクをレンダリングして、接続されたレコードへのナビゲートを支援します。

次のコマンドを実行すると、すべてのカスタムクエリを見つけることができます(出力とともに表示)。

$ curl http://localhost:8080/people/search
{
  "_links" : {
    "findByLastName" : {
      "href" : "http://localhost:8080/people/search/findByLastName{?name}",
      "templated" : true
    }
  }
}

HTTP クエリパラメーター name を含むクエリの URL を確認できます。これは、インターフェースに埋め込まれた @Param("name") アノテーションと一致することに注意してください。

findByLastName クエリを使用するには、次のコマンドを実行します(出力とともに表示)。

$ curl http://localhost:8080/people/search/findByLastName?name=Baggins
{
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        },
        "person" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/search/findByLastName?name=Baggins"
    }
  }
}

コードで List<Person> を返すように定義しているため、すべての結果が返されます。Person のみを返すように定義している場合、Person オブジェクトの 1 つを選択して返します。これは予測できないため、複数のエントリを返す可能性のあるクエリに対してはそうしたくないでしょう。

PUTPATCH および DELETE REST 呼び出しを発行して、既存のレコードを置換、更新、または削除することもできます。次の例(出力とともに表示)は、PUT 呼び出しを示しています。

$ curl -X PUT -H "Content-Type:application/json" -d '{ "firstName": "Bilbo", "lastName": "Baggins" }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}

次の例(出力とともに表示)は、PATCH 呼び出しを示しています。

$ curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
PUT はレコード全体を置き換えます。指定されていないフィールドは null に置き換えられます。PATCH を使用して、アイテムのサブセットを更新できます。

次の例に示すように、レコードを削除することもできます(出力とともに表示)。

$ curl -X DELETE http://localhost:8080/people/0
$ curl http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

このハイパーメディア駆動型インターフェースの便利な側面は、curl(または任意の REST クライアント)を使用して、すべての RESTful エンドポイントを検出する方法です。正式な契約書やインターフェースドキュメントを顧客と交換する必要はありません。

要約

おめでとう!ハイパーメディアベースの RESTful フロントエンドと Neo4j ベースのバックエンドを備えたアプリケーションを開発しました。