First and most likely the most frequently required extension to KIE Server is to extend REST api of already available extension - Drools or jBPM. There are few simple steps that needs to be done to provide extra endpoints in KIE Server.
Before you start create empty maven project (packaging jar) with following dependencies:
this method is then invoked by KIE Server when booting up and should return all resources that REST container should deploy.
This method implementation should take into consideration following:
Our use case
We are going to extend Drools extension with additional endpoint that will do very simple thing - expose single endpoint that will accept list of facts to be inserted and automatically call fire all rules and retrieve all objects from ksession.
Endpoint will be bound to following path:
server/containers/instances/{id}/ksession/{ksessionId}
where:
- id is container identifier
- ksessionId is name of the ksession within container to be used
Before you start create empty maven project (packaging jar) with following dependencies:
<properties>
<version.org.kie>6.4.0-SNAPSHOT</version.org.kie>
</properties>
<dependencies>
<dependency>
<groupId>org.kie</groupId>
<artifactId>kie-api</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.kie</groupId>
<artifactId>kie-internal</artifactId>
<version>${version.org.kie}</version>
</dependency>
<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-services-common</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.kie.server</groupId>
<artifactId>kie-server-services-drools</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.kie.server</groupId>
<artifactId>kie-server-rest-common</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.drools</groupId>
<artifactId>drools-core</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.drools</groupId>
<artifactId>drools-compiler</artifactId>
<version>${version.org.kie}</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.7.2</version>
</dependency>
</dependencies>
Implement KieServerApplicationComponentsService
First step is to implement org.kie.server.services.api.KieServerApplicationComponentsService that is responsible for delivering REST endpoints (aka resources) to the KIE Server infrastructure that will be then deployed on application start. This interface is very simple and has only one method:
Collection<Object> getAppComponents(String extension,
SupportedTransports type, Object... services)
this method is then invoked by KIE Server when booting up and should return all resources that REST container should deploy.
This method implementation should take into consideration following:
- it is called by all extensions and thus it provides extension name so custom implementations can decide if this extension is for it or not
- supported type - either REST or JMS - in our case it will be REST only
- services - dedicated services to given extensions that can be then used as part of custom extension - usually these are engine services
Here is a sample implementation that uses Drools extension as base (and by that its services)
public class CusomtDroolsKieServerApplicationComponentsService implements KieServerApplicationComponentsService {
private static final String OWNER_EXTENSION = "Drools";
public Collection<Object> getAppComponents(String extension, SupportedTransports type, Object... services) {
// skip calls from other than owning extension
if ( !OWNER_EXTENSION.equals(extension) ) {
return Collections.emptyList();
}
RulesExecutionService rulesExecutionService = null;
KieServerRegistry context = null;
for( Object object : services ) {
if( RulesExecutionService.class.isAssignableFrom(object.getClass()) ) {
rulesExecutionService = (RulesExecutionService) object;
continue;
} else if( KieServerRegistry.class.isAssignableFrom(object.getClass()) ) {
context = (KieServerRegistry) object;
continue;
}
}
List<Object> components = new ArrayList<Object>(1);
if( SupportedTransports.REST.equals(type) ) {
components.add(new CustomResource(rulesExecutionService, context));
}
return components;
}
}
So what can be seen here is that it only reacts to Drools extension services and others are ignored. Next it will select RulesExecutionService and KieServerRegistry from available services. Last will create new CustomResource (implemented in next step) and returns it as part of the components list.
Implement REST resource
Next step is to implement custom REST resource that will be used by KIE Server to provide additional functionality. Here we do a simple, single method resource that:
- uses POST http method
- expects following data to be given:
- container id as path argument
- ksession id as path argument
- list of facts as message payload
- supports all KIE Server data formats:
- XML - JAXB
- JSON
- XML - Xstream
It will then unmarshal the payload into actual List<?> and create for each item in the list new InsertCommand. These inserts will be then followed by FireAllRules and GetObject commands. All will be then added as commands of BatchExecutionCommand and used to call rule engine. As simple as that. It is already available on KIE Server out of the box but requires complete setup of BatchExecutionCommand to be done on client side. Not that it's not possible but this extension is tailored one for simple pattern :
insert -> evaluate -> return
Here is how the simple implementation could look like:
@Path("server/containers/instances/{id}/ksession")
public class CustomResource {
private static final Logger logger = LoggerFactory.getLogger(CustomResource.class);
private KieCommands commandsFactory = KieServices.Factory.get().getCommands();
private RulesExecutionService rulesExecutionService;
private KieServerRegistry registry;
public CustomResource() {
}
public CustomResource(RulesExecutionService rulesExecutionService, KieServerRegistry registry) {
this.rulesExecutionService = rulesExecutionService;
this.registry = registry;
}
@POST
@Path("/{ksessionId}")
@Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public Response insertFireReturn(@Context HttpHeaders headers,
@PathParam("id") String id,
@PathParam("ksessionId") String ksessionId,
String cmdPayload) {
Variant v = getVariant(headers);
String contentType = getContentType(headers);
MarshallingFormat format = MarshallingFormat.fromType(contentType);
if (format == null) {
format = MarshallingFormat.valueOf(contentType);
}
try {
KieContainerInstance kci = registry.getContainer(id);
Marshaller marshaller = kci.getMarshaller(format);
List<?> listOfFacts = marshaller.unmarshall(cmdPayload, List.class);
List<Command<?>> commands = new ArrayList<Command<?>>();
BatchExecutionCommand executionCommand = commandsFactory.newBatchExecution(commands, ksessionId);
for (Object fact : listOfFacts) {
commands.add(commandsFactory.newInsert(fact, fact.toString()));
}
commands.add(commandsFactory.newFireAllRules());
commands.add(commandsFactory.newGetObjects());
ExecutionResults results = rulesExecutionService.call(kci, executionCommand);
String result = marshaller.marshall(results);
logger.debug("Returning OK response with content '{}'", result);
return createResponse(result, v, Response.Status.OK);
} catch (Exception e) {
// in case marshalling failed return the call container response to keep backward compatibility
String response = "Execution failed with error : " + e.getMessage();
logger.debug("Returning Failure response with content '{}'", response);
return createResponse(response, v, Response.Status.INTERNAL_SERVER_ERROR);
}
}
}
Make it discoverable
Once we have all that needs to be implemented, it's time to make it discoverable so KIE Server can find and register this extension on runtime. Since KIE Server is based on Java SE ServiceLoader mechanism we need to add one file into our extension jar file:
META-INF/services/org.kie.server.services.api.KieServerApplicationComponentsService
And the content of this file is a single line that represents fully qualified class name of our custom implementation of KieServerApplicationComponentsService.
Last step is to build this project (which will result in jar file) and copy the result into:
kie-server.war/WEB-INF/lib
And that's all that is needed. Start KIE Server and then you can start interacting with your new REST endpoint that relies on Drools extension.
Usage example
Clone this repository and build the kie-server-demo project. Once you build it you will be able to deploy it to KIE Server (either directly using KIE Server management REST api) or via KIE workbench controller.
Once deployed you can use following to invoke new endpoint:
URL:
http://localhost:8080/kie-server/services/rest/server/containers/instances/demo/ksession/defaultKieSession
HTTP Method: POST
Headers:
Content-Type: application/json
Accept: application/json
Message payload:
[
{
"org.jbpm.test.Person":{
"name":"john",
"age":25}
},
{
"org.jbpm.test.Person":{
"name":"mary",
"age":22}
}
]
A simple list with two items representing people, execute it and you should see following in server log:
13:37:20,347 INFO [stdout] (default task-24) Hello mary
13:37:20,348 INFO [stdout] (default task-24) Hello john
And the response should contain objects retrieved after rule evaluation where each Person object has:
- address set to 'JBoss Community'
- registered flag set to true
With this sample use case we illustrated how easy it is to extend REST api of KIE Server. Complete code for this extension can be found here.
