LinkRestへのガイド

LinkRestガイド

1. 概要

LinkRestは、データ駆動型のRESTWebサービスを構築するためのオープンソースフレームワークです。 JAX-RSApache Cayenne ORMの上に構築され、HTTP / JSONベースのメッセージプロトコルを使用します。

基本的に、このフレームワークは、Webでデータストアを公開する簡単な方法を提供することを目的としています。

次のセクションでは、LinkRestを使用してデータモデルにアクセスするためのRESTWebサービスを構築する方法を見ていきます。

2. Mavenの依存関係

ライブラリの操作を開始するには、最初にlink-rest依存関係を追加する必要があります。


    com.nhl.link.rest
    link-rest
    2.9

これにより、cayenne-serverアーティファクトも発生します。

さらに、JAX-RSの実装としてJerseyを使用するため、JSON応答をシリアル化するためにjersey-container-servlet依存関係とjersey-media-moxyを追加する必要があります。


    org.glassfish.jersey.containers
    jersey-container-servlet
    2.25.1


    org.glassfish.jersey.media
    jersey-media-moxy
    2.25.1

この例では、セットアップが簡単なため、メモリ内のH2データベースを使用します。結果として、h2も追加します:


    com.h2database
    h2
    1.4.196

3. Cayenneデータモデル

使用するデータモデルには、1対多の関係を表すDepartmentエンティティとEmployeeエンティティが含まれています。

image

前述のように、LinkRest works with data objects generated using Apache Cayenne ORMCayenneの操作はこの記事の主な主題ではないため、詳細についてはApache Cayenne documentationを確認してください。

Cayenneプロジェクトをcayenne-linkrest-project.xmlファイルに保存します。

cayenne-maven-pluginを実行した後、これにより2つのDepartment_ and Employee_抽象クラスが生成されます。これにより、CayenneDataObjectクラスと、それらから派生した2つの具象クラスDepartmentおよびEmployee

これらの後者のクラスは、カスタマイズしてLinkRestで使用できるクラスです。

4. LinkRestアプリケーションの起動

次のセクションでは、RESTエンドポイントを作成してテストするので、それらを実行できるようにするには、ランタイムを設定する必要があります。

JAX-RSの実装としてJerseyを使用しているので、ResourceConfigを拡張し、RESTエンドポイントを定義するクラスを保持するパッケージを指定するクラスを追加しましょう。

@ApplicationPath("/linkrest")
public class LinkRestApplication extends ResourceConfig {

    public LinkRestApplication() {
        packages("com.example.linkrest.apis");

        // load linkrest runtime
    }
}

同じコンストラクターで、LinkRestRuntimeをビルドしてJerseyコンテナーに登録する必要があります。 このクラスは、最初にCayenneRuntimeをロードすることに基づいています。

ServerRuntime cayenneRuntime = ServerRuntime.builder()
  .addConfig("cayenne-linkrest-project.xml")
  .build();
LinkRestRuntime lrRuntime = LinkRestBuilder.build(cayenneRuntime);
super.register(lrRuntime);

最後に、クラスをweb.xmlに追加する必要があります。


    linkrest
    org.glassfish.jersey.servlet.ServletContainer
        
            javax.ws.rs.Application
            com.example.LinkRestApplication
        
    1


    linkrest
    /*

5. RESTリソース

モデルクラスができたので、RESTリソースの作成を開始できます。

REST endpoints are created using standard JAX-RS annotations, while the response is built using the LinkRest class.

この例では、さまざまなHTTPメソッドを使用して/departmentURLにアクセスする一連のCRUDエンドポイントを作成します。

まず、/departmentにマップされるDepartmentResourceクラスを作成しましょう。

@Path("department")
@Produces(MediaType.APPLICATION_JSON)
public class DepartmentResource {

    @Context
    private Configuration config;

    // ...
}

LinkRestクラスには、JAX-RS Configurationクラスのインスタンスが必要です。これは、JAX-RSによって提供されるContextアノテーションを使用して挿入されます。

次に、Departmentオブジェクトにアクセスする各エンドポイントの記述を続けましょう。

5.1. POSTを使用したエンティティの作成

エンティティを作成するために、LinkRestクラスはUpdateBuilderオブジェクトを返すcreate()メソッドを提供します。

@POST
public SimpleResponse create(String data) {
    return LinkRest.create(Department.class, config).sync(data);
}

データパラメータは、Departmentを表す単一のJSONオブジェクト、またはオブジェクトの配列のいずれかです。 このパラメーターは、sync()メソッドを使用してUpdateBuilderに送信され、1つ以上のオブジェクトが作成され、レコードがデータベースに挿入されます。その後、メソッドはSimpleResponseを返します。

ライブラリは、応答用に3つの追加形式を定義します。

  • DataResponse<T>Tのコレクションを表す応答

  • MetadataResponse<T> –タイプに関するメタデータ情報が含まれています

  • SimpleResponse – 2つのsuccess属性とmessage属性を含むオブジェクト

次に、curlを使用して、Departmentレコードをデータベースに追加しましょう。

curl -i -X POST -H "Content-Type:application/json"
  -d "{"name":"IT"}" http://localhost:8080/linkrest/department

その結果、コマンドはステータス201 Createdsuccess属性を返します。

{"success":true}

JSON配列を送信して、複数のオブジェクトを作成することもできます。

curl -i -X POST -H "Content-Type:application/json"
  -d "[{"name":"HR"},{"name":"Marketing"}]"
  http://localhost:8080/linkrest/department

5.2. GETを使用したエンティティの読み取り

オブジェクトをクエリするための主なメソッドは、LinkRestクラスのselect()メソッドです。 これは、追加のクエリまたはフィルタリングメソッドをチェーンするために使用できるSelectBuilderオブジェクトを返します。

データベース内のすべてのDepartmentオブジェクトを返すDepartmentResourceクラスにエンドポイントを作成しましょう。

@GET
public DataResponse getAll(@Context UriInfo uriInfo) {
    return LinkRest.select(Department.class, config).uri(uriInfo).get();
}

uri()呼び出しは、SelectBuilderの要求情報を設定し、get()は、DataResponse<Department>オブジェクトとしてラップされたDepartmentsのコレクションを返します。

このエンドポイントを使用する前に追加した部門を見てみましょう。

curl -i -X GET http://localhost:8080/linkrest/department

応答は、data配列とtotalプロパティを持つJSONオブジェクトの形式を取ります。

{"data":[
  {"id":200,"name":"IT"},
  {"id":201,"name":"Marketing"},
  {"id":202,"name":"HR"}
],
"total":3}

または、オブジェクトのコレクションを取得するために、get()の代わりにgetOne()を使用して単一のオブジェクトを取得することもできます。

指定されたIDを持つオブジェクトを返す/department/{departmentId}にマップされたエンドポイントを追加しましょう。 この目的のために、byId()メソッドを使用してレコードをフィルタリングします。

@GET
@Path("{id}")
public DataResponse getOne(@PathParam("id") int id,
  @Context UriInfo uriInfo) {
    return LinkRest.select(Department.class, config)
      .byId(id).uri(uriInfo).getOne();
}

次に、次のURLにGETリクエストを送信できます。

curl -i -X GET http://localhost:8080/linkrest/department/200

結果は、1つの要素を持つdata配列です。

{"data":[{"id":200,"name":"IT"}],"total":1}

5.3. PUTを使用したエンティティの更新

レコードを更新するには、update()またはcreateOrUpdate()メソッドを使用できます。 後者は、存在する場合はレコードを更新し、存在しない場合は作成します。

@PUT
public SimpleResponse createOrUpdate(String data) {
    return LinkRest.createOrUpdate(Department.class, config).sync(data);
}

前のセクションと同様に、data引数は単一のオブジェクトまたはオブジェクトの配列にすることができます。

以前に追加した部門の1つを更新しましょう:

curl -i -X PUT -H "Content-Type:application/json"
  -d "{"id":202,"name":"Human Resources"}"
  http://localhost:8080/linkrest/department

これにより、成功またはエラーメッセージを含むJSONオブジェクトが返されます。 その後、ID 202の部門名が変更されたかどうかを確認できます。

curl -i -X GET http://localhost:8080/linkrest/department/202

案の定、このコマンドは新しい名前のオブジェクトを返します:

{"data":[
  {"id":202,"name":"Human Resources"}
],
"total":1}

5.4. DELETEを使用したエンティティの削除

また、オブジェクトを削除するには、DeleteBuilderを作成するdelete()メソッドを呼び出し、id()メソッドを使用して削除するオブジェクトの主キーを指定します。

@DELETE
@Path("{id}")
public SimpleResponse delete(@PathParam("id") int id) {
    return LinkRest.delete(Department.class, config).id(id).delete();
}

次に、curlを使用してこのエンドポイントを呼び出すことができます。

curl -i -X DELETE http://localhost:8080/linkrest/department/202

5.5. エンティティ間の関係の操作

LinkRestには、オブジェクト間の関係の操作を容易にするメソッドも含まれています。

DepartmentEmployeeと1対多の関係にあるため、EmployeeSubResourceクラスにアクセスする/department/{departmentId}/employeesエンドポイントを追加しましょう。

@Path("{id}/employees")
public EmployeeSubResource getEmployees(
  @PathParam("id") int id, @Context UriInfo uriInfo) {
    return new EmployeeSubResource(id);
}

EmployeeSubResourceクラスは部門に対応しているため、部門IDを設定するコンストラクターとConfigurationインスタンスがあります。

@Produces(MediaType.APPLICATION_JSON)
public class EmployeeSubResource {
    private Configuration config;

    private int departmentId;

    public EmployeeSubResource(int departmentId, Configuration configuration) {
        this.departmentId = departmentId;
        this.config = config;
    }

    public EmployeeSubResource() {
    }
}

オブジェクトをJSONオブジェクトとしてシリアル化するには、デフォルトのコンストラクターが必要であることに注意してください。

次に、部門からすべての従業員を取得するエンドポイントを定義しましょう。

@GET
public DataResponse getAll(@Context UriInfo uriInfo) {
    return LinkRest.select(Employee.class, config)
      .toManyParent(Department.class, departmentId, Department.EMPLOYEES)
      .uri(uriInfo).get();
}

この例では、SelectBuildertoManyParent()メソッドを使用して、特定の親を持つオブジェクトのみをクエリしました。

POST、PUT、DELETEメソッドのエンドポイントも同様の方法で作成できます。

従業員を部門に追加するには、POSTメソッドを使用してdepartments/{departmentId}/employeesエンドポイントを呼び出すことができます。

curl -i -X POST -H "Content-Type:application/json"
  -d "{"name":"John"}" http://localhost:8080/linkrest/department/200/employees

次に、部門の従業員を表示するためにGETリクエストを送信しましょう。

curl -i -X GET "http://localhost:8080/linkrest/department/200/employees
これは、データ配列を持つJSONオブジェクトを返します
{"data":[{"id":200,"name":"John"}],"total":1}

6. リクエストパラメータを使用したレスポンスのカスタマイズ

LinkRestは、要求に特定のパラメーターを追加することにより、応答をカスタマイズする簡単な方法を提供します。 これらを使用して、結果セットの属性セットをフィルタリング、ソート、ページ分割、または制限できます。

6.1. フィルタリング

cayenneExpパラメータを使用して、属性の値に基づいて結果をフィルタリングできます。 名前が示すように、これはCayenne expressionsの形式に従います。

「IT」という名前の部門のみを返すリクエストを送信しましょう。

curl -i -X GET http://localhost:8080/linkrest/department?cayenneExp=name='IT'

6.2. ソート

結果のセットをソートするために追加するパラメーターは、sortdirです。 これらの最初はソートする属性を指定し、2番目はソートの方向を指定します。

名前でソートされたすべての部門を見てみましょう。

curl -i -X GET "http://localhost:8080/linkrest/department?sort=name&dir=ASC"

6.3. ページ付け

ライブラリは、startおよびlimitパラメータを追加することでページネーションをサポートします。

curl -i -X GET "http://localhost:8080/linkrest/department?start=0&limit=2

6.4. 属性の選択

includeおよびexcludeパラメータを使用して、結果で返される属性または関係を制御できます。

たとえば、部門の名前のみを表示するリクエストを送信しましょう。

curl -i -X GET "http://localhost:8080/linkrest/department?include=name

名前とその名前だけの部門の従業員を表示するには、include属性を2回使用します。

curl -i -X GET "http://localhost:8080/linkrest/department?include=name&include=employees.name

7. 結論

この記事では、LinkRestフレームワークを使用して、RESTエンドポイントを介してデータモデルをすばやく公開する方法を示しました。

例の完全なソースコードはover on GitHubにあります。