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");