16.3. Extending the KIE Server client with a custom client API

Procedure

1. Create an empty Maven project and define the following packaging type and dependencies in the pom.xml file for the project:

   Example pom.xml file in the sample project

   <packaging>jar</packaging>
   
   <properties>
      <version.org.kie>7.48.0.Final-redhat-00004</version.org.kie>
    </properties>
   
    <dependencies>
      <dependency>
        <groupId>org.kie.server</groupId>
        <artifactId>kie-server-api</artifactId>
        <version>${version.org.kie}</version>
      </dependency>
      <dependency>
         <groupId>org.kie.server</groupId>
         <artifactId>kie-server-client</artifactId>
         <version>${version.org.kie}</version>
       </dependency>
      <dependency>
        <groupId>org.drools</groupId>
        <artifactId>drools-compiler</artifactId>
        <version>${version.org.kie}</version>
      </dependency>
    </dependencies>

2. Implement the relevant ServicesClient interface in a Java class in your project, as shown in the following example:

   Sample RulesMinaServicesClient interface

   public interface RulesMinaServicesClient extends RuleServicesClient {
   
   }

   A specific interface is required because you must register client implementations based on the interface, and you can have only one implementation for a given interface.

   For this example, the custom MINA-based data transport uses the Drools extension, so this example RulesMinaServicesClient interface extends the existing RuleServicesClient client API from the Drools extension.

3. Implement the RulesMinaServicesClient interface that the KIE Server can use to provide the additional client functionality for the new MINA transport, as shown in the following example:

   Sample implementation of the RulesMinaServicesClient interface

   public class RulesMinaServicesClientImpl implements RulesMinaServicesClient {
   
       private String host;
       private Integer port;
   
       private Marshaller marshaller;
   
       public RulesMinaServicesClientImpl(KieServicesConfiguration configuration, ClassLoader classloader) {
           String[] serverDetails = configuration.getServerUrl().split(":");
   
           this.host = serverDetails[0];
           this.port = Integer.parseInt(serverDetails[1]);
   
           this.marshaller = MarshallerFactory.getMarshaller(configuration.getExtraJaxbClasses(), MarshallingFormat.JSON, classloader);
       }
   
       public ServiceResponse<String> executeCommands(String id, String payload) {
   
           try {
               String response = sendReceive(id, payload);
               if (response.startsWith("{")) {
                   return new ServiceResponse<String>(ResponseType.SUCCESS, null, response);
               } else {
                   return new ServiceResponse<String>(ResponseType.FAILURE, response);
               }
           } catch (Exception e) {
               throw new KieServicesException("Unable to send request to KIE Server", e);
           }
       }
   
       public ServiceResponse<String> executeCommands(String id, Command<?> cmd) {
           try {
               String response = sendReceive(id, marshaller.marshall(cmd));
               if (response.startsWith("{")) {
                   return new ServiceResponse<String>(ResponseType.SUCCESS, null, response);
               } else {
                   return new ServiceResponse<String>(ResponseType.FAILURE, response);
               }
           } catch (Exception e) {
               throw new KieServicesException("Unable to send request to KIE Server", e);
           }
       }
   
       protected String sendReceive(String containerId, String content) throws Exception {
   
           // Flatten the content to be single line:
           content = content.replaceAll("\\n", "");
   
           Socket minaSocket = null;
           PrintWriter out = null;
           BufferedReader in = null;
   
           StringBuffer data = new StringBuffer();
           try {
               minaSocket = new Socket(host, port);
               out = new PrintWriter(minaSocket.getOutputStream(), true);
               in = new BufferedReader(new InputStreamReader(minaSocket.getInputStream()));
   
               // Prepare and send data:
               out.println(containerId + "|" + content);
               // Wait for the first line:
               data.append(in.readLine());
               // Continue as long as data is available:
               while (in.ready()) {
                   data.append(in.readLine());
               }
   
               return data.toString();
           } finally {
               out.close();
               in.close();
               minaSocket.close();
           }
       }
   }

   This example implementation specifies the following data and behavior:

   • Uses socket-based communication for simplicity
   • Relies on default configurations from the KIE Server client and uses ServerUrl for providing the host and port of the MINA server
   • Specifies JSON as the marshalling format
   • Requires received messages to be JSON objects that start with an open bracket {
   • Uses direct socket communication with a blocking API while waiting for the first line of the response and then reads all lines that are available
   • Does not use stream mode and therefore disconnects the KIE Server session after invoking a command

4. Implement the org.kie.server.client.helper.KieServicesClientBuilder interface in a Java class in your project, as shown in the following example:

   Sample implementation of the KieServicesClientBuilder interface

   public class MinaClientBuilderImpl implements KieServicesClientBuilder {  

   1

   
   
       public String getImplementedCapability() {  

   2

   
           return "BRM-Mina";
       }
   
       public Map<Class<?>, Object> build(KieServicesConfiguration configuration, ClassLoader classLoader) {  

   3

   
           Map<Class<?>, Object> services = new HashMap<Class<?>, Object>();
   
           services.put(RulesMinaServicesClient.class, new RulesMinaServicesClientImpl(configuration, classLoader));
   
           return services;
       }
   
   }

   1

   Enables you to provide additional client APIs to the generic KIE Server client infrastructure

   2

   Defines the KIE Server capability (extension) that the client uses

   3

   Provides a map of the client implementations, where the key is the interface and the value is the fully initialized implementation

5. To make the new client API discoverable for the KIE Server client, create a META-INF/services/org.kie.server.client.helper.KieServicesClientBuilder file in your Maven project and add the fully qualified class name of the KieServicesClientBuilder implementation class within the file. For this example, the file contains the single line org.kie.server.ext.mina.client.MinaClientBuilderImpl.
6. Build your project and copy the resulting JAR file into the ~/kie-server.war/WEB-INF/lib directory of your project. For example, on Red Hat JBoss EAP, the path to this directory is EAP_HOME/standalone/deployments/kie-server.war/WEB-INF/lib.

7. Start the KIE Server and deploy the built project to the running KIE Server. You can deploy the project using either the Business Central interface or the KIE Server REST API (a PUT request to http://SERVER:PORT/kie-server/services/rest/server/containers/{containerId}).

   After your project is deployed on a running KIE Server, you can start interacting with your new KIE Server client. You use your new client in the same way as the standard KIE Server client, by creating the client configuration and client instance, retrieving the service client by type, and invoking client methods.

   For this example, you can create a RulesMinaServiceClient client instance and invoke operations on KIE Server through the MINA transport:

   Sample implementation to create the RulesMinaServiceClient client

   protected RulesMinaServicesClient buildClient() {
       KieServicesConfiguration configuration = KieServicesFactory.newRestConfiguration("localhost:9123", null, null);
       List<String> capabilities = new ArrayList<String>();
       // Explicitly add capabilities (the MINA client does not respond to `get-server-info` requests):
       capabilities.add("BRM-Mina");
   
       configuration.setCapabilities(capabilities);
       configuration.setMarshallingFormat(MarshallingFormat.JSON);
   
       configuration.addJaxbClasses(extraClasses);
   
       KieServicesClient kieServicesClient =  KieServicesFactory.newKieServicesClient(configuration);
   
       RulesMinaServicesClient rulesClient = kieServicesClient.getServicesClient(RulesMinaServicesClient.class);
   
       return rulesClient;
   }

   Sample configuration to invoke operations on KIE Server through the MINA transport

   RulesMinaServicesClient rulesClient = buildClient();
   
   List<Command<?>> commands = new ArrayList<Command<?>>();
   BatchExecutionCommand executionCommand = commandsFactory.newBatchExecution(commands, "defaultKieSession");
   
   Person person = new Person();
   person.setName("mary");
   commands.add(commandsFactory.newInsert(person, "person"));
   commands.add(commandsFactory.newFireAllRules("fired"));
   
   ServiceResponse<String> response = rulesClient.executeCommands(containerId, executionCommand);
   Assert.assertNotNull(response);
   
   Assert.assertEquals(ResponseType.SUCCESS, response.getType());
   
   String data = response.getResult();
   
   Marshaller marshaller = MarshallerFactory.getMarshaller(extraClasses, MarshallingFormat.JSON, this.getClass().getClassLoader());
   
   ExecutionResultImpl results = marshaller.unmarshall(data, ExecutionResultImpl.class);
   Assert.assertNotNull(results);
   
   Object personResult = results.getValue("person");
   Assert.assertTrue(personResult instanceof Person);
   
   Assert.assertEquals("mary", ((Person) personResult).getName());
   Assert.assertEquals("JBoss Community", ((Person) personResult).getAddress());
   Assert.assertEquals(true, ((Person) personResult).isRegistered());