com.pega.pegarules.pub.database
Interface RulesetContext

public interface RulesetContext

This class provides tools necessary when editing a rule. This includes the ability to open other rules according to the RuleSets visible to a rule, and the ability to record certain types of objects that a rule refers to

Currently, the following references are tracked:

References to other rules

These are added automatically whenever the open(com.pega.pegarules.pub.util.StringMap) or openForAllCircumstanceVals(com.pega.pegarules.pub.util.StringMap, com.pega.pegarules.pub.database.RuleResolutionInformation) method is called.

References to named clipboard pages

These are added when validatePagesAndClasses(com.pega.pegarules.pub.clipboard.ClipboardProperty, com.pega.pegarules.pub.clipboard.ClipboardProperty) is called, or when addNamedPageReference(java.lang.String) is called.

References to API methods

These are added when the addAPIMethodReference(java.lang.String, java.lang.String, java.lang.String[]) method is called.

References are tracked only when reference tracking is enabled. Reference tracking is enabled by calling startTrackingReferences(), and disabled by calling stopTrackingReferences().

Instances of this class can also find a version of a rule that is related to a given version. Two rules are related if they have the same rule name.

Version:

$Revision: 3533 $ $Date: 2010-03-02 17:45:02 -0500 (Tue, 02 Mar 2010) $

Author:

Jamie Gentry

Field Summary

static java.lang.String	COPYRIGHT
static java.lang.String	VERSION

Method Summary

void	addAPIMethodReference(java.lang.String aClassName, java.lang.String aMethodName, java.lang.String[] aParameterTypes) Records a call to an API method, if reference tracking is enabled.
void	addNamedPageReference(java.lang.String aPageName) Records a reference to a named page, if reference tracking is enabled.
java.lang.String	findHandle(StringMap aKeys) Finds the handle of the instance that would be opened from the RuleSet context, given a set of keys.
boolean	findRuleInClassSet(StringMap aKeys, java.util.Set aClassToTry) Looks for the specified rule in any of the classes given in the aClassToTry list.
ClipboardPage	getClosestVersion(ClipboardPage aRulePage) Returns the version of a rule that is most closely related to a given version.
Dictionary	getDictionary() Returns a Dictionary that uses the this RuleSet context to open rules, and that tracks references in this RuleSet context's rule page.
java.util.List	getListOfRulesets() Returns a list of Strings representing the unlocalized rulesets in this RulesetContext.
boolean	isBasisOf(ClipboardPage aVersion1, ClipboardPage aVersion2) Is one version of a rule the basis of another version.
boolean	isClassVisible(java.lang.String aClassName) Indicates whether a particular class is visible to the rule being edited (according to the list of rulesets).
ClipboardPage	open(StringMap aInstancePage) Opens an instance given its key properties.
ClipboardPage	openDefault(StringMap aKeys) Opens the default version of the Rule with the given keys.
java.util.Map	openForAllCircumstanceVals(StringMap aInstancePage, RuleResolutionInformation aRuleInfo) Deprecated.
void	openRuleUtilityFunction(StringMap aKeyPage) Opens the undecorated and decorated(if any) Rule-Utility-Function instances and add it to Rule Referencing.
void	startTrackingReferences() Causes this RuleSet context to track references.
void	stopTrackingReferences() Causes this RuleSet context to stop tracking references.
void	validatePagesAndClasses(ClipboardProperty aPagesAndClassesProperty, ClipboardProperty aParameterProperty) Validates the pages and classes table for the rule.

Field Detail

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

VERSION

static final java.lang.String VERSION

See Also:

Constant Field Values

Method Detail

startTrackingReferences

void startTrackingReferences()

Causes this RuleSet context to track references. If references are already being tracked, does nothing.

stopTrackingReferences

void stopTrackingReferences()

Causes this RuleSet context to stop tracking references. If references are not being tracked, does nothing.

openDefault

ClipboardPage openDefault(StringMap aKeys)
                          throws BadClassDefinitionException,
                                 ConfigurationException,
                                 MultipleCircumstancePropertiesException,
                                 MultipleRuleVersionException,
                                 BadInputException,
                                 BadInstanceDataException,
                                 DatabaseException

Opens the default version of the Rule with the given keys.

This method may be used to open data instances also--if the data instance being opened contains a pyRuleSet property with a non-blank value, then the open succeeds only if the value of pyRuleSet is the name of at least one of the RuleSets in the list--otherwise, it returns null.

The rule being opened is added to the list or referenced rules.

Parameters:

aKeys - the instance's key parts

Returns:

the requested instance, or null if it does not exist

Throws:

BadClassDefinitionException - if the instance keys specify an invalid instance class (pxObjClass) or if the instance keys specify an instance that belongs to class that uses inheritance, and the keys specify a bad object class (pyClassName). The processing status is set to error and the message is Database-BadClassDef-BadObjectClass.

ConfigurationException - if the database table configuration is bad

MultipleCircumstancePropertiesException - if, during Rule Resolution, Rules with conflicting Circumstance Properties or with conflicting Circumstance Date Properties were encountered

MultipleRuleVersionException - if the requested instance belongs to a class that uses Rule Resolution, and there is more than one version of the rule that may be considered the best version

NoRuleVersionWithoutCircumstanceException - if Rule Resolution was used to find the instance, and a default version of the Rule was expected but not found

BadInputException - if there is a problem with the key page. The processing status is set to the error Database-BadInput-ClassCannotHaveInstances. Examples of problems are:

• The page belongs to a class with no defined key properties.
• The page belongs to an abstract class.
• The page belongs to a class that cannot have instances in the database, such as a class that descends from Code-.

BadInstanceDataException - if the database instance is corrupt

DatabaseException - if there is a problem with the database

open

ClipboardPage open(StringMap aInstancePage)
                   throws DatabaseException

Opens an instance given its key properties. If the instance is a rule, then it is opened based on the RuleSets visible to the rule being edited.

This method may be used to open data instances also--if the data instance being opened contains a pyRuleSet property with a non-blank value, then the open succeeds only if the value of pyRuleSet is the name of at least one of the RuleSets in the list--otherwise, it returns null.

If the instance that is opened is a rule, then it is added to the list of rules referenced by the rule being edited.

Parameters:

aInstancePage - a page containing the instance's key properties (including pxObjClass)

Returns:

the requested instance, or null if it does not exist

Throws:

DatabaseException - if there is a problem opening the instance

openRuleUtilityFunction

void openRuleUtilityFunction(StringMap aKeyPage)
                             throws DatabaseException

Opens the undecorated and decorated(if any) Rule-Utility-Function instances and add it to Rule Referencing.

Parameters:

aKeyPage - contains instance's key part

Throws:

DatabaseException - if there is a problem opening the instance

openForAllCircumstanceVals

java.util.Map openForAllCircumstanceVals(StringMap aInstancePage,
                                         RuleResolutionInformation aRuleInfo)
                                         throws DatabaseException

Deprecated.

Returns the rules with he requested keys, performing Rule Resolution based on the RuleSets visible to the rule being edited. All the rule versions that could be chosen for all possible circumstances are returned. Both blocked and unblocked rule versions are returned.

If the instance that is opened is a rule, then it is added to the list of rules referenced by the rule being edited.

Parameters:

aInstancePage - a page containing the instance's key parts

aRuleInfo - filled in with information about the returned rule

Returns:

a map of potential circumstance values to the results of performing rule resolution for each circumstance value. These results are expressed as instances of CircumstanceResult. If there is a default result (that is, a version that is to be used if none of the circumstance-qualified versions match), then it is stored in the map with a null key. (This map should not be updated--it might be read-only.)

Throws:

BadClassDefinitionException - if the instance keys specify an invalid instance class (pxObjClass) or if the instance keys specify an instance that belongs to class that uses inheritance, and the keys specify a bad object class (pyClassName). The processing status is set to error and the message is Database-BadClassDef-BadObjectClass.

ConfigurationException - if the database table configuration is bad

MultipleCircumstancePropertiesException - if more than one circumstance property is found

BadInputException - if there is a problem with the key page

BadInstanceDataException - if the database instance is corrupt

DatabaseException - if there is a problem with the database

getClosestVersion

ClipboardPage getClosestVersion(ClipboardPage aRulePage)
                                throws DatabaseException

Returns the version of a rule that is most closely related to a given version.

Parameters:

aRulePage - a version of a rule

Returns:

another version of the aRulePage, which is most closely related to it; or null if there are no versions related to it

Throws:

BadClassDefinitionException - if the instance is of (or defined on) an bad class

ConfigurationException - if the database table configuration is bad

MultipleCircumstancePropertiesException - if more than one circumstance property is found

MultipleRuleVersionException - if more than one version of the rule is found

BadInputException - if there is a problem with the rule page--or if the page is not of a class that uses rule resolution or class inheritance

BadInstanceDataException - if the database instance is corrupt

DatabaseException - if there is a problem with the database

isBasisOf

boolean isBasisOf(ClipboardPage aVersion1,
                  ClipboardPage aVersion2)

Is one version of a rule the basis of another version. A rule version r is the basis of version s if s is a better version of the rule (by rule resolution standards) than r is.

Parameters:

aVersion1 - the first rule version

aVersion2 - the second rule version

Returns:

true if the first version is a basis of the second version

Throws:

java.lang.IllegalArgumentException - if aVersion1 and aVersion2 are not versions of the same rule

isClassVisible

boolean isClassVisible(java.lang.String aClassName)

Indicates whether a particular class is visible to the rule being edited (according to the list of rulesets).

Parameters:

aClassName - the name of the class

Returns:

true iff the class is visible

addNamedPageReference

void addNamedPageReference(java.lang.String aPageName)

Records a reference to a named page, if reference tracking is enabled. If reference tracking is not enabled, does nothing.

Parameters:

aPageName - the name of the page

addAPIMethodReference

void addAPIMethodReference(java.lang.String aClassName,
                           java.lang.String aMethodName,
                           java.lang.String[] aParameterTypes)

Records a call to an API method, if reference tracking is enabled. If reference tracking is not enabled, does nothing.

Parameters:

aClassName - the name of the Java class to which the method belongs, with complete package

aMethodName - the name of the method

aParameterTypes - the types of parameters for the method, with complete package names where appropriate

validatePagesAndClasses

void validatePagesAndClasses(ClipboardProperty aPagesAndClassesProperty,
                             ClipboardProperty aParameterProperty)

Validates the pages and classes table for the rule. If it is invalid, then messages are added to the rule's page.

Parameters:

aPagesAndClassesProperty - property containing the pages and classes information

aParameterProperty - the parameters property for the rule, or null if none

getDictionary

Dictionary getDictionary()

Returns a Dictionary that uses the this RuleSet context to open rules, and that tracks references in this RuleSet context's rule page.

Returns:

a Dictionary

findHandle

java.lang.String findHandle(StringMap aKeys)
                            throws DatabaseException

Finds the handle of the instance that would be opened from the RuleSet context, given a set of keys. This method is less expensive than calling one of the open methods, as it does not read the storage stream from the database.

Instances opened through this method are not added as a reference to the Rule being edited.

This method may be used to open both Rule-Resolved instances and non-Rule-Resolved instances. When opening non-Rule-Resolved instances, it does not check the pyRuleSet property on the instance, as open(com.pega.pegarules.pub.util.StringMap) does.

Parameters:

aKeys - the keys of the instance in question

Returns:

the pzInsKey of the instance that is named by those keys, or null if such an instance does not exist

Throws:

BadClassDefinitionException - if the instance keys specify an invalid instance class (pxObjClass) or if the instance keys specify an instance that belongs to class that uses inheritance, and the keys specify a bad object class (pyClassName). The processing status is set to error and the message is Database-BadClassDef-BadObjectClass.

MultipleCircumstancePropertiesException - if, during Rule Resolution, Rules with conflicting Circumstance Properties or with conflicting Circumstance Date Properties were encountered

MultipleRuleVersionException - if the requested instance belongs to a class that uses Rule Resolution, and there is more than one version of the rule that may be considered the best version

NoRuleVersionWithoutCircumstanceException - if Rule Resolution was used to find the instance, and a default version of the Rule was expected but not found

DatabaseException - if there is a problem with the database

findRuleInClassSet

boolean findRuleInClassSet(StringMap aKeys,
                           java.util.Set aClassToTry)
                           throws DatabaseException

Looks for the specified rule in any of the classes given in the aClassToTry list. These classes may be related in an inheritance chain, but this is not taken into account. This may result in searching the same class more than once.

Parameters:

aKeys - the keys for the rule to find

aClassToTry - the set of class names to try

Returns:

true iff the rule could be found

Throws:

DatabaseException - if there is a database problem or a rule resolution problem

getListOfRulesets

java.util.List getListOfRulesets()

Returns a list of Strings representing the unlocalized rulesets in this RulesetContext.

Returns:

List of Strings