Chapter 4. Drools Commands

4.1. API

XML marshalling/unmarshalling of the Drools Commands requires the use of special classes, which are going to be described in the following sections.

The following urls show sample script examples for jaxb, xstream and json marshalling using:

http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD
http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD
http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/xstream.mvt?r=HEAD

Options xjcOpts = new Options();

xjcOpts.setSchemaLanguage(Language.XMLSCHEMA);

JaxbConfiguration jaxbConfiguration = KnowledgeBuilderFactory.newJaxbConfiguration( xjcOpts, "xsd" );

kbuilder.add(ResourceFactory.newClassPathResource("person.xsd", getClass()), ResourceType.XSD, jaxbConfiguration);

KnowledgeBase kbase = kbuilder.newKnowledgeBase();


List<String> classesName = new ArrayList<String>();

classesName.add("org.drools.test.Person");

   

JAXBContext jaxbContext = KnowledgeBuilderHelper.newJAXBContext(classesName.toArray(new String[classesName.size()]), kbase);

4.1.3.2. Using a POJO model

In this case you need to use DroolsJaxbContextHelper to create the JAXBContext. This class has two parameters:

classNames: A List with the canonical name of the classes that you want to use in the marshalling/unmarshalling process.
properties: JAXB custom properties

List<String> classNames = new ArrayList<String>();

classNames.add("org.drools.test.Person");

JAXBContext jaxbContext = DroolsJaxbContextHelper.createDroolsJaxbContext(classNames, null);

Marshaller marshaller = jaxbContext.createMarshaller();

4.2. Commands supported

Currently, the following commands are supported:

BatchExecutionCommand
InsertObjectCommand
RetractCommand
ModifyCommand
GetObjectCommand
InsertElementsCommand
FireAllRulesCommand
StartProcessCommand
SignalEventCommand
CompleteWorkItemCommand
AbortWorkItemCommand
QueryCommand
SetGlobalCommand
GetGlobalCommand
GetObjectsCommand

Note

In the next snippets code we are going to use a POJO org.drools.test.Person that has two fields

name: String
age: Integer

Note

In the next examples, to marshall the commands we have used the nexts snippet codes:

XStream

String xml = BatchExecutionHelper.newXStreamMarshaller().toXML(command);

JSON

String xml = BatchExecutionHelper.newJSonMarshaller().toXML(command);

JAXB

Marshaller marshaller = jaxbContext.createMarshaller();

StringWriter xml = new StringWriter();

marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

marshaller.marshal(command, xml);

4.2.1. BatchExecutionCommand

Description: The command that contains a list of commands, which will be sent and executed.
Attributes
Table 4.1. BatchExecutionCommand attributes
Name Description required
lookup Sets the knowledge session id on which the commands are going to be executed true
commands List of commands to be executed false

Name	Description	required
lookup	Sets the knowledge session id on which the commands are going to be executed	true
commands	List of commands to be executed	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

InsertObjectCommand insertObjectCommand = new InsertObjectCommand(new Person("john", 25));

FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();

command.getCommands().add(insertObjectCommand);

command.getCommands().add(fireAllRulesCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <insert>

    <org.drools.test.Person>

      <name>john</name>

      <age>25</age>

    </org.drools.test.Person>

  </insert>

  <fire-all-rules/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":[{"insert":{"object":{"org.drools.test.Person":{"name":"john","age":25}}}},{"fire-all-rules":""}]}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <insert>

        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>25</age>

            <name>john</name>

        </object>

    </insert>

    <fire-all-rules max="-1"/>

</batch-execution>

4.2.2. InsertObjectCommand

Description: Insert an object in the knowledge session.

Attributes

Table 4.2. InsertObjectCommand attributes

Name	Description	required
object	The object to be inserted	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false
returnObject	Boolean to establish if the object must be returned in the execution results. Default value: true	false
entryPoint	Entrypoint for the insertion	false

Command creation

List<Command> cmds = ArrayList<Command>();


Command insertObjectCommand = CommandFactory.newInsert(new Person("john", 25), "john", false, null);

cmds.add( insertObjectCommand );


BatchExecutionCommand command = CommandFactory.createBatchExecution(cmds, "ksession1" );

XML output

XStream


<batch-execution lookup="ksession1">

  <insert out-identifier="john" entry-point="my stream" return-object="false">

    <org.drools.test.Person>

      <name>john</name>

      <age>25</age>

    </org.drools.test.Person>

  </insert>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"insert":{"entry-point":"my stream", "out-identifier":"john","return-object":false,"object":{"org.drools.test.Person":{"name":"john","age":25}}}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <insert out-identifier="john" entry-point="my stream" >

        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>25</age>

            <name>john</name>

        </object>

    </insert>

</batch-execution>

4.2.3. RetractCommand

Description: Retract an object from the knowledge session.
Attributes
Table 4.3. RetractCommand attributes
Name Description required
handle The FactHandle associated to the object to be retracted true

Name	Description	required
handle	The FactHandle associated to the object to be retracted	true

Command creation: we have two options, with the same output result:

Create the Fact Handle from a string

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

RetractCommand retractCommand = new RetractCommand();

retractCommand.setFactHandleFromString("123:234:345:456:567");

command.getCommands().add(retractCommand);

Set the Fact Handle that you received when the object was inserted

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

RetractCommand retractCommand = new RetractCommand(factHandle);

command.getCommands().add(retractCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <retract fact-handle="0:234:345:456:567"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"retract":{"fact-handle":"0:234:345:456:567"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <retract fact-handle="0:234:345:456:567"/>

</batch-execution>

4.2.4. ModifyCommand

Description: Allows you to modify a previously inserted object in the knowledge session.
Attributes
Table 4.4. ModifyCommand attributes
Name Description required
handle The FactHandle associated to the object to be retracted true
setters List of setters object's modifications true

Name	Description	required
handle	The FactHandle associated to the object to be retracted	true
setters	List of setters object's modifications	true

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

ModifyCommand modifyCommand = new ModifyCommand();

modifyCommand.setFactHandleFromString("123:234:345:456:567");

List<Setter> setters = new ArrayList<Setter>();

setters.add(new SetterImpl("age", "30"));

modifyCommand.setSetters(setters);

command.getCommands().add(modifyCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <modify fact-handle="0:234:345:456:567">

    <set accessor="age" value="30"/>

  </modify>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"modify":{"fact-handle":"0:234:345:456:567","setters":{"accessor":"age","value":30}}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <modify fact-handle="0:234:345:456:567">

        <set value="30" accessor="age"/>

    </modify>

</batch-execution>

4.2.5. GetObjectCommand

Description: Used to get an object from a knowledge session

Attributes

Table 4.5. GetObjectCommand attributes

Name	Description	required
factHandle	The FactHandle associated to the object to be retracted	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

GetObjectCommand getObjectCommand = new GetObjectCommand();

getObjectCommand.setFactHandleFromString("123:234:345:456:567");

getObjectCommand.setOutIdentifier("john");

command.getCommands().add(getObjectCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <get-object fact-handle="0:234:345:456:567" out-identifier="john"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"get-object":{"fact-handle":"0:234:345:456:567","out-identifier":"john"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <get-object out-identifier="john" fact-handle="0:234:345:456:567"/>

</batch-execution>

4.2.6. InsertElementsCommand

Description: Used to insert a list of objects.

Attributes

Table 4.6. InsertElementsCommand attributes

Name	Description	required
objects	The list of objects to be inserted on the knowledge session	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false
returnObject	Boolean to establish if the object must be returned in the execution results. Default value: true	false
entryPoint	Entrypoint for the insertion	false

Command creation

List<Command> cmds = ArrayList<Command>();


List<Object> objects = new ArrayList<Object>();

objects.add(new Person("john", 25));

objects.add(new Person("sarah", 35));


Command insertElementsCommand = CommandFactory.newInsertElements( objects );

cmds.add( insertElementsCommand );


BatchExecutionCommand command = CommandFactory.createBatchExecution(cmds, "ksession1" );

XML output

XStream


<batch-execution lookup="ksession1">

  <insert-elements>

    <org.drools.test.Person>

      <name>john</name>

      <age>25</age>

    </org.drools.test.Person>

    <org.drools.test.Person>

      <name>sarah</name>

      <age>35</age>

    </org.drools.test.Person>

  </insert-elements>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"insert-elements":{"objects":[{"containedObject":{"@class":"org.drools.test.Person","name":"john","age":25}},{"containedObject":{"@class":"org.drools.test.Person","name":"sarah","age":35}}]}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <insert-elements return-objects="true">

        <objects xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>25</age>

            <name>john</name>

        </objects>

        <objects xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>35</age>

            <name>sarah</name>

        </objects>

    </insert-elements>

</batch-execution>

4.2.7. FireAllRulesCommand

Description: Allow execution of the rules activations created.

Attributes

Table 4.7. FireAllRulesCommand attributes

Name	Description	required
max	The max number of rules activations to be executed. default is -1 and will not put any restriction on execution	false
outIdentifier	Add the number of rules activations fired on the execution results	false
agendaFilter	Allow the rules execution using an Agenda Filter	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();

fireAllRulesCommand.setMax(10);

fireAllRulesCommand.setOutIdentifier("firedActivations");

command.getCommands().add(fireAllRulesCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <fire-all-rules max="10" out-identifier="firedActivations"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"fire-all-rules":{"max":10,"out-identifier":"firedActivations"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

   <fire-all-rules out-identifier="firedActivations" max="10"/>

</batch-execution>

4.2.8. StartProcessCommand

Description: Allows you to start a process using the ID. Also you can pass parameters and initial data to be inserted.

Attributes

Table 4.8. StartProcessCommand attributes

Name	Description	required
processId	The ID of the process to be started	true
parameters	A Map<String, Object> to pass parameters in the process startup	false
data	A list of objects to be inserted in the knowledge session before the process startup	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

StartProcessCommand startProcessCommand = new StartProcessCommand();

startProcessCommand.setProcessId("org.drools.task.processOne");

command.getCommands().add(startProcessCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <start-process processId="org.drools.task.processOne"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"start-process":{"process-id":"org.drools.task.processOne"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <start-process processId="org.drools.task.processOne">

        <parameter/>

    </start-process>

</batch-execution>

4.2.9. SignalEventCommand

Description: Send a signal event.
Attributes
Table 4.9. SignalEventCommand attributes
Name Description required
event-type true
processInstanceId false
event false

Name	Description	required
event-type		true
processInstanceId		false
event		false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

SignalEventCommand signalEventCommand = new SignalEventCommand();

signalEventCommand.setProcessInstanceId(1001);

signalEventCommand.setEventType("start");

signalEventCommand.setEvent(new Person("john", 25));

command.getCommands().add(signalEventCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <signal-event process-instance-id="1001" event-type="start">

    <org.drools.pipeline.camel.Person>

      <name>john</name>

      <age>25</age>

    </org.drools.pipeline.camel.Person>

  </signal-event>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"signal-event":{"process-instance-id":1001,"@event-type":"start","event-type":"start","object":{"org.drools.pipeline.camel.Person":{"name":"john","age":25}}}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <signal-event event-type="start" process-instance-id="1001">

        <event xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>25</age>

            <name>john</name>

        </event>

    </signal-event>

</batch-execution>

4.2.10. CompleteWorkItemCommand

Description: Allows you to complete a WorkItem.
Attributes
Table 4.10. CompleteWorkItemCommand attributes
Name Description required
workItemId The ID of the WorkItem to be completed true
results false

Name	Description	required
workItemId	The ID of the WorkItem to be completed	true
results		false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

CompleteWorkItemCommand completeWorkItemCommand = new CompleteWorkItemCommand();

completeWorkItemCommand.setWorkItemId(1001);

command.getCommands().add(completeWorkItemCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <complete-work-item id="1001"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"complete-work-item":{"id":1001}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <complete-work-item id="1001"/>

</batch-execution>

4.2.11. AbortWorkItemCommand

Description: Allows you abort an WorkItem. The same as session.getWorkItemManager().abortWorkItem(workItemId)
Attributes
Table 4.11. AbortWorkItemCommand attributes
Name Description required
workItemId The ID of the WorkItem to be completed true

Name	Description	required
workItemId	The ID of the WorkItem to be completed	true

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

AbortWorkItemCommand abortWorkItemCommand = new AbortWorkItemCommand();

abortWorkItemCommand.setWorkItemId(1001);

command.getCommands().add(abortWorkItemCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <abort-work-item id="1001"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"abort-work-item":{"id":1001}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <abort-work-item id="1001"/>

</batch-execution>

4.2.12. QueryCommand

Description: Executes a query defined in knowledge base.

Attributes

Table 4.12. QueryCommand attributes

Name	Description	required
name	The query name	true
outIdentifier	The identifier of the query results. The query results are going to be added in the execution results with this identifier	false
arguments	A list of objects to be passed as a query parameter	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

QueryCommand queryCommand = new QueryCommand();

queryCommand.setName("persons");

queryCommand.setOutIdentifier("persons");

command.getCommands().add(queryCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <query out-identifier="persons" name="persons"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"query":{"out-identifier":"persons","name":"persons"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <query name="persons" out-identifier="persons"/>

</batch-execution>

4.2.13. SetGlobalCommand

Description: Allows you to set a global.

Attributes

Table 4.13. SetGlobalCommand attributes

Name	Description	required
identifier	The identifier of the global defined in the knowledge base	true
object	The object to be setted into the global	false
out	A boolean to add, or not, the set global result into the execution results	false
outIdentifier	The identifier of the global execution result	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

SetGlobalCommand setGlobalCommand = new SetGlobalCommand();

setGlobalCommand.setIdentifier("helper");

setGlobalCommand.setObject(new Person("kyle", 30));

setGlobalCommand.setOut(true);

setGlobalCommand.setOutIdentifier("output");

command.getCommands().add(setGlobalCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <set-global identifier="helper" out-identifier="output">

    <org.drools.test.Person>

      <name>kyle</name>

      <age>30</age>

    </org.drools.test.Person>

  </set-global>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"set-global":{"identifier":"helper","out-identifier":"output","object":{"org.drools.test.Person":{"name":"kyle","age":30}}}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <set-global out="true" out-identifier="output" identifier="helper">

        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

            <age>30</age>

            <name>kyle</name>

        </object>

    </set-global>

</batch-execution>

4.2.14. GetGlobalCommand

Description: Allows you to get a global previously defined.
Attributes
Table 4.14. GetGlobalCommand attributes
Name Description required
identifier The identifier of the global defined in the knowledge base true
outIdentifier The identifier to be used in the execution results false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

GetGlobalCommand getGlobalCommand = new GetGlobalCommand();

getGlobalCommand.setIdentifier("helper");

getGlobalCommand.setOutIdentifier("helperOutput");

command.getCommands().add(getGlobalCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <get-global identifier="helper" out-identifier="helperOutput"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"get-global":{"identifier":"helper","out-identifier":"helperOutput"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <get-global out-identifier="helperOutput" identifier="helper"/>

</batch-execution>

4.2.15. GetObjectsCommand

Description: Returns all the objects from the current session as a Collection.

Attributes

Table 4.15. GetObjectsCommand attributes

Name	Description	required
objectFilter	An ObjectFilter to filter the objects returned from the current session	false
outIdentifier	The identifier to be used in the execution results	false

Command creation

BatchExecutionCommand command = new BatchExecutionCommand();

command.setLookup("ksession1");

GetObjectsCommand getObjectsCommand = new GetObjectsCommand();

getObjectsCommand.setOutIdentifier("objects");

command.getCommands().add(getObjectsCommand);

XML output

XStream


<batch-execution lookup="ksession1">

  <get-objects out-identifier="objects"/>

</batch-execution>

JSON

{"batch-execution":{"lookup":"ksession1","commands":{"get-objects":{"out-identifier":"objects"}}}}

JAXB


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<batch-execution lookup="ksession1">

    <get-objects out-identifier="objects"/>

</batch-execution>