Bags

To explain Bags, lets use a small example. Let's consider a Business Object called "account" that has a child business object called "owner." An account can have one or more owners.

For each owner, there is a field called "percent" that represents the ownership percentage of the account attributed to that owner. Additionally, we want each owner to have a target object with an "accumulated" field that keeps track of the cumulative ownership percentage.

For example, suppose we have an account with four owners, each having a 25% ownership. In this case, the "accumulated" field for the first owner would be 25, for the second owner would be 50, for the third owner would be 75, and for the last owner would be 100.

We also want an Exit Rule to verify that the sum of ownership percentages adds up to exactly 100%. This can be achieved using Rules. As we have seen in previous examples, a rule has access to the interface and its fields.

Implementing this check in an Exit Rule would involve summing up all the ownership percentages and verifying if it reaches 100%. Similarly, a mapping rule can access the target object, allowing us to refer to previously created target objects and calculate the cumulative percentage.

However, using Rules alone can be a bit cumbersome. This is where Bags come in. Bags are like rules on steroids. They can hold state, both internal state for their own purposes and exposed state as properties that can be used as values elsewhere in the mapping.

The state in a Bag is reset each time we start processing a new group business object. Additionally, Bags can have methods. You can define as many methods as you need, and each method closely resembles a rule in terms of its signature, parameters, return value, and ability to raise flags.

In fact, these Bag methods can be used anywhere in the mapping where rules can be used. Returning to our sample, let's say we have a property called "accumulated" in the Bag. We also define a method called "Accumulate" and another method called "Check."

The "accumulated" property holds the cumulative ownership percentage, the "Accumulate" method adds to this property, and the "Check" method verifies if the percentage reaches 100%.

In this case, as an Entry Rule on the owner, we can directly call the "Accumulate" method. So when we start processing each owner, we invoke the method and pass the percentage as a parameter. The method can then simply accumulate the percentage in the property.

When we reach the target field, instead of using a mapping rule, we can directly assign the value of this property as the target field's value.

Finally, when we reach the end of the account, we can call the "Check" method as an exit rule, without needing to pass any parameters. The "Check" method can read the "accumulated" property and verify if it equals 100%. If not, it can raise a flag that can be handled in the mapping.

That's it! Bags are rules on steroids, offering more flexibility and functionality in handling complex mappings.

This article is also the topic of this video: