LinkRestのガイド

投稿日: 2019-10-18 2022-10-28
タグ: REST

1. 概要

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

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

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

**2. Mavenの依存関係**

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

<dependency>
    <groupId>com.nhl.link.rest</groupId>
    <artifactId>link-rest</artifactId>
    <version>2.9</version>
</dependency>

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

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

<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet</artifactId>
    <version>2.25.1</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-moxy</artifactId>
    <version>2.25.1</version>
</dependency>

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

<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>1.4.196</version>
</dependency>

3.3。カイエンデータ・モデル

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

前述のように、 LinkRestは、Apache CayenneORMを使用して生成されたデータオブジェクトを処理します。 Cayenne の操作はこの記事の主な主題ではないため、詳細については、ApacheCayenneのドキュメントを確認してください。

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

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

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

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

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

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

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

    public LinkRestApplication() {
        packages("com.baeldung.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に追加する必要があります。

<servlet>
    <servlet-name>linkrest</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.baeldung.LinkRestApplication</param-value>
        </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>linkrest</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

5. RESTリソース

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

RESTエンドポイントは、標準のJAX-RSアノテーションを使用して作成されますが、応答はLinkRestクラスを使用して作成されます。

この例では、さまざまな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アノテーションを使用して挿入されます。 X174X]。

次に、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[を返します。 X209X]。

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

DataResponse –のコレクションを表す応答 T
MetadataResponse –タイプに関するメタデータ情報が含まれています
SimpleResponse –2つのsuccessおよびmessage属性を含むオブジェクト

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

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

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

{"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<Department> getAll(@Context UriInfo uriInfo) {
    return LinkRest.select(Department.class, config).uri(uriInfo).get();
}

The uri（）呼び出しは、の要求情報を設定します SelectBuilder 、get（）はのコレクションを返します部門として包まれた DataResponse 物体。

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

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<Department> 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オブジェクトが返されます。その後、ID202の部門の名前が変更されたかどうかを確認できます。

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

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

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

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

また、オブジェクトを削除するには、 delete（）メソッドを呼び出して DeleteBuilder を作成し、を使用して削除するオブジェクトの主キーを指定します。 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 には、オブジェクト間の関係の操作を容易にするメソッドも含まれています。

DepartmentはEmployeeと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<Employee> getAll(@Context UriInfo uriInfo) {
    return LinkRest.select(Employee.class, config)
      .toManyParent(Department.class, departmentId, Department.EMPLOYEES)
      .uri(uriInfo).get();
}

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

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式の形式に従います。

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

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

6.2. 並べ替え

結果のセットをソートするために追加するパラメーターは、sortおよびdirです。これらの最初のものは並べ替える属性を指定し、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エンドポイントを介してデータモデルをすばやく公開する方法を示しました。

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

getdocs

13036