CAP Java用のプラグイン作成方法

Posted at 2025-12-06

はじめに

この記事は SAP Advent Calendar 2025 の12月4日分の記事として執筆しています。

CAPには、共通で行いたいイベントハンドラの処理やCDSモデルなどを「プラグイン」として登録し、他のプロジェクトから利用するための仕組みがあります。
この記事では、CAP Javaでのプラグイン作成手順について紹介します。

💡CAP Node.jsでのプラグインの作成と利用方法についてはこちら

CAP Javaのプラグイン作成手順

以下のドキュメントとブログを参考に、@emojiというアノテーションをつけた項目に絵文字を追加するプラグインを作成します。

完成形は以下のようになります。

プラグインはNew Maven Artifactとして作成します。今回は以下のGroupIdとArtifactIdを使用します。

GroupId: com.example.cap.plugins
ArtifactId: emoji-plugin

ステップ

プラグインプロジェクトを初期化
pom.xmlを編集
イベントハンドラを追加
RuntimeConfigurationを追加
ServiceLoader メタ情報を登録
cdsファイルを追加
プラグインをビルド

1. プラグインプロジェクトを初期化

以下のコマンドでプロジェクトを初期化します。

mvn -q archetype:generate \
  -DgroupId=com.example.cap.plugins \
  -DartifactId=emoji-plugin \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DinteractiveMode=false

2. pom.xmlを編集

pom.xmlを以下のように編集します。

<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 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.cap.plugins</groupId>
  <artifactId>emoji-plugin</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>emoji-plugin</name>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <!-- プラグイン使用側のcds.javaバージョン -->
    <cds.services.version>4.4.0</cds.services.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-services-bom</artifactId>
        <version>${cds.services.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>  
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>com.sap.cds</groupId>
      <artifactId>cds-services-api</artifactId>
    </dependency>
  </dependencies>  
</project>

3. イベントハンドラを追加

src/main/java/<package-folder>にイベントハンドラを追加します。

@emojiというアノテーションがついた要素に📚の絵文字を追加します。

package com.example.cap.plugins;

import com.sap.cds.CdsDataProcessor;
import com.sap.cds.services.cds.ApplicationService;
import com.sap.cds.services.cds.CdsReadEventContext;
import com.sap.cds.services.handler.EventHandler;
import com.sap.cds.services.handler.annotations.After;
import com.sap.cds.services.handler.annotations.ServiceName;

@ServiceName(value = "*", type = ApplicationService.class)
public class EmojiReadHandler implements EventHandler{
    private static final String EMOJI_ANNOTATION_NAME = "@emoji";
    
    @After
    public void decorateEmoji(CdsReadEventContext context) {
        CdsDataProcessor.create()
            .addConverter(
                (path, element, type) -> element.findAnnotation(EMOJI_ANNOTATION_NAME).isPresent(),
                (path, element, value) -> value + " 📚"
            ).process(context.getResult());
    }
}

4. RuntimeConfigurationを追加

同じディレクトリにRuntimeConfiguration用のJavaファイルを追加します。

CAP JavaのService Loaderがステップ3で作成したイベントハンドラをロードするようにします。

package com.example.cap.plugins;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.sap.cds.services.runtime.CdsRuntimeConfiguration;
import com.sap.cds.services.runtime.CdsRuntimeConfigurer;

public class EmojiRuntimeConfiguration implements CdsRuntimeConfiguration{
    private static final Logger logger = LoggerFactory.getLogger(EmojiRuntimeConfiguration.class);

    @Override
    public void eventHandlers(CdsRuntimeConfigurer configurer) {
        configurer.eventHandler(new EmojiReadHandler());
        logger.info("[emoji-plugin] EmojiReadHandler successfully registered ✅");
    }
}

5. ServiceLoader メタ情報を登録

CAPは実行時にServiceLoaderの仕組みを使用してアプリケーションのクラスパスにあるCdsRuntimeConfigurationインターフェースのすべての実装を読み込みます。このときに4で作成したクラスが認識されるように、以下の設定を行います。

src/main/resources/META-INF/servicesにcom.sap.cds.services.runtime.CdsRuntimeConfigurationというファイルを作成し、ステップ4で実装したクラス名を登録します。

com.example.cap.plugins.EmojiRuntimeConfiguration

6. cdsファイルを追加

プラグインでcdsモデル（アスペクト、タイプなど）を作成して再利用したいケースがあります。その場合は、src/main/resources/cds/<groupId>/<artifactId>配下にindex.cdsというファイルを作成します。

namespace com.example.cap.plugins.emoji;

type EmojiString: String(200);

aspect emoji {
    emojiString: EmojiString;
}

目的別に.cdsファイルを分けて構造化したい場合はCAP JavaのAttachmentsプラグインが参考になります。

プラグインにはindex.cdsのほかに2つの.cdsファイルがあります。

それぞれのcdsファイルで定義したモデルをindex.cdsにインポートしています。

index.cds

using from`./attachments`;
using from`./attachments-annotations`;
using from '@sap/cds/srv/outbox';

7. プラグインをビルド

以下のコマンドでプラグインをビルドし、ローカル Maven リポジトリへインストールします。

mvn -q -DskipTests clean install

この結果、成果物（JAR）がローカル環境の Maven リポジトリ（~/.m2/repository）に登録されるため、同じマシン上の他のプロジェクトからプラグインを依存関係として利用できるようになります。

プラグイン利用手順

次に、プラグイン利用側のCAPプロジェクトを作成します。プロジェクトの初期化後、以下の設定を行います。

ステップ

srv/pom.xmlにプラグインを追加
プラグインを利用
アプリケーションを実行

1. srv/pom.xmlにプラグインを追加

srv/pom.xmlにdependencyを追加します。

		<dependency>
			<groupId>com.example.cap.plugins</groupId>
			<artifactId>emoji-plugin</artifactId>
			<version>1.0-SNAPSHOT</version>
		</dependency>

2. プラグインを利用

プラグインで定義した.cdsファイルを取り込むため、mvn clean packageを実行します。
その結果、targetフォルダに.cdsファイルが取り込まれます。

db/schema.cdsで絵文字用のアノテーションと、プラグインで定義したアスペクトおよび型を使用します。

namespace my.book;
using { com.example.cap.plugins.emoji as emoji } from 'com.example.cap.plugins/emoji-plugin';

entity Books: emoji.emoji {  // ← プラグイン由来のアスペクトを継承
  key ID    : UUID;
  @emoji                 // ← 絵文字付与の対象フィールド
  title     : String(200);
  author    : String(200);
  emoji     : emoji.EmojiString;  // ← プラグイン由来の型を使用
}

usingでCDSモデルを取り込んだときに、エディタでモジュールが見つからないというエラーが出ますが、ビルドは可能なので問題ありません。

3. アプリケーションを実行

mvn spring-boot:runで実行します。

ブラウザからアクセスすると、titleの後ろに絵文字が追加されます。

プラグインの共有方法

今回はローカルで作成したプラグインをローカルで利用する方法について紹介しました。プラグインを他の人と共有したい場合は、GitHub PackageやMaven Centralに登録する必要があります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up