During the first phase, the rules engine will test the rule condition of all rules to determine which facts or combination of facts the rule conditions evaluate to true. A group of facts that together cause a given rule condition to evaluate to true, is known as a fact set row, with a fact set being a collection of all fact set rows that evaluate to true for a given rule.

In many ways it's similar to the concept of executing the rule condition as a query over the facts in working memory, with every row returned by the query equivalent to a fact set row, and the entire result set being equivalent to the fact set.

For each fact set row, the rules engine will activate the rule. This involves adding each fact set row with a reference to the corresponding rule to the agenda of rules which need to be fired. At this point, the action block of any rule has not been executed.

When rule activations are placed on the rule agenda, they are ordered based on the priority of the rule, with those rules with a higher priority placed at the top of the agenda.

When there are multiple activations with the same priority, the most recently added activation is the next rule to fire. However, it's quite common for multiple activations to be added to the ruleset at the same time; the ordering of these activations is not specified.

Once all rule conditions have been evaluated, then the rule engine will start to process the agenda. It will take the rule activation at the top of the agenda and execute the action block for the fact set row and the corresponding rule.

During executing of the action block, the rule may assert new facts, assert updated facts, or retract exiting facts from the working memory. As the rule engine does this, it may cause existing activations to be removed from the agenda, or may add new activations to the agenda.

When an activation is added to the agenda, it will be inserted into the agenda based on the priority of the rule. If there are already previous activations on the agenda with the same priority, the new activation will be inserted in front of these activations. This means that the set of new activations will be processed before any of the older activations with the same priority, but after any activation with a higher priority.

Once the rule engine has completed the execution of the action block for an activation, it will take the next activation from the agenda and process that. Once all activations on the agenda have been processed then the rule engine has completed execution of the ruleset.

Even with the above logging information, it can be useful to produce more fine grain logging within your ruleset. You can do this using the DM.println function within your ruleset.

This function can be used either within your own functions or called as part of the action block for a rule. Again to enable these statements to be written to the BPEL domain log, you need to set the logger default.collaxa.cube.services to debug.

So we need to define a second pattern that checks to see if no other bids exist (with a status of NEW) with an earlier bid time; in other words we have to check for the non-existence of a fact.

We do this by defining a pattern of type There is no case which will fire once if there are no matches, that is, no earlier bids. So our extended rule condition is implemented as follows:

nextBid is a TBid and
nextBid.status == "NEW"
There is no case where anotherBid is a TBid and
anotherBid.status == "NEW" &&
anotherBid.bidtime.before(nextBid.bidtime)

This condition works as follows; the first test will select all the bids with a status of NEW. For each bid selected it will execute the second test where it will select all other bids with a status of new and an earlier bid time; if no bids are selected then this test will evaluate to true and the rule will be activated and placed on the agenda.

When the activation is placed on the agenda, only the fact referenced by nextBid is included in the fact row set, because for the rule condition to be true, anotherBid won't actually reference any other bid.

You may have noted that the property bidtime, which is defined within our schema as xsd:datetime maps to a java.util.Calendar. When comparing properties of type Calendar within a rule, we can't use the standard operators (such as >, >=, <= and <) to do this.

Rather we need to use the appropriate methods (for example before, after) provided by the Calendar class. Now we could write our own functions that wrap these methods calls, or alternatively as we have done above invoke them directly within our rules.

In order to do this, we first need to import the java.util.Calendar class as a Java fact within our dictionary. Once we have done this, the rule editor won't expose the methods. Rather we need to specify that our test is an Advanced Test and manually enter the code.

Once we have located the next bid, we need to set its status to NEXT and re-assert it; we do this with the following statements in our action block.

Assign nextBid.status = "NEXT"
Assert nextBid

An interesting side effect is that as soon as we assert our modified bid, the rule engine will re-apply the test condition and potentially find another bid with a status of "NEW", that is, the next bid to be processed after this one.

On finding this bid, it will place a new activation on the agenda for this rule referencing this new bid. To prevent this rule from firing before any of the rules which process bids with a status of "NEXT", we have set the priority of this rule to 0.

So the complete rule to get the next bid is defined as follows:

Using inference we can now write our rules to process the next bid on the basis that we already know which bid is next and that the bid is valid. Using this approach, the rule condition for the first scenario where the next bid is higher than the current winning bid, would be specified as:

nextBid is a TBid and
nextBid.status == "NEXT"
winningBid is a TBid and
winningBid.status == "WINNING" &&
winningBid.maxAmount < nextBid.maxAmount

This, as we can see, is considerably simpler than the previous example.

If this evaluates to true for our next bid, then we have a new winning bid and need to take the appropriate actions to update the affected facts as well as the result set.

The first action we need to take is to calculate the actual winning amount by adding one bidding increment to the maximum amount of the losing bid. So the first statement in our rules action block is as follows:

Assign nextBid.bidAmount = winningBid.maxAmount +
getBidIncrement (winningBid.maxAmount)

Where DM.getBidIncrement is a function that calculates the next bid increment, based on the size of the current winning amount.

Next, we need to update its status to WINNING and re-assert the bid in order that it will be re-evaluated as a winning bid by our ruleset.

In addition, we need to update the status of our previous winning bid to OUTBID and retract, if from the rule space, as we no longer need to evaluate it.

To record details of a new winning bid in the result set, we have defined the function DM.assertWinningBid, which takes a single parameter bid of type TBid, used to pass in a reference to the winning bid. The code for this function is as follows:

// Update Status of Winning Bid

bid.setStatus("WINNING");
assert(bid);
 // Update result set with details of Winning Bid

varAuctionItem.setWinningPrice(bid.getBidAmount());
com.packtpub.schema.obay.auction.TBid winningBid = varAuctionItem.getWinningBid();
// Create Winning Bid if one doesn't exist
if (winningBid == null)
{
com.packtpub.schema.obay.auc.ObjectFactory of =
new com.packtpub.schema.obay.auc.ObjectFactory();
winningBid = of.createTBid();
varAuctionItem.setWinningBid(winningBid);
}
winningBid.setBidAmount(bid.getBidAmount());
winningBid.setBidderId(bid.getBidderId());
winningBid.setBidId(bid.getBidId());
winningBid.setBidtime(bid.getBidtime());
winningBid.setMaxAmount(bid.getMaxAmount());
winningBid.setStatus(bid.getStatus());

Looking at this, we can see it breaks into two parts. The first part updates the status of the winning bid to 'WINNING', and asserts the bid. Now, we didn't need to include this functionality within the function, we could have achieved the same result within the rule itself be defining the following actions:

Assign nextBid.status = "WINNING"
Assert nextBid

We need to process a winning bid in multiple rules; including this in the function both simplifies our rules and ensures that we handle winning bids in a consistent way. Either approach is valid; it just comes down to personal preference.

However, to indicate to callers of the function that we are asserting the winning bid in the function, we have prefixed the name of the function with 'assert'.

The second part of the function is used to update the result set with details of the winning bid. The first line updates the element winningPrice to contain the bid amount of the winning bid.

The next set of code is more interesting. First it calls the method getWinningbid() on the result set to get a reference to the winning bid element. This may return null, as the AuctionItem may not currently have a winning bid (that is, if this is the first winning bid).

To create any new XML elements we need an appropriate ObjectFactory, so we create a new instance of one with the following line of code:

com.packtpub.schema.obay.auc.ObjectFactory of =
new com.packtpub.schema.obay.auc.ObjectFactory();

Next we use the ObjectFactory to create a new element of type TBid as follows:

winningBid = of.createTBid();

Finally we update the winning bid element in AuctionItem to point to this newly created element as follows:

varAuctionItem.setWinningBid(winningBid);

Once we've done this we update the details of the winningBid element with those of the bid element.

The final thing to note is that we are not asserting varAuctionItem or any of the elements we have added to it. Hence, none of these changes will be visible to our ruleset, which is exactly what we want. This is because we are using the result set as a place to build up the result of executing our ruleset and thus don't want it included in the evaluation.

To record details of a losing bid in the result set, we have followed a similar approach and defined the function DM.retractLosingBid, which takes a single parameter bid of type TBid. The code for the function is as follows:

// Update Status of Losing Bid
bid.setStatus("OUTBID");
bid.setBidAmount(bid.getMaxAmount());
retract(bid);
// Record Details of Bid in Result Set
com.packtpub.schema.obay.auc.TBid losingBid = DM.cloneTBid(bid);
java.util.List bidHistory = varAuctionItem.getBidHistory().getBid();
if (bidHistory.isEmpty()) {
bidHistory.add(losingBid);
}
else {
bidHistory.add(0,losingBid);
}

Looking at this, we can see that, as with the previous function, it breaks into two parts. The first part updates the status of the losing bid and then retracts it. The second part of the function is used to record details of losing bid within the bidHistory element of our result set.

The first line of this part calls the function DM.cloneTBid to create a new element of type TBid and initialize it with the values of the losing bid using a approach similar to the one previously used to create a new winning bid element.

Once we've done that, we then add it to the bidHistory element. The bid history itself is a collection of bid elements. JAXB implements this as a java.util.List, the method getBid returns a reference to this list.

The final part of the function inserts the losing bid at the start of this list, so that the bid history contains the most recently processed bid at the start of the list.

With our functions defined, we can finish the implementation of the rule for a new winning bid, which is shown in the following screenshot:

Due to the use of inference to simplify the rule condition and the use of functions to manipulate the result set, the final rule is very straightforward.

The only thing we need to take into account is the priority of the rule, which we have set to 50. This is to ensure that the validation rules for a bid have a higher priority so that they are fired first.

For the above rule to be complete we need to define the rules which validate the next bid before we process it; the two conditions that we need to check are:

To validate that max bid amount is greater than or equal to the auction starting price, we have defined the following rule:

The function retractInvalidBid is almost identical to the function retractLosingBid, the only difference being that it sets the status of the bid to 'INVALID'.

We have also defined a similar rule, validateBidAgainstWinningPrice to validate that the max bid amount is greater than the current winning amount plus one bidding increment.

Each of these rules has a priority of 80, which is higher than the rules for processing the next bid. This ensures that any invalid bids are retracted before they can be processed.

The rules to handle the other potential outcomes for the next bid, namely where it's our first bid, and thus by default a winning bid or a losing bid, are straightforward, apart for one exception. The rule for the scenario where the next bid is a losing bid is shown here:

If we look at the first action that sets the bid amount of the winning bid equal to the maximum amount of the losing bid plus the next bid increment, there is a possibility that this could cause the bid amount to exceed the maximum amount specified.

For example if the maximum bid was $10, with the current winning amount being $5, then it would be valid for the next bid to be $10. This bid would fail but the new winning amount according to the above would be $10.50.

Capping the winning bid amount

To prevent this from happening we need to write another rule to test if the winning amount of the bid is greater than its maximum amount and if it is then set the winning amount equal to the maximum amount. The rule for this is shown in the following screenshot:

The rule itself is straightforward. But as this rule is being used to correct an inconsistent state we have given it a priority of 90 so that it is fired even before the validation rules.

One alternative is to use the BPEL process to hold the state of the rule session. With this technique we need to ensure that all relevant facts contained within the rule session are returned within the facts that the decision service is watching.

Next time we invoke the decision service, we can re-submit these facts (along with any new facts to be evaluated) and re-assert them back into a new rule session.

In the case of our Auction ruleset, the relevant facts that need to be maintained between invocations are auctionItem and winningBid which is contained within auctionItem.

With this approach, each time we receive a new bid we just need to assert the auctionItem element as returned by the previous invocation of the ruleset and the new bid (within the bids element). As a result, each time we submit a new bid, rather than re-evaluate all bids to determine the winning bid, we just need to evaluate the new bid against the winning bid, which is clearly more efficient.

To support this, we do not have to make any modifications to our ruleset, because we have implemented it in such a way that it supports either asserting all bids in one go or submitting them incrementally.

The only remaining drawback with this approach is that the ruleset will still assert all bid objects contained within the bidHistory element of auctionItem into working memory. While this won't change the outcome, it still means all these bids will be evaluated in the process of firing the rules, though none of them will cause an activation to happen.

Where we have only a relatively small number of facts this doesn't really cause a problem, but if the number of facts is in the high hundreds or order of 1000s, then this may make a noticeable difference.