# com.bea.p13n.controls.rules
RulesExecutorControl Interface

public interface RulesExecutorControl
extends `Control`

This control defines the API for executing named rule sets and/or rules using the underlying BEA rules engine. The ruleset, rule, and filters are all set as attributes on the control and may be edited in the control property set GUI. It is assumed the user knows which rules exist in the rules repository. Use the RulesManagerControl to list, access, or manage these rules.

Rulesets are stored in the Portal data repository and are updated using data sync. They are loaded automatically when the server starts. To facilitate loading rulesets via data sync, simply place the ruleset file (generally ends with .rls) into the application's META-INF/data directory. For better organization, you may place the rulesets into a subdirectory, such as META-INF/data/rulesets. The ruleset uri is relative to the META-INF/data directory and looks something like this: '/rulesets/MyRule.rls'

There are two ways to configure this control, depending on whether you intend to invoke the control multiple times. For a single control invocation, configure the control properties, then use the evaluateRule() and evaluateRuleset() methods. If you intend to execute multiple rulesets within the same page, use the evaluate() and evaluateAll() methods, optionally overriding the control filter properties with the set*() methods.

Once the rules engine has finished executing, several objects will exist in working memory, including those that were originally input to the evaluate methods. Specifying the filter class names allows you to view only those classes in the results you're interested in. Those filtering parameters may be set on the control properties, or set programatically. If they are not set, the results are returned as-is, without filtering. For more information on filtering results, see the javadocs for com.bea.p13n.rules.manager.RuleResultClassFilter and the javadocs below on the 'setDoFilter' method.
Control properties:

- rulesetUri (OPTIONAL) URI of the ruleset to use. This is relative to the application's META-INF/data directory. Use the RulesMangerControl to list rulesets and rules.
- ruleName (OPTIONAL) Name of the rule to use. Must be contained within the ruleset URI specified for this control.
- filterResults (OPTIONAL) Whether to filter the results after the rule(s) have been evaluated. If false, all objects remaining in working memory will be returned.
- filterClassName (OPTIONAL) Filter rule results on this class. Enter class name (eg, java.lang.String). If left empty, results will not be filtered. Specify either this or the 'filterClassNames' but not both. The 'filterResults' property must be set to true to use this property.
- filterClassNames (OPTIONAL) Filter rule results on these classes. Enter as a comma-separated list of class names. Specify either this or the 'filterClassName' but not both. The 'filterResults' property must be set to true to use this property.
- filterRuleName (OPTIONAL) Filter rule results on the rule that produced the result. If this is left empty, then results from all rules will be returned. Otherwise, results from only this rule will be returned. This filter is applied in conjunction with the Class filters, if those are specified. The 'filterResults' property must be set to true to use this property.

Security requirements: none

All Superinterfaces
  `Control`, `Control`, `Serializable`

## Method Summary

`public `Iterator`` | `evaluate`(`String` rulesetUri, `String` ruleName, `Object`[] inputObjects) Applies a named rule in the ruleset uri to the set of objects provided by the caller and returns an iterator over the resultant set of objects.
`public `Iterator`` | `evaluateAll`(`String` rulesetUri, `Object`[] inputObjects) Applies all rules within the named rule set to the set of objects provided by the caller and returns an iterator over the resultant set of objects.
`public `Iterator`` | `evaluateRule`(`Object`[] inputObjects) Applies a named rule to the set of objects provided by the caller and returns an iterator over the resultant set of objects.
`public `Iterator`` | `evaluateRuleSet`(`Object`[] inputObjects) Applies all rules within the named rule set to the set of objects provided by the caller and returns an iterator over the resultant set of objects.
`public void` | `setDoFilter`(boolean doFilter) Toggle the filtering option, overriding the control property setting.
`public void` | `setFilterClass`(`String` className) Set the Java Class on which the rules results will be filtered.
`public void` | `setFilterClasses`(`String`[] classNames) Set the array of Java Class names on which the rules results will be filtered.
`public void` | `setFilterRuleName`(`String` ruleName) Set the rule name for which the filter will be applied.

## Method Detail

### evaluate(String, String, Object[]) Method

    public Iterator evaluate(String rulesetUri,
                             String ruleName,
                             Object[] inputObjects)
         throws IllegalArgumentException, ApplicationException, P13nControlException

Applies a named rule in the ruleset uri to the set of objects provided by the caller and returns an iterator over the resultant set of objects.

Use this method for multiple invocations of the same control, where you'd like to execute different rulesets/rules each time.

#### Parameters

rulesetUri
  Then URI of the ruleset containing the rule. This is relative to the application's META-INF/data directory and begins with '/'

ruleName
  The name of the rule within the ruleset to execute.

inputObjects
  The set of objects to which the rule is to be applied

#### Returns

The set of objects which resulted from the application of the rule and optionally filtered.

#### Exceptions

``IllegalArgumentException``
  if `ruleSetUri` or `ruleName` are `null` or zero-length, or if `inputObjects` is `null`.
``ApplicationException``
  if the rule set execution subsystem is unable to execute the rule.
``P13nControlException``
  if remote exceptions are encountered.

### evaluateAll(String, Object[]) Method

    public Iterator evaluateAll(String rulesetUri,
                                Object[] inputObjects)
         throws IllegalArgumentException, ApplicationException, P13nControlException

Applies all rules within the named rule set to the set of objects provided by the caller and returns an iterator over the resultant set of objects.

Use this method for multiple invocations of the same control, where you'd like to execute different rulesets each time.

#### Parameters

rulesetUri
  Then URI of the ruleset containing the rule. This is relative to the application's META-INF/data directory and begins with '/'

inputObjects
  The set of objects to which the rules are to be applied.

#### Returns

The set of objects which resulted from the application of the rules and optionally filtered

#### Exceptions

``IllegalArgumentException``
  if `ruleSetUri` is `null` or zero-length, or if `inputObjects` is `null`.
``ApplicationException``
  if the rule set execution subsystem is unable to execute the rule set.
``P13nControlException``
  if remote errors are encountered.

### evaluateRule(Object[]) Method

    public Iterator evaluateRule(Object[] inputObjects)
         throws IllegalArgumentException, ApplicationException, P13nControlException

Applies a named rule to the set of objects provided by the caller and returns an iterator over the resultant set of objects. Both the ruleset URI and rule name must be specified on the control properties.

Use this method for a single invocation of the control, where all properties have been configured on the control.

#### Parameters

inputObjects
  The set of objects to which the rule is to be applied

#### Returns

The set of objects which resulted from the application of the rule and optionally filtered.

#### Exceptions

``IllegalArgumentException``
  if `ruleSetUri` or `ruleName` are `null` or zero-length, or if `inputObjects` is `null`.
``ApplicationException``
  if the rule set execution subsystem is unable to execute the rule.
``P13nControlException``
  if remote exceptions are encountered.

### evaluateRuleSet(Object[]) Method

    public Iterator evaluateRuleSet(Object[] inputObjects)
         throws IllegalArgumentException, ApplicationException, P13nControlException

Applies all rules within the named rule set to the set of objects provided by the caller and returns an iterator over the resultant set of objects. The ruleset URI must be specified on the control properties.

Use this method for a single invocation of the control, where all properties have been configured on the control.

#### Parameters

inputObjects
  The set of objects to which the rules are to be applied.

#### Returns

The set of objects which resulted from the application of the rules and optionally filtered

#### Exceptions

``IllegalArgumentException``
  if `ruleSetUri` is `null` or zero-length, or if `inputObjects` is `null`.
``ApplicationException``
  if the rule set execution subsystem is unable to execute the rule set.
``P13nControlException``
  if remote errors are encountered.

### setDoFilter(boolean) Method

    public void setDoFilter(boolean doFilter)

Toggle the filtering option, overriding the control property setting. When filtering, you must specify either the filterClass or the filterClasses. Specifying the filter rule name is optional (see javadocs above).

When the rules engine has finished executing, its working memory will always include the input objects as well as any new objects created when the rule(s) fired. These new objects are of type 'com.bea.p13n.rules.Result' and you can use that API to get at the underlying object.

Use this method for multiple invocations of the same control using different filter rules. Otherwise, this property may be set on the control and applied to all invocations of the control

This method overrides the 'filterRuleName' property of this control and allows multiple invocations of the same control using different filters. It automatically sets the 'filterResults' parameter to true.

#### Parameters

doFilter
  Whether or not to filter the rule results.

### setFilterClass(String) Method

    public void setFilterClass(String className)
         throws ClassNotFoundException

Set the Java Class on which the rules results will be filtered. Once the rules engine has finished executing, several objects will exist in working memory, including those that were originally input to the evaluate methods. Specifying the filter class allows you to view only those classes in the results you're interested in.

This method overrides the 'filterClass' property of this control and allows multiple invocations of the same control using different filters. It automatically sets the 'filterResults' parameter to true.

Specify either this or the filterClasses, but not both.

Use this method for multiple invocations of the same control using different filter classes. Otherwise, this property may be set on the control and applied to all invocations of the control

#### Parameters

className
  The Java Class name on which the results will be filtered.

#### Exceptions

``ClassNotFoundException``
  if the name class cannot be instantiated

### setFilterClasses(String[]) Method

    public void setFilterClasses(String[] classNames)
         throws ClassNotFoundException

Set the array of Java Class names on which the rules results will be filtered. Once the rules engine has finished executing, several objects will exist in working memory, including those that were originally input to the evaluate methods. Specifying the filter class names allows you to view only those classes in the results you're interested in.

This method overrides the 'filterClasses' property of this control and allows multiple invocations of the same control using different filters. It automatically sets the 'filterResults' parameter to true.

Specify either this or the filterClass, but not both.

Use this method for multiple invocations of the same control using different filter classes. Otherwise, this property may be set on the control and applied to all invocations of the control.

#### Parameters

classNames
  The array of Java Class names on which the results will be filtered.

#### Exceptions

``ClassNotFoundException``
  if the name class cannot be instantiated

### setFilterRuleName(String) Method

    public void setFilterRuleName(String ruleName)

Set the rule name for which the filter will be applied. Once the rules engine has finished executing, several objects will exist in working memory, including those that were originally input to the evaluate methods. You may be interested in the results of only one particular rule. If no rule name is specified, the filter is applied to the results of all rule executions.

Use this method for multiple invocations of the same control using different filter rules. Otherwise, this property may be set on the control and applied to all invocations of the control

This method overrides the 'filterRuleName' property of this control and allows multiple invocations of the same control using different filters. It automatically sets the 'filterResults' parameter to true.

#### Parameters

ruleName
  The rule for which the filter will be applied.