You can register map listeners programmatically, using one of the methods defined by the com.tangosol.util.ObservableMap interface:

public interface ObservableMap extends java.util.Map {
void addMapListener(MapListener mapListener);
void addMapListener(MapListener mapListener,Object key, boolean fLite);
void addMapListener(MapListener mapListener,
Filter filter, boolean fLite);
void removeMapListener(MapListener mapListener);
void removeMapListener(MapListener mapListener, Object key);
void removeMapListener(MapListener mapListener, Filter filter);
}

As you can see, there are three overloads of the addMapListener method, as well as the matching variants of the removeMapListener method, which is used to unregister a listener.

The first method registers a cache-wide listener that receives all cache events, as well as the old and new values. This method is also called when you register a listener in the configuration file.

The second overload of addMapListener allows you to register for events on a single cache entry by specifying the entry key as the second argument. You can also choose whether to receive standard or lite events by specifying fLite flag as the third argument.

Finally, using the third overload you can register for events based on filter evaluation, and this is probably the most interesting of the three. What it basically allows you to do is to register interest in events that occur within a subset of cache entries that satisfy certain criteria. For example, you could register to be notified whenever a withdrawal exceeding a certain amount is posted for a specific account.

This method can also be used to listen for lite events on the cache as a whole, which the first method doesn't allow you to do. You can achieve this by passing AlwaysFilter.INSTANCE as the filter argument.

Listening for events based on a filter presents some interesting challenges. For instance, when you update a cache entry, that update could impact whether that entry satisfies the filter or not. When an entry that didn't match the filter is modified so it does, should that be treated as an update or as an insert event? Similarly, when an entry that did match the filter is modified so it doesn't anymore, should that be treated as update or a delete event?

The answer is that Coherence only raises insert and delete events when an entry is physically inserted into or removed from the cache, so the answer to both of the above questions is that an update event will be raised. However, because it is sometimes important to know whether an update happened within the filter, or caused an entry to enter or leave the filter, Coherence provides a special filter type, MapEventFilter, which allows you to more selectively register for events.

NamedCache accounts = CacheFactory.getCache("accounts");
accounts.addMapListener(new BalanceChangedListener(),
new ValueChangeEventFilter("getBalance"), false);

public interface MapEventTransformer {
MapEvent transform(MapEvent event);
MapEventTransformerabout}

public class BalanceChangedEventTransformer
implements MapEventTransformer, PortableObject {
public MapEvent transform(MapEvent mapEvent) {
Account oldAccount = (Account) mapEvent.getOldValue();
Account newAccount = (Account) mapEvent.getNewValue();
return new MapEvent(mapEvent.getMap(), mapEvent.getId(),
mapEvent.getKey(), oldAccount.getBalance(),
newAccount.getBalance());
}
// serialization methods omitted for brevity
}

NamedCache accounts = CacheFactory.getCache("accounts");
Filter filter = new MapEventTransformerFilter(
new ValueChangeEventFilter("getBalance"),
new BalanceChangedEventTransformer());
accounts.addMapListener(new BalanceChangedListener(),
filter, false);

NamedCache accounts = CacheFactory.getCache("accounts");
Filter filter = new MapEventTransformerFilter(
new ValueChangeEventFilter("getBalance"),
new ExtractorEventTransformer("getBalance"));
accounts.addMapListener(new BalanceChangedListener(), filter, false);

As mentioned at the beginning of this section, you can also register cache listeners by specifying them in the cache configuration file. All you need to do is add a listener element to the cache scheme configuration, and specify the fully qualified name of the class implementing a listener:

<distributed-scheme>
<scheme-name>example-distributed</scheme-name>
<service-name>DistributedCache</service-name>
<listener>
<class-scheme>
<class-name>BalanceChangedListener</class-name>
</class-scheme>
</listener>
<backing-map-scheme>
<local-scheme>
<scheme-ref>unlimited-backing-map</scheme-ref>
</local-scheme>
</backing-map-scheme>
<autostart>true</autostart>
</distributed-scheme>

While this allows us to register a listener automatically on every node in the cluster, it has several major drawbacks:

For all these reasons, you should register listeners within the cache configuration file only when you have a listener that can be applied to multiple caches and needs to listen for all events and receive old and new value. Otherwise, you are better off registering a more specifically targeted listener programmatically, as described in the previous sections.

What we want is an abstract base class that provides convenience methods that allow us to extract key and values from the internal representation of a MapEvent and convert them to their standard object form. We will also implement a method that allows us to convert a whole MapEvent instance at once, which might be more convenient if you need to convert both the key and the values. Finally, because backing map events can be triggered not only by regular inserts, updates, and deletes, but also by cache evictions or distributions, we will add a few methods that allow us to differentiate among these event causes.

Anyway, to cut long story short, here is what our base class for backing map listeners might look like:

public abstract class AbstractBackingMapListener
extends AbstractMapListener {
private BackingMapManagerContext context;
protected AbstractBackingMapListener(
BackingMapManagerContext context) {
this.context = context;
}
protected BackingMapManagerContext getContext() {
return context;
}
protected MapEvent convertFromInternal(MapEvent event) {
return ConverterCollections.getMapEvent(
event.getMap(), event,
context.getKeyFromInternalConverter(),
context.getValueFromInternalConverter());
}
protected Object getKey(MapEvent event) {
return context.getKeyFromInternalConverter() .convert(event.getKey());
}
protected Object getOldValue(MapEvent event) {
return context.getValueFromInternalConverter() .convert(event.getOldValue());
}
protected Object getNewValue(MapEvent event) {
return context.getValueFromInternalConverter() .convert(event.getNewValue());
}
protected boolean isEviction(MapEvent event) {
return context.isKeyOwned(event.getKey())
&& event instanceof CacheEvent
&& ((CacheEvent) event).isSynthetic();
}
protected boolean isDistribution(MapEvent event) {
return !context.isKeyOwned(event.getKey());
}
}

The getKey, getOldValue, and getNewValue methods should be self-explanatory, as we discussed usage of backing map converters in the previous chapter, so let's focus on the topics we haven't covered yet.

The com.tangosol.util.ConverterCollections class is a utility class that provides a number of methods that either allow you to convert items stored in various collection types, or in the case of a getMapEvent method, a wrapper implementation of a MapEvent that lazily converts the key and the values.

Finally, let's look at the methods that allow us to determine the cause of an event. The isEviction method returns true if the MapEvent is an instance of a more specific CacheEvent class and is a synthetic event, meaning that it didn't occur as a result of direct cache manipulation by the application.

The isDistribution method returns true if the key of the entry that raised the event does not belong to the backing map we are working with anymore, which implies that Coherence had to repartition data due to changes in cluster membership.

That pretty much concludes our discussion of the base class for backing map listeners, so we are ready to extend it and implement our first real backing map listener.

Now that we have both the base class and the LowBalanceAlertTask implemented, the implementation of the actual LowBalanceListener is quite simple:

public class LowBalanceListener extends AbstractBackingMapListener {
private static final WorkManager lowBalanceAlertManager =
WorkManagerFactory.getInstance("LowBalanceAlertManager", 3);
private int lowBalance;
public LowBalanceListener(BackingMapManagerContext context,
int lowBalance) {
super(context);
this.lowBalance = lowBalance;
}
public void entryUpdated(MapEvent event) {
Account account = (Account) getNewValue(event);
if (account.getBalance().intValue() < lowBalance) {
try {
lowBalanceAlertManager.schedule(
new LowBalanceAlertTask(account));
}
catch (WorkException e) {
log(e);
}
}
}
}

The first thing we do is obtain a reference to a WorkManager instance. In this case, we have done that using the WorkManagerFactory.getInstance method, which allows us to specify the number of worker threads we want our Work Manager to use.

Our constructor accepts both the BackingMapManagerContext instance and the threshold amount we should use when checking if the balance is too low. We will see shortly how both of these arguments are passed to the constructor.

Finally, we implement the entryUpdated method to obtain a converted Account instance from the event, and to schedule LowBalanceAlertTask for execution if the balance is lower than the threshold.

In this case we don't really care if the alert tasks execute or not, so we simply log any exceptions that might occur when scheduling the task for execution, and we don't wait for its completion, which would in this case defeat the purpose of using WorkManager for asynchronous execution in the first place.

That's really all there is to it, so we are ready to connect the dots by registering our listener with the backing map.

There are many existing validation frameworks out there, either as independent utilities or within larger frameworks, such as Spring or XWork/Struts 2. There is also a soon-to-be-final JSR-303: Bean Validation, which is based on Hibernate Validation and aims to standardize validation of JavaBeans. The result of JSR-303 will likely be included in the future release of Java SE, so the natural question is why we don't just use that, instead of building another, non-standard validation framework.

The answer is: we won't build a whole framework. We will simply build a thin abstraction layer that uses JSR-303 validation under the hood by default, but also allows us to perform data validation using a hand-coded Java class or even a script written in one of the languages supported by the Scripting API, which has been a standard part of Java SE since version 6.

The reason that we want this flexibility is that JSR-303 is purely metadata driven, which has some inherent limitations. One of them is that you cannot easily perform conditional validation, where certain properties of an object are either not validated or are validated differently based on the state of other properties. An example would be validation of an account transaction where we want to make sure that the transaction amount is not more than $300, but only if the transaction type is ATM withdrawal. While you can achieve this to a certain extent using JSR-303 validation groups, it requires you to validate a specific group explicitly, instead of adapting constraints dynamically based on the state of the TransactionType property.

Second, being able to implement a validator using a custom Java class or a script makes it much easier to integrate things such as rules engines into your validations.

The first step we need to take is to define an interface that will allow us to initiate validation of an object and obtain the result:

public interface Validator
extends Serializable {
ValidationResult validate(Object target);
}

The result of the validation should include two things—whether or not it was successful and a collection of error messages if it wasn't:

public interface ValidationResult
extends Serializable {
boolean isValid();
Collection<String> getErrorMessages();
}

That's really all we need from the API perspective. In the sample code for the book, you will also find two concrete implementations of the Validator interface—DefaultValidator, which uses JSR-303 validation and ScriptValidator, which uses Java Scripting API to execute script-based validators. Of course, you can also create custom Java classes that implement the Validator interface, if that's what you prefer.

Also, notice that both validators and results must be serializable, as they will need to be moved across the wire when registering a trigger or throwing a validation exception.

Now that we have a validation framework in place, implementing ValidationTrigger is fairly straightforward:

public class ValidationTrigger
implements MapTrigger, PortableObject {
private Validator validator;
public ValidationTrigger() {
validator = Validator.DEFAULT;
}
public ValidationTrigger(Validator validator) {
this.validator = validator;
}
public void process(Entry entry) {
ValidationResult result = validator.validate(entry.getValue());
if (!result.isValid()) {
throw new ValidationException(result);
}
}
// serialization methods omitted for brevity
}

As you can see, all we need to do is perform the validation using the specified validator and throw a ValidationException if the object is not valid.

One final thing to note is that map triggers must be serializable and override the equals and hashCode methods. Otherwise, if you register the same trigger multiple times (which is highly probable considering that you will likely invoke the registration method from each cluster node, as you'll see shortly) there will be multiple redundant registrations inside the cluster that will be performing the same processing and have the same ultimate result.

The final thing we need to do in order to activate the ValidationTrigger we just implemented is to register it with the cache. In order to do that, we need to register a special map listener called MapTriggerListener:

NamedCache transactions = CacheFactory.getCache("transactions");
transactions.addMapListener(
new MapTriggerListener(new ValidationTrigger()));

The previous code snippet would register our ValidationTrigger with the transactions cache and would use the default JSR-303-based validator to validate Transaction objects when they are inserted into the cache.

If we wanted to validate transactions using Groovy script instead, we could accomplish that by simple registering the trigger slightly differently:

transactions.addMapListener(
new MapTriggerListener(
new ValidationTrigger(
new ScriptValidator(
"groovy",
"validators/transaction.groovy"))));

It should be noted that the MapTriggerListener is really more of a hack whose only purpose is to register a map trigger with the cache service. It is never used as a true map listener, and it has to be registered globally, using single-argument addMapListener overload.

My personal preference is to bury MapTriggerListener and its registration deep under the hood by providing a utility registerMapTrigger method in the AbstractCoherenceRepository class. That way all I need to worry about is how to create a trigger instance, and the registerMapTrigger method takes care of the rest.