JBoss AS 5 Performance TuningJBoss AS 5 Performance Tuning will teach you how to deliver fast applications on the JBoss Application Server and Apache Tomcat, giving you a decisive competitive advantage over your competitors. You will learn how to optimize hardware resources, meeting your application requirements with less expenditure.

also read:

• WebLogic Interview Questions
• JBoss Portal Server Development
• Tomcat Interview Questions

The performance of Java Enterprise applications is the sum of a set of components including the Java Virtual Machine configuration, the application server configuration (in our case,JBoss AS), the application code itself, and ultimately the operating system. This book will show you how to apply the correct tuning methodology and use the tuning tools that will help you to monitor and address any performance issues.

By looking more closely at the Java Virtual Machine, you will get a deeper understanding of what the available options are for your applications, and how their performance will be affected. Learn about thread pool tuning, EJB tuning, and JMS tuning, which are crucial parts of enterprise applications.

The persistence layer and the JBoss Clustering service are two of the most crucial elements which need to be configured correctly in order to run a fast application. These aspects are covered in detail with a chapter dedicated to each of them.

Finally, Web server tuning is the last (but not least) topic covered, which shows how to configure and develop web applications that get the most out of the embedded Tomcat web server.

What This Book Covers

Chapter 1, Performance Tuning Concepts, discusses correct tuning methodology and how it fits in the overall software development cycle.

Chapter 2, Installing the Tools for Tuning, shows how to install and configure the instruments for tuning, including VisualVM, JMeter, Eclipse TPTP Platform, and basic OS tools.

Chapter 3, Tuning the Java Virtual Machine, provides an in-depth analysis of the JVM heap and garbage collector parameters, which are used to start up the application server.

Chapter 4, Tuning the JBoss AS, discusses the application server’s core services including the JBoss System Thread Pool, the Connection Pool, and the Logging Service.

Chapter 5, Tuning the Middleware Services, covers the tuning of middleware services including the EJB and JMS services.

Chapter 6, Tuning the Persistence Layer, introduces the principles of good database design and the core concepts of Java Persistence API with special focus on JBoss‘s implementation (Hibernate).

Chapter 7, JBoss AS Cluster Tuning, covers JBoss Clustering service covering the lowlevel details of server communication and how to use JBoss Cache for optimal data replication and caching.

Chapter 8, Tomcat Web Server Tuning, covers the JBoss Web server performance tuning including mod_jk, mod_proxy, and mod_cluster modules.

Chapter 9, Tuning Web Applications on JBoss AS, discusses developing fast web applications using JSF API and JBoss richfaces libraries.

JBoss AS Cluster Tuning

6th Circle of Hell: Heresy. This circle houses administrators who accurately set up
a cluster to use Buddy Replication. Without caring about steady sessions.

Clustering allows us to run applications on several parallel instances (also known as cluster nodes). The load is distributed across different servers, and even if any of the servers fails, the application is still accessible via other cluster nodes. Clustering is crucial for scalable Enterprise applications, as you can improve performance by simply adding more nodes to the cluster.
In this chapter, we will cover the basic building blocks of JBoss Clustering with the following schedule:

• A short introduction to JBoss Clustering platform

• In the next section we will cover the low level details of the JGroups library, which is used for all clustering-related communications between nodes

• In the third section we will discuss JBoss Cache, which provides distributed cache and state replication services for the JBoss cluster on top of the JGroups library

Introduction to JBoss clustering

Clustering plays an important role in Enterprise applications as it lets you split the load of your application across several nodes, granting robustness to your applications. As we discussed earlier, for optimal results it’s better to limit the size of your JVM to a maximum of 2-2.5GB, otherwise the dynamics of the garbage collector will decrease your application’s performance.

Combining relatively smaller Java heaps with a solid clustering configuration can lead to a better, scalable configuration plus significant hardware savings.

The only drawback to scaling out your applications is an increased complexity in the programming model, which needs to be correctly understood by aspiring architects.

JBoss AS comes out of the box with clustering support. There is no all-in-one library that deals with clustering but rather a set of libraries, which cover different kinds of aspects. The following picture shows how these libraries are arranged:

The backbone of JBoss Clustering is the JGroups library, which provides the communication between members of the cluster. Built upon JGroups we meet two building blocks, the JBoss Cache framework and the HAPartition service. JBoss Cache handles the consistency of your application across the cluster by means of a replicated and transactional cache.

On the other hand, HAPartition is an abstraction built on top of a JGroups Channel that provides support for making and receiving RPC invocations from one or more cluster members. For example HA-JNDI (High Availability JNDI) or HA Singleton (High Availability Singleton) both use HAPartition to share a single Channel and multiplex RPC invocations over it, eliminating the configuration complexity and runtime overhead of having each service create its own Channel. (If you need more information about the HAPartition service you can consult the JBoss AS documentation http://community.jboss.org/wiki/jBossAS5ClusteringGuide.). In the next section we will learn more about the JGroups library and how to configure it to reach the best performance for clustering communication.

Configuring JGroups transport

Clustering requires communication between nodes to synchronize the state of running applications or to notify changes in the cluster definition. JGroups (http://jgroups.org/manual/html/index.html) is a reliable group communication toolkit written entirely in Java. It is based on IP multicast, but extends by providing reliability and group membership.

Member processes of a group can be located on the same host, within the same Local Area Network (LAN), or across a Wide Area Network (WAN). A member can be in turn part of multiple groups. The following picture illustrates a detailed view of JGroups architecture:

A JGroups process consists basically of three parts, namely the Channel, Building blocks, and the Protocol stack. The Channel is a simple socket-like interface used by application programmers to build reliable group communication applications. Building blocks are an abstraction interface layered on top of Channels, which can be used instead of Channels whenever a higher-level interface is required. Finally we have the Protocol stack, which implements the properties specified for a given channel.

In theory, you could configure every service to bind to a
different Channel. However this would require a complex thread
infrastructure with too many thread context switches. For this
reason, JBoss AS is configured by default to use a single Channel
to multiplex all the traffic across the cluster.

The Protocol stack contains a number of layers in a bi-directional list. All messages sent and received over the channel have to pass through all protocols. Every layer may modify, reorder, pass or drop a message, or add a header to a message. A fragmentation layer might break up a message into several smaller messages, adding a header with an ID to each fragment, and re-assemble the fragments on the receiver’s side.

The composition of the Protocol stack (that is, its layers) is determined by the creator of the channel: an XML file defines the layers to be used (and the parameters for each layer).

Knowledge about the Protocol stack is not necessary when
just using Channels in an application. However, when an
application wishes to ignore the default properties for a Protocol
stack, and configure their own stack, then knowledge about what
the individual layers are supposed to do is needed.

In JBoss AS, the configuration of the Protocol stack is located in the file, \deploy\cluster\jgroups-channelfactory.sar\META-INF\jgroupschannelfactory-stacks.xml.

The file is quite large to fit here, however, in a nutshell, it contains the following basic elements:

The first part of the file includes the UDP transport configuration. UDP is thedefault protocol for JGroups and uses multicast (or, if not available, multiple unicast messages) to send and receive messages.

A multicast UDP socket can send and receive datagrams from multiple
clients. The interesting and useful feature of multicast is that a client
can contact multiple servers with a single packet, without knowing the
specific IP address of any of the hosts.

Next to the UDP transport configuration, three protocol stacks are defined:

• udp: The default IP multicast based stack, with flow control

• udp-async: The protocol stack optimized for high-volume asynchronous RPCs

• udp-sync: The stack optimized for low-volume synchronous RPCs

Thereafter, the TCP transport configuration is defined . TCP stacks are typically used when IP multicasting cannot be used in a network (for example, because it is disabled) or because you want to create a network over a WAN (that’s conceivably possible but sharing data across remote geographical sites is a scary option from the performance point of view).

You can opt for two TCP protocol stacks:

• tcp: Addresses the default TCP Protocol stack which is best suited to high-volume asynchronous calls.

• tcp-async: Addresses the TCP Protocol stack which can be used for low-volume synchronous calls.

If you need to switch to TCP stack, you can simply include the following
in your command line args that you pass to JBoss:
-Djboss.default.jgroups.stack=tcp
Since you are not using multicast in your TCP communication, this
requires configuring the addresses/ports of all the possible nodes in the
cluster. You can do this by using the property -Djgroups.tcpping.
initial_hosts. For example:
-Djgroups.tcpping.initial_hosts=host1[7600],host2[7600]

Ultimately, the configuration file contains two stacks which can be used for optimising JBoss Messaging Control Channel (jbm-control) and Data Channel (jbm-data).

How to optimize the UDP transport configuration

The default UDP transport configuration ships with a list of attributes, which can be tweaked once you know what they are for. A complete reference to the UDP transport configuration can be found on the JBoss clustering guide (http://docs. jboss.org/jbossclustering/cluster_guide/5.1/html/jgroups.chapt. html); for the purpose of our book we will point out which are the most interesting ones for fine-tuning your transport. Here’s the core section of the UDP transport configuration:

The biggest performance hit can be achieved by properly tuning the attributes concerning buffer size (ucast_recv_buf_size, ucast_send_buf_size, mcast_recv_buf_size, and mcast_send_buf_size ).
[code lang=”java”] <UDP
singleton_name="shared-udp"
mcast_port="${jboss.jgroups.udp.mcast_port:45688}"
mcast_addr="${jboss.partition.udpGroup:228.11.11.11}"
tos="8"
ucast_recv_buf_size="20000000"
ucast_send_buf_size="640000"
mcast_recv_buf_size="25000000"
mcast_send_buf_size="640000"
loopback="true"
discard_incompatible_packets="true"
enable_bundling="false"
max_bundle_size="64000"
max_bundle_timeout="30"
. . . .
/>
[/code]
As a matter of fact, in order to guarantee optimal performance and adequate reliability of UDP multicast, it is essential to size network buffers correctly. Using inappropriate network buffers the chances are that you will experience a high frequency of UDP packets being dropped in the network layers, which therefore need to be retransmitted.

The default values for JGroups’ UDP transmission are 20MB and 64KB for unicast transmission and respectively 25MB and 64KB for multicast transmission. While these values sound appropriate for most cases, they can be insufficient for applications sending lots of cluster messages. Think about an application sending a thousand 1KB messages: with the default receive size, we will not be able to buffer all packets, thus increasing the chance of packet loss and costly retransmission.

Monitoring the intra-clustering traffic can be done through the jboss.jgroups domain Mbeans. For example, in order to monitor the amount of bytes sent and received with the UDP transmission protocol, just open your jmx-console and point at the jboss.jgroups domain. Then select your cluster partition. (Default the partition if you are running with default cluster settings). In the following snapshot (we are including only the relevant properties) we can see the amount of Messages sent/received along with their size (in bytes).

Besides increasing the JGroups’ buffer size, another important aspect to consider is that most operating systems allow a maximum UDP buffer size, which is generally ower than JGroups’ defaults. For completeness, we include here a list of default maximum UDP buffer size:

So, as a rule of thumb, you should always configure your operating system to take advantage of the JGroups’ transport configuration. The following table shows the command required to increase the maximum buffer to 25 megabytes. You will need root privileges in order to modify these kernel parameters:

Another option that is worth trying is enable_bundling, which specifies whether to enable message bundling. If true, the transport protocol would queue outgoing messages until max_bundle_size bytes have accumulated, or max_bundle_time milliseconds have elapsed, whichever occurs first.

The advantage of using this approach is that the transport protocol would send bundled queued messages in one single larger message. Message bundling can have significant performance benefits for channels using asynchronous high volume messages (for example, JBoss Cache components configured for REPL_ASYNC. JBoss Cache will be covered in the next section named Tuning JBoss Cache).

On the other hand, for applications based on a synchronous exchange of RCPs, the introduction of message bundling would introduce a considerable latency so it is not recommended in this case. (That’s the case with JBoss Cache components configured as REPL_SYNC).

How to optimize the JGroups’ Protocol stack

The Protocol stack contains a list of layers protocols, which need to be crossed by the message. A layer does not necessarily correspond to a transport protocol: for example a layer might take care to fragment the message or to assemble it. What’s important to understand is that when a message is sent, it travels down in the stack, while when it’s received it walks just the way back.

For example, in the next picture, the FLUSH protocol would be executed first, then the STATE, the GMS, and so on. Vice versa, when the message is received, it would meet the PING protocol first, them MERGE2, up to FLUSH.

Following here, is the list of protocols triggered by the default UDP’s Protocol stack.
[code lang=”xml”]<stack name="udp"
description="Default: IP multicast based stack, with flow
control.">
<config>
<PING timeout="2000" num_initial_members="3"/>
<MERGE2 max_interval="100000" min_interval="20000"/>
<FD_SOCK/>
<FD timeout="6000" max_tries="5" shun="true"/>
<VERIFY_SUSPECT timeout="1500"/>
<pbcast.NAKACK use_mcast_xmit="false" gc_lag="0"
retransmit_timeout="300,600,1200,2400,4800"
discard_delivered_msgs="true"/>
<UNICAST timeout="300,600,1200,2400,3600"/>
<pbcast.STABLE stability_delay="1000"
desired_avg_gossip="50000"
max_bytes="400000"/>
<pbcast.GMS print_local_addr="true" join_timeout="3000"
shun="true"
view_bundling="true"
view_ack_collection_timeout="5000"/>
<FC max_credits="2000000" min_threshold="0.10"
ignore_synchronous_response="true"/>
<FRAG2 frag_size="60000"/>
<pbcast.STATE_TRANSFER/>
<pbcast.FLUSH timeout="0"/>
</config>
</stack>[/code]
The following table will shed some light on the above cryptic configuration:

While all the above protocols play a role in message exchanging, it’s not necessary that you know the inner details of all of them for tuning your applications. So we will focus just on a few interesting ones.

The FC protocol, for example can be used to adapt the rate of messages sent with the rate of messages received. This has the advantage of creating an homogeneous rate of exchange, where no sender member overwhelms receiver nodes, thus preventing potential problems like filling up buffers causing packet loss. Here’s an example of FC configuration:
[code lang=”xml”] <FC max_credits="2000000"
min_threshold="0.10"
ignore_synchronous_response="true"/>[/code]
The message rate adaptation is done with a simple credit system in which each time a sender sends a message a credit is subtracted (equal to the amount of bytes sent). Conversely, when a receiver collects a message, a credit is added.

• max_credits specifies the maximum number of credits (in bytes) and should obviously be smaller than the JVM heap size

• min_threshold specifies the value of min_credits as a percentage of the max_credits element

• ignore_synchronous_response specifies whether threads that have carried messages up to the application should be allowed to carry outgoing messages back down through FC without blocking for credits

The following image depicts a simple scenario where HostA is sending messages (and thus its max_credits is reduced) to HostB and HostC, which increase their max_credits accordingly.

The FC protocol, while providing a control over the flow of messages, can be a bad choice for applications that are issuing synchronous group RPC calls. In this kind of applications, if you have fast senders issuing messages, but some slow receivers across the cluster, the overall rate of calls will be slowed down. For this reason, remove FD from your protocol list if you are sending synchronous messages or just switch to the udpsync protocol stack.

Besides JGroups, some network interface cards (NICs) and switches
perform ethernet flow control (IEEE 802.3x), which causes overhead
to senders when packet loss occurs. In order to avoid a redundant flow
control, you are advised to remove ethernet flow control. For managed
switches, you can usually achieve this via a web or Telnet/SSH interface.
For unmanaged switches, unfortunately the only chance is to hope that
ethernet flow control is disabled, or to replace the switch.
If you are using NICs, you can disable ethernet flow control by means of
a simple shell command, for example, on Linux with the ethtool:
/sbin/ethtool -A eth0 autoneg off tx on rx on
If you want simply to verify if ethernet flow control is off:
/sbin/ethtool -a eth0

One more thing you must be aware of is that, by using JGroups, cluster nodes must store all messages received for potential retransmission in case of a failure. However, if we store all messages forever, we will run out of memory. The distributed garbage collection service in JGroups periodically removes messages that have been seen by all nodes from the memory in each node. The distributed garbage collection service is configured in the pbcast.STABLE sub-element like so:
[code lang=”xml”] <pbcast.STABLE stability_delay="1000"
desired_avg_gossip="5000"
max_bytes="400000"/>
[/code]
The configurable attributes are as follows:

• desired_avg_gossip: Specifies the interval (in milliseconds) between garbage collection runs. Setting this parameter to 0 disables this service.

• max_bytes: Specifies the maximum number of bytes to receive before triggering a garbage collection run. Setting this parameter to 0 disables this service.

You are advised to set a max_bytes value if you have a high-traffic cluster.

Tuning JBoss Cache

JBoss Cache provides the foundation for many clustered services, which need to synchronize application state information across the set of nodes.

The cache is organized as a tree, with a single root. Each node in the tree essentially contains a map, which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that they implement java.io.Serializable.

 Actually EJB 3 Stateful Session Beans, HttpSessions, and Entity/Hibernate rely on JBoss Cache to replicate information across the cluster. We have discussed thoroughly data persistence in Chapter 6, Tuning the Persistence Layer, so we will focus in the next sections on SFSB and HttpSession cluster tuning.

The core configuration of JBoss Cache is contained in the JBoss Cache Service. In JBoss AS 5, the scattered cache deployments have been replaced with a new CacheManager service, deployed via the /deploy/cluster/jbosscache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml.

The CacheManager acts as a factory for creating caches and as a registry for JBoss Cache instances. It is configured with a set of named JBoss Cache configurations. Here’s a fragment of the standard SFSB cache configuration:
[code lang=”xml”] <b><entry><key>sfsb-cache</key></b>
<value>
<bean name="StandardSFSBCacheConfig"
class="org.jboss.cache.config.Configuration">
<property
name="clusterName">${jboss.partition.name:DefaultPartition}-
SFSBCache</property>
<property
name="multiplexerStack">${jboss.default.jgroups.stack:udp}</property>
<property name="fetchInMemoryState">true</property>
<property name="nodeLockingScheme">PESSIMISTIC</property>
<property name="isolationLevel">REPEATABLE_READ</property>
<property name="useLockStriping">false</property>
<property name="cacheMode">REPL_SYNC</property>
. . . . .
</bean>
</value>
</entry>
[/code]
Services that need a cache ask the CacheManager for the cache by name, which is specified by the key element; the cache manager creates the cache (if not already created) and returns it.

The simplest way to reference a custom cache is by means of the org.jboss.ejb3. annotation.CacheConfig annotation. For example, supposing you were to use a newly created Stateful Session Bean cache named custom_sfsb_cache:
[code lang=”java”] @Stateful
@Clustered
@CacheConfig(name="custom_sfsb_cache")
public Class SFSBExample {
}
[/code]
The CacheManager keeps a reference to each cache it has created, so all services that request the same cache configuration name will share the same cache. When a service is done with the cache, it releases it to the CacheManager. The CacheManager keeps track of how many services are using each cache, and will stop and destroy the cache when all services have released it.

Understanding JBoss Cache configuration

In order to tune your JBoss Cache, it’s essential to learn some key properties. In particular we need to understand

• • How data can be transmitted between its members. This is controlled by the cacheMode property.
• How the cache handles concurrency on data between cluster nodes. This is handled by nodeLockingScheme and isolationLevel configuration attributes.

Configuring cacheMode

The cacheMode property determines how JBoss Cache keeps in sync data across all nodes. Actually it can be split in two important aspects: how to notify changes across the cluster and how other nodes accommodate these changes on the local data.

As far data notification is concerned, there are the following choices:

• Synchronous means the cache instance sends a notification message to other nodes and before returning waits for them to acknowledge that they have applied the same changes. Waiting for acknowledgement from all nodes adds delay. However, if a synchronous replication returns successfully, the caller knows for sure that all modifications have been applied to all cache instances.

• Asynchronous means the cache instance sends a notification message andthen immediately returns, without any acknowledgement that changes have been applied. The Asynchronous mode is most useful for cases like session replication (for example, Stateful Session Beans), where the cache sending data expects to be the only one that accesses the data. Asynchronous messaging adds a small potential risk that a fail over to another node may generate stale data, however, for many session-type applications this risk is acceptable given the major performance benefits gained.

• Local means the cache instance doesn’t send a message at all. You should use this mode when you are running JBoss Cache as a single instance, so that it won’t attempt to replicate anything. For example, JPA/Hibernate Query Cache uses a local cache to invalidate stale query result sets from the second level cache, so that JBoss Cache doesn’t need to send messages around the cluster for a query result set cache.

As far as the second aspect is concerned (what should the other caches in the cluster do to refl ect the change) you can distinguish between:

Replication: means that the cache replicates cached data across all cluster nodes. This means the sending node needs to include the changed state, increasing the cost of the message. Replication is necessary if the other nodes have no other way to obtain the state.

Invalidation means that you do not wish to replicate cached data but simply inform other caches in a cluster that data under specific addresses are now stale and should be evicted from memory. Invalidation reduces the cost of the cluster update messages, since only the cache key of the changed state needs to be transmitted, not the state itself.

By combining these two aspects we have a combination of five valid values for the cacheMode configuration attribute:

Should I use invalidation for session data?
No, you shouldn’t. As a matter of fact, data invalidation it is an
excellent option for a clustered JPA/Hibernate Entity cache,
since the cached state can be re-read from the database in case
of failure. If you use the invalidation option, with SFSBs or
HttpSession, then you lose failover capabilities. If this matches
with your project requirements, you could achieve better
performance by simply turning off the cache.

Configuring cache concurrency

JBoss Cache is a thread-safe caching API, and uses its own efficient mechanisms of controlling concurrent access. Concurrency is configured via the nodeLockingScheme and isolationLevel configuration attributes.

There are three choices for nodeLockingScheme:

• Pessimistic locking involves threads/transactions acquiring locks on nodes before reading or writing. Which is acquired depends on the isolationLevel but in most cases a non-exclusive lock is acquired for a read and an exclusive lock is acquired for a write. Pessimistic locking requires a considerable overhead and allows lesser concurrency, since reader
  threads must block until a write has completed and released its exclusive lock (potentially a long time if the write is part of a transaction). The drawbacks include the potential for deadlocks, which are ultimately solved by a TimeoutException.
• Optimistic locking seeks to improve upon the concurrency available with Pessimistic by creating a workspace for each request/transaction that accesses the cache. All data is versioned; on completion of non-transactional requests or commits of transactions the version of data in the workspace is compared to the main cache, and an exception is raised if there are inconsistencies. This eliminates the cost of reader locks but, because of the cost associated with the parallel workspace, it carries a high memory overhead and low scalability.
• MVCC is the new locking schema that has been introduced in JBoss Cache 3.x (and packed with JBoss AS 5.x). In a nutshell, MVCC reduces the cost of slow, and synchronization-heavy schemas with a multi-versioned concurrency control, which is a locking scheme commonly used by modern database implementations to control concurrent access to shared data.

The most important features of MVCC are:

1. Readers don’t acquire any locks.
2. Only one additional version is maintained for shared state, for a single writer.
3. All writes happen sequentially, to provide fail-fast semantics.

How does MVCC can achieve this?

For each reader thread, the MVCC’s interceptors wraps state in a lightweight container object, which is placed in the thread’s InvocationContext (or TransactionContext if running in a transaction). All subsequent operations on the state are carried out on the container object using Java references, which allow repeatable read semantics even if the actual state changes simultaneously.

Writer threads, on the other hand, need to acquire a lock before any writing can start. Currently, lock striping is used to improve the memory performance of the cache, and the size of the shared lock pool can be tuned using the concurrencyLevel attribute of the locking element.

After acquiring an exclusive lock on a cache Full Qualified Name, the writer thread then wraps the state to be modified in a container as well, just like with reader threads, and then copies this state for writing. When copying, a reference to the original version is still maintained in the container (for rollbacks). Changes are then made to the copy and the copy is finally written to the data structure
when the write completes.

Should I use MVCC with session data too?
While MVCC is the default and recommended choice for JPA/Hibernate
Entity caching, as far as Session caching is concerned, Pessimistic is still the
default concurrency control. Why? As a matter of fact, accessing the same
cached data by concurrent threads it’s not the case with a user’s session. This is
strictly enforced in the case of SFSB, whose instances are not accessible
concurrently. So don’t bother trying to change this property for session data.

Configuring the isolationLevel

The isolationLevel attribute has two possible values, READ_COMMITTED and REPEATABLE_READ which correspond in semantics to database-style isolation levels. Previous versions of JBoss Cache supported all database isolation levels, and if an unsupported isolation level is configured, it is either upgraded or downgraded to the closest supported level.

REPEATABLE_READ is the default isolation level, to maintain compatibility with previous versions of JBoss Cache. READ_COMMITTED, while providing a slightly weaker isolation, has a significant performance benefit over REPEATABLE_READ.

Tuning session replication

As we have learnt, the user session needs replication in order to achieve a consistent state of your applications across the cluster. Replication can be a costly affair, especially if the amount of data held in session is significant. There are however some available strategies, which can mitigate a lot the cost of data replication and thus improve the performance of your cluster:

• Override isModified method: By including an isModified method in your SFSBs, you can achieve fine-grained control over data replication. Applicable to SFSBs only.
• Use buddy replication. By using buddy replication you are not replicating the session data to all nodes but to a limited set of nodes. Can be applicable both to SFSBs and HttpSession.
• Configure replication granularity and replication trigger. You can apply custom session policies to your HttpSession to define when data needs to be replicated and which elements need to be replicated as well. Applicable to HttpSession.

Override SFSB’s isModified method

One of the simplest ways to reduce the cost of SFSBs data replication is implementing in your EJB a method with the following signature: public boolean isModified ();

Before replicating your bean, the container will detect if your bean implements this method. If your bean does, the container calls the isModified method and it only replicates the bean when the method returns true. If the bean has not been modified (or not enough to require replication, depending on your own preferences), you can return false and the replication will not occur.

If your session does not hold critical data (such as financial information), using the isModified method is a good option to achieve a substantial benefit in terms of performance. A good example could be a reporting application, which needs session management to generate aggregate reports through a set of wizards. Here’s a graphical view of this process:

The following benchmark is built on exactly the use case of an OLAP application, which uses SFSBs to drive some session data across a four step wizard. The benchmark compares the performance of the wizard without including isModified and by returning true to isModified at the end of the wizard.

Ultimately, by using the isModified method to propagate the session data at wider intervals you can improve the performance of your application with an acceptable risk to re-generate your reports in case of node failures.

Use buddy replication

By using buddy replication, sessions are replicated to a configurable number of backup servers in the cluster (also called buddies), rather than to all servers in the cluster. If a user fails over from the server that is hosting his or her session, the session data is transferred to the new server from one of the backup buddies. Buddy replication provides the following benefits:

• Reduced memory usage
• Reduced CPU utilization
• Reduced network transmission

The reason behind this large set of advantages is that each server only needs to store in its memory the sessions it is hosting as well as those of the servers for which it is acting as a backup. Thus, less memory required to store data, less CPU to elaborate bits to Java translations, and less data to transmit.

For example, in an 8-node cluster with each server configured to have one buddy, a server would just need to store 2 sessions instead of 8. That’s just one fourth of the memory required with total replication.

In the following picture, you can see an example of a cluster configured for buddy replication:

Here, each node contains a cache of its session data and a backup of another node. For example, node A contains its session data and a backup of node E. Its data is in turn replicated to node B and so on.

In case of failure of node A, its data moves to node B which becomes the owner of both A and B data, plus the backup of node E. Node B in turn replicates (A + B) data to node C.

In order to configure your SFSB sessions or HttpSessions to use buddy replication you have just to set to the property enabled of the bean BuddyReplicationConfig inside the /deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml configuration file, as shown in the next code fragment:
[code lang=”xml”]
<property name="buddyReplicationConfig">
<bean
class="org.jboss.cache.config.BuddyReplicationConfig">
<b><property name="enabled">true</property></b>
. . .
</bean>
</property>
[/code]
In the following test, we are comparing the throughput of a 5-node clustered web application which uses buddy replication against one which replicates data across all members of the cluster.

In this benchmark, switching on buddy replication improved the application throughput of about 30%. No doubt that by using buddy replication there’s a high potential for scaling because memory/CPU/network usage per node does not increase linearly as new nodes are added.

Advanced buddy replication

With the minimal configuration we have just described, each server will look for one buddy across the network where data needs to be replicated. If you need to backup your session to a larger set of buddies you can modify the numBuddies property of the BuddyReplicationConfig bean. Consider, however, that replicating the session to a large set of nodes would conversely reduce the benefits of buddy replication.

Still using the default configuration, each node will try to select its buddy on a different physical host: this helps to reduce chances of introducing a single point of failure in your cluster. Just in case the cluster node is not able to find buddies on different physical hosts, it will not honour the property ignoreColocatedBuddies and fall back to co-located nodes.

The default policy is often what you might need in your applications, however if you need a fine-grained control over the composition of your buddies you can use a feature named buddy pool. A buddy pool is an optional construct where each
instance in a cluster may be configured to be part of a group- just like an “exclusive club membership”.

This allows system administrators a degree of fl exibility and control over how buddies are selected. For example, you might put two instances on separate physical servers that may be on two separate physical racks in the same buddy pool. So rather than picking an instance on a different host on the same rack, the BuddyLocators would rather pick the instance in the same buddy pool, on a separate rack which may add a degree of redundancy.

Here’s a complete configuration which includes buddy pools:
[code lang=”xml”] <property name="buddyReplicationConfig">
<bean class="org.jboss.cache.config.BuddyReplicationConfig">
<b><property name="enabled">true</property>
<property name="buddyPoolName">rack1</property></b>
<property name="buddyCommunicationTimeout">17500</property>
<property name="autoDataGravitation">false</property>
<property name="dataGravitationRemoveOnFind">true</property>
<property name="dataGravitationSearchBackupTrees">true</property>
<property name="buddyLocatorConfig">
<bean
class="org.jboss.cache.buddyreplication.NextMemberBuddyLocatorConfig">
<b><property name="numBuddies">1</property>
<property name="ignoreColocatedBuddies">true</property></b>
</bean>
</property>
</bean>
</property>
[/code]
In this configuration fragment, the buddyPoolName element, if specified, creates a logical subgroup and only picks buddies who share the same buddy pool name. If not specified, this defaults to an internal constant name, which then treats the entire cluster as a single buddy pool.

If the cache on another node needs data that it doesn’t have locally, it can ask the other nodes in the cluster to provide it; nodes that have a copy will provide it as part of a process called data gravitation. The new node will become the owner of the data, placing a backup copy of the data on its buddies.

The ability to gravitate data means there is no need for all requests for data to occur on a node that has a copy of it; that is, any node can handle a request for any data. However, data gravitation is expensive and should not be a frequent occurrence; ideally it should only occur if the node that is using some data fails or is shut down, forcing interested clients to fail over to a different node.

The following optional properties pertain to data gravitation:

• autoDataGravitation: Whether data gravitation occurs for every cache miss. By default this is set to false to prevent unnecessary network calls.
• DataGravitationRemoveOnFind: Forces all remote caches that own the data or hold backups for the data to remove that data, thereby making the requesting cache the new data owner. If set to false, an evict is broadcast instead of a remove, so any state persisted in cache loaders will remain. This is useful if you have a shared cache loader configured. (See next section about Cache loader). Defaults to true.
• dataGravitationSearchBackupTrees: Asks remote instances to search through their backups as well as main data trees. Defaults to true. The resulting effect is that if this is true then backup nodes can respond to data gravitation requests in addition to data owners.

Buddy replication and session affinity

One of the pre-requisites to buddy replication working well and being a real benefit is the use of session affinity, also known as sticky sessions in HttpSession replication speak. What this means is that if certain data is frequently accessed, it is desirable that this is always accessed on one instance rather than in a “round-robin” fashion as this helps the cache cluster optimise how it chooses buddies, where it stores data, and minimises replication traffic.

If you are replicating SFSBs session, there is no need to configure anything since SFSBs, once created, are pinned to the server that created them.

When using HttpSession, you need to make sure your software or hardware load balancer maintain the session on the same host where it was created.

By using Apache’s mod_jk, you have to configure the workers file (workers. properties) specifying where the different node and how calls should be load-balanced across them. For example, on a 5-node cluster:
[code lang=”java”] worker.loadbalancer.balance_workers=node1,node2,node3,node4,node5
worker.loadbalancer.sticky_session=1[/code]
Basically, the above snippet configures mod_jk to perform round-robin load balancing with sticky sessions (sticky_session=1) across 5 nodes of a cluster.

Configure replication granularity and replication trigger

Applications that want to store data in the HttpSession need to use the methods setAttribute to store the attributes and getAttribute to retrieve them. You can define two kind of properties related to HttpSessions:

• The replication-trigger configures when data needs to be replicated.
• The replication-granularity defines which part of the session needs
  to be replicated.

Let’s dissect both aspects in the following sections:

How to configure the replication-trigger

The replication-trigger element determines what triggers a session replication and can be configured by means of the jboss-web.xml element (packed in the WEB-INF folder of your web application). Here’s an example:
[code lang=”xml”] <jboss-web>
<replication-config>
<b><replication-trigger>SET</replication-trigger></b>
</replication-config>
</jboss-web>
[/code]
The following is a list of possible alternative options:

• SET_AND_GET is conservative but not performance-wise; it will always replicate session data even if its content has not been modified but simply accessed. This setting made (a little) sense in AS 4 since using it was a way to ensure that every request triggered replication of the session’s timestamp. Setting max_unreplicated_interval to 0 accomplishes the same thing at much lower cost.
• SET_AND_NON_PRIMITIVE_GET is conservative but will only replicate if an object of a non-primitive type has been accessed (that is, the object is not of a well-known immutable JDK type such as Integer, Long, String, and so on.)This is the default value.
• SET assumes that the developer will explicitly call setAttribute on the session if the data needs to be replicated. This setting prevents unnecessary replication and can have a major beneficial impact on performance.

In all cases, calling setAttribute marks the session as dirty and thus triggers replication.

For the purpose of evaluating the available alternatives in performance terms, we have compared a benchmark of a web application using different replication-triggers:

In the first benchmark, we are using the default rule (SET_AND_NON_PRIMITIVE_GET). In the second we have switched to SET policy, issuing a setAttribute on 50% of the requests. In the last benchmark, we have formerly populated the session with the required attributes and then issued only queries on the session via the getAttribute method.

As you can see the benefit of using the SET replication trigger is obvious, especially if you follow a read-mostly approach on non-primitive types. On the other hand, this requires very good coding practices to ensure setAttribute is always called whenever a mutable object stored in the session is modified.

How to configure the replication-granularity

As far as what data needs to be replicated is concerned, you can opt for the following choices:

• SESSION indicates that the entire session attribute map should be replicated when any attribute is considered modified. Replication occurs at request end. This option replicates the most data and thus incurs the highest replication cost, but since all attributes values are always replicated together it ensures that any references between attribute values will not be broken when the session is deserialized. For this reason it is the default setting.
• ATTRIBUTE indicates that only attributes that the session considers to be potentially modified are replicated. Replication occurs at request end. For sessions carrying large amounts of data, parts of which are infrequently updated, this option can significantly increase replication performance.
• FIELD level replication only replicates modified data fields inside objects stored in the session. Its use could potentially drastically reduce the data traffic between clustered nodes, and hence improve the performance of the whole cluster. To use FIELD-level replication, you have to first prepare (that is bytecode enhance) your Java class to allow the session cache to detect when fields in cached objects have been changed and need to be replicated. 

In order to change the default replication granularity, you have to configure the desired attribute in your jboss-web.xml configuration file:
[code lang=”xml”] <jboss-web>
<replication-config>
<b><replication-granularity>FIELD</replication-granularity></b>
<replication-field-batch-mode>true</replication-field-batchmode>
</replication-config>
</jboss-web>
[/code]
In the above example, the replication-field-batch-mode element indicates whether you want all replication messages associated with a request to be batched into one message.

Additionally, if you want to use FIELD level replication you need to perform a bit of extra work. At first you need to add the @org.jboss.cache.pojo.annotation. Replicable annotation at class level:
[code lang=”java”] @Replicable
public class Person { … }[/code]

If you annotate a class with @Replicable, then all of its subclasses will
be automatically annotated as well.

Once you have annotated your classes, you will need to perform a post-compiler processing step to bytecode enhance your classes for use by your cache. Please check the JBoss AOP documentation (http://www.jboss.org/jbossaop) for the usage of the aoc post-compiler. The JBoss AOP project also provides easy to use ANT tasks to help integrate those steps into your application build process.

As proof of concept, let’s build a use case to compare the performance of ATTRIBUTE and FIELD granularity policies. Supposing you are storing in your HttpSession an object of Person type. The object contains references to an Address, ContactInfo, and PersonalInfo objects. It contains also an ArrayList of WorkExperience.

A prerequisite to this benchmark is that there are no references between
the field values stored in the Person class (for example between the
contactInfo and personalInfo fields), otherwise the references will
be broken by ATTRIBUTE or FIELD policies.

By using the SESSION or ATTRIBUTE replication-granularity policy, even if just one of these fields is modified, the whole Person object need to be retransmitted. Let’s compare the throughput of two applications using respectively the ATTRIBUTE and FIELD replication-granularity.

In this example, based on the assumption that we have a single dirty field of Person’ class per request, by using FIELD Replication generate a substantial 10% gain.

Tuning cache storage

Cache loading allows JBoss Cache to store cached data in a persistent store and is used mainly for HttpSession and SFSB sessions. Hibernate and JPA on the other hand, have already their persistence storage in the database so it doesn’t make sense to add another storage.

This data can either be an overflow, where the data in the persistent store has been evicted from memory. Or it can be a replication of what is in memory, where everything in memory is also refl ected in the persistent store, along with items that have been evicted from memory.

The cache storage used for web session and EJB3 SFSB caching comes into play in two circumstances:

• Whenever a cache element is accessed, and that element is not in the cache (for example, due to eviction or due to server restart), then the cache loader transparently loads the element into the cache if found in the backend store.
• Whenever an element is modified, added or removed, then that modification is persisted in the backend store via the cache loader (except if the ignoreModifications property has been set to true for a specific cache loader). If transactions are used, all modifications created within a transaction are persisted as well.

Cache loaders are configured by means of the property cacheLoaderConfig of session caches. For example, in the case of SFSB cache:
[code lang=”xml”]
<b><entry><key>sfsb-cache</key></b>
<value>
<bean name="StandardSFSBCacheConfig"
class="org.jboss.cache.config.Configuration">
. . . . .
<b><property name="cacheLoaderConfig"></b>
<bean class="org.jboss.cache.config.CacheLoaderConfig">
<b><property name="passivation">true</property>
<property name="shared">false</property></b>
<property name="individualCacheLoaderConfigs">
<list>
<bean
class="org.jboss.cache.loader.FileCacheLoaderConfig">
<property
name="location">${jboss.server.data.dir}${/}sfsb</property>
<property name="async">false</property>
<property name="fetchPersistentState">true</property>
<property name="purgeOnStartup">true</property>
<property name="ignoreModifications">false</property>
<property
name="checkCharacterPortability">false</property>
</bean>
</list>
</property>
</bean>
. . . ..
</entry>
[/code]
The passivation property , when set to true, means the persistent store acts as an overflow area written to when data is evicted from the in-memory cache.

The shared attribute indicates that the cache loader is shared among different cache instances, for example where all instances in a cluster use the same JDBC settings to talk to the same remote, shared database. Setting this to true prevents repeated and  unnecessary writes of the same data to the cache loader by different cache instances. The default value is false.

Where does cache data get stored?

By default, the Cache loader uses a filesystem implementation based on the class org.jboss.cache.loader.FileCacheLoaderConfig, which requires the location property to define the root directory to be used.

If set to true, the async attribute read operations are done synchronously, while write (CRUD – Create, Remove, Update, and Delete) operations are done asynchronously. If set to false (default), both read and writes are performed synchronously.

Should I use an async channel for my Cache Loader?
When using an async channel, an instance of org.jboss.cache.
loader.AsyncCacheLoader is constructed which will act as an
asynchronous channel to the actual cache loader to be used. Be aware
that, using the AsyncCacheLoader, there is always the possibility of
dirty reads since all writes are performed asynchronously, and it is thus
impossible to guarantee when (and even if) a write succeeds. On the
other hand the AsyncCacheLoader allows massive writes to be written
asynchronously, possibly in batches, with large performance benefits.
Checkout the JBoss Cache docs for further information http://docs.
jboss.org/jbosscache/3.2.1.GA/apidocs/index.html.

fetchPersistentState determines whether or not to fetch the persistent state of a cache when a node joins a cluster and conversely the purgeOnStartup property evicts data from the storage on startup, if set to true.

Finally, checkCharacterPortability should be false for a minor performance improvement.

The FileCacheLoader is a good choice in terms of performance, however it has some limitations, which you should be aware of before rolling your application in a production environment. In particular:

1. Due to the way the FileCacheLoader represents a tree structure on disk (directories and files) traversal is “inefficient” for deep trees.
2. Usage on shared filesystems such as NFS, Windows shares, and others should be avoided as these do not implement proper file locking and can cause data corruption.
3. Filesystems are inherently not “transactional”, so when attempting to use your cache in a transactional context, failures when writing to the file (which happens during the commit phase) cannot be recovered.

As a rule of thumb, it is recommended that the FileCacheLoader not
be used in a highly concurrent, transactional. or stressful environment,
and, in this kind of scenario consider using it just in the testing
environment.

As an alternative, consider that JBoss Cache is distributed with a set of different Cache loaders which can be used as alternative. For example:

• The JDBC-based cache loader implementation that stores/loads nodes’ state into a relational database. The implementing class is org.jboss.cache. loader.JDBCCacheLoader.
• The BdbjeCacheLoader, which is a cache loader implementation based on the Oracle/Sleepycat’s BerkeleyDB Java Edition (note that the BerkeleyDB implementation is much more efficient than the filesystem-based implementation, and provides transactional guarantees, but requires a commercial license if distributed with an application (see http://www.oracle.com/database/berkeley-db/index.html for details).
• The JdbmCacheLoader, which is a cache loader implementation based on the JDBM engine, a fast and free alternative to BerkeleyDB.
• Finally, S3CacheLoader, which uses the Amazon S3 solution (Simple Storage Solution http://aws.amazon.com/) for storing cache data. Since Amazon S3 is remote network storage and has fairly high latency, it is really best for
  caches that store large pieces of data, such as media or files.

When it comes to measuring the performance of different Cache Loaders, here’s a benchmark executed to compare the File CacheLoader, the JDBC CacheLoader (based on Oracle Database) and Jdbm CacheLoader.

In the above benchmark we are testing cache insertion and cache gets of batches of 1000 Fqn each one bearing 10 attributes. The File CacheLoader accomplished the overall best performance, while the JBDM CacheLoader is almost as fast for Cache gets.

The JDBC CacheLoader is the most robust solution but it adds more overhead to the Cache storage of your session data.

Summary

Clustering is a key element in building scalable Enterprise applications. The infrastructure used by JBoss AS for clustered applications is based on JGroups framework for the nodes inter-communication and JBoss Cache for keeping the cluster data synchronized across nodes.

• JGroups can use both UDP and TCP as communication protocol. Unless you have network restriction, you should stay with the default UDP that uses multicast to send and receive messages.
• You can tune the transmission protocol by setting an appropriate buffer size with the properties mcast_recv_buf_size, mcast_send_buf_size, ucast_recv_buf_size, and ucast_send_buf_size. You should as well increase your O/S buffer size, which need to be adequate to accept JGroups’ settings.
• JBoss Cache provides the foundation for robust clustered services.
• By configuring the cacheMode you can choose if your cluster messages will be synchronous (that is will wait for message acknowledgement) or asynchronous. Unless you need to handle cache message exceptions, stay with the asynchronous pattern, which provides the best performance.
• Cache messages can trigger as well cluster replication or cluster invalidation. A cluster replication is needed for transferring the session state across the cluster while invalidation is the default for Entity/Hibernate, where state
  can be recovered from the database.
• The cache concurrency can be configured by means of the nodeLockingScheme property. The most efficient locking schema is the MVCC, which reduces the cost of slow, or synchronization-heavy schemas of Pessimistic and Optimistic schemas.
• Cache replication of sessions can be optimised mostly in three ways:
• By overriding the isModified method of your SFSBs you can achieve a fine-grained control over data replication. It’s an optimal quick-tuning option for OLAP applications using SFSBs.
• Buddy replication is the most important performance addition to your session replication. It helps to increase the performance by reducing memory and CPU usage as well as network traffic. Use buddy replication pools to achieve a higher level of redundancy for mission critical applications.
• Clustered web applications can configure replication-granularity and replication-trigger:
• As far as the replication trigger is concerned, if you mostly read immutable data from your session, the SET attribute provides a substantial benefit over the default SET_AND_PRIMITIVE_GET.
• As far as replication granularity is concerned, if your sessions are generally small, you can stay with the default policy (SESSION). If your session is larger and some parts are infrequently accessed, ATTRIBUTE replication will be more effective. If your application has very big data objects in session attributes and only fields in those objects are frequently modified, the FIELD policy would be the best.

Drools JBoss Rules 5.0 Developer’s GuideBusiness rules and processes can help your business by providing a level of agility and flexibility. As a developer, you will be largely responsible for implementing these business rules and processes effectively, but implementing them systematically can often be difficult due to their complexity. Drools, or JBoss Rules, makes the process of implementing these rules and processes quicker and handles the complexity, making your life a lot easier!

also read:

• WebLogic Interview Questions
• JBoss Portal Server Development
• Tomcat Interview Questions

This book guides you through various features of Drools, such as rules, ruleflows, decision tables, complex event processing, Drools Rete implementation with various optimizations, and others. It will help you to set up the Drools platform and start creating your own business. It’s easy to start developing with Drools if you follow our real-world examples that are intended to make your life easier.

Starting with an introduction to the basic syntax that is essential for writing rules, the book will guide you through validation and human-readable rules that define, maintain, and support your business agility. As a developer, you will be expected to represent policies, procedures, and constraints regarding how an enterprise conducts its business; this book makes it easier by showing you the ways in which it can be done.

A real-life example of a banking domain allows you to see how the internal workings of the rules engine operate. A loan approval process example shows the use of the Drools Flow module. Parts of a banking fraud detection system are implemented with Drools Fusion module, which is the Complex Event Processing part of Drools. This in turn, will help developers to work on preventing fraudulent users from accessing systems in an illegal way.

Finally, more technical details are shown on the inner workings of Drools, the implementation of the ReteOO algorithm, indexing, node sharing, and partitioning.

What This Book CoversChapter 1: This chapter introduces the reader to the domain of business rules and business processes. It talks about why the standard solutions fail at implementing complex business logic. It shows a possible solution in the form of a declarative programming model. The chapter talks about advantages and disadvantages of Drools. A brief history of Drools is also mentioned.

Chapter 2: This chapter shows us the basics of working with the Drools rule engine—Drools Expert. It starts with a simple example that is explained step-by-step. It begins with the development environment setup, writing a simple rule, and then executing it. The chapter goes through some necessary keywords and concepts that are needed for more complex examples.

Chapter 3: This chapter introduces the reader to a banking domain that will be the basis for examples later in this book. The chapter then goes through an implementation of a decision service for validating this banking domain. A reporting model is designed that holds reports generated by this service.

Chapter 4: This chapter shows how Drools can be used for carrying out complex data transformation tasks. It starts with writing some rules to load the data, continues with the implementation of various transformation rules, and finally puts together the results of this transformation. The chapter shows how we can work with a generic data structure such as a map in Drools.

Chapter 5: The focus of this chapter is on rules that are easy to read and change. Starting with domain specific languages, the chapter shows how to create a data transformation specific language. Next, it focuses on decision tables as another more user-friendly way of representing business rules. An interest rate calculation example is shown. Finally, the chapter introduces the reader to Drools Flow module as a way of managing the rule execution order.

Chapter 6: This chapter talks about executing the validation decision service in a stateful manner. The validation results are accumulated between service calls. This shows another way of interacting with a rule engine. Logical assertions are used to keep the report up-todate. Various ways of serializing a stateful session are discussed.

Chapter 7: This chapter talks about Drools Fusion—another cornerstone of the Drools platform is about writing rules that react to various events. The power of Drools Fusion is shown through a banking fraud detection system. The chapter goes through various features such as events, type declarations, temporal operators, sliding windows, and others.

Chapter 8: This chapter goes into more detail about the workflow aspect of the Drools platform. It is showed through a loan approval service that demonstrates the use of various nodes in a flow. Among other things, the chapter talks about implementing a custom work item, human task, or a sub-flow.

Chapter 9: The purpose of this chapter is to show you how to integrate Drools in a real web application. We’ll go through design and implementation of persistence, business logic, and presentation layers. All of the examples written so far will be integrated into this application.

Chapter 10: The focus of this chapter is to give you an idea about the various ways of testing your business logic. Starting with unit testing, integration testing through acceptance testing that will be shown with the help of the Business Rules Management Server—Guvnor, this chapter provides useful advice on various troubleshooting techniques.

Chapter 11: This chapter shows integration with the Spring Framework. It describes how we can make changes to rules and processes while the application runs. It shows how to use an external build tool such as Ant to compile rules and processes. It talks about the rule execution server that allows us to execute rules remotely. It briefly mentions support of various standards.

Chapter 12: This chapter goes under the hood of the Drools rule engine. By understanding how the technology works, you’ll be able to write more efficient rules and processes. It talks about the ReteOO algorithm, node sharing, node indexing, and rule partitioning for parallel execution.

Human-readable Rules (JBoss Rules 5.0)

Business rules implementations presented so far were aimed mostly at developers. However, it is sometimes needed that these rules are readable and understandable by the business analysts. Ideally, they should be able to change the rules or even write new ones. An important aspect of business rules is their readability and user friendliness. Looking at a rule, you should immediately have an idea of what it is about. In this chapter, we’ll look at Domain Specific Languages (DSLs), decision tables, and rule flows to create human-readable rules.

Domain Specific Language

The domain in this sense represents the business area (for example, life insurance or billing). Rules are expressed with the  terminology of the problem domain. This means that domain experts can understand, validate, and modify these rules more easily.

You can think of DSL as a translator. It defines how to translate sentences from the problem-specific terminology into rules. The translation process is defined in a .dsl file. The sentences themselves are stored in a .dslr file. The result of this process must be a valid .drl file.

Building a simple DSL might look like:

[code lang=”java”] [condition][]There is a Customer with firstName
{name}=$customer : Customer(firstName == {name})
[consequence][]Greet Customer=System.out.println("Hello " +
$customer.getFirstName());
[/code]

Code listing 1: Simple DSL file simple.dsl.

[code] The code listing above contains only two lines (each begins with [).
However, because the lines are too long, they are wrapped effectively
creating four lines. This will be the case in most of the code listings.

When you are using the Drools Eclipse plugin to write this DSL, enter the
text before the first equal sign into the field called <b>Language expression</b>,
the text after equal sign into <b>Rule mapping</b>, leave the object field blank
and select the correct scope.
[/code]

The previous DSL defines two DSL mappings. They map a DSLR sentence to a DRL rule. The first one translates to a condition that matches a Customer object with the specified first name. The first name is captured into a variable called name. This variable is then used in the rule condition. The second line translates to a greeting message that is printed on the console. The following .dslr file can be written based on the previous DSL:

[code lang=”java”] package droolsbook.dsl;
import droolsbook.bank.model.*;
expander simple.dsl
rule "hello rule"
when
There is a Customer with firstName "David"
then
Greet Customer
end
[/code]

Code listing 2: Simple .dslr file (simple.dslr) with rule that greets a customer with name David.

As can be seen, the structure of a .dslr file is the same as the structure of a .drl file. Only the rule conditions and consequences are different. Another thing to note is the line containing expander simple.dsl. It informs Drools how to translate sentences in this file into valid rules. Drools reads the simple.dslr file and tries to translate/expand each line by applying all mappings from the simple.dsl file (it does it in a single pass process, line-by-line from top to bottom). The order of lines is important in a .dsl file. Please note that one condition/consequence must be written on one line, otherwise the expansion won’t work (for example, the condition after the when
clause, from the rule above, must be on one line).

When you are writing .dslr files, consider using the Drools Eclipse plugin. It provides a special editor for .dslr files that has an editing mode and a read-only mode for viewing the resulting .drl file. A simple DSL editor is provided as well.

The result of the translation process will look like the following screenshot:

This translation process happens in memory and no .drl file is physically stored. We can now run this example. First of all, a knowledge base must be created from the simple.dsl and simple.dslr files. The process of creating a package using a DSL is as follows (only the package creation is shown, the rest is the same as we’ve seen in Chapter 2, Basic Rules):

KnowledgeBuilder acts as the translator. It takes the .dslr file, and based on the .dsl file, creates the DRL. This DRL is then used as normal (we don’t see it; it’s internal to KnowledgeBuilder). The implementation is as follows:

[code lang=”java”] private KnowledgeBase createKnowledgeBaseFromDSL()
throws Exception {
KnowledgeBuilder builder =
KnowledgeBuilderFactory.newKnowledgeBuilder();
builder.add(ResourceFactory.newClassPathResource(
"simple.dsl"), ResourceType.DSL);
builder.add(ResourceFactory.newClassPathResource(
"simple.dslr"), ResourceType.DSLR);
if (builder.hasErrors()) {
throw new RuntimeException(builder.getErrors()
.toString());
}
KnowledgeBase knowledgeBase = KnowledgeBaseFactory
.newKnowledgeBase();
knowledgeBase.addKnowledgePackages(
builder.getKnowledgePackages());
return knowledgeBase;
}
[/code]

Code listing 3: Creating knowledge base from .dsl and .dslr files.

The .dsl and subsequently the .dslr files are passed into KnowledgeBuilder. The rest is similar to what we’ve seen before.

DSL as an interface

DSLs can be also looked at as another level of indirection between your .drl files and business requirements. It works as shown in the following figure:

The figure above shows DSL as an interface (dependency diagram). At the top are the business requirements as defined by the business analyst. These requirements are represented as DSL sentences (.dslr file). The DSL then represents the interface between DSL sentences and rule implementation (.drl file) and the domain model. For example, we can change the transformation to make the resulting rules more efficient without changing the language. Further, we can change the language, for example, to make it more user friendly, without changing the rules. All this can be done just by changing the .dsl file.

DSL for validation rules

The first three implemented object/field required rules from Chapter 2, Basic Rules, can be rewritten as:

• If the Customer does not have an address, then Display warning message
• If the Customer does not have a phone number or it is blank, then Display error message
• If the Account does not have an owner, then Display error message for Account

We can clearly see that all of them operate on some object (Customer/Account), test its property (address/phone/owner), and display a message (warning/error) possibly with some context (account). Our validation.dslr file might look like the following code:

[code] expander validation.dsl
rule "address is required"
when
The Customer does not have address
then
Display warning
end
rule "phone number is required"
when
The Customer does not have phone number or it is blank
then
Display error
end
rule "account owner is required"
when
The Account does not have owner
then
Display error for Account
end
[/code]

Code listing 4: First DSL approach at defining the required object/field rules (validation.dslr file).

The conditions could be mapped like this:

[code lang=”java”]
[condition][]The {object} does not have {field}=${object} : {object}(
{field} == null )
[/code]

Code listing 5: validation.dsl.

This covers the address and account conditions completely. For the phone number rule, we have to add the following mapping at the beginning of the validation.dsl file:

[code lang=”java”]
[condition][] or it is blank = == "" ||
[/code]

Code listing 6: Mapping that checks for a blank phone number.

As it stands, the phone number condition will be expanded to:

[code lang=”java”]
$Customer : Customer( phone number == "" || == null )
[/code]

Code listing 7: Unfinished phone number condition.

To correct it, phone number has to be mapped to phoneNumber. This can be done by adding the following at the end of the validation.dsl file:

[code lang=”java”]
[condition][]phone number=phoneNumber
[/code]

Code listing 8: Phone number mapping.

The conditions are working. Now, let’s focus on the consequences. The following mapping will do the job:

[code lang=”java”] [consequence][]Display {message_type} for {object}={message_type}(
kcontext, ${object} );
[consequence][]Display {message_type}={message_type}( kcontext );
[/code]

Code listing 9: Consequence mappings.

The three validation rules are now being expanded to the same .drl representation as we’ve seen in Chapter 2.

File formats

Before we go further, we’ll examine each file format in more detail.

DSL file format

A line in a .dsl file has the following format:

[code lang=”java”]
[<scope>][<Type>]<language expression>=<rule mapping>
[/code]

Code listing 10: The format of one line in a .dsl file.

As we’ve already seen, an example of a line in DSL file might look like this:

[code lang=”java”]
[condition][droolsbook.bank.model.Customer]The Customer does not have
address=Customer(address == null)
[/code]

Code listing 11: Sample line from DSL file (note that it is just one line that has been wrapped).

The scope can have the following values:

• condition: Specifies that this mapping can be used in the condition part of a rule.
• consequence: Specifies that this mapping can be used in the consequence part of a rule.
• *: Specifies that this mapping can be used in both the condition and the consequence part of a rule.
• keyword: This mapping is applied to the whole file (not just the condition or the consequence part). Used mainly when writing DSLs in languages other than English or to hide the package/import/global statements at the beginning of the file behind a business friendly sentence.

Type can be used to further limit the scope of the mapping. Scope and Type are used by the Drools Eclipse plugin to provide auto-completion when writing .dslr files (when pressing Ctrl + Space, only relevant choices are offered). This is especially useful with the multiple constraints feature (refer to the section, DSL for multiple constraints in a condition).

DSL supports comments by starting the line with the hash character, #. For example:

[code lang=”java”] #this is a comment in a .dsl file
[/code]

RL file format

As a side note, in a .drl file, it is valid to write the whole rule on a single line. This allows us to write more complex DSLs because one sentence in .dslr file can be translated into multiple conditions—even the whole rule. For example, these arevalid rules on a single line:

[code lang=”java”] rule "addressRequired" when Customer( address == null ) then
warning(kcontext); end
[/code]

Code listing 12: addressRequired rule on one line.

Make sure that you add spaces between Drools keywords. Another more complex example of a rule on one line:

[code lang=”java”] rule "studentAccountCustomerAgeLessThan" when Customer( eval (year
sPassedSince(dateOfBirth) >= 27) ) and $account : Account( type ==
Account.Type.STUDENT ) then error(kcontext, $account); System.out.
println("another statement"); end
[/code]

Code listing 13: studentAccountCustomerAgeLessThan rule on one line.

The preceding rule contains two conditions and two Java statements in the consequence block. There is also an optional and keyword between the conditions to make it more readable.

DSLR file format

A . dslr file contains the sentences written using the DSL. The .dslr file is very similar to the .drl file. One thing to note is that by prepending a line with a ‘>’, we can turn off the expander for the line. This allows us to write a hybrid .dslr file that contains traditional DRL rules and DSL rules. For example, if we are not yet sure how to map some complex rule, we can leave it in its original .drl file format.

DSL for multiple constraints in a condition

We’ ll go through more complex DSLs. Let’s look at a standard condition for example:

[code lang=”java”]
Account( owner != null, balance > 100, currency == "EUR" )
[/code]

Code listing 14: Condition that matches some account.

It is difficult to write DSL that will allow us to create conditions with any subset of constraints from the code listing above (without writing down all possible permutations). The ‘-‘ feature comes to the rescue:

[code lang=”java”]
[condition][]There is an Account that=$account : Account( )
[condition][]-has owner=owner != null
[condition][]-has balance greater than {amount}=balance > {amount}
[condition][]-has currency equal to {currency}=currency == {currency}
[/code]

Code listing 15: DSL using the ‘-‘ feature. This can create seven combinations of the constraints.

When the DSL condition starts with ‘-‘, the DSL parser knows that this constraint should be added to the last condition (in a .dslr file). With the preceding DSL, the following condition can be created:

[code lang=”java”] There is an Account that
– has currency equal to "USD"
"has balance greater than 2000"
[/code]

Code listing 16: Condition using the ‘-‘ feature (in a .dslr file).

The ‘-‘ feature increases the fl exibility of the resulting language. It works just fine for simple cases involving only one pair of brackets. In case of multiple brackets in the condition, Drools always adds the constraint to the last pair of brackets. This may not always be what we want. We have to find a different way of specifying multiple constraints in a condition. We can also write our DSL in the following manner:

[code lang=”java”]
[condition][]There is an Account that {constraints} = Account(
{constraints} )
[condition][]has {field} equal to {value}={field} == {value}
[condition][]and has {field} equal to {value}=, {field} == {value}
[/code]

Code listing 17: Flexible DSL that can be expanded to a condition with two field constraints.

With this DSL, the following DSLR can be written:

[code lang=”java”]
There is an Account that has owner equal to null and has balance equal
to 100
[/code]

Code listing 18: DSLR that describes an account with two constraints.

If we want to have more conditions, we can simply duplicate the last line in the DSL. Remember? Translation is a single pass process.

Named capture groups

Som etimes, when a more complex DSL is needed, we need to be more precise at specifying what a valid match is. We can use named capture groups with regular expressions to give us the needed precision. For example:

[code lang=”java”]
{name:[a-zA-Z]+}
[/code]

Code listing 19: Name that matches only characters.

[code]
Regular expressions (java.util.regex.Pattern) can be used not
only for capturing variables but also within the DSL. For example, in
order to carry out case insensitive matching. If we look at the DSL from
code listing 15, the users should be allowed to type Account, account,
ACCOUNT, or even aCcount in their .dslr files. This can be done by
enabling the embedded case insensitive fl ag expression—(?i):
[condition][]There is an (?i:account) that ….

Another useful example is sentences that are sensitive to
gender—(s)?he to support "he" and "she", and so on.

In order to make the sentences space insensitive, Drools automatically
replaces all spaces with \s+. Each \s+ matches one or more spaces. For
example, the following line in a .dslr file will be successfully expanded
by the DSL from code listing 15:
There is an Account that ….
[/code]

DSL for data transformation rules

We’ ll now implement DSL for the data transformation rules from Chapter 4, Data Transformation. We’ll reuse our rule unit tests to verify that we don’t change the functionality of the rules but only their representation. The unit test class will be extended and the method for creating KnowledgeBase will be overridden to use the .dsl file and .dslr file as inputs. Rule names will stay the same. Let’s start with the twoEqualAddressesDifferentInstance rule:

[code lang=”java”]
rule twoEqualAddressesDifferentInstance
when
There is legacy Address-1
There is legacy Address-2
– same as legacy Address-1
then
remove legacy Address-2
Display WARNING for legacy Address-2
end
[/code]

Code listing 20: Rule for removing redundant addresses (dataTransformation.dslr file).

The conditions can be implemented with the following DSL:

[code lang=”java”]
[condition][] legacy {object}-{id} = {object}-{id}
[condition][] There is {object}-{id} = ${object}{id} : Map( this["_
type_"] == "{object}" )
[condition][]- same as {object}-{id} = this == ${object}{id}, eval(
${object}1 != ${object}2 )
[/code]

Code listing 21: DSL for conditions (dataTransformation.dsl file).

The first mapping is a simple translation rule, where we remove the word legacy. The next mapping captures a map with its type. The last mapping includes the equality test with the object identity test. Mapping for consequences is as follows:

[code lang=”java”]
[consequence][] legacy {object}-{id} = ${object}{id}
[consequence][]Display {message_type_enum} for {object}=validationRepo
rt.addMessage(reportFactory.createMessage(Message.Type.{message_type_
enum}, kcontext.getRule().getName(), {object}));
[consequence][]remove {object} = retract( {object} );
[/code]

Code listing 22: DSL for consequences.

The first mapping just removes the word legacy. The second mapping adds a message to validationReport. Finally, the last mapping removes an object from the knowledge session. This is all we need for the twoEqualAddressesDifferentInstance rule.

As you can see, we started with the sentence in the domain specific language (code listing 1) and then we’ve written the transformation to refl ect the rules (from Chapter 4). In reality, this is an iterative process. You’ll modify the .dslr and .dsl files until you are happy with the results. It is also a good idea to write your rules in standard .drl first and only then try to write a DSL for them.

We ‘ll move to the next rule, addressNormalizationUSA:

[code lang=”java”]
rule addressNormalizationUSA
when
There is legacy Address-1
– country is one of "US", "U.S.", "USA", "U.S.A"
then
for legacy Address-1 set country to USA
end
[/code]

Code listing 23: DSLR rule for normalizing address country field. The rule just needs another constraint type:

[code lang=”java”]
[condition][]- country is one of {country_list} = this["country"] in
({country_list})
[/code]

Code listing 24: Another condition mapping.

The consequence is defined with two mappings. The first one will translate the country to an enum and the second will then perform the assignment.

[code lang=”java”]
[consequence][]set country to {country}=set country to Address.
Country.{country}
[consequence][]for {object}set {field} to {value} = modify( {object} )
\{ put("{field}", {value} ) \}
[/code]

Code listing 25: Consequence mapping for the country normalization rule.

Please note that the curly brackets are escaped. Moreover, the original rule used mvel dialect. It is a good idea to write your rules using the same dialect. It makes the DSL easier. Otherwise, the DSL will have to be “dialect aware”.

The other country normalization rule can be written without modifying the DSL. We’ll now continue with unknownCountry rule:

[code lang=”java”]
rule unknownCountry
Apply after address normalizations
when
There is legacy Address-1
– country is not normalized
then
Display ERROR for legacy Address-1
end
[/code]

Code listing 26: DSLR representation of the unknownCountry rule.

The whole sentence Apply after address normalizations is mapped as a keyword mapping:

[code lang=”java”]
[keyword][] Apply after address normalizations = salience -10
[/code]

Code listing 27: salience keyword mapping.

Now, we can use the other rule attributes to achieve the same goal just by changing the DSL.

Additional mapping that is needed:

[code lang=”java”]
[condition][]- country is not normalized = eval(!($Address1.
get("country") instanceof Address.Country))
[/code]

Code listing 28: Another condition mapping.

In the condition mapping, the $Address1 is hard-coded. This is fine for the rules that we have.

As you can imagine, the rest of the rules follow similar principles.

What we have achieved by writing this DSL is better readability. A business analyst can verify the correctness of these rules more easily. We could push this further by defining a complete DSL that can represent any concept from the problem domain. The business analyst will then be able to express any business requirement just by editing the .dslr file.

Decision tables

Decision tables are another form of human-readable rules that are useful when there are lots of similar rules with different values. Rules that share the same conditions with different parameters can be captured in a decision table. Decision tables can be
represented in an Excel spreadsheet (.xls file) or a comma separated values (.csv file) format. Starting from version 5.0, Drools supports web-based decision tables as well. They won’t be discussed in this book; however, they are very similar. Let’s have
a look at a simple decision table in .xls format.

The preceding screenshot shows a decision table in validation.xls opened with OpenOffice Calc editor. It shows one decision table for validating a customer. Line 10 shows four columns. The first one defines rule name, the next two define conditions,and the last one is for defining actions/consequences. The next three lines (11-13) represent the individual rules—one line per rule. Each cell defines parameters for conditions/consequences. If a cell doesn’t have a value, that condition/action is ignored. Some rows in the spreadsheet are grouped and hidden (see the two plus (+) signs in the left). This makes the decision tables more user-friendly, especially for
business users. Please note that tables don’t have to start on the first column. The full validation.xls file is as follows:

Every file for defining decision tables start with a global configuration section. The configuration consists of name-value pairs. As can be seen from the screenshot above:

• RuleSet defines the package
• Import specifies the classes used, including static imported functions
• Variables is used for global variables
• Notes can be any text

Further:

• Functions can be used to write local functions as in .drl format
• Worksheet specifies the sheet to be used; by default only the first sheet is checked for rules

The RuleTable then denotes the start of the decision table. It has no specific purpose. It is used only to group rules that operate on the same objects and share conditions. The next line defines column types. The following column types are available:

• CONDITION—defines a single rule condition or constraint, the following row can contain type for this condition, if it doesn’t, then the next row must define full condition (with a type, not just a constraint as in the preceding case).
• ACTION—rule action. Similar to condition, the next line can contain any global or bound variable. Drools will then assume that the next line is a method that should be called on this global or bound variable.
• PRIORITY—for defining rule salience.
• NAME—by default rule names are auto generated, NAME can be used to explicitly specify the name.
• No-loop or Unloop—specifies the rule no-loop attribute.
• XOR-GROUP—specifies rule activation-group (this will be discussed in the upcoming section, Drools Flow).

For full configuration options, please consult the Drools manual (http://www.jboss.org/drools/documentation.html).

The next line from the preceding screenshot looks similar to what we see in a .drl file. It is a simple condition that matches any Customer object and exposes this object as the $customer variable. The only difference is that there are no brackets. They will be added automatically by Drools at parsing time. Please note that this line contains only two columns. The first two columns are merged into one column. This is because they operate on the same type (Customer). If we don’t merge the two columns, they’ll match two separate objects (which may or may not be the same instance).

The next line then defines individual constraints (in case of conditions) or code blocks (in case of actions). Special parameters can be used as $param or $1, $2, $3, and so on. The first one is used if our constraint needs only one parameter; otherwise, the $n format should be used.

The following line (corresponds to line 10 in the preceding screenshot showing a decision table in validation.xls file) is for pure informational purposes. It should contain some meaningful description of the column/action so that we don’t have to always look at how it is implemented (by expanding/collapsing rows).

Finally, the actual values follow in subsequent rows. Each line represents one rule. For example, the first line gets translated behind the scenes to the following .drl rule:

[code lang=”java”]
#From row number: 11
rule "addressRequired"
when
$customer : Customer(address == null)
then
warning(kcontext);
end
[/code]

Code listing 29: Generated rule from a decision table.

The .drl rule is exactly the same as we’ve implemented in Chapter 3, Validation. We can even reuse the same unit test to test this rule.

Advantages of a decision table

Here are the advantages of a decision table:

• It is easy to read and understand.
• Refactoring is quicker because we just have to change a column definition to change a group of related rules (that is, it is easy to change conditions across group of rules).
• Isolation is similar to DSL; decision tables can hide the rule implementation details.
• Provides separation between the rules and data (they are still in one file but separated).
• Any formatting available in a spreadsheet editor can be applied to present these data in a more readable manner (for example, using a drop-down for a list of values. It can reduce errors from mistyping a value into a cell by allowing only valid values).
• Eclipse Drools plugin can also validate a spreadsheet. This is very useful when writing rules. The Problems view in Eclipse shows what exactly is wrong with the generated .drl file.

Disadvantages of a decision table

• It can be awkward to debug/write these rules. Sometimes it helps to convert the spreadsheet to a .drl file, save this file, and fix it, as we’re used to.
• Decision tables shouldn’t be used if the rules don’t share many conditions.Further, the order of conditions is important. In a decision table, the order of a condition is given by the order of a column. Care should be taken if you want to convert the existing DRL rules into decision tables, as the order of conditions may change (to take advantage of the reuse).
• XLS is a binary format which makes version management more difficult.

Calculating the interest rate

As an example, we’ll calculate the interest rate based on the account balance, currency, duration, and type. This calculation is ideal for a decision table because we have a lot of constraints that are reused across rules with different data. The decision table looks as follows:

Please note that the Account object is used in every condition so the CONDITION columns are merged. We can see the use of parameters $1 and $2. The first line can be read as: For every transactional account with currency EUR, set its interest rate to 0.01
percent (regardless of the balance). Another line can be read as: For every savings account whose balance is between 100 EUR and 1000 EUR that is opened for one to three months, set its interest rate to 3 percent. The following rule will be generated:

[code lang=”java”]
#From row number: 16
rule "Interest Calculation_16"
when
$a:Account(type == Account.Type.SAVINGS,
currency == "EUR", balance >= 100 &amp;&amp; < 1000,
monthsBetweenStartAndEndDate >= 1 &amp;&amp; < 3)
then
$a.setInterestRate(new BigDecimal("3.00"));
end
[/code]

Code listing 30: Generated rule for calculating the interest rate.

If we had not used a decision table, we would have to write such rules by hand. Please note that the second condition column in the decision table above doesn’t have any operator or operand. It simply says currency. It is a special feature and this is automatically translated to currency == $param.

The last condition column uses getMonthsBetweenStartAndEndDate method of the Account class.

[code lang=”java”]
private DateMidnight startDate;
private DateMidnight endDate;
/**
* @return number of months between start and end date
*/
public int getMonthsBetweenStartAndEndDate() {
if (startDate == null || endDate == null) {
return 0;
}
return Months.monthsBetween(startDate, endDate)
.getMonths();
}
[/code]

Code listing 31: Implementation of getMonthsBetweenStartAndEndDate method of Account.

The implementation uses the Joda-Time library to do the calculation.

Project setup

The following libraries are needed on the classpath:

• drools-decisiontables-5.0.1.jar: used for compiling spreadsheets into .drl file format; it knows how to handle .xls and .csv formats.
• jxl-2.4.2.jar XLS API: used for parsing .xls spreadsheets.

Testing

For testing the interest calculation rules, we’ll use a stateless knowledge session, an account, and a date object. All tests will reuse the stateless session. The test can be set up as follows:

[code lang=”java”]
static StatelessKnowledgeSession session;
Account account;
static DateMidnight DATE;

@BeforeClass
public static void setUpClass() throws Exception {
KnowledgeBase knowledgeBase =
createKnowledgeBaseFromSpreadsheet();
session = knowledgeBase.newStatelessKnowledgeSession();
DATE = new DateMidnight(2008, 1, 1);
}

@Before
public void setUp() throws Exception {
account = new Account();
}
[/code]

Code listing 32: Setup of the decision table test.

The date will be used to set deposit durations. An account is created for every test method. The createKnowledgeBaseFromSpreadsheet method is implemented as follows:

[code lang=”java”]
private static KnowledgeBase createKnowledgeBaseFromSpreadsheet()
throws Exception {
DecisionTableConfiguration dtconf =KnowledgeBuilderFactory
.newDecisionTableConfiguration();
dtconf.setInputType( DecisionTableInputType.XLS );
//dtconf.setInputType( DecisionTableInputType.CSV );
KnowledgeBuilder knowledgeBuilder =
KnowledgeBuilderFactory.newKnowledgeBuilder();
knowledgeBuilder.add(ResourceFactory.newClassPathResource(
"interest calculation.xls"), ResourceType.DTABLE,
dtconf);
//knowledgeBuilder.add(ResourceFactory
// .newClassPathResource("interest calculation.csv"),
// ResourceType.DTABLE, dtconf);

if (knowledgeBuilder.hasErrors()) {
throw new RuntimeException(knowledgeBuilder.getErrors()
.toString());
}
KnowledgeBase knowledgeBase = KnowledgeBaseFactory
.newKnowledgeBase();
knowledgeBase.addKnowledgePackages(
knowledgeBuilder.getKnowledgePackages());
return knowledgeBase;
}
[/code]

Code listing 33: Creating a knowledgeBase from a spreadsheet.

As opposed to the other knowledge definitions, the decision table needs a special configuration that is encapsulated in DecisionTableConfiguration class. This configuration specifies the type of decision table and it is then passed on to the knowledge builder. The commented lines show how to create a knowledge base from a .csv format. The rest should be familiar.

Note if you want to see the generated .drl source, you can get it like this:

[code lang=”java”]
String drlString = DecisionTableFactory
.loadFromInputStream(ResourceFactory
.newClassPathResource("interest calculation.xls")
.getInputStream(), dtconf);
[/code]

Code listing 34: Getting the .drl representation of the decision table.

It is stored in a drlString string variable; it can be printed to the console and used for debugging purposes.

We’ll now write a test for depositing 125 EUR for 40 days:

[code lang=”java”]
@Test
public void deposit125EURfor40Days() throws Exception {
account.setType(Account.Type.SAVINGS);
account.setBalance(new BigDecimal("125.00"));
account.setCurrency("EUR");
account.setStartDate(DATE.minusDays(40));
account.setEndDate(DATE);
session.execute(account);
assertEquals(new BigDecimal("3.00"), account
.getInterestRate());
}
[/code]

Code listing 35: Test for depositing 125 EUR for 40 days.

The preceding test verifies that the correct interest rate is set on the account. And one test for default transactional account rate:

[code lang=”java”] @Test
public void defaultTransactionalRate() throws Exception {
account.setType(Account.Type.TRANSACTIONAL);
account.setCurrency("EUR");
session.execute(account);
assertEquals(new BigDecimal("0.01"), account
.getInterestRate());
}
[/code]

Code listing 36: Test for the default transactional account rate.

The test above, again, verifies that the correct interest rate is set.

Comma Separated values

The XLS spreadsheet can be easily converted into CSV format. Just select Save as CSV in your spreadsheet editor. However, there is one caveat—CSV format doesn’t support merging of columns by default. For overcoming this, Drools has the following workaround: if we add three dots at the end of type declarations, they will be merged into one. It can be seen in the last line of the following CSV excerpt:

[code lang=”java”] "RuleTable Interest Calculation",,,,
"CONDITION","CONDITION","CONDITION","CONDITION","ACTION"
"$a:Account…","$a:Account…","$a:Account…","$a:Account…",
[/code]

Code listing 37: Excerpt from the interest calculation.csv file.

It is the only change that needs to be done. Tests should pass for CSV format as well.

CSV is a text format as opposed to XLS, which is a binary format. Binary format makes version management harder. For example, it is very difficult to merge changes between two binary files. CSV doesn’t have these problems. On the other hand, the presentation suffers.

Rule Templates

If you like the concept of decision tables, you may want to look at Drools Rule Templates. They are similar to the decision tables but more powerful. With Rule Templates, the data is fully separated from the rule (for example, it can come from a database and have different templates over the same data). You have more power in defining the resulting rule. The data can define any part of rule (for example, condition operator, class, or property name). For more information, refer to the Rule Templates section of the Drools Experts User Guide (available at http://www.jboss.org/drools/documentation.html).

Drools Flow

Drools Flow (or ruleflow in short) is another way we can have human readable rules. It is not a substitute to rules as was the case with DSLs and decision tables. It is a way of defining the execution flow between complex rules. The rules are then easier to understand.

Drools Flow can externalize the execution order from the rules. The execution order can be then managed externally. Potentially, you may define more execution orders for one KnowledgeBase.

Drools Flow can be even used as a workflow engine replacement. It can execute arbitrary actions or user-defined work items at specific points within the flow. It can be even persisted as we’ll see in Chapter 8, Drools Flow, which shows a bigger example of using ruleflows.

Drools Agenda

Before we talk about how to manage rule execution order, we have to understand Drools Agenda. When an object is inserted into the knowledge session, Drools tries to match this object with all of the possible rules. If a rule has all of its conditions met, its consequence can be executed. We say that a rule is activated. Drools records this event by placing this rule onto its agenda (it is a collection of activated rules). As you may imagine, many rules can be activated, and also deactivated, depending on what objects are in the rule session. After the fireAllRules method call, Drools picks one rule from the agenda and executes its consequence. It may or may not cause further activations or deactivations. This continues until the Drools Agenda is empty. The purpose of the agenda is to manage the execution order of rules.

Methods for managing rule execution order

The following are the methods for managing the rule execution order (from the user’s perspective). They can be viewed as alternatives to ruleflow. All of them are defined as rule attributes.

• salience: This is the most basic one. Every rule has a salience value. By default it is set to 0. Rules with higher salience value will fire first. The problem with this approach is that it is hard to maintain. If we want to add new rule with some priority, we may have to shift the priorities of existing rules. It is often hard to figure out why a rule has certain salience, so we have to comment every salience value. It creates an invisible dependency on other rules.
• activation-group: This used to be called xor-group. When two or more rules with the same activation group are on the agenda, Drools will fire just one of them.
• agenda-group: Every rule has an agenda group. By default it is MAIN. However, it can be overridden. This allows us to partition Drools Agenda into multiple groups that can be executed separately.

The figure above shows partitioned Agenda with activated rules. The matched rules are coming from left and going into Agenda. One rule is chosen from the Agenda at a time and then executed/fired.

At runtime we can programmatically set the active Agenda group (through the getAgenda().getAgendaGroup(String agendaGroup).setFocus() method of KnowledgeRuntime), or declaratively, by setting the rule attribute auto-focus to true. When a rule is activated and has this attribute set to true, the active agenda group is automatically changed to rule’s agenda group. Drools maintains a stack of agenda groups. Whenever the focus is set to a different agenda group, Drools adds this group onto this stack. When there are no rules to fire in the current agenda group, Drools pops from the stack and sets the agenda group to the next one. Agenda groups are similar to ruleflow groups with the exception that ruleflow groups are not stacked. Note that only one instance of each of these attributes is allowed per rule (for example, a rule can only be in one ruleflow-group; however, it can also
define a salience within that group).

Ruleflow

As we’ve already said, ruleflow can externalize the execution order from the rule definitions. Rules just define a ruleflow-group attribute, which is similar to agenda-group. It is then used to define the execution order. A simple ruleflow (in the example.rf file) is shown in the following screenshot:

The preceding screenshot shows a ruleflow opened with the Drools Eclipse plugin. On the lefthand side are the components that can be used when building a ruleflow. On the righthand side is the ruleflow itself. It has a Start node which goes to ruleflow group called Group 1. After it finishes execution, an Action is executed, then the flow continues to another ruleflow group called Group 2, and finally it finishes at an End node.

Ruleflow definitions are stored in a file with the .rf extension. This file has an XML format and defines the structure and layout for presentational purposes.

[code] Another useful rule attribute for managing which rules can be activated
is lock-on-active. It is a special form of the no-loop attribute. It can
be used in combination with ruleflow-group or agenda-group. If it
is set to true, and an agenda/ruleflow group becomes active/focused,
it discards any further activations for the rule until a different group
becomes active. Please note that activations that are already on the
agenda will be fired.
[/code]

A ruleflow consists of various nodes. Each node has a name, type, and other specific attributes. You can see and change these attributes by opening the standard Properties view in Eclipse while editing the ruleflow file. The basic node types are
as follows:

• Start
• End
• Action
• RuleFlowGroup
• Split
• Join

They are discussed in the following sections.

Start

It is the initial node. The flow begins here. Each ruleflow needs one start node. This node has no incoming connection—just one outgoing connection.

End

It is a terminal node. When execution reaches this node, the whole ruleflow is terminated (all of the active nodes are canceled). This node has one incoming connection and no outgoing connections.

Action

Used to execute some arbitrary block of code. It is similar to the rule consequence—it can reference global variables and can specify dialect.

RuleFlowGroup

This node will activate a ruleflow-group, as specified by its RuleFlowGroup attribute. It should match the value in ruleflow-group rule attribute.

Split

This node splits the execution flow into one or many branches. It has two properties—name and type. Name is just for display purposes. Type can have three values: AND, OR, and XOR:

• AND: The execution continues through all of the branches.
• OR : Each branch has a condition. The condition is basically same as a rule condition. If the condition is true, the ruleflow continues through this branch. There must be at least one condition that is true; otherwise, an exception will be thrown.
• XOR: Similar to OR type, each branch has a condition, but in this case, with a priority. The ruleflow continues through just one branch, whose condition is true and it has the lowest value in the priority field. There must be at least one condition that is true; otherwise, an exception will be thrown.

The dialog for defining OR and XOR split types looks like the following screenshot:

The screenshot above shows Drools Eclipse plugin ruleflow constraint editor. It is accessible from the standard Eclipse Properties view.

Join

It joins multiple branches into one. It has two properties—name and a type. Name is for display purposes. Type decides when the execution will continue. It can have following values:

• AND: Join waits for all the incoming branches. The execution then continues.
• XOR: Join node waits for one incoming branch.

Pl ease consult the Drools manual for further node types.

Example

If you look at data transformation rule in Chapter 4, Data Transformation, you’ll see that in some rules we’ve used salience to define rule execution order. For example, all of the addresses needed to be normalized (that is, converted to enum) before we could report the unknown countries. The unknown country rule used salience of -10, which meant that it would fire only after all address normalization rules. We’ll now extract this execution order logic into a ruleflow to demonstrate how it works. The ruleflow might look like the following screenshot:

When the execution starts, it goes through the Start node straight into the Split node. In this case, it is an and type split node. It basically creates two parallel branches that will be executed concurrently (note that this doesn’t mean multiple threads). We can see that the flow is explicitly specified. address normalization happens before unknown country reporting. Parallel to this branch is a default ruleflow group. It contains the other rules. Finally, a join node of type and is used to block until all branches complete and then the flow continues to the terminal node. We had to use the Join node (instead of going straight to the End node), because as soon as some branch in a ruleflow reaches the End node, it terminates the whole ruleflow (that is, our branches may be canceled before competition, which is not what we want).

The process ID is set to dataTransformation. Click on the canvas in the ruleflow editor and then in the Properties view (Eclipse Properties plugin), set the ID to this value.

Rules

Next we create copy of dataTransformation.drl file from Chapter 4 and we’ll name it dataTransformation-ruleflow.drl. We’ll make the following changes:

• Each rule gets new attribute: ruleflow-group “default”
• Except the address normalization rules for example:

[code lang=”java”] rule addressNormalizationUSA
ruleflow-group "address normalization"
[/code]

Code listing 37: Top part of the USA address normalization rule.

• Unknown country rule gets the “unknown country” ruleflow group.

KnowledgeBase setup

We c an now create a knowledge base out of the ruleflow file and the .drl file.

[code lang=”java”] static KnowledgeBase createKnowledgeBaseFromRuleFlow()
throws Exception {
KnowledgeBuilder builder = KnowledgeBuilderFactory
.newKnowledgeBuilder();
builder.add(ResourceFactory.newClassPathResource(
"dataTransformation-ruleflow.drl"), ResourceType.DRL);
builder.add(ResourceFactory.newClassPathResource(
"dataTransformation.rf"), ResourceType.DRF);
if (builder.hasErrors()) {
throw new RuntimeException(builder.getErrors()
.toString());
}
KnowledgeBase knowledgeBase = KnowledgeBaseFactory
.newKnowledgeBase();
knowledgeBase.addKnowledgePackages(builder
.getKnowledgePackages());
return knowledgeBase;
}
[/code]

Code listing 38: Method that creates KnoweldgeBase with a ruleflow.

[code] A knowledge base is created from both files .drl and .rf. To achieve
true isolation of unit tests, consider constructing the knowledge base only
from the .drl file or .rf file. That way, the unit tests can focus only on
the relevant part.
[/code]

Tests

The test setup needs to be changed as well. Ruleflows are fully supported only for stateful sessions. Stateful sessions can’t be shared across tests because they maintain state. We need to create a new stateful session for each test. We’ll move the session initialization logic from the setUpClass method that is called once per test class into the intialize method that will be called once per test method:

[code lang=”java”]
static KnowledgeBase knowledgeBase;
StatefulKnowledgeSession session;

@BeforeClass
public static void setUpClass() throws Exception {
knowledgeBase = createKnowledgeBaseFromRuleFlow();
}

@Before
public void initialize() throws Exception {
session = knowledgeBase.newStatefulKnowledgeSession();
[/code]

Code listing 39: Excerpt from the unit test initialization.

Once the stateful session is initialized, we can use it.

We’ll write a test that will create a new address map with an unknown country. This address map will be inserted into the session. We’ll start the ruleflow and execute all of the rules. The test will verify that the unknownCountry rule has been fired:

[code lang=”java”] @Test
public void unknownCountryUnknown() throws Exception {
Map addressMap = new HashMap();
addressMap.put("_type_", "Address");
addressMap.put("country", "no country");

session.insert(addressMap);
session.startProcess("dataTransformation");
session.fireAllRules();

assertTrue(validationReport.contains("unknownCountry"));
}
[/code]

Code listing 40: Test for the unknown country rule with an unknown country.

Note that the order of the three session methods is important. All of the facts need to be in the session before the ruleflow can be started and rules can be executed.

Please note that in order to test this scenario, we didn’t use any agenda filter. This test is more like an integration test where we need to test more rules cooperating together.

Another test verifies that the ruleflow works with a known country:

[code lang=”java”] @Test
public void unknownCountryKnown() throws Exception {
Map addressMap = new HashMap();
addressMap.put("_type_", "Address");
addressMap.put("country", "Ireland");

session.startProcess("dataTransformation");
session.insert(addressMap);
session.fireAllRules();

assertFalse(validationReport.contains("unknownCountry"));
}
[/code]

Code listing 41: Test for the unknown country rule with a known country.

As a stateful session is being used, every test should call the dispose method on the session after it finishes. It can be done in the following manner:

[code lang=”java”]
@After
public void terminate() {
session.dispose();
}
[/code]

Code listing 42: Calling the session.dispose method after every test.