com.ibm.websphere.brb.mgmt
Interface IRuleFolder

All Superinterfaces:
java.io.Serializable

public interface IRuleFolder
extends java.io.Serializable

A folder in which rules are contained. All rules are contained within a folder much like files are contained within directories. The root rule folder is needed to begin working with rules. Use the method getRootFolder on class RuleMgmtHelper to get the root rule folder. From the root rule folder you can add, delete, and retrieve folders and rules using methods on this interface.

The following example shows how to add a new folder "com" in the root.

    IRuleFolder root = RuleMgmtHelper.getRootFolder();
    IRuleFolder newFolder = root.createSubFolder("com");
 
The method createSubFolder can also be used to create a sequence of rule folders by passing a path to the method. The path is relative to the rule folder on which the method is called. An example path is "com/acme/lifeInsurance". Note that the path should not start with a slash (/). The following example creates the folder "com/acme/lifeInsurance".
   IRuleFolder lifeFolder = root.createSubFolder("com/acme/lifeInsurance");
 
If you are not sure if the folder exists, an overloaded version of method getSubFolder can be used to create a folder or to return the folder if it already exists. The method takes a folder path as a parameter. The path is relative to the rule folder on which the method is called. The following example creates the folder "com/acme/lifeInsurance" if it does not exist and returns the new folder to the caller or simply returns the folder if it already existed. Note that the boolean true indicates that the folder should be created if it does not already exist.
   IRuleFolder lifeFolder = root.getSubFolder("com/acme/lifeInsurance", true);
 
The method getSubFolders is used to get a collection of the IRuleFolders contained directly within this folder. This method will not return folders contained within the subfolders. The following example gets all subfolders and prints their names to standard out.
   IRuleFolder lifeFolder = root.getSubFolder("com/acme/lifeInsurance");
   Collection folders = lifeFolder.getSubFolders();
   Iterator iterator = folders.iterator();
   while (iterator.hasNext()) {
      IRuleFolder folder = (IRuleFolder)iterator.next();
      System.out.println(folder.getName());
   }
 
A folder can be moved into a different folder. Suppose you wish to change your folder structure such that "com/acme/lifeInsurance" should now be called "com/acme/insurance/lifeInsurance". Essentially, we want to move "lifeInsurance" into "com/acme/insurance". The following example accomplishes this.
   IRuleFolder lifeFolder = root.getSubFolder("com/acme/lifeInsurance");
   IRuleFolder insuranceFolder = root.getSubFolder("com/acme/insurance");
   lifeFolder.move(insuranceFolder);
 

Rules can be retrieved by reference or by copy. The differences are described in detail in the com.ibm.websphere.brb.mgmt package-level documentation.

Let's look at a few examples. The following code shows how to get all rules from the com/ibm/websphere/brb folder. The method can return references to the persistent rule or local copies of the rule. In this case references are being returned. Passing false for the first parameter on the findRules method indicates that only rules within the com/ibm/websphere/brb folder will be returned, not rules contained within its subfolders.

   IRuleFolder brbFolder = root.getSubFolder("com/ibm/websphere/brb");
   Collection rules = brbFolder.findRules(false, IRule.TYPE_REFERENCE);
 
The following example creates a new Rule into the com/ibm/websphere/brb folder using a reference to the Rule.
   IRuleFolder brbFolder = root.getSubFolder("com/ibm/websphere/brb");
   IRule rule = brbFolder.createRule(IRule.TYPE_REFERENCE, "GreaterThanRule");
   rule.setDescription("Performs a greater than operation");
   ... set the rest of the attributes ...
 
The following example creates a new rule into the com/ibm/webspherebrb folder using a local copy of the Rule.
   IRuleFolder brbFolder = root.getSubFolder("com/ibm/websphere/brb");
   IRuleCopy ruleCopy = (IRuleCopy) 
       brbFolder.createRule(IRule.TYPE_COPY, "GreaterThanRule");
   ruleCopy.setDescription("Performs a greater than operation");
   ... set the rest of the attributes ...

   // Tell the local copy of the rule to update the persistent rule
   ruleCopy.updatePersistentRule();
 
Working with a local copy of a rule introduces the possibility that the copy becomes out of date with the persistent rule. This is particularly troubling when changes are being made to the copy and the persistent rule is to be updated with these changes. The overloaded method IRuleCopy.updatePersistentRule(IRuleCopy,int) is intended to handle this situation.

The createRule methods which take an IRule as a parameter are used to copy or "clone" rules based on already existing rules. The following example demonstrates this:

   Collection coll = brbFolder.findRulesByName("GreaterThanRule", IRule.TYPE_REFERENCE);
   IRule existingRule = coll.iterator().next(); // assumes only one rule exists with this name
   IRule newRule = brbFolder.createRule(IRule.TYPE_COPY, existingRule);

   // The existing rule will expire when the new rule starts
   Date dateForNewRule = new Date(2001, 1, 1);
   existingRule.setEndDate(dateForNewRule);
   newRule.setStartDate(dateForNewRule);

   // Any other changes to the new rule
   ...

   // Update the copy of the rule, this will create the new rule on the server
   newRule.updatePersistentRule();
 
In this example, the new rule is created as a local copy. When receiving a local copy, the persistent rule is not created on the server until the method updatePersistentRule is called. Note that you could just as well create the rule and receive a reference. In this case, the rule is created on the server at the time the create is called.

See Also:
RuleMgmtHelper, IRule, IRuleCopy, com.ibm.websphere.brb.mgmt

Method Summary
 IRule createRule(int ruleReturnType, IRule sourceRule)
          Creates a rule into this folder initialized with the contents of the given rule.
 IRule createRule(int ruleReturnType, IRule sourceRule, java.lang.String primaryKey)
          Creates a rule into this folder initialized with the contents of the given rule and set to the given primary key.
 IRule createRule(int ruleReturnType, java.lang.String name)
          Creates a rule into this folder with the given name.
 IRule createRule(int ruleReturnType, java.lang.String name, java.lang.String primaryKey)
          Creates a rule into this folder with the given name and primary key.
 IRuleFolder createSubFolder(java.lang.String path)
          Creates a folder or hierarchy of folders as a child of this folder.
 void delete()
          Deletes this folder and all of its children.
 void deleteAllRules()
          Delete all rules contained in this folder.
 void deleteAllSubFolders()
          Delete all subfolders contained in this folder.
 IRule findRuleByPrimaryKey(java.lang.String primaryKey, boolean includeSubFolders, int returnType)
          Find a rule in this folder with the given primary key.
 java.util.Collection findRules(boolean includeSubFolders, int returnType)
          Gets all rules contained within this folder.
 java.util.Collection findRules(QueryNode queryNode, boolean includeSubFolders, int returnType)
          Look in this folder for rules that match the given query.
 java.util.Collection findRulesByName(java.lang.String ruleName, boolean includeSubFolders, int returnType)
          Look in this folder for a rule with the given name.
 java.lang.String getFullName()
          Get the fully qualified name of this folder.
 java.lang.String getName()
          Returns the name of this folder.
 IRuleFolder getParent()
          This method returns the parent folder for this folder.
 IRuleFolder getRoot()
          Returns the root IRuleFolder for this rule namespace.
 IRuleFolder getSubFolder(java.lang.String path)
          Gets the folder for the given relative path.
 IRuleFolder getSubFolder(java.lang.String path, boolean createFolder)
          Gets the folder for the given relative path.
 java.util.Collection getSubFolders()
          Gets all folders directly contained within this folder.
 void move(IRuleFolder toFolder)
          Move this folder into a new folder.
 void rename(java.lang.String newName)
          Renames this folder.
 

Method Detail

createRule

public IRule createRule(int ruleReturnType,
                        IRule sourceRule)
                 throws BusinessRuleBeansException,
                        java.rmi.RemoteException
Creates a rule into this folder initialized with the contents of the given rule. The new rule will be the same as the original rule, except that a new primary key is generated and the folder containing the new rule is this folder. 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. 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)
sourceRule - the rule whose values are copied to get the new rule
Returns:
the newly created rule
Throws:
BRBeansIllegalArgumentException - if the ruleReturnType is not valid or the sourceRule is null
BusinessRuleBeansException
java.rmi.RemoteException

createRule

public IRule createRule(int ruleReturnType,
                        IRule sourceRule,
                        java.lang.String primaryKey)
                 throws BusinessRuleBeansException,
                        java.rmi.RemoteException
Creates a rule into this folder initialized with the contents of the given rule and set to the given primary key. The new rule will be the same as the original rule, except that the primary key has the given value and the folder containing the new rule is this folder. 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. 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)
sourceRule - the rule whose values are copied to get the new rule
primaryKey - the primary key of the new rule
Returns:
the newly created rule
Throws:
BRBeansIllegalArgumentException - if the ruleReturnType is not valid or the sourceRule or primaryKey is null
BusinessRuleBeansException
java.rmi.RemoteException

createRule

public IRule createRule(int ruleReturnType,
                        java.lang.String name)
                 throws BusinessRuleBeansException,
                        java.rmi.RemoteException
Creates a rule into this folder with the given name. 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. 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)
name - the name of the Rule
Returns:
the newly created rule
Throws:
BRBeansIllegalArgumentException - if the ruleReturnType is not valid
BusinessRuleBeansException
java.rmi.RemoteException

createRule

public IRule createRule(int ruleReturnType,
                        java.lang.String name,
                        java.lang.String primaryKey)
                 throws BusinessRuleBeansException,
                        java.rmi.RemoteException
Creates a rule into this folder with the given name and primary key. 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. 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 copy (IRule.TYPE_COPY) or a reference (IRule.TYPE_REFERENCE)
name - the name of the rule
primaryKey - the primary key to give this rule
Returns:
the newly created rule
Throws:
BRBeansIllegalArgumentException - if the ruleReturnType is not valid or the primaryKey is null
BusinessRuleBeansException
java.rmi.RemoteException

createSubFolder

public IRuleFolder createSubFolder(java.lang.String path)
                            throws BusinessRuleBeansException,
                                   java.rmi.RemoteException
Creates a folder or hierarchy of folders as a child of this folder. The name passed can be either a single folder name or a relative path name. Any folders along the path that do not exist will be created. If the given path already exists a BusinessRuleBeansException is thrown. The given path must be non-null and non-empty.

Parameters:
path - the path of the new folder
Returns:
the newly created folder
Throws:
BusinessRUleBeansException - if the folder or path already exists
BusinessRuleBeansException
java.rmi.RemoteException

delete

public void delete()
            throws BusinessRuleBeansException,
                   java.rmi.RemoteException
Deletes this folder and all of its children. All contained rules and subfolders are deleted.

Throws:
BusinessRUleBeansException - if this folder is the root folder
BusinessRuleBeansException
java.rmi.RemoteException

deleteAllRules

public void deleteAllRules()
                    throws BusinessRuleBeansException,
                           java.rmi.RemoteException
Delete all rules contained in this folder. Subfolders will not be removed.

Throws:
BusinessRuleBeansException
java.rmi.RemoteException

deleteAllSubFolders

public void deleteAllSubFolders()
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Delete all subfolders contained in this folder. Any rules contained within the subfolders are also deleted.

Throws:
BusinessRuleBeansException
java.rmi.RemoteException

findRuleByPrimaryKey

public IRule findRuleByPrimaryKey(java.lang.String primaryKey,
                                  boolean includeSubFolders,
                                  int returnType)
                           throws BusinessRuleBeansException,
                                  java.rmi.RemoteException
Find a rule in this folder with the given primary key. This method will search in this folder and, optionally, subfolders of this folder. It will not find rules in folders higher in the hierarchy. To find a rule anywhere in the rule namespace, call this method on the root folder (which can be obtained by calling method getRoot). Null is returned if the rule is not found.

Parameter includeSubFolders determines whether to search subfolders. Pass true to search subfolders.

This method can return either a reference to the rule (IRule.TYPE_REFERENCE) or a local copy of the rule (IRule.TYPE_COPY).

Parameters:
primaryKey - the primaryKey of the rule
includeSubFolders - indicates whether to include subfolders as well
returnType - indicates whether to return a reference to the persistent rule or a local copy of the rule
Returns:
the rule with the given primary key, or null if not found
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

findRules

public java.util.Collection findRules(QueryNode queryNode,
                                      boolean includeSubFolders,
                                      int returnType)
                               throws BusinessRuleBeansException,
                                      java.rmi.RemoteException
Look in this folder for rules that match the given query. This allows arbitrary queries to be specified. An empty collection is returned if no rules are found that match the specified query. Parameter includeSubFolders determines whether to search subfolders. Pass true to search subfolders.

This method can return references to the rules (IRule.TYPE_REFERENCE) or local copies of the rule (IRule.TYPE_COPY). Pass this value to parameter returnType

For example, find all rules named "isEligible".

   RuleNameNode nameNode = new RuleNameNode("isEligible", AbstractStringNode.EQUALS);
   Collection rules = root.findRules(nameNode, true, IRule.TYPE_REFERENCE);
 
The following finds rules named "isEligible" with a classification of "SeniorCitizen".
   RuleNameNode nameNode = new RuleNameNode("isEligible", AbstractStringNode.EQUALS);
   ClassificationNode cNode = new ClassificationNode("SeniorCitizen", 
                                                     AbstractStringNode.EQUALS);
   AndNode andNode = new AndNode(nameNode, cNode);
   Collection rules = root.findRules(andNode, true, IRule.TYPE_REFERENCE);
 

Parameters:
queryNode - represents the type of query to perform
includeSubFolders - indicates whether to include subfolders as well
returnType - indicates whether to return a reference to the persistent rule or a local copy of the rule
Returns:
a collection of the rules that match the given query
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

findRules

public java.util.Collection findRules(boolean includeSubFolders,
                                      int returnType)
                               throws BusinessRuleBeansException,
                                      java.rmi.RemoteException
Gets all rules contained within this folder. An empty collection is returned if there are no rules in this folder or subfolders. Parameter includeSubFolders determines whether to search subfolders. Pass true to search subfolders.

This method can return either references to the rules (IRule.TYPE_REFERENCE) or local copies of the rules (IRule.TYPE_COPY).

Parameters:
includeSubFolders - indicates whether to include subfolders as well
returnType - indicates whether to return references to the persistent rules or local copies of the rules
Returns:
a collection containing the rules in this folder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

findRulesByName

public java.util.Collection findRulesByName(java.lang.String ruleName,
                                            boolean includeSubFolders,
                                            int returnType)
                                     throws BusinessRuleBeansException,
                                            java.rmi.RemoteException
Look in this folder for a rule with the given name. This method returns a Collection because there could be multiple rules with this same name. An empty collection is returned if no rule is found with this name. The parameter ruleName can specify a relative path followed by the name of the rule or may simply specify a name of the rule. If a relative path is specified, then the includeSubFolders parameter must be false. This is because a particular subfolder is already being specified by the relative path. If parameter includeSubFolders is not false and a relative path is specified, then a BRBeansIllegalArgumentException is thrown.

This method can return references to the rules (IRule.TYPE_REFERENCE) or local copies of the rule (IRule.TYPE_COPY). Pass this value to parameter returnType

For example, the following will return the rule named "isEligibleForDiscount" in folder lifeFolder.

   IRuleFolder lifeFolder = root.getSubFolder("com/acme/lifeInsurance");
   Collection rules = lifeFolder.findRules("isEligibleForDiscount",
                                           IRule.TYPE_REFERENCE);
 
The following finds a rule specifying a fully qualified name:
   Collection rules = root.findRules("com/acme/lifeInsurance/isEligibleForDiscount",
                                     IRule.TYPE_REFERENCE);
 

Parameters:
ruleName - the name of the rule for which to search
includeSubFolders - indicates whether to include subfolders as well. true cannot be specified if a relative path is specified for the ruleName parameter.
returnType - indicates whether to return a reference to the persistent rule or a local copy of the rule
Returns:
a collection of rules with the given name
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getFullName

public java.lang.String getFullName()
                             throws BusinessRuleBeansException,
                                    java.rmi.RemoteException
Get the fully qualified name of this folder.

Returns:
the fully qualified name of the folder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getName

public java.lang.String getName()
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Returns the name of this folder. This name does not include parent folders. Use method getFullName to get a fully qualified name.

Returns:
the name of the folder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getParent

public IRuleFolder getParent()
                      throws BusinessRuleBeansException,
                             java.rmi.RemoteException
This method returns the parent folder for this folder.

Returns:
the parent folder for this folder.
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getRoot

public IRuleFolder getRoot()
                    throws BusinessRuleBeansException,
                           java.rmi.RemoteException
Returns the root IRuleFolder for this rule namespace.

Returns:
the root IRuleFolder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

getSubFolder

public IRuleFolder getSubFolder(java.lang.String path)
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Gets the folder for the given relative path. Null is returned if the folder does not exist.

Parameters:
path - the relative path of the folder to retrieve
Returns:
the folder for the given relative path or null if not found
Throws:
BRBeansIllegalArgumentException - if the path is invalid. A valid path name must not be null or the empty string and must not start with a '/' character.
BusinessRuleBeansException
java.rmi.RemoteException

getSubFolder

public IRuleFolder getSubFolder(java.lang.String path,
                                boolean createFolder)
                         throws BusinessRuleBeansException,
                                java.rmi.RemoteException
Gets the folder for the given relative path. The boolean createFolder determines whether to create the folders if they do not exist. Passing true will cause the folders to be created. If false is passed and the folder does not exist, null is returned.

Parameters:
path - the relative path of the folder to retrieve
createFolder - indicates whether to create the folder if it doesn't exist
Returns:
the folder for the given relative path
Throws:
BRBeansIllegalArgumentException - if the path is invalid. A valid path name must not be null or the empty string and must not start with a '/' character.
BusinessRuleBeansException
java.rmi.RemoteException

getSubFolders

public java.util.Collection getSubFolders()
                                   throws BusinessRuleBeansException,
                                          java.rmi.RemoteException
Gets all folders directly contained within this folder. An empty collection is returned if there are no subfolders.

Returns:
a collection containing the sub-folders
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

move

public void move(IRuleFolder toFolder)
          throws BusinessRuleBeansException,
                 java.rmi.RemoteException
Move this folder into a new folder. Any rules contained in this folder or subfolder are moved as well.

Parameters:
toFolder - the folder into which to move this folder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException

rename

public void rename(java.lang.String newName)
            throws BusinessRuleBeansException,
                   java.rmi.RemoteException
Renames this folder. All rules and subfolders of this folder will continue to be contained in the newly named folder.

Parameters:
newName - the new name of this folder
Throws:
BusinessRuleBeansException
java.rmi.RemoteException