IBM WebSphere Application ServerTM
Release 7

com.ibm.wbiserver.brules.mgmt
Class BusinessRuleManager

java.lang.Object
  extended by com.ibm.wbiserver.brules.mgmt.BusinessRuleManager

public class BusinessRuleManager
extends java.lang.Object

This class is the starting point for accessing information about business rules that are installed and available on the WPS server. Methods are provided to either get all business rule groups available to this server (getBusinessRuleGroups) or to query for specific business rule groups by property values (methods starting with getBRGsBy). Each logical business rule group is represented by a BusinessRuleGroup object in the returned List. Each BusinessRuleGroup object can then be used to navigate to the desired information.

After a set of BusinessRuleGroup objects has been obtained, the client can use the methods on these objects and on any sub-objects accessible from the BusinessRuleGroup objects to read and/or update data. Many changes are validated at the time the relevant set method is called. Some changes are not validated at that time. These are cases where there are dependencies among multiple pieces of data that can't necessarily be validated until all changes are complete. An example of such a dependency is the default target and the set of date-specific targets on an operation. An operation must have at least one target defined. The target could be either the default target or a date-specific target. Now consider an operation that currently has a default target specified and no date-specified targets. The user wants to change this so that there is no default target and there is one or more date-specfic targets. If the default target is set to null first, a validation error should not be given because we don't know if a date-specific target is going to be added later. A validate method is provided on the BusinessRuleGroup class to validate these kind of dependencies. For situations where a business rule group or sub-objects are of a newer version than what the runtime supports, a shell business rule group will be returned. This situation occurs when the runtime configuration involves multiple servers in a single cell where the servers are of different runtime versions. Because a server can only support a certain amount of features or level of the business rule language, those business rule groups or sub-objects that use newer versions, will not be recognized by a management client and changes to these artifacts may remove or corrupt the new items in the objects. The shell business rule group limits what can be seen and changed in the newer business rule group version. The shell business rule group will be limited to only the name and target namespace of the business rule group as well as two properties, IBMSystemVersion and IBMSystemShell. The IBMSystemVersion property will list the version of the model that was used to create the business rule group. If it is a sub-object that is of a newer version, the version will be x.x.x signifing that it is a newer version that can not be determined as only the business rule group has a version recorded with the model. This property will not be part of the normal list of properties if the business rule group is not a shell. The existance of the IBMSystemShell property indicates the business rule group is a shel and not a regular business rule group. The isShell method can also be used to check if the business rule group is a shell. A shell business rule group is limited in function and basically read only. The getName, getTargetNameSpace, getProperties, getProperty, and getPropertyValue methods are the only methods which are supported. All other get and set methods will result in a UnsupportedOperationException exception thrown.

As set methods are called the Java objects are updated but no changes are made to the underlying persistent data that is actually used when an operation is invoked on a business rule group. To change the persistent data the publish method should be called to publish the changes to persistent storage. The publish method validates the specified business rules groups. If no errors are detected, the business rule groups are published to persistent storage. After the changes are published the changed data will be used the next time an operation on a business rule group is called. Any in-flight operations will continue to use the old data.

The business rule management API uses an optimistic locking scheme when retrieving data from persistent storage. This means that two clients could be making changes to Java objects representing the same set of persistent data at the same time. Neither client has any sort of lock on the persistent data. In this case the first one to call publish wins. The second call to publish will detect that the persistent data has been updated since the transient copies were obtained and the publish will fail. In this case the second client must start over by retrieving the data again using getBusinessRuleGroups and making any changes to the newly-retrieved objects. Because of the read-only nature of a shell business rule group, if a shell business rule group is part of a list of business rule groups to published will be ignored as the other business rule groups are validated and published.

All methods on this class are static. There is no need to ever create an instance of this class.


Field Summary
static com.ibm.wbiservers.customization.audit.AuditRecorder auditRecorder
           
static java.lang.String COPYRIGHT
           
 
Method Summary
static java.util.List<BusinessRuleGroup> getBRGsByName(java.lang.String name, QueryOperator op, int numberToSkip, int maxToReturn)
          Get business rule groups using the name as a key.
static java.util.List<BusinessRuleGroup> getBRGsByProperties(QueryNode queryTree, int numberToSkip, int maxToReturn)
          Get business rule groups that have property values that match the query specified in the given query tree.
static java.util.List<BusinessRuleGroup> getBRGsBySingleProperty(java.lang.String propertyName, QueryOperator op, java.lang.String propertyValue, int numberToSkip, int maxToReturn)
          Get business rule groups that have a property matching the specified parameters.
static java.util.List<BusinessRuleGroup> getBRGsByTNS(java.lang.String tns, QueryOperator op, int numberToSkip, int maxToReturn)
          Get business rule groups using the target name space as a key.
static java.util.List<BusinessRuleGroup> getBRGsByTNSAndName(java.lang.String tns, QueryOperator tnsOp, java.lang.String name, QueryOperator nameOp, int numberToSkip, int maxToReturn)
          Get business rule groups using the target name space and name as a key.
static java.util.List<BusinessRuleGroup> getBusinessRuleGroups(int numberToSkip, int maxToReturn)
          Get all business rule groups that are installed and available to the WPS server in which this code is being run.
protected static com.ibm.wsspi.uow.UOWManager getUOWManager()
           
static void publish(java.util.List<BusinessRuleGroup> updatedBusinessRuleGroups, boolean publishOnlyChangedArtifacts)
          Publish the changes in the specified BusinessRuleGroup objects to persistent storage.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
See Also:
Constant Field Values

auditRecorder

public static com.ibm.wbiservers.customization.audit.AuditRecorder auditRecorder
Method Detail

getBusinessRuleGroups

public static java.util.List<BusinessRuleGroup> getBusinessRuleGroups(int numberToSkip,
                                                                      int maxToReturn)
                                                               throws BusinessRuleManagementException
Get all business rule groups that are installed and available to the WPS server in which this code is being run. The BusinessRuleGroup objects returned by this method are copies of the actual data which is stored persistently in the database. For shell business rule groups as described above, a copy with limited capabilities will be returned. Each time this method is invoked, new copies are returned. This means that each client that invokes the method will get a different set of objects and that the client does not need to worry about other clients accessing the same set of Java objects.

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would start by making the following invocation:

 List<BusinessRuleGroup> firstGroup = BusinessRuleManager.getBusinessRuleGroups(
                0, 20);
 
The second group would be obtained with the following invocation:
 List<BusinessRuleGroup> secondGroup = BusinessRuleManager
                .getBusinessRuleGroups(20, 20);
 
the third group with the following invocation:
 List<BusinessRuleGroup> secondGroup = BusinessRuleManager
                .getBusinessRuleGroups(40, 20);
 
and so on.

Parameters:
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that no rule groups will be skipped.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
See Also:
BusinessRuleGroup

getBRGsByTNS

public static java.util.List<BusinessRuleGroup> getBRGsByTNS(java.lang.String tns,
                                                             QueryOperator op,
                                                             int numberToSkip,
                                                             int maxToReturn)
                                                      throws BusinessRuleManagementException
Get business rule groups using the target name space as a key. This is a convenience method that allows the user to perform a query based on the target name space property by calling one method rather than setting up a query tree using the APIs defined in the com.ibm.wbiserver.brules.mgmt.query package. The query is performed using the specified target name space string and the specified operator.

For example, the following invocation:

    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByTNS("%www.ibm.com/test%", QueryOperator.LIKE, 0, 0);
 
is equivalent to doing the following:
    PropertyQueryNode node = QueryNodeFactory.createPropertyQueryNode(QueryNodeFactory.PROPERTY_NAME__TARGET_NAME_SPACE, QueryOperator.LIKE, "%www.ibm.com/test%");
    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByProperties(node, 0, 0);
 

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would pass 0 for numberToSkip and 20 for maxToReturn on the first invocation. On the second, you would pass 20 and 20. On the third 40 and 20, and so on.

Parameters:
tns - The target name space string to query on. This string may contain the wildcard characters '%' and '_' as used in SQL for "like" queries. Must not be null.
op - The operator to be used in the query. This specifies whether, for example, the query should be an exact match query or a "like" query using wildcards. Must not be null.
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that all rule groups are to be returned.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups that have target name spaces matching the specified query. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
java.lang.IllegalArgumentException - if the tns or op argument is null.
See Also:
BusinessRuleGroup

getBRGsByName

public static java.util.List<BusinessRuleGroup> getBRGsByName(java.lang.String name,
                                                              QueryOperator op,
                                                              int numberToSkip,
                                                              int maxToReturn)
                                                       throws BusinessRuleManagementException
Get business rule groups using the name as a key. This is a convenience method that allows the user to perform a query based on the name property by calling one method rather than setting up a query tree using the APIs defined in the com.ibm.wbiserver.brules.mgmt.query package. The query is performed using the specified name string and the specified operator.

For example, the following invocation:

 List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByName(
                "ChristmasSaleRuleGroup%", QueryOperator.LIKE, 0, 0);
 
is equivalent to doing the following:
 PropertyQueryNode node = QueryNodeFactory.createPropertyQueryNode(
                QueryNodeFactory.PROPERTY_NAME__NAME, QueryOperator.LIKE,
                "ChristmasSaleRuleGroup%");
 List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByProperties(node,
                0, 0);
 

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would pass 0 for numberToSkip and 20 for maxToReturn on the first invocation. On the second, you would pass 20 and 20. On the third 40 and 20, and so on.

Parameters:
name - The name string to query on. This string may contain the wildcard characters '%' and '_' as used in SQL for "like" queries. Must not be null.
op - The operator to be used in the query. This specifies whether, for example, the query should be an exact match query or a "like" query using wildcards. Must not be null.
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that all rule groups are to be returned.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups that have names matching the specified query. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
java.lang.IllegalArgumentException - if the name or op argument is null.
See Also:
BusinessRuleGroup

getBRGsByTNSAndName

public static java.util.List<BusinessRuleGroup> getBRGsByTNSAndName(java.lang.String tns,
                                                                    QueryOperator tnsOp,
                                                                    java.lang.String name,
                                                                    QueryOperator nameOp,
                                                                    int numberToSkip,
                                                                    int maxToReturn)
                                                             throws BusinessRuleManagementException
Get business rule groups using the target name space and name as a key. This is a convenience method that allows the user to perform a query based on the target name space property and the name property together by calling one method rather than setting up a query tree using the APIs defined in the com.ibm.wbiserver.brules.mgmt.query package. The query is performed using the specified target name space string, the specified name, and the specified operator for each.

For example, the following invocation:

    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByTNSAndName("www.ibm.com/test", QueryOperator.EQUAL, "%Christmas%", QueryOperator.LIKE, 0, 0);
 
is equivalent to doing the following:
    PropertyQueryNode tnsNode = QueryNodeFactory.createPropertyQueryNode(QueryNodeFactory.PROPERTY_NAME__TARGET_NAME_SPACE, QueryOperator.EQUAL, "www.ibm.com/test");
    PropertyQueryNode nameNode = QueryNodeFactory.createPropertyQueryNode(QueryNodeFactory.PROPERTY_NAME__NAME, QueryOperator.LIKE, "%Christmas%");
    AndNode andNode = new AndNode(tnsNode, nameNode);
    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByProperties(andNode, 0, 0);
 

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would pass 0 for numberToSkip and 20 for maxToReturn on the first invocation. On the second, you would pass 20 and 20. On the third 40 and 20, and so on.

Parameters:
tns - The target name space string to query on. This string may contain the wildcard characters '%' and '_' as used in SQL for "like" queries. Must not be null.
tnsOp - The operator to be used in the query for the target name space property. This specifies whether, for example, the query should be an exact match query or a "like" query using wildcards. Must not be null.
name - The name string to query on. This string may contain the wildcard characters '%' and '_' as used in SQL for "like" queries. Must not be null.
nameOp - The operator to be used in the query for the name property. This specifies whether, for example, the query should be an exact match query or a "like" query using wildcards. Must not be null.
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that all rule groups are to be returned.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups that have target name spaces and names matching the specified query. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
java.lang.IllegalArgumentException - if the tnsOp, the nameOp, the tns, or the name argument is null.
See Also:
BusinessRuleGroup

getBRGsBySingleProperty

public static java.util.List<BusinessRuleGroup> getBRGsBySingleProperty(java.lang.String propertyName,
                                                                        QueryOperator op,
                                                                        java.lang.String propertyValue,
                                                                        int numberToSkip,
                                                                        int maxToReturn)
                                                                 throws BusinessRuleManagementException
Get business rule groups that have a property matching the specified parameters. This is a convenience method that allows the user to perform a query based on a single property by calling one method rather than setting up a query tree using the APIs defined in the com.ibm.wbiserver.brules.mgmt.query package. The query is performed using the specified property name, property value, and the specified operator.

For example, the following invocation:

    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsBySingleProperty("Department", QueryOperator.LIKE, "%Engineering%", 0, 0);
 
is equivalent to doing the following:
    PropertyQueryNode node = QueryNodeFactory.createPropertyQueryNode("Department", QueryOperator.LIKE, "%Engineering%");
    List<BusinessRuleGroup> result = BusinessRuleManager.getBRGsByProperties(node, 0, 0);
 

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would pass 0 for numberToSkip and 20 for maxToReturn on the first invocation. On the second, you would pass 20 and 20. On the third 40 and 20, and so on.

Parameters:
propertyName - The property name to be queried. Must not be null or the zero-length string.
op - The operator to be used in the query. This specifies whether, for example, the query should be an exact match query or a "like" query using wildcards. Must not be null.
propertyValue - The property value to query on. This string may contain the wildcard characters '%' and '_' as used in SQL for "like" queries. Must not be null.
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that all rule groups are to be returned.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups that have target name spaces matching the specified query. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
java.lang.IllegalArgumentException - if the propertyName, op, or propertyValue argument is null or if the propertyName argument is the zero-length string.
See Also:
BusinessRuleGroup

getBRGsByProperties

public static java.util.List<BusinessRuleGroup> getBRGsByProperties(QueryNode queryTree,
                                                                    int numberToSkip,
                                                                    int maxToReturn)
                                                             throws BusinessRuleManagementException
Get business rule groups that have property values that match the query specified in the given query tree.

The numberToSkip and maxToReturn parameters can be used together to implement paging where only a certain number of rule groups is returned with each invocation. This could be useful in situations where there are many rule groups and you don't want to wait for them all to be returned. For example, to get the rule groups in separate groups each containing 20 rule groups you would pass 0 for numberToSkip and 20 for maxToReturn on the first invocation. On the second, you would pass 20 and 20. On the third 40 and 20, and so on.

Parameters:
queryTree - A tree of QueryNode objects specifying the query to be performed. Must not be null.
numberToSkip - The number of business rule groups to skip. If this number is greater than 0, then the specified number of rule groups will be skipped and not returned by this invocation of the method. A negative or 0 value indicates that all rule groups are to be returned.
maxToReturn - The maximum number of business rule groups to return. If this number is greater than 0, then at most the specified number of rule groups will be returned by this invocation of the method. A negative or 0 value indicates that all rule groups will be returned starting with the first non-skipped rule group to the end of the results.
Returns:
A List of BusinessRuleGroup objects representing the business rule groups that have property values matching the specified query. If the maxToReturn parameter is greater than 0, then this list will contain at most maxToReturn rule groups.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
java.lang.IllegalArgumentException - if the queryTree argument is null.
See Also:
BusinessRuleGroup, QueryNode, QueryNodeFactory

publish

public static void publish(java.util.List<BusinessRuleGroup> updatedBusinessRuleGroups,
                           boolean publishOnlyChangedArtifacts)
                    throws BusinessRuleManagementException,
                           ChangeConflictException,
                           ValidationException
Publish the changes in the specified BusinessRuleGroup objects to persistent storage. This method checks to see if any of the changed data has been updated in persistent storage since it was retrieved. If it has, then a ChangeConflictException is thrown.

Under a given business rule group there are generally many artifacts (selection tables, rulesets, decision tables). It may be the case that only a small number of these artifacts have actually been changed. The caller may want to publish all artifacts regardless of whether or not they have changes or to publish only those artifacts that actually have changes. A flag is provided on the interface to allow the caller to specify which option is desired. Publishing only those artifacts with changes will be faster if only some artifacts have been changed. Another consideration is the fact if all artifacts are published the caller may get a ChangeConflictException on an artifact that wasn't even changed in this session because another client has changed that artifact. This may or may not be the desired behavior. The flag allows the caller to choose.

The specified business rule groups are validated before being published. If any errors are detected, a ValidationException is thrown.

The BusinessRuleGroup objects passed in, as well as any of their sub-objects, should not be changed again until after the publish method returns. Any attempt to change these objects while the publish is in progress will result in a ChangesNotAllowedException.

If a global transaction is in effect at the time this method is called, then this method will join that transaction. In other words, all database operations performed by this method will happen within the existing transaction. In this case when the method completes successfully the global transaction will still be in effect. The publish method will not commit it. This means that any rows in the database that were accessed by the publish method will remain locked until the global transaction is completed. Any errors that are detected that result in the publish method throwing an exception will cause the transaction to be marked rollback-only. If there is no global transaction in effect when this method is called, one will be started in which the database operations can be performed. It will be committed (or rolled back if there are errors) before the publish method returns. Note that this is the only method in the business rules API that will join an existing transaction. All other methods that perform database accesses will perform the work under their own sub-transaction, leaving any existing transaction unchanged. If there are any shell business rule groups in the list, these will be ignored when the publish is executed as they are read-only and can not be changed.

Parameters:
updatedBusinessRuleGroups - A List of BusinessRuleGroup objects containing changes that are to be published. Must not be null. Elements within the List must not be null.
publishOnlyChangedArtifacts - Flag indicating that only artifacts with changes should be published to persistent storage.
Throws:
BusinessRuleManagementException - if an unexpected error is detected.
ChangeConflictException - if the underlying persistent data has been changed by another client since the data was retrieved by this client.
ValidationException - if any validation errors are detected.
java.lang.IllegalArgumentException - if the updatedBusinessRuleGroups parameter is null or if any element in the updatedBusinessRuleGroups list is null.

getUOWManager

protected static com.ibm.wsspi.uow.UOWManager getUOWManager()

IBM WebSphere Application ServerTM
Release 7