第6章 Decision Server テンプレートおよびインスタンス用の Decision Manager コントローラー Java クライアント API

Red Hat Decision Manager は Decision Manager コントローラー Java クライアント API を提供し、これを使用することで Java クライアントアプリケーションから REST もしくは WebSocket プロトコルを使って Decision Manager コントローラー に接続できるようになります。Decision Manager コントローラー REST API の代わりに Decision Manager コントローラー Java クライアント API を使って、Business Central ユーザーインターフェースを使わずに Red Hat Decision Manager で Decision Server の インスタンス (リモートサーバー)、関連する KIE コンテナー (デプロイメントユニット) を操作することができます。この API のサポートにより、Red Hat Decision Manager サーバーのリソースをより効率的に維持でき、Red Hat Decision Manager の統合と開発を最適化できるようになります。

Decision Manager コントローラー Java クライアント API を使用すると、Decision Manager コントローラー REST API でもサポートされている以下のアクションが実行可能になります。

  • Decision Server テンプレート、インスタンス、および関連する KIE コンテナーについての情報の取得
  • Decision Server テンプレートおよびインスタンスに関連付けられ KIE コンテナーの更新、起動、停止
  • Decision Server テンプレートの作成、更新、削除
  • Decision Server インスタンスの作成、更新、削除

Decision Manager コントローラー Java クライアント API 要求には以下のコンポーネントが必要です。

認証

Decision Manager コントローラー Java クライアント API は、コントローラーのタイプによって、以下のユーザーロールに HTTP の Basic 認証を必要とします。

  • Business Central をインストールしていて、ビルトインの Decision Manager コントローラーを使用する場合は、rest-all のユーザーロール。
  • ヘッドレス Decision Manager コントローラーを Business Central とは別にインストールしている場合は、kie-server のユーザーロール。

お使いの Red Hat Decision Manager に設定されているユーザーロールを表示するには、~/$SERVER_HOME/standalone/configuration/application-roles.properties~/application-users.properties に移動します。

ユーザーに kie-server ロールか rest-all ロール、もしくはそれら両方を追加するには、~/$SERVER_HOME/bin に移動し、ロールを指定して以下のコマンドを実行します。

$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server,rest-all

Decision Manager コントローラーのアクセスで kie-server または rest-all ユーザーを設定するには、~/$SERVER_HOME/standalone/configuration/standalone-full.xml を開き、 (該当する場合) org.kie.server プロパティーをコメント解除して、コントローラーユーザーログイン認証情報とコントローラーの位置を (必要に応じて) 追加します。

<property name="org.kie.server.location" value="http://localhost:8080/kie-server/services/rest/server"/>
<property name="org.kie.server.controller" value="http://localhost:8080/decision-central/rest/controller"/>
<property name="org.kie.server.controller.user" value="baAdmin"/>
<property name="org.kie.server.controller.pwd" value="password@1"/>
<property name="org.kie.server.id" value="default-kieserver"/>

ユーザーロールと Red Hat Decision Manager のインストールオプションについての詳細は、『RED HAT DECISION MANAGER インストールのプラニング』を参照してください。

プロジェクトの依存関係

DecisionManager コントローラー Java クライアント API には、Java プロジェクト内の適切なクラスパスに、以下の依存関係を必要です。

<!-- For remote execution on controller -->
<dependency>
  <groupId>org.kie.server</groupId>
  <artifactId>kie-server-controller-client</artifactId>
  <version>${rhdm.version}</version>
</dependency>

<!-- For REST client -->
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-client</artifactId>
  <version>${resteasy.version}</version>
</dependency>

<!-- For WebSocket client -->
<dependency>
  <groupId>io.undertow</groupId>
  <artifactId>undertow-websockets-jsr</artifactId>
  <version>${undertow.version}</version>
</dependency>

<!-- For debug logging (optional) -->
<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>${logback.version}</version>
</dependency>

Red Hat Decision Manager 依存関係の <version> は、プロジェクトで現在使用する Red Hat Decision Manager の Maven アーティファクトバージョンです (例: 7.23.0.Final-redhat-00002)。

注記

個別の依存関係に対して Red Hat Decision Manager <version> を指定するのではなく、Red Hat Business Automation 部品表 (BOM) の依存関係をプロジェクトの pom.xml ファイルに追加することを検討してください。Red Hat Business Automation BOM は、Red Hat Decision Manager と Red Hat Process Automation Manager の両方に適用します。BOM ファイルを追加すると、指定の Maven リポジトリーからの一時的な依存関係の内、正しいバージョンが、このプロジェクトに追加されます。

BOM 依存関係の例:

<dependency>
  <groupId>com.redhat.ba</groupId>
  <artifactId>ba-platform-bom</artifactId>
  <version>7.4.0.GA-redhat-00002</version>
  <scope>import</scope>
  <type>pom</type>
</dependency>

Red Hat Business Automation BOM (Bill of Materials) についての詳細情報は、「What is the mapping between RHDM product and maven library version?」を参照してください。

クライアント要求の設定

Decision Manager コントローラー Java クライアント API による Java クライアント要求はすべて、少なくとも以下のコントローラー通信コンポーネントを定義する必要があります。

  • Business Central をインストールしている場合は rest-all ユーザーの認証情報、またはヘッドレス Decision Manager コントローラーを Business Central とは別にインストールしている場合は kie-server のユーザーの認証情報。
  • REST もしくは WebSocket プロトコル用 Decision Manager コントローラー の場所。

    • REST URL の例: http://localhost:8080/decision-central/rest/controller
    • WebSocket URL の例: ws://localhost:8080/headless-controller/websocket/controller
  • API 要求および応答のマーシャリングフォーマット (JSON または JAXB)
  • KieServerControllerClient オブジェクト。これは、Java クライアント API を使用してサーバー通信を開始するためのエントリーポイントの役割を果たします。
  • REST プロトコルまたは WebSocket プロトコルおよびユーザーアクセスを定義する KieServerControllerClientFactory
  • Decision Manager コントローラークライアントサービス。たとえば、listServerTemplatesgetServerTemplategetServerInstances など。

以下は、これらのコンポーネントを使用した REST および WebSocket クライアントの設定例です。

REST によるクライアント設定例

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.controller.api.model.spec.ServerTemplateList;
import org.kie.server.controller.client.KieServerControllerClient;
import org.kie.server.controller.client.KieServerControllerClientFactory;

public class ListServerTemplatesExample {

    private static final String URL = "http://localhost:8080/decision-central/rest/controller";
    private static final String USER = "baAdmin";
    private static final String PASSWORD = "password@1";

    private static final MarshallingFormat FORMAT = MarshallingFormat.JSON;

    public static void main(String[] args) {
        KieServerControllerClient client = KieServerControllerClientFactory.newRestClient(URL,
                                                                                          USER,
                                                                                          PASSWORD);

        final ServerTemplateList serverTemplateList = client.listServerTemplates();
        System.out.println(String.format("Found %s server template(s) at controller url: %s",
                                         serverTemplateList.getServerTemplates().length,
                                         URL));
    }
}

WebSocket によるクライアント設定例

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.controller.api.model.spec.ServerTemplateList;
import org.kie.server.controller.client.KieServerControllerClient;
import org.kie.server.controller.client.KieServerControllerClientFactory;

public class ListServerTemplatesExample {

    private static final String URL = "ws://localhost:8080/my-controller/websocket/controller";
    private static final String USER = "baAdmin";
    private static final String PASSWORD = "password@1";

    private static final MarshallingFormat FORMAT = MarshallingFormat.JSON;

    public static void main(String[] args) {
        KieServerControllerClient client = KieServerControllerClientFactory.newWebSocketClient(URL,
                                                                                               USER,
                                                                                               PASSWORD);

        final ServerTemplateList serverTemplateList = client.listServerTemplates();
        System.out.println(String.format("Found %s server template(s) at controller url: %s",
                                         serverTemplateList.getServerTemplates().length,
                                         URL));
    }
}

6.1. Decision Manager コントローラー Java クライアント API を使った要求送信

Decision Manager コントローラー Java クライアント API を使用すると、Java クライアントアプリケーションから REST もしくは WebSocket プロトコルを使って Decision Manager コントローラー に接続できるようになります。Decision Manager コントローラー REST API の代わりに Decision Manager コントローラー Java クライアント API を使って、Business Central ユーザーインターフェースを使わずに Red Hat Decision Manager で Decision Server の インスタンス (リモートサーバー)、関連する KIE コンテナー (デプロイメントユニット) を操作することができます。

前提条件

  • Decision Server をインストールし、実行している。
  • Decision Manager コントローラーもしくはヘッドレス Decision Manager コントローラーがインストールされ、実行している。
  • Business Central をインストールしている場合は Decision Manager コントローラーにアクセスする rest-all ユーザーロールがあること。もしくは、Business Central とは別にインストールされたヘッドレス Decision Manager コントローラーにアクセスする kie-server ユーザーロールがあること。
  • Red Hat Decision Manager リソースを使った Java プロジェクトがある。

手順

  1. クライアントアプリケーションで、Java プロジェクト内の適切なクラスパスに以下の依存関係が追加されていることを確認します。

    <!-- For remote execution on controller -->
    <dependency>
      <groupId>org.kie.server</groupId>
      <artifactId>kie-server-controller-client</artifactId>
      <version>${rhdm.version}</version>
    </dependency>
    
    <!-- For REST client -->
    <dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-client</artifactId>
      <version>${resteasy.version}</version>
    </dependency>
    
    <!-- For WebSocket client -->
    <dependency>
      <groupId>io.undertow</groupId>
      <artifactId>undertow-websockets-jsr</artifactId>
      <version>${undertow.version}</version>
    </dependency>
    
    <!-- For debug logging (optional) -->
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>${logback.version}</version>
    </dependency>
  2. Red Hat カスタマーポータル から Red Hat Decision Manager 7.4.0 Source Distribution をダウンロードし、~/rhdm-7.4.0-sources/src/droolsjbpm-integration-$VERSION/kie-server-parent/kie-server-controller/kie-server-controller-client/src/main/java/org/kie/server/controller/client に移動して Decision Manager コントローラー Java クライアントにアクセスします。
  3. ~/kie/server/controller/client ディレクトリーで、Decision Server テンプレートや KIE コンテナーが REST プロトコルでクライアントサービスにアクセスするために、RestKieServerControllerClient 実装などの送信する要求用の関連 Java クライアントを特定します。
  4. クライアントアプリケーションで、API 要求用の .java クラスを作成します。クラスには、Decision Manager コントローラーの場所とユーザー認証情報、KieServerControllerClient オブジェクト、RestKieServerControllerClient 実装からの createServerTemplatecreateContainer などの実行するクライアントメソッドを含める必要があります。ご自分のユースケースに合わせて、設定詳細を調整します。

    Decision Server テンプレートおよび KIE コンテナーの作成と対話

    import java.util.Arrays;
    import java.util.HashMap;
    import java.util.Map;
    
    import org.kie.server.api.marshalling.MarshallingFormat;
    import org.kie.server.api.model.KieContainerStatus;
    import org.kie.server.api.model.KieScannerStatus;
    import org.kie.server.api.model.ReleaseId;
    import org.kie.server.controller.api.model.spec.*;
    import org.kie.server.controller.client.KieServerControllerClient;
    import org.kie.server.controller.client.KieServerControllerClientFactory;
    
    public class RestTemplateContainerExample {
    
      private static final String URL = "http://localhost:8080/decision-central/rest/controller";
      private static final String USER = "baAdmin";
      private static final String PASSWORD = "password@1";
    
        private static KieServerControllerClient client;
    
        public static void main(String[] args) {
            KieServerControllerClient client = KieServerControllerClientFactory.newRestClient(URL,
                                                                                              USER,
                                                                                              PASSWORD,
                                                                                              MarshallingFormat.JSON);
            // Create server template and KIE container, start and stop KIE container, and delete server template
            ServerTemplate serverTemplate = createServerTemplate();
            ContainerSpec container = createContainer(serverTemplate);
            client.startContainer(container);
            client.stopContainer(container);
            client.deleteServerTemplate(serverTemplate.getId());
        }
    
        // Re-create and configure server template
        protected static ServerTemplate createServerTemplate() {
            ServerTemplate serverTemplate = new ServerTemplate();
            serverTemplate.setId("example-client-id");
            serverTemplate.setName("example-client-name");
            serverTemplate.setCapabilities(Arrays.asList(Capability.PROCESS.name(),
                                                         Capability.RULE.name(),
                                                         Capability.PLANNING.name()));
    
            client.saveServerTemplate(serverTemplate);
    
            return serverTemplate;
        }
    
        // Re-create and configure KIE containers
        protected static ContainerSpec createContainer(ServerTemplate serverTemplate){
            Map<Capability, ContainerConfig> containerConfigMap = new HashMap();
    
            ProcessConfig processConfig = new ProcessConfig("PER_PROCESS_INSTANCE", "kieBase", "kieSession", "MERGE_COLLECTION");
            containerConfigMap.put(Capability.PROCESS, processConfig);
    
            RuleConfig ruleConfig = new RuleConfig(500l, KieScannerStatus.SCANNING);
            containerConfigMap.put(Capability.RULE, ruleConfig);
    
            ReleaseId releaseId = new ReleaseId("org.kie.server.testing", "stateless-session-kjar", "1.0.0-SNAPSHOT");
    
            ContainerSpec containerSpec = new ContainerSpec("example-container-id", "example-client-name", serverTemplate, releaseId, KieContainerStatus.STOPPED, containerConfigMap);
            client.saveContainerSpec(serverTemplate.getId(), containerSpec);
    
            return containerSpec;
        }
    }

  5. 設定済み .java クラスをプロジェクトディレクトリーから実行して、要求を出し、Decision Manager コントローラーの応答を確認します。

    デバッグのロギングが有効になっている場合は、JSON などの設定済みマーシャリングフォーマットに従って、Decision Server が詳細を返します。エラーが発生した場合は、返されたエラーメッセージを確認して、それに応じて Java 設定を調整します。

6.2. サポート対象の Decision Manager コントローラー Java クライアント

以下は、Red Hat Decision Manager の org.kie.server.controller.client パッケージで利用可能な Java クライアントサービスの一部です。これらのサービスを使用して、Decision Manager コントローラー REST API と同様に Decision Manager コントローラー の関連リソースを操作できます。

  • KieServerControllerClient: Decision Manager コントローラーとの通信のエントリーポイントとして使用します。
  • RestKieServerControllerClient: REST プロトコルでの Decision Server テンプレートと KIE コンテナーとの対話に使用される実装 (~/org/kie/server/controller/client/rest に格納)。
  • WebSocketKieServerControllerClient: WebSocket プロトコルでの Decision Server テンプレートと KIE コンテナーとの対話に使用される実装 (~/org/kie/server/controller/client/websocket に格納)。

利用可能な Decision Manager コントローラー Java クライアントの完全一覧については、Red Hat カスタマーポータル から Red Hat Decision Manager 7.4.0 Source Distribution をダウンロードして、~/rhdm-7.4.0-sources/src/droolsjbpm-integration-$VERSION/kie-server-parent/kie-server-controller/kie-server-controller-client/src/main/java/org/kie/server/controller/client に移動してください。

6.3. Decision Manager コントローラー Java クライアント API を使った要求例

以下は、Decision Manager コントローラー との基本的な対話のための Decision Manager コントローラー Java クライアント API 要求の例です。利用可能な Decision Manager コントローラー Java クライアントの完全一覧については、Red Hat カスタマーポータル から Red Hat Decision Manager 7.4.0 Source Distribution をダウンロードして、~/rhdm-7.4.0-sources/src/droolsjbpm-integration-$VERSION/kie-server-parent/kie-server-controller/kie-server-controller-client/src/main/java/org/kie/server/controller/client に移動してください。

Decision Server テンプレートおよび KIE コンテナーの作成と対話

REST または WebSocket の Decision Manager コントローラークライアントで ServerTemplate および ContainerSpec サービスを使用すると、Decision Server テンプレートと KIE コンテナーの作成、破棄、更新が可能で、さらに KIE コンテナーの起動と停止もできます。以下に例を示します。

Decision Server テンプレートおよび KIE コンテナーによる作成と対話要求の例

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.api.model.KieContainerStatus;
import org.kie.server.api.model.KieScannerStatus;
import org.kie.server.api.model.ReleaseId;
import org.kie.server.controller.api.model.spec.*;
import org.kie.server.controller.client.KieServerControllerClient;
import org.kie.server.controller.client.KieServerControllerClientFactory;

public class RestTemplateContainerExample {

  private static final String URL = "http://localhost:8080/decision-central/rest/controller";
  private static final String USER = "baAdmin";
  private static final String PASSWORD = "password@1";

    private static KieServerControllerClient client;

    public static void main(String[] args) {
        KieServerControllerClient client = KieServerControllerClientFactory.newRestClient(URL,
                                                                                          USER,
                                                                                          PASSWORD,
                                                                                          MarshallingFormat.JSON);
        // Create server template and KIE container, start and stop KIE container, and delete server template
        ServerTemplate serverTemplate = createServerTemplate();
        ContainerSpec container = createContainer(serverTemplate);
        client.startContainer(container);
        client.stopContainer(container);
        client.deleteServerTemplate(serverTemplate.getId());
    }

    // Re-create and configure server template
    protected static ServerTemplate createServerTemplate() {
        ServerTemplate serverTemplate = new ServerTemplate();
        serverTemplate.setId("example-client-id");
        serverTemplate.setName("example-client-name");
        serverTemplate.setCapabilities(Arrays.asList(Capability.PROCESS.name(),
                                                     Capability.RULE.name(),
                                                     Capability.PLANNING.name()));

        client.saveServerTemplate(serverTemplate);

        return serverTemplate;
    }

    // Re-create and configure KIE containers
    protected static ContainerSpec createContainer(ServerTemplate serverTemplate){
        Map<Capability, ContainerConfig> containerConfigMap = new HashMap();

        ProcessConfig processConfig = new ProcessConfig("PER_PROCESS_INSTANCE", "kieBase", "kieSession", "MERGE_COLLECTION");
        containerConfigMap.put(Capability.PROCESS, processConfig);

        RuleConfig ruleConfig = new RuleConfig(500l, KieScannerStatus.SCANNING);
        containerConfigMap.put(Capability.RULE, ruleConfig);

        ReleaseId releaseId = new ReleaseId("org.kie.server.testing", "stateless-session-kjar", "1.0.0-SNAPSHOT");

        ContainerSpec containerSpec = new ContainerSpec("example-container-id", "example-client-name", serverTemplate, releaseId, KieContainerStatus.STOPPED, containerConfigMap);
        client.saveContainerSpec(serverTemplate.getId(), containerSpec);

        return containerSpec;
    }
}

Decision Server テンプレートの一覧および接続タイムアウトの指定 (REST)

Decision Manager コントローラー Java クライアント API 要求に REST プロトコルを使用すると、独自の javax.ws.rs.core.Configuration 仕様で接続タイムアウトなどの基本的な REST クライアント API を変更することができます。

サーバーテンプレートを返し、接続タイムアウトを指定する REST 要求の例

import java.util.concurrent.TimeUnit;
import javax.ws.rs.core.Configuration;
import org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder;

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.controller.api.model.spec.ServerTemplateList;
import org.kie.server.controller.client.KieServerControllerClient;
import org.kie.server.controller.client.KieServerControllerClientFactory;

public class RESTTimeoutExample {

  private static final String URL = "http://localhost:8080/decision-central/rest/controller";
  private static final String USER = "baAdmin";
  private static final String PASSWORD = "password@1";

  public static void main(String[] args) {

      // Specify connection timeout
      final Configuration configuration =
              new ResteasyClientBuilder()
                      .establishConnectionTimeout(10,
                                                    TimeUnit.SECONDS)
                      .socketTimeout(60,
                                       TimeUnit.SECONDS)
                        .getConfiguration();
        KieServerControllerClient client = KieServerControllerClientFactory.newRestClient(URL,
                                                                                          USER,
                                                                                          PASSWORD,
                                                                                          MarshallingFormat.JSON,
                                                                                          configuration);

        // Retrieve list of server templates
        final ServerTemplateList serverTemplateList = client.listServerTemplates();
        System.out.println(String.format("Found %s server template(s) at controller url: %s",
                                         serverTemplateList.getServerTemplates().length,
                                         URL));
    }
}

Decision Server テンプレートの一覧およびイベント通知の指定 (WebSocket)

Decision Manager コントローラー Java クライアント API 要求に WebSocket プロトコルを使用すると、クライアント API の接続先である特定の Decision Manager コントローラーで発生した変更に基づいてイベントが通知されるようにすることができます。たとえば、Decision Server テンプレートもしくはインスタンスが接続された、または Decision Manager コントローラー内で更新されると、通知を受け取ることができます。

サーバーテンプレートを返し、イベント通知を指定する WebSocket 要求の例

import org.kie.server.api.marshalling.MarshallingFormat;
import org.kie.server.controller.api.model.events.*;
import org.kie.server.controller.api.model.spec.ServerTemplateList;
import org.kie.server.controller.client.KieServerControllerClient;
import org.kie.server.controller.client.KieServerControllerClientFactory;
import org.kie.server.controller.client.event.EventHandler;

public class WebSocketEventsExample {

    private static final String URL = "ws://localhost:8080/my-controller/websocket/controller";
    private static final String USER = "baAdmin";
    private static final String PASSWORD = "password@1";

    public static void main(String[] args) {
        KieServerControllerClient client = KieServerControllerClientFactory.newWebSocketClient(URL,
                                                                                               USER,
                                                                                               PASSWORD,
                                                                                               MarshallingFormat.JSON,
                                                                                               new TestEventHandler());

        // Retrieve list of server templates
        final ServerTemplateList serverTemplateList = client.listServerTemplates();
        System.out.println(String.format("Found %s server template(s) at controller url: %s",
                                         serverTemplateList.getServerTemplates().length,
                                         URL));
        try {
            Thread.sleep(60 * 1000);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    // Set up event notifications
    static class TestEventHandler implements EventHandler {

        @Override
        public void onServerInstanceConnected(ServerInstanceConnected serverInstanceConnected) {
            System.out.println("serverInstanceConnected = " + serverInstanceConnected);
        }

        @Override
        public void onServerInstanceDeleted(ServerInstanceDeleted serverInstanceDeleted) {
            System.out.println("serverInstanceDeleted = " + serverInstanceDeleted);
        }

        @Override
        public void onServerInstanceDisconnected(ServerInstanceDisconnected serverInstanceDisconnected) {
            System.out.println("serverInstanceDisconnected = " + serverInstanceDisconnected);
        }

        @Override
        public void onServerTemplateDeleted(ServerTemplateDeleted serverTemplateDeleted) {
            System.out.println("serverTemplateDeleted = " + serverTemplateDeleted);
        }

        @Override
        public void onServerTemplateUpdated(ServerTemplateUpdated serverTemplateUpdated) {
            System.out.println("serverTemplateUpdated = " + serverTemplateUpdated);
        }

        @Override
        public void onServerInstanceUpdated(ServerInstanceUpdated serverInstanceUpdated) {
            System.out.println("serverInstanceUpdated = " + serverInstanceUpdated);
        }

        @Override
        public void onContainerSpecUpdated(ContainerSpecUpdated containerSpecUpdated) {
            System.out.println("onContainerSpecUpdated = " + containerSpecUpdated);
        }
    }
}