此内容没有您所选择的语言版本。
Chapter 6. Decision Manager controller Java client API for Decision Server templates and instances
Red Hat Decision Manager provides a Decision Manager controller Java client API that enables you to connect to the Decision Manager controller using REST or WebSocket protocol from your Java client application. You can use the Decision Manager controller Java client API as an alternative to the Decision Manager controller REST API to interact with your Decision Server templates (configurations), Decision Server instances (remote servers), and associated KIE containers (deployment units) in Red Hat Decision Manager without using the Business Central user interface. This API support enables you to maintain your Red Hat Decision Manager servers and resources more efficiently and optimize your integration and development with Red Hat Decision Manager.
With the Decision Manager controller Java client API, you can perform the following actions also supported by the Decision Manager controller REST API:
- Retrieve information about Decision Server templates, instances, and associated KIE containers
- Update, start, or stop KIE containers associated with Decision Server templates and instances
- Create, update, or delete Decision Server templates
- Create, update, or delete Decision Server instances
Decision Manager controller Java client API requests require the following components:
- Authentication
The Decision Manager controller Java client API requires HTTP Basic authentication for the following user roles, depending on controller type:
-
rest-all
user role if you installed Business Central and you want to use the built-in Decision Manager controller -
kie-server
user role if you installed the headless Decision Manager controller separately from Business Central
To view configured user roles for your Red Hat Decision Manager distribution, navigate to
~/$SERVER_HOME/standalone/configuration/application-roles.properties
and~/application-users.properties
.To add a user with the
kie-server
role or therest-all
role or both, navigate to~/$SERVER_HOME/bin
and run the following command with the role or roles specified:$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server,rest-all
To configure the
kie-server
orrest-all
user with Decision Manager controller access, navigate to~/$SERVER_HOME/standalone/configuration/standalone-full.xml
, uncomment theorg.kie.server
properties (if applicable), and add the controller user login credentials and controller location (if needed):<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"/>
For more information about user roles and Red Hat Decision Manager installation options, see Planning a Red Hat Decision Manager installation.
-
- Project dependencies
The Decision Manager controller Java client API requires the following dependencies on the relevant classpath of your Java project:
<!-- 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>
The
<version>
for Red Hat Decision Manager dependencies is the Maven artifact version for Red Hat Decision Manager currently used in your project (for example, 7.18.0.Final-redhat-00002).NoteInstead of specifying a Red Hat Decision Manager
<version>
for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your projectpom.xml
file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.Example BOM dependency:
<dependency> <groupId>com.redhat.ba</groupId> <artifactId>ba-platform-bom</artifactId> <version>7.3.0.GA-redhat-00002</version> <scope>import</scope> <type>pom</type> </dependency>
For more information about the Red Hat Business Automation BOM, see What is the mapping between RHDM product and maven library version?.
- Client request configuration
All Java client requests with the Decision Manager controller Java client API must define at least the following controller communication components:
-
Credentials of the
rest-all
user if you installed Business Central, or thekie-server
user if you installed the headless Decision Manager controller separately from Business Central Decision Manager controller location for REST or WebSocket protocol:
-
Example REST URL:
http://localhost:8080/decision-central/rest/controller
-
Example WebSocket URL:
ws://localhost:8080/headless-controller/websocket/controller
-
Example REST URL:
- Marshalling format for API requests and responses (JSON or JAXB)
-
A
KieServerControllerClient
object, which serves as the entry point for starting the server communication using the Java client API -
A
KieServerControllerClientFactory
defining REST or WebSocket protocol and user access -
The Decision Manager controller client service or services used, such as
listServerTemplates
,getServerTemplate
, orgetServerInstances
The following are examples of REST and WebSocket client configurations with these components:
Client configuration example with 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)); } }
Client configuration example with 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)); } }
-
Credentials of the
6.1. Sending requests with the Decision Manager controller Java client API
The Decision Manager controller Java client API enables you to connect to the Decision Manager controller using REST or WebSocket protocols from your Java client application. You can use the Decision Manager controller Java client API as an alternative to the Decision Manager controller REST API to interact with your Decision Server templates (configurations), Decision Server instances (remote servers), and associated KIE containers (deployment units) in Red Hat Decision Manager without using the Business Central user interface.
Prerequisites
- Decision Server is installed and running.
- The Decision Manager controller or headless Decision Manager controller is installed and running.
-
You have
rest-all
user role access to the Decision Manager controller if you installed Business Central, orkie-server
user role access to the headless Decision Manager controller installed separately from Business Central. - You have a Java project with Red Hat Decision Manager resources.
Procedure
In your client application, ensure that the following dependencies have been added to the relevant classpath of your Java project:
<!-- 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>
-
Download the Red Hat Decision Manager 7.3.0 Source Distribution from the Red Hat Customer Portal and navigate to
~/rhdm-7.3.0-sources/src/droolsjbpm-integration-$VERSION/kie-server-parent/kie-server-controller/kie-server-controller-client/src/main/java/org/kie/server/controller/client
to access the Decision Manager controller Java clients. -
In the
~/kie/server/controller/client
folder , identify the relevant Java client implementation for the request you want to send, such as theRestKieServerControllerClient
implementation to access client services for Decision Server templates and KIE containers in REST protocol. In your client application, create a
.java
class for the API request. The class must contain the necessary imports, the Decision Manager controller location and user credentials, aKieServerControllerClient
object, and the client method to execute, such ascreateServerTemplate
andcreateContainer
from theRestKieServerControllerClient
implementation. Adjust any configuration details according to your use case.Creating and interacting with a Decision Server template and KIE containers
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; } }
Run the configured
.java
class from your project directory to execute the request, and review the Decision Manager controller response.If you enabled debug logging, Decision Server responds with a detailed response according to your configured marshalling format, such as JSON. If you encounter request errors, review the returned error code messages and adjust your Java configurations accordingly.
6.2. Supported Decision Manager controller Java clients
The following are some of the Java client services available in the org.kie.server.controller.client
package of your Red Hat Decision Manager distribution. You can use these services to interact with related resources in the Decision Manager controller similarly to the Decision Manager controller REST API.
-
KieServerControllerClient
: Used as the entry point for communicating with the Decision Manager controller -
RestKieServerControllerClient
: Implementation used to interact with Decision Server templates and KIE containers in REST protocol (found in~/org/kie/server/controller/client/rest
) -
WebSocketKieServerControllerClient
: Implementation used to interact with Decision Server templates and KIE containers in WebSocket protocol (found in~/org/kie/server/controller/client/websocket
)
For the full list of available Decision Manager controller Java clients, download the Red Hat Decision Manager 7.3.0 Source Distribution from the Red Hat Customer Portal and navigate to ~/rhdm-7.3.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. Example requests with the Decision Manager controller Java client API
The following are examples of Decision Manager controller Java client API requests for basic interactions with the Decision Manager controller. For the full list of available Decision Manager controller Java clients, download the Red Hat Decision Manager 7.3.0 Source Distribution from the Red Hat Customer Portal and navigate to ~/rhdm-7.3.0-sources/src/droolsjbpm-integration-$VERSION/kie-server-parent/kie-server-controller/kie-server-controller-client/src/main/java/org/kie/server/controller/client
.
- Creating and interacting with Decision Server templates and KIE containers
You can use the
ServerTemplate
andContainerSpec
services in the REST or WebSocket Decision Manager controller clients to create, dispose, and update Decision Server templates and KIE containers, and to start and stop KIE containers, as illustrated in this example.Example request to create and interact with a Decision Server template and KIE containers
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; } }
- Listing Decision Server templates and specifying connection timeout (REST)
When you use REST protocol for Decision Manager controller Java client API requests, you can provide your own
javax.ws.rs.core.Configuration
specification to modify the underlying REST client API, such as connection timeout.Example REST request to return server templates and specify connection timeout
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)); } }
- Listing Decision Server templates and specifying event notifications (WebSocket)
When you use WebSocket protocol for Decision Manager controller Java client API requests, you can enable event notifications based on changes that happen in the particular Decision Manager controller to which the client API is connected. For example, you can receive notifications when Decision Server templates or instances are connected to or updated in the Decision Manager controller.
Example WebSocket request to return server templates and specify event notifications
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); } } }