Drools Commands

Runtime Commands in Drools

Drools supports runtime commands that you can use in combination with KIE API operations, such as executing all rules or inserting or retracting objects in a KIE session. The full list of supported runtime commands is located in the org.drools.core.command.runtime package in your Drools instance.

Sample runtime Commands in Drools

The following are sample runtime commands that you can use in combination with KIE API operations:

  • BatchExecutionCommand

  • InsertObjectCommand

  • RetractCommand

  • ModifyCommand

  • GetObjectCommand

  • GetObjectsCommand

  • InsertElementsCommand

  • FireAllRulesCommand

  • QueryCommand

  • SetGlobalCommand

  • GetGlobalCommand

For the full list of supported runtime commands, see the org.drools.core.command.runtime package in your Drools instance.

Each command in this section includes a Java command example, making use of an object org.drools.compiler.test.Person with the fields name (String) and age (Integer).

BatchExecutionCommand

Contains multiple commands to be executed together.

Table 1. Command attributes
Name Description Requirement

commands

List of commands to be executed.

Required

lookup

Sets the KIE session ID on which the commands will be executed. For stateless KIE sessions, this attribute is required. For stateful KIE sessions, this attribute is optional and if not specified, the default KIE session is used.

Required for stateless KIE session, optional for stateful KIE session

KIE session IDs are in the kmodule.xml file of your Drools project.
Example Java command
InsertObjectCommand insertCommand = new InsertObjectCommand(new Person("john", 25));
FireAllRulesCommand fireCommand = new FireAllRulesCommand();

BatchExecutionCommand batch = new BatchExecutionCommandImpl(Arrays.asList(insertCommand, fireCommand), "ksession1");

InsertObjectCommand

Inserts an object into the KIE session.

Table 2. Command attributes
Name Description Requirement

object

The object to be inserted

Required

out-identifier

ID of the FactHandle created from the object insertion and added to the execution results

Optional

return-object

Boolean to determine whether the object must be returned in the execution results (default: true)

Optional

entry-point

Entry point for the insertion

Optional

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

ksession.execute(insertObjectCommand);

RetractCommand

Retracts an object from the KIE session.

Table 3. Command attributes
Name Description Requirement

fact-handle

The FactHandle associated with the object to be retracted

Required

Example Java command: Use FactHandleFromString
RetractCommand retractCommand = new RetractCommand();
retractCommand.setFactHandleFromString("123:234:345:456:567");
Example Java command: Use FactHandle from inserted object
RetractCommand retractCommand = new RetractCommand(factHandle);

ModifyCommand

Modifies a previously inserted object in the KIE session.

Table 4. Command attributes
Name Description Requirement

fact-handle

The FactHandle associated with the object to be modified

Required

setters

List of setters for object modifications

Required

Example Java command
ModifyCommand modifyCommand = new ModifyCommand(factHandle);

List<Setter> setters = new ArrayList<Setter>();
setters.add(new SetterImpl("age", "25"));

modifyCommand.setSetters(setters);

GetObjectCommand

Retrieves an object from a KIE session.

Table 5. Command attributes
Name Description Requirement

fact-handle

The FactHandle associated with the object to be retrieved

Required

out-identifier

ID of the FactHandle created from the object insertion and added to the execution results

Optional

Example Java command
GetObjectCommand getObjectCommand = new GetObjectCommand();
getObjectCommand.setFactHandleFromString("123:234:345:456:567");
getObjectCommand.setOutIdentifier("john");

GetObjectsCommand

Retrieves all objects from the KIE session as a collection.

Table 6. Command attributes
Name Description Requirement

object-filter

Filter for the objects returned from the KIE session

Optional

out-identifier

Identifier to be used in the execution results

Optional

Example Java command
GetObjectsCommand getObjectsCommand = new GetObjectsCommand();
getObjectsCommand.setOutIdentifier("objects");

InsertElementsCommand

Inserts a list of objects into the KIE session.

Table 7. Command attributes
Name Description Requirement

objects

The list of objects to be inserted into the KIE session

Required

out-identifier

ID of the FactHandle created from the object insertion and added to the execution results

Optional

return-object

Boolean to determine whether the object must be returned in the execution results. Default value: true.

Optional

entry-point

Entry point for the insertion

Optional

Example Java command
List<Object> objects = new ArrayList<Object>();
objects.add(new Person("john", 25));
objects.add(new Person("sarah", 35));

Command insertElementsCommand = CommandFactory.newInsertElements(objects);

FireAllRulesCommand

Executes all rules in the KIE session.

Table 8. Command attributes
Name Description Requirement

max

Maximum number of rules to be executed. The default is -1 and does not put any restriction on execution.

Optional

out-identifier

ID to be used for retrieving the number of fired rules in execution results.

Optional

agenda-filter

Agenda Filter to be used for rule execution.

Optional

Example Java command
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
fireAllRulesCommand.setMax(10);
fireAllRulesCommand.setOutIdentifier("firedActivations");

QueryCommand

Executes a query defined in the KIE base.

Table 9. Command attributes
Name Description Requirement

name

Query name.

Required

out-identifier

ID of the query results. The query results are added in the execution results with this identifier.

Optional

arguments

List of objects to be passed as a query parameter.

Optional

Example Java command
QueryCommand queryCommand = new QueryCommand();
queryCommand.setName("persons");
queryCommand.setOutIdentifier("persons");

SetGlobalCommand

Sets an object to a global state.

Table 10. Command attributes
Name Description Requirement

identifier

ID of the global variable defined in the KIE base

Required

object

Object to be set into the global variable

Optional

out

Boolean to exclude the global variable you set from the execution results

Optional

out-identifier

ID of the global execution result

Optional

Example Java command
SetGlobalCommand setGlobalCommand = new SetGlobalCommand();
setGlobalCommand.setIdentifier("helper");
setGlobalCommand.setObject(new Person("kyle", 30));
setGlobalCommand.setOut(true);
setGlobalCommand.setOutIdentifier("output");

GetGlobalCommand

Retrieves a previously defined global object.

Table 11. Command attributes
Name Description Requirement

identifier

ID of the global variable defined in the KIE base

Required

out-identifier

ID to be used in the execution results

Optional

Example Java command
GetGlobalCommand getGlobalCommand = new GetGlobalCommand();
getGlobalCommand.setIdentifier("helper");
getGlobalCommand.setOutIdentifier("helperOutput");