com.ibm.websphere.brb
Class TriggerPoint

java.lang.Object
  |
  +--com.ibm.websphere.brb.TriggerPoint
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

public final class TriggerPoint
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

The primary interface for triggering rules. A "trigger point" is the place where an application bundles parameters and triggers 1 or more rules is known as a trigger point. This class is used to transfer control to the Trigger Point Framework in order to find and fire those rules in the application's trigger point. This assumes that the code that contains the trigger point is running in a WebSphere container, such as a client container, and EJB, or a servlet.

The TriggerPoint is used by creating a TriggerPoint object.

The TriggerPoint is used by first creating a TriggerPoint object. After the TriggerPoint is created, a trigger method is invoked to find and fire a number of rules. The three basic trigger methods are trigger(), which finds unclassified rules, triggerClassifier(), which finds classifier rules, and triggerSituational(), which first finds classifier rules, and then uses the classifier results to find classified rules. Returned from the trigger method is a set of results which are determined by the rules which were fired. Here is an example of a typical trigger point:

 import com.ibm.websphere.brb.TriggerPoint;

 TriggerPoint tp = new TriggerPoint();

 Object[] ruleInput = { theVehicle };
 Object result = tp.trigger(null,
                         ruleInput,
                         "com/acme/CheckVehicle");
 

After the TriggerPoint is created, it can be used as many times as desired; in this instance, we want to check a vehicle. To do this, we create an array which contains theVehicle, which is the vehicle to test. Then we simply call trigger() on the trigger point, passing the desired parameters. The first parameter is the "target" object. THe next parameter contains the firing parameters, which are passed to the RuleImplementor. The last parameter here is the full name of the rule, which includes the name of the folder in which the rule is stored.

The two simple trigger methods, trigger and triggerClassifier, perform their function in four steps:

  1. find the rules
  2. filter out those rules which are not desired
  3. fire the remaining rules
  4. combine the results and return to the caller
The method, triggerSituational does this sequence of steps twice, the first step to find the classification to feed into the second step.

The way that each of these steps is performed can be modified through various methods on this object. The implementation of each step is defined by a strategy object. There are different strategy objects which can be set, each of which are called at a certain time. First, there is a different set of strategy objects for each of the four steps outlined above. For each of these steps, there are actually (at least) two strategy objects which are used, one for triggering classifier rules, and one for triggering non-classifier rules. Finally, for the filtering step there are three pairs of strategies which are used, based on the number of rules which the finding strategy returns (zero, one, or multiple). While the sheer number of strategies which are available can be intimidating (twelve different strategy classes can be set), typically very few will need updating, and in reality most users will only modify the filtering strategies or the combining strategies. Here is a list of the strategies that are used by default.

	setFindingStrategy(FindingStrategy.DEFAULT_CLASSIFIER, CLASSIFIER_RULES);
	setFindingStrategy(FindingStrategy.DEFAULT_NONCLASSIFIER, NONCLASSIFIER_RULES);
	setNoRulesFilteringStrategy(FilteringStrategy.ACCEPT_ANY, ALL_RULES);
	setOneRuleFilteringStrategy(FilteringStrategy.ACCEPT_ANY, ALL_RULES);
	setMultipleRulesFilteringStrategy(FilteringStrategy.ACCEPT_ANY, ALL_RULES);
	setFiringStrategy(FiringStrategy.DEFAULT, ALL_RULES);
	setCombiningStrategy(CombiningStrategy.RETURN_ALL, ALL_RULES);
 

In addition to the strategies, users can also specify the date to use to find rules. By default, only rules that are in effect as of the current date will be found. However, if the asOfDate is set, rules will be found as if the current date were the specified date.

See Also:
Serialized Form

Field Summary
static int ALL_RULES
          Constant for applying a strategy to all rules (classifier and non-classifier).
static int CLASSIFIER_RULES
          Constant for applying a strategy to only classifier rules.
static int NONCLASSIFIER_RULES
          Constant for applying a strategy to only non-classifier rules.
protected  com.ibm.ws.brb.LocalRuleManager ruleMgr
          The rule manager which takes care of caching rules.
 
Constructor Summary
TriggerPoint()
          Create a new TriggerPoint object.
TriggerPoint(java.lang.String baseFolder)
          Create a new TriggerPoint object.
TriggerPoint(TriggerPoint triggerPointToCopy)
          Creates a new TriggerPoint object that is a copy of the specified TriggerPoint.
 
Method Summary
 boolean cacheEnabled()
          Determine whether or not this TriggerPoint uses caching.
 void disableCaching()
          Disable caching for this TriggerPoint.
 void enableCaching()
          Enable caching for this TriggerPoint.
 java.util.Date getAsOfDate()
          Returns the AsOfDate which has been specified for this TriggerPoint.
 java.lang.String getBaseFolder()
          Returns the base folder relative to which the rules are found.
 CombiningStrategy getCombiningStrategy(int ruleType)
          Returns the combining strategy which is used for the specified type of rule.
 FindingStrategy getFindingStrategy(int ruleType)
          Returns the finding strategy which is used for the specified type of rule.
 FiringStrategy getFiringStrategy(int ruleType)
          Returns the firing strategy which is used for the specified type of rule.
 com.ibm.ws.brb.LocalRuleManager getLocalRuleManager()
          FOR IBM INTERNAL USE ONLY.
 FilteringStrategy getMultipleRulesFilteringStrategy(int ruleType)
          Returns the filtering strategy which is used if multiple rules are found for the specified type of rule.
 FilteringStrategy getNoRulesFilteringStrategy(int ruleType)
          Returns the filtering strategy which is used if no rules are found for the specified type of rule.
 FilteringStrategy getOneRuleFilteringStrategy(int ruleType)
          Returns the filtering strategy which is used if exactly one rule is found for the specified type of rule.
 void refreshCache()
          Refresh the cache.
 void setAsOfDate(java.util.Date newAsOfDate)
          Sets the AsOfDate to use for this TriggerPoint.
 void setBaseFolder(java.lang.String newBaseFolder)
          Sets the base folder that rules are found relative to.
 void setCombiningStrategy(CombiningStrategy newCombiningStrategy, int ruleType)
          Sets the combining strategy to be used for the specified type of rule.
 void setFindingStrategy(FindingStrategy newFindingStrategy, int ruleType)
          Sets the finding strategy to be used for the specified type of rule.
 void setFiringStrategy(FiringStrategy newFiringStrategy, int ruleType)
          Sets the firing strategy to be used for the specified type of rule.
 void setMultipleRulesFilteringStrategy(FilteringStrategy newFilteringStrategy, int ruleType)
          Sets the filtering strategy to be used if multiple rules are found for the specified type of rule.
 void setNoRulesFilteringStrategy(FilteringStrategy newFilteringStrategy, int ruleType)
          Sets the filtering strategy to be used if no rules are found for the specified type of rule.
 void setOneRuleFilteringStrategy(FilteringStrategy newFilteringStrategy, int ruleType)
          Sets the filtering strategy to be used if exactly one rule is found for the specified type of rule.
 java.lang.Object trigger(java.lang.Object target, java.lang.Object[] firingParams, java.lang.Object ruleNameInfo)
          Finds and fires the non-classifier and non-classified rules which have the given name.
 java.lang.Object triggerClassifier(java.lang.Object target, java.lang.Object[] firingParams, java.lang.Object ruleNameInfo)
          Finds and fires the classifier rules which have the given name.
 java.lang.Object triggerSituational(java.lang.Object target, java.lang.Object[] firingParams, java.lang.Object[] classifierFiringParams, java.lang.Object ruleNameInfo, java.lang.Object classifierNameInfo)
          Finds and fires the classified rules which have the given name.
 void unsetAsOfDate()
          Specify to use the current date to find rules.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLASSIFIER_RULES

public static final int CLASSIFIER_RULES
Constant for applying a strategy to only classifier rules.

NONCLASSIFIER_RULES

public static final int NONCLASSIFIER_RULES
Constant for applying a strategy to only non-classifier rules.

ALL_RULES

public static final int ALL_RULES
Constant for applying a strategy to all rules (classifier and non-classifier).

ruleMgr

protected com.ibm.ws.brb.LocalRuleManager ruleMgr
The rule manager which takes care of caching rules. This is marked as transient so that it doesn't get serialized to the server.
Constructor Detail

TriggerPoint

public TriggerPoint()
             throws BusinessRuleBeansException
Create a new TriggerPoint object.
Throws:
BusinessRuleBeansException - The exception description.

TriggerPoint

public TriggerPoint(TriggerPoint triggerPointToCopy)
Creates a new TriggerPoint object that is a copy of the specified TriggerPoint.
Parameters:
triggerPointToCopy - The TriggerPoint object to be copied.

TriggerPoint

public TriggerPoint(java.lang.String baseFolder)
             throws BusinessRuleBeansException
Create a new TriggerPoint object.
Parameters:
baseFolder - java.lang.String
Throws:
BusinessRuleBeansException - The exception description.
Method Detail

cacheEnabled

public boolean cacheEnabled()
Determine whether or not this TriggerPoint uses caching.

Returns:
true if caching is used; otherwise false.

disableCaching

public void disableCaching()
Disable caching for this TriggerPoint. Does not affect whether or not caching is used by other TriggerPoints.

enableCaching

public void enableCaching()
Enable caching for this TriggerPoint. Does not affect whether or not caching is used by other TriggerPoints.

getAsOfDate

public java.util.Date getAsOfDate()
Returns the AsOfDate which has been specified for this TriggerPoint.

Returns:
the current AsOfDate, or null if there is none

getBaseFolder

public java.lang.String getBaseFolder()
Returns the base folder relative to which the rules are found. Rule names passed on the trigger methods are all relative to this folder. If this is null, the rule names passed must be absolute names.

Returns:
the base folder for rules to be found, or null if none specified

getCombiningStrategy

public CombiningStrategy getCombiningStrategy(int ruleType)
Returns the combining strategy which is used for the specified type of rule.

Parameters:
ruleType - the type of rule to return the combining strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the combining strategy for the given rule type

getFindingStrategy

public FindingStrategy getFindingStrategy(int ruleType)
Returns the finding strategy which is used for the specified type of rule.

Parameters:
ruleType - the type of rule to return the finding strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the finding strategy for the given rule type

getFiringStrategy

public FiringStrategy getFiringStrategy(int ruleType)
Returns the firing strategy which is used for the specified type of rule.

Parameters:
ruleType - the type of rule to return the firing strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the firing strategy for the given rule type

getLocalRuleManager

public com.ibm.ws.brb.LocalRuleManager getLocalRuleManager()
FOR IBM INTERNAL USE ONLY. Returns the internal LocalRuleManager object associated with this TriggerPoint. This is intended to be an internal BRBeans method.

Returns:
the associated LocalRuleManager

getMultipleRulesFilteringStrategy

public FilteringStrategy getMultipleRulesFilteringStrategy(int ruleType)
Returns the filtering strategy which is used if multiple rules are found for the specified type of rule.

Parameters:
ruleType - the type of rule to return the filtering strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the filtering strategy for the given rule type

getNoRulesFilteringStrategy

public FilteringStrategy getNoRulesFilteringStrategy(int ruleType)
Returns the filtering strategy which is used if no rules are found for the specified type of rule.

Parameters:
ruleType - the type of rule to return the filtering strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the filtering strategy for the given rule type

getOneRuleFilteringStrategy

public FilteringStrategy getOneRuleFilteringStrategy(int ruleType)
Returns the filtering strategy which is used if exactly one rule is found for the specified type of rule.

Parameters:
ruleType - the type of rule to return the filtering strategy for: CLASSIFIER_RULES or NONCLASSIFIER_RULES
Returns:
the filtering strategy for the given rule type

refreshCache

public void refreshCache()
Refresh the cache.

setAsOfDate

public void setAsOfDate(java.util.Date newAsOfDate)
Sets the AsOfDate to use for this TriggerPoint. After setting this value, all trigger methods will use this date instead of the current date for finding rules. To use the current date again, call this method passing null, or use unsetAsOfDate().

Parameters:
newAsOfDate - the date to use for finding rules

setBaseFolder

public void setBaseFolder(java.lang.String newBaseFolder)
Sets the base folder that rules are found relative to. Rule names passed on the trigger methods are all relative to this folder.

Parameters:
newBaseFolder - the base folder for rules to be found, or null if absolute names should be passed on the trigger methods

setCombiningStrategy

public void setCombiningStrategy(CombiningStrategy newCombiningStrategy,
                                 int ruleType)
Sets the combining strategy to be used for the specified type of rule. This object will be used to combine the results if multiple rules are fired.

Parameters:
newCombiningStrategy - the combining strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

setFindingStrategy

public void setFindingStrategy(FindingStrategy newFindingStrategy,
                               int ruleType)
Sets the finding strategy to be used for the specified type of rule. This object will be used to find the named rules passed to the TriggerPoint.

Parameters:
newFindingStrategy - the finding strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

setFiringStrategy

public void setFiringStrategy(FiringStrategy newFiringStrategy,
                              int ruleType)
Sets the firing strategy to be used for the specified type of rule. This object will be used to fire the rules which are found by the FindingStrategy.

Parameters:
newFiringStrategy - the firing strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

setMultipleRulesFilteringStrategy

public void setMultipleRulesFilteringStrategy(FilteringStrategy newFilteringStrategy,
                                              int ruleType)
Sets the filtering strategy to be used if multiple rules are found for the specified type of rule. This object will be used to filter out unexpected number of rules or do anything desired before the rules are passed to the FiringStrategy.

Parameters:
newFilteringStrategy - the filtering strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

setNoRulesFilteringStrategy

public void setNoRulesFilteringStrategy(FilteringStrategy newFilteringStrategy,
                                        int ruleType)
Sets the filtering strategy to be used if no rules are found for the specified type of rule. This object will be used to filter out unexpected number of rules or do anything desired before the rules are passed to the FiringStrategy.

Parameters:
newFilteringStrategy - the filtering strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

setOneRuleFilteringStrategy

public void setOneRuleFilteringStrategy(FilteringStrategy newFilteringStrategy,
                                        int ruleType)
Sets the filtering strategy to be used if exactly one rule is found for the specified type of rule. This object will be used to filter out unexpected number of rules or do anything desired before the rules are passed to the FiringStrategy.

Parameters:
newFilteringStrategy - the filtering strategy to use
ruleType - the type of rule this strategy will be used for: CLASSIFIER_RULES, NONCLASSIFIER_RULES, or ALL_RULES

trigger

public java.lang.Object trigger(java.lang.Object target,
                                java.lang.Object[] firingParams,
                                java.lang.Object ruleNameInfo)
                         throws BusinessRuleBeansException

Finds and fires the non-classifier and non-classified rules which have the given name.

The target and all the objects in the firingParams array should usually implement the java.io.Serializable interface, as rules can be fired remotely. If any of these are not serializable, the rules that can be found should be marked as IRule.FIRE_LOCAL to prevent the parameters from being serialized to the server.

Parameters:
target - The target parameter for the RuleImplementor.
firingParams - firingParams parameter for the RuleImplementor.
ruleNameInfo - Information used to derive the full names of the rules to find, relative to the baseFolder if one is set. The BRBeans-supplied finding strategies expect this parameter to be a single String specifying the rule name or else a String[] or Object[] containing Strings, each of which specifies one rule name to find. If a custom finding strategy is being used, this parameter can be whatever type of object that strategy expects.
Returns:
The result of firing the rules.
Throws:
BusinessRuleBeansException - If an exception occured finding and firing the rules.

triggerClassifier

public java.lang.Object triggerClassifier(java.lang.Object target,
                                          java.lang.Object[] firingParams,
                                          java.lang.Object ruleNameInfo)
                                   throws BusinessRuleBeansException

Finds and fires the classifier rules which have the given name.

The target and all the objects in the firingParams array should usually implement the java.io.Serializable interface, as rules can be fired remotely. If any of these are not serializable, the rules that can be found should be marked as IRule.FIRE_LOCAL to prevent the parameters from being serialized to the server.

Parameters:
target - The target parameter for the RuleImplementor.
firingParams - firingParams parameter for the RuleImplementor.
ruleNameInfo - Information used to derive the full names of the rules to find, relative to the baseFolder if one is set. The BRBeans-supplied finding strategies expect this parameter to be a single String specifying the rule name or else a String[] or Object[] containing Strings, each of which specifies one rule name to find. If a custom finding strategy is being used, this parameter can be whatever type of object that strategy expects.
Returns:
The result of firing the rules.
Throws:
BusinessRuleBeansException - If an exception occured finding and firing the rules.

triggerSituational

public java.lang.Object triggerSituational(java.lang.Object target,
                                           java.lang.Object[] firingParams,
                                           java.lang.Object[] classifierFiringParams,
                                           java.lang.Object ruleNameInfo,
                                           java.lang.Object classifierNameInfo)
                                    throws BusinessRuleBeansException

Finds and fires the classified rules which have the given name. This is accomplished in two phases: in the first phase, the classifier rules named by classifierNameInfo are found and fired. In the second phase, classified rules named by the ruleNameInfo parameter and classified by the results of the first phase are fired. The results of this second phase are returned.

The target and all the objects in the firingParams array should usually implement the java.io.Serializable interface, as rules can be fired remotely. If any of these are not serializable, the rules that can be found should be marked as IRule.FIRE_LOCAL to prevent the parameters from being serialized to the server.

Parameters:
target - The target parameter for the classified RuleImplementor.
firingParams - firingParams parameter for the RuleImplementor.
classifierFiringParams - firingParams parameter for the classifier RuleImplementor.
ruleNameInfo - Information used to derive the full names of the rules to find, relative to the baseFolder if one is set. The BRBeans-supplied finding strategies expect this parameter to be a single String specifying the rule name or else a String[] or Object[] containing Strings, each of which specifies one rule name to find. If a custom finding strategy is being used, this parameter can be whatever type of object that strategy expects.
classifierNameInfo - Information used to derive the full names of the classifier rules to find, relative to the baseFolder, if one is set. The BRBeans-supplied finding strategies expect this parameter to be a single String specifying the rule name or else a String[] or Object[] containing Strings, each of which specifies one rule name to find. If a custom finding strategy is being used, this parameter should be whatever type of object that strategy expects.
Returns:
the result of firing the rules
Throws:
BusinessRuleBeansException - if an exception occured finding and firing the rules

unsetAsOfDate

public void unsetAsOfDate()
Specify to use the current date to find rules.