com.ibm.websphere.brb.mgmt
Interface IRule

All Superinterfaces:
java.io.Serializable
All Known Subinterfaces:
IRuleCopy

public interface IRule
extends java.io.Serializable

A business rule; an object that encapsulates the highly time and context-dependent behavior needed to ensure that work done with the application conforms to current business practices. Rules can be in exactly one of four states at any particular time, based on the values in the start and end date fields:

Only rules which are "in effect" are usually found from the BRBeans runtime. This behavior can be overriden by setting an asOfDate on the TriggerPoint object, which will then find rules as if the current date is the given date.

When a Rule is first created it is marked as ready for use and will be found when firing Rules. If the Rule is not complete and should not be found by BRBeans, mark the Rule as not being ready for use by calling method setReady passing false.

A Rule can be represented as both a Rule (a server-side representation) or as a RuleCopy (a client-side representation). This IRule interface is the parent interface of both types of Rules.


Field Summary
static int DATE_STATUS_EXPIRED
          Status constant - the rule has expired.
static int DATE_STATUS_IN_EFFECT
          Status constant - the rule is currently in effect.
static int DATE_STATUS_INVALID
          Status constant - the rule has a start date that is after its end date.
static int DATE_STATUS_NO_START_DATE
          Status constant - the rule has no start date so it will never be in effect.
static int DATE_STATUS_PENDING
          Status constant - the rule is scheduled to take effect in the future.
static int FIRE_ANYWHERE
          FireLocation constant - Rules can be fired anywhere.
static int FIRE_LOCAL
          FireLocation constant - Rules must be fired on the client.
static int FIRE_REMOTE
          FireLocation constant - Rules must be fired on the server.
static int TYPE_COPY
          Return type constant - get a copy of the persistent Rule when creating or retrieving Rules.
static int TYPE_REFERENCE
          Return type constant - get a reference to the persistent Rule when creating or retrieving Rules.
 
Method Summary
 void addInitParameter(ConstantParameter initParameter)
          Adds the given init parameter to the end of the list of init parameters.
 java.util.Vector checkRuleData()
          Check for errors in the data for this rule.
 IRule copy(int ruleReturnType)
          Creates a new rule initialized with the contents of this rule.
 void delete()
          Deletes this rule.
 java.lang.Object fire(TriggerPoint tp, java.lang.Object target, java.lang.Object[] firingParams)
          Fires this rule.
 java.lang.String getBusinessIntent()
          Returns the business intent of this rule.
 java.lang.String getClassification()
          Returns the classification of this rule.
 int getDateStatus()
          Determine the rule's status.
 java.lang.String[] getDependentRules()
          Returns the names of the dependent rules of this rule.
 java.lang.String getDescription()
          Returns the description of this rule.
 java.util.Date getEndDate()
          Returns the date when this rule expires.
 int getFiringLocation()
          Returns the firing location for this rule.
 IParameter[] getFiringParameters()
          Returns the firing parameters for this rule.
 java.lang.String getId()
          Returns the primary key of this rule.
 ConstantParameter[] getInitParameters()
          Returns the init parameters for this rule.
 java.lang.String getJavaRuleImplementorName()
          Returns the full class name of the Java rule implementor of this rule.
 java.lang.String getOriginalRequirement()
          Returns the initial business analyst requirement of this rule.
 int getPrecedence()
          Returns the relative priority of this rule.
 IRule getRuleAtFiringLocation()
          FOR IBM INTERNAL USE ONLY.
 IRuleCopy getRuleCopy()
          Creates a copy of this rule and returns it.
 IRuleFolder getRuleFolder()
          Returns the folder in which this rule is stored.
 java.lang.String getRuleName()
          Returns the name of this rule.
 java.util.Date getStartDate()
          Returns the date this rule comes into effect.
 java.lang.String getUserDefinedData()
          Returns any user-defined data for this rule.
 boolean isClassifier()
          Returns a value indicating if this rule is a classifier rule.
 boolean isReady()
          Returns a value indicating whether this rule is ready for use.
 void move(IRuleFolder newRuleFolder)
          Moves this rule to the given rule folder.
 void removeInitParameter(int index)
          Removes the init parameter that is at the given index.
 void setBusinessIntent(java.lang.String newBusinessIntent)
          Sets the business intent of this rule.
 void setClassification(java.lang.String newClassification)
          Sets the classification of this rule.
 void setClassifier(boolean isClassifier)
          Sets a value indicating if this rule is a classifier rule.
 void setDependentRules(java.lang.String[] newDependentRules)
          Sets the names of the dependent rules of this rule.
 void setDescription(java.lang.String newDescription)
          Sets the description of this rule.
 void setEndDate(java.util.Date newEndDate)
          Sets the date when this rule expires.
 void setFiringLocation(int newFiringLocation)
          Sets the firing location for this rule.
 void setFiringParameters(IParameter[] parameters)
          Sets the firing parameters for this rule.
 void setInitParameters(ConstantParameter[] newInitParameters)
          Sets the init parameters for this rule.
 void setJavaRuleImplementorName(java.lang.String newRuleImplementor)
          Sets the full class name of the Java rule implementor of this rule.
 void setOriginalRequirement(java.lang.String newOriginalReq)
          Sets the initial business analyst requirement of this rule.
 void setPrecedence(int newPrecedence)
          Sets the relative priority of this rule.
 void setReady(boolean ready)
          Sets a value indicating whether this rule is ready for use.
 void setRuleName(java.lang.String newRuleName)
          Sets the name of this rule.
 void setStartDate(java.util.Date newStartDate)
          Sets the date this rule comes into effect.
 void setUserDefinedData(java.lang.String newUserDefinedData)
          Sets the user-defined data for this rule.
 java.lang.String toXML()
          Returns the XML representation of this rule.
 

Field Detail

TYPE_REFERENCE

public static final int TYPE_REFERENCE
Return type constant - get a reference to the persistent Rule when creating or retrieving Rules.

See Also:
Constant Field Values

TYPE_COPY

public static final int TYPE_COPY
Return type constant - get a copy of the persistent Rule when creating or retrieving Rules. Any changes made to this copy are not persisted unless the user invokes the method updatePersistentRule.

See Also:
Constant Field Values

FIRE_ANYWHERE

public static final int FIRE_ANYWHERE
FireLocation constant - Rules can be fired anywhere. An attempt is made to fire the Rule locally first. If this fails, the Rule is fired remotely.

See Also:
Constant Field Values

FIRE_LOCAL

public static final int FIRE_LOCAL
FireLocation constant - Rules must be fired on the client.

See Also:
Constant Field Values

FIRE_REMOTE

public static final int FIRE_REMOTE
FireLocation constant - Rules must be fired on the server.

See Also:
Constant Field Values

DATE_STATUS_IN_EFFECT

public static final int DATE_STATUS_IN_EFFECT
Status constant - the rule is currently in effect.

See Also:
Constant Field Values

DATE_STATUS_PENDING

public static final int DATE_STATUS_PENDING
Status constant - the rule is scheduled to take effect in the future.

See Also:
Constant Field Values

DATE_STATUS_EXPIRED

public static final int DATE_STATUS_EXPIRED
Status constant - the rule has expired.

See Also:
Constant Field Values

DATE_STATUS_NO_START_DATE

public static final int DATE_STATUS_NO_START_DATE
Status constant - the rule has no start date so it will never be in effect.

See Also:
Constant Field Values

DATE_STATUS_INVALID

public static final int DATE_STATUS_INVALID
Status constant - the rule has a start date that is after its end date.

See Also:
Constant Field Values
Method Detail

addInitParameter

public void addInitParameter(ConstantParameter initParameter)
                      throws BusinessRuleBeansException,
                             java.rmi.RemoteException
Adds the given init parameter to the end of the list of init parameters.

Parameters:
initParameter - an init parameter to add to this rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

checkRuleData

public java.util.Vector checkRuleData()
                               throws java.rmi.RemoteException
Check for errors in the data for this rule. If any errors are found, return a Vector of ErrorMessage objects indicating what problems were found. The errors checked by this method will prevent the rule from working correctly. If the rule is not marked ready, any ErrorMessages returned will be marked as warnings since it may be valid to save the rule with errors. If the rule is marked ready, then these ErrorMessages will be marked as errors.

Returns:
Vector of ErrorMessages indicating what errors were found; null if no errors.
Throws:
java.rmi.RemoteException

copy

public IRule copy(int ruleReturnType)
           throws BusinessRuleBeansException,
                  java.rmi.RemoteException
Creates a new rule initialized with the contents of this rule. The new rule will be the same as this rule, except that a new primary key is generated. The rule is created into the same folder as this rule. The rule can be created as a copy (IRule.TYPE_COPY) or as a reference to the persistent rule (IRule.TYPE_REFERENCE). When creating the rule as a local copy, an instance of class IRuleCopy is returned. In this case, the persistent rule is not created on the server until method updatePersistentRule is called on the IRuleCopy.

When returning a reference, the persistent rule is created on the server immediately.

Parameters:
ruleReturnType - indicates whether to return a local copy (IRule.TYPE_COPY) or a reference (IRule.TYPE_REFERENCE)
Returns:
the newly created rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

delete

public void delete()
            throws BusinessRuleBeansException,
                   java.rmi.RemoteException
Deletes this rule. If this rule is an IRuleCopy, the method updatePersistentRule must be called before the rule will be deleted from persistent storage.

Throws:
BusinessRuleBeansException
java.rmi.RemoteException

fire

public java.lang.Object fire(TriggerPoint tp,
                             java.lang.Object target,
                             java.lang.Object[] firingParams)
                      throws BusinessRuleBeansException,
                             java.rmi.RemoteException
Fires this rule. If the rule implementor has not yet been instantiated, this method first instantiates it and initializes it with the values specified in this rule's initialization parameters. It then invokes the fire method on the rule implementor passing the values given to this method. Finally the result of firing the implementor is returned. This method should only be used in implementing a FiringStrategy.

Parameters:
tp - the trigger point with which this rule is called
target - the target object passed by the application
firingParams - the parameters passed by the application
Returns:
the result of firing the rule implementor
Throws:
BusinessRuleBeansException - if a problem occurs
java.rmi.RemoteException

getBusinessIntent

public java.lang.String getBusinessIntent()
                                   throws java.rmi.RemoteException
Returns the business intent of this rule. The business intent is the analyst-level description of this rule.

Returns:
the business intent, or null if there is none
Throws:
java.rmi.RemoteException

getClassification

public java.lang.String getClassification()
                                   throws java.rmi.RemoteException
Returns the classification of this rule. The classification identifies a particular rule among a number of other rules with the same full rule name. Rules with a non-null classification are known as "classified" rules.

Returns:
the classification, or null if it is unclassified
Throws:
java.rmi.RemoteException

getDateStatus

public int getDateStatus()
                  throws java.rmi.RemoteException
Determine the rule's status. The status can be one of the following: See the description for each of these values above.

Returns:
The status of this rule.
Throws:
java.rmi.RemoteException - An error occurred processing the request.

getDependentRules

public java.lang.String[] getDependentRules()
                                     throws java.rmi.RemoteException
Returns the names of the dependent rules of this rule. The dependent rules are a list of full rule names (both the folder and rule names) on which this rule depends. This value is passed to the rule implementor as the dependentRules parameter on the init method. Generally a rule implementor that handles dependent rules (for example RuleAND and RuleIfThenElse) will fire each of the named rules.

Returns:
an array of full rule names of the dependent rules, or null if there are none
Throws:
java.rmi.RemoteException

getDescription

public java.lang.String getDescription()
                                throws java.rmi.RemoteException
Returns the description of this rule. The description is a programmer-level description of the rule.

Returns:
the description, or null if none exists
Throws:
java.rmi.RemoteException

getEndDate

public java.util.Date getEndDate()
                          throws java.rmi.RemoteException
Returns the date when this rule expires. At this date and any date after it, this rule will not be "in effect". If the rule does not have an end date, null will be returned. A null end date means that the rule never expires.

Returns:
the end date, or null if no end date is specified
Throws:
java.rmi.RemoteException

getFiringLocation

public int getFiringLocation()
                      throws java.rmi.RemoteException
Returns the firing location for this rule. The firing location indicates where the rule implementor should actually be fired. There are three options:
IRule.FIRE_LOCAL
Fires the rule implementor local to the trigger point. In some environments, in a servlet for example, this would actually be on the application server. The rule implementor class should exist on the same host as the trigger point.
IRule.FIRE_REMOTE
Fires the rule implementor remote from the trigger point. The rule implementor class should exist on the same host as the rule beans.
IRule.FIRE_ANYWHERE
First attempts to fire the rule implementor locally. If the rule implementor class cannot be found locally, it attempts to fire the rule implementor remotely.

Returns:
the location at which this rule's implementor is fired
Throws:
java.rmi.RemoteException

getFiringParameters

public IParameter[] getFiringParameters()
                                 throws java.rmi.RemoteException
Returns the firing parameters for this rule. If firing parameters are specified on the rule, these will override the firing parameters specified on the trigger point. Otherwise, the firing parameters are passed directly from the trigger point.

Returns:
the firing parameters, or null if the firing parameters are passed directly from the trigger point.
Throws:
java.rmi.RemoteException

getId

public java.lang.String getId()
                       throws java.rmi.RemoteException
Returns the primary key of this rule.

Returns:
the primary key of this rule
Throws:
java.rmi.RemoteException

getInitParameters

public ConstantParameter[] getInitParameters()
                                      throws java.rmi.RemoteException
Returns the init parameters for this rule. The init parameters are passed to the rule implementor's init method.

Returns:
the init parameters, null if there are none
Throws:
java.rmi.RemoteException

getJavaRuleImplementorName

public java.lang.String getJavaRuleImplementorName()
                                            throws java.rmi.RemoteException
Returns the full class name of the Java rule implementor of this rule.

Returns:
the full class name of the Java rule implementor of this rule
Throws:
java.rmi.RemoteException

getOriginalRequirement

public java.lang.String getOriginalRequirement()
                                        throws java.rmi.RemoteException
Returns the initial business analyst requirement of this rule. It can be used to keep track of why this rule was originally created, for example to help keep auditing records.

Returns:
the original requirement of this rule, or null if none is specified
Throws:
java.rmi.RemoteException

getPrecedence

public int getPrecedence()
                  throws java.rmi.RemoteException
Returns the relative priority of this rule. The default finding strategy uses this value to order the rules, from the lowest numerical value to the highest.

Returns:
the relative priority of this rule, which is zero by default
Throws:
java.rmi.RemoteException

getRuleAtFiringLocation

public IRule getRuleAtFiringLocation()
                              throws BusinessRuleBeansException,
                                     java.rmi.RemoteException
FOR IBM INTERNAL USE ONLY. Returns the correct type of rule based on the firing location:

Returns:
a local copy or a reference to a rule on the server, depending on the firing location
Throws:
BusinessRuleBeansException
java.rmi.RemoteException
See Also:
getFiringLocation()

getRuleCopy

public IRuleCopy getRuleCopy()
                      throws BusinessRuleBeansException,
                             java.rmi.RemoteException
Creates a copy of this rule and returns it.

Returns:
a new copy of this rule
Throws:
BusinessRuleBeansException - if an exception occurs creating the rule
java.rmi.RemoteException - if a remote exception occurs

getRuleFolder

public IRuleFolder getRuleFolder()
                          throws BusinessRuleBeansException,
                                 java.rmi.RemoteException
Returns the folder in which this rule is stored.

Returns:
the folder in which this rule is stored
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getRuleName

public java.lang.String getRuleName()
                             throws java.rmi.RemoteException
Returns the name of this rule. The value returned does not contain information about the folder in which this rule is contained.

Returns:
the name of this rule
Throws:
java.rmi.RemoteException

getStartDate

public java.util.Date getStartDate()
                            throws java.rmi.RemoteException
Returns the date this rule comes into effect. At any dates before this one, this rule will not be "in effect". If the start date is null, the rule is considered invalid.

Returns:
the start date
Throws:
java.rmi.RemoteException

getUserDefinedData

public java.lang.String getUserDefinedData()
                                    throws java.rmi.RemoteException
Returns any user-defined data for this rule. The user-defined data can contain any data desired by the rule user.

Returns:
the user-defined data, or null if none is specified
Throws:
java.rmi.RemoteException

isClassifier

public boolean isClassifier()
                     throws java.rmi.RemoteException
Returns a value indicating if this rule is a classifier rule. Only classifier rules are fired by triggerClassifier and the first phase of triggerSituational. Classifier rules are not found by trigger and the second phase of triggerSituational.

Returns:
true if this is a classifier rule, false otherwise
Throws:
java.rmi.RemoteException

isReady

public boolean isReady()
                throws java.rmi.RemoteException
Returns a value indicating whether this rule is ready for use. Rules that are not ready are not found by BRBeans when firing rules.

Returns:
true if this rule is ready for use, false otherwise
Throws:
java.rmi.RemoteException

move

public void move(IRuleFolder newRuleFolder)
          throws BusinessRuleBeansException,
                 java.rmi.RemoteException
Moves this rule to the given rule folder.

Parameters:
newRuleFolder - the new rule folder which will hold this rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

removeInitParameter

public void removeInitParameter(int index)
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Removes the init parameter that is at the given index.

Parameters:
index - the index of the init parameter to remove
Throws:
BRBeansIllegalArgumentException - if given an illegal index
BusinessRuleBeansException
java.rmi.RemoteException

setBusinessIntent

public void setBusinessIntent(java.lang.String newBusinessIntent)
                       throws java.rmi.RemoteException
Sets the business intent of this rule. The business intent is the analyst-level description of this rule.

Parameters:
newBusinessIntent - the new business intent
Throws:
java.rmi.RemoteException

setClassification

public void setClassification(java.lang.String newClassification)
                       throws BusinessRuleBeansException,
                              java.rmi.RemoteException
Sets the classification of this rule. The classification identifies a particular rule among a number of other rules with the same full rule name. Rules with a non-null classification are known as "classified" rules.

Parameters:
newClassification - the new classification of this rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

setClassifier

public void setClassifier(boolean isClassifier)
                   throws java.rmi.RemoteException
Sets a value indicating if this rule is a classifier rule. Only classifier rules are fired by triggerClassifier and the first phase of triggerSituational. Classifier rules are not found by trigger and the second phase of triggerSituational.

Parameters:
isClassifier - true if this is a classifier rule, false otherwise
Throws:
java.rmi.RemoteException

setDependentRules

public void setDependentRules(java.lang.String[] newDependentRules)
                       throws BusinessRuleBeansException,
                              java.rmi.RemoteException
Sets the names of the dependent rules of this rule. The dependent rules are a list of full rule names (both the folder and rule names) on which this rule depends. This value is passed to the rule implementor as the dependentRules parameter on the init method. Generally a rule implementor that handles dependent rules (for example RuleAND and RuleIfThenElse) will fire each of the named rules.

Parameters:
newDependentRules - an array of full rule names of the dependent rules
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

setDescription

public void setDescription(java.lang.String newDescription)
                    throws java.rmi.RemoteException
Sets the description of this rule. The description is a programmer-level description of the rule.

Parameters:
newDescription - the new description
Throws:
java.rmi.RemoteException

setEndDate

public void setEndDate(java.util.Date newEndDate)
                throws java.rmi.RemoteException
Sets the date when this rule expires. At this date and any date after it, this rule will not be "in effect". Null should be passed if the rule is to have no expiration date.

Parameters:
newEndDate - the new end date, or null if the rule should not expire
Throws:
java.rmi.RemoteException

setFiringLocation

public void setFiringLocation(int newFiringLocation)
                       throws BusinessRuleBeansException,
                              java.rmi.RemoteException
Sets the firing location for this rule. The firing location indicates where the rule implementor should actually be fired. There are three options:
Rule.FIRE_LOCAL
Fires the rule implementor local to the trigger point. In some environments, in a servlet for example, this would actually be on the application server. The rule implementor class should exist on the same host as the trigger point.
Rule.FIRE_REMOTE
Fires the rule implementor remote from the trigger point. The rule implementor class should exist on the same host as the rule beans.
Rule.FIRE_ANYWHERE
First attempts to fire the rule implementor local to the trigger point. If the rule implementor is not found locally, an attempt will then be made to fire the rule remotely.

Parameters:
newFiringLocation - the location at which this rule's implementor is fired
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

setFiringParameters

public void setFiringParameters(IParameter[] parameters)
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Sets the firing parameters for this rule. If firing parameters are specified on the rule, these will override the firing parameters specified on the trigger point. Otherwise, the firing parameters are passed directly from the trigger point.

Parameters:
parameters - the firing parameters, or null if the firing parameters are passed directly from the trigger point.
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

setInitParameters

public void setInitParameters(ConstantParameter[] newInitParameters)
                       throws BusinessRuleBeansException,
                              java.rmi.RemoteException
Sets the init parameters for this rule. The init parameters are passed to the rule implementor's init method.

Parameters:
newInitParameters - the new init parameters
Throws:
BusinessRuleBeansException
java.rmi.RemoteException
See Also:
addInitParameter(ConstantParameter)

setJavaRuleImplementorName

public void setJavaRuleImplementorName(java.lang.String newRuleImplementor)
                                throws BusinessRuleBeansException,
                                       java.rmi.RemoteException
Sets the full class name of the Java rule implementor of this rule.

Parameters:
newRuleImplementor - the full class name of the Java rule implementor of this rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

setOriginalRequirement

public void setOriginalRequirement(java.lang.String newOriginalReq)
                            throws java.rmi.RemoteException
Sets the initial business analyst requirement of this rule. It can be used to keep track of why this rule was originally created, for example to help keep auditing records.

Parameters:
newOriginalReq - the new original requirement of this rule
Throws:
java.rmi.RemoteException

setPrecedence

public void setPrecedence(int newPrecedence)
                   throws java.rmi.RemoteException
Sets the relative priority of this rule. The default finding strategy uses this value to order the rules discovered in the database, from lowest to highest.

Parameters:
newPrecedence - the relative priority of this rule
Throws:
java.rmi.RemoteException

setReady

public void setReady(boolean ready)
              throws java.rmi.RemoteException
Sets a value indicating whether this rule is ready for use. Rules that are not ready are not found by BRBeans when triggering (firing) rules.

Parameters:
ready - boolean indicating whether this rule is ready for use
Throws:
java.rmi.RemoteException

setRuleName

public void setRuleName(java.lang.String newRuleName)
                 throws BusinessRuleBeansException,
                        java.rmi.RemoteException
Sets the name of this rule.

Parameters:
newRuleName - the name of this rule
Throws:
BusinessRuleBeansException - if the newRuleName is invalid. A valid rule name cannot be null, cannot contain a '/' character, and cannot be empty or all blanks.
java.rmi.RemoteException

setStartDate

public void setStartDate(java.util.Date newStartDate)
                  throws java.rmi.RemoteException
Sets the date this rule comes into effect. At any dates before this one, this rule will not be "in effect". A null value will make the rule invalid.

Parameters:
newStartDate - the new start date of this rule
Throws:
java.rmi.RemoteException

setUserDefinedData

public void setUserDefinedData(java.lang.String newUserDefinedData)
                        throws java.rmi.RemoteException
Sets the user-defined data for this rule. The user-defined data can contain any data desired by the rule user.

Parameters:
newUserDefinedData - the user-defined data
Throws:
java.rmi.RemoteException

toXML

public java.lang.String toXML()
                       throws BusinessRuleBeansException,
                              java.rmi.RemoteException
Returns the XML representation of this rule.

Returns:
the XML representation of this rule
Throws:
BusinessRuleBeansException
java.rmi.RemoteException