BAL collections sample details

You use Rule Designer to run this sample.

Running this sample

By default, Rule Designer executes the ruleflow_correctUsage ruleflow because it is set as the main flow task.

To run the BAL collections sample using ruleflow_correctUsage:
  1. Click Run > Run Configurations.
  2. In the Run Configurations dialog, open Decision Operation and select collections-rule, and then click Run.

    The Console view displays the execution output.

To use the ruleflow_incorrectUsage, you set it as the main flow task.

To run the BAL collections sample using ruleflow_incorrectUsage:
  1. In the Rule Explorer, open the deployment folder and double-click collections-rulesOperation.
  2. Under Ruleflow, click ruleflow_correct.Usage.
  3. Select ruleflow_incorrectUsage, and click OK.
  4. Click Run > Run Configurations.
  5. In the Run Configurations dialog, open Decision Operation, select collections-rule, and then click Run.

    The Console view displays the execution output.

How this sample works

Collections are created automatically for members and method arguments that are of array type or java.util.Collection type. Although they are both treated as collections by the BAL parser, they have different characteristics and are not used in the same way.

The collection-rules project contains two rule packages that show some examples of correct and incorrect use of collections in action rules, for:
  • assigning collections
  • populating collections
  • sorting collections

The following table shows how to use BAL to assign collections.

Table 1. Assigning collections correctly
Package/Rule Use case BAL Comment
correctUsage/setCollection Assign a collection of type java.util.Collection to an array of objects. 
set 'the collection' to 'the array of items' ;
 'the collection' is a ruleset parameter of type java.util.Collection, whereas 'the array of items' is an array of Item objects.
correctUsage/setCollection Assign a collection of type java.util.Collection to a java.util.Collection object. 
set 'the collection' to a copy ( type Collections ) of 'the collection' ;
 The ruleset parameter 'the collection' is assigned to its own copy (clone) which is also of type java.util.Collection.
correctUsage/setArray Assign a collection of type array to an array of the same type of objects. 
set 'the array of items' to the items of 'the shopping cart' ;

This only works if the array is of the same type of objects.

For example, 'the array of items' is assigned to 'the shopping cart' which is an array of Item objects.

The following table shows what you cannot do to assign collections.

Table 2. Assigning collections incorrectly
Package/Rule Use case BAL Comment
incorrectUsage/setArray Assign an array to a collection of type java.util.Collection. 
set 'the array of items' to 'the collection' ;
 An array cannot be assigned to a collection.

To view the errors, remove print <string> as indicated in the rule.
incorrectUsage/setArray Use a generic method to copy an array. 
set 'the array of items' to a copy (type Array) of 'the array of items'  ;
 You cannot use a generic method to copy an array. This is because the return type of the copy method is java.lang.Object [] and the type of the ruleset parameter is com.sample.Item[].

To view the errors, remove print <string> as indicated in the rule.

The following table shows how to use BAL to populate collections.

Table 3. Populating collections correctly
Package/Rule Use case BAL Comment
correctUsage/addToCollection Populate a java.util.Collection object with elements or objects of various types. 
add the price of 'the best seller item' into 'the collection'  ;
 the price of 'the best seller item' is an integer.
correctUsage/addToCollection Populate a java.util.Collection object with elements or objects of various types. 
add 'the shopping cart' into 'the collection' ;
 'the shopping cart' is an object from the ShoppingCart class.
correctUsage/addToCollection Populate a java.util.Collection object with elements or objects of various types. 
add as single 'the array of items' into 'the collection' ;
 The return type of the asSingle method is java.lang.Object.
correctUsage/addToCollection Populate a java.util.Collection object with elements from both array and java.util.Collection objects. 
add all elements from { a new item "TV Set" with price 500 , 
a new item "DVD" with price 25 }
into 'the collection' ;
add all elements from 'basic items' into 'the collection' ;
 You can populate a java.util.Collection object with elements from both array and java.util.Collection objects.

The following table shows what you cannot do to populate collections.

Table 4. Populating collections incorrectly
Package/Rule Use case BAL Comment
incorrectUsage/addToArray Add elements to an array using the add method with a java.util.Collection argument. 
add all elements from 'the collection' into 'the array of items' ;

In collections-tools-xom/Collections.java, there is no Java™ method to add elements to an array. However, the BAL lets you construct a rule that adds elements to an array using the add method with a java.util.Collection argument.

No errors are reported in the Problems view as the BAL is used in the same way for collections and arrays. The BAL parser treats both the array and java.util.Collection types as collections. Yet, it does not work at run time as shown in the Console view. For more information about how to use ruleflow_incorrectUsage, see the Running this sample section.

The following table shows how to use BAL to sort collections.

Table 5. Sorting collections correctly
Package/Rule Use case BAL Comment
correctUsage/sortCollection Use the sort method from the java.util.Collection class to sort the collection of type java.util.Collection. 
sort 'the collection'   ;
 You have to use the sort method from the java.util.Collection class to sort the collection of type java.util.Collection.
correctUsage/sortArray Use the sort method from java.util.Arrays to sort the collection of type array. 
sort [] 'the array of items' ;
 You have to use the sort method from java.util.Arrays to sort the collection of type array.

The following table shows what you cannot do to sort collections.

Table 6. Sorting collections incorrectly
Package/Rule Use case BAL Comment
incorrectUsage/sortCollection Use the sort method from the java.util.Arrays class to sort the collection of type java.util.Collection. 
sort [] 'the collection' ;
 The collection elements is not properly sorted, as shown in the Console view. For more information about how to run the sample using ruleflow_incorrectUsage, see the Running this sample section.
incorrectUsage/sortArray Use the sort method from the java.util.Collection class to sort the collection of type array. 
sort 'the array of items' ;
 The array elements is not properly sorted, as shown in the Console view. For more information about how to run the sample using ruleflow_incorrectUsage, see the Running this sample section.
incorrectUsage/sortCollectionDiffTypes Populate a java.util.Collection object with different types of elements using the sort method. 
set 'the collection' to { the price of 'the best seller item' , 
the name of 'the best seller item' , 'the best seller item' } ;

sort 'the collection' ;
 This action rule uses price, name, item, therefore a ClassCastExeption error is raised at runtime, as shown in the Console view. For more information about how to run the sample using ruleflow_incorrectUsage, see the Running this sample section.
Parent topic: Sample: BAL collections