Enhancing Composite Specifications with Message Notifications

In this blog entry we'll enhance our previous Composite Specifications implementation, in order to sending message notifications at evaluation time.

We'll take back some ideas from A notification strategy for business errors and related comments by Johannes Brodwall.
We'll use the same concept of Notification object, but intended as a carrier of generic messages (not only errors).

So, let's start with some code.

First, we need a simple Message class.

public interface Message {
    
    /**
     * Set the message code.
     * @param code The code to set.
     */
    public void setCode(String code);
    
    /**
     * Get the message code.
     * @return The message code.
     */
    public String getCode();
    
    /**
     * Set the default message string of this message object.
     * @param message The default message string.
     */
    public void setDefaultMessage(String message);
    
    /**
     * Get the default message string of this message object.
     * @return The default message string.
     */
    public String getDefaultMessage();
}

It is very simple and contains just the message code (intended to be resolved using i18n), and a default message string.

We need also the Notification class, for carrying messages all around.

public interface Notification {
    
    public enum Type { ERROR, WARNING, INFO };
    
    /**
     * Add a message.
     * @param message The message to add.
     * @param type The notification type of the message to add.
     */
    public void addMessage(Message message, Notification.Type type);
    
    /**
     * Remove a message.
     * @param message The message to remove.
     * @param type The notification type of the message to remove.
     * @return True if removed.
     */
    public boolean removeMessage(Message message, Notification.Type type);
    
    /**
     * Get messages of the given type.
     * @param type The type of messages to retrieve.
     * @return An array of messages.
     */
    public Message[] getMessages(Notification.Type type);
    
    /**
     * Check if this notification has messages of the given type.
     * @param type The type of messages to look for.
     * @return True if this notification has messages of the given type,
     * false otherwise.
     */
    public boolean hasMessages(Notification.Type type);
    
    /**
     * Get all messages contained in this notification.
     * @return An array of messages.
     */
    public Message[] getAllMessages();
    
    /**
     * Check if this notification has messages of whatever type.
     * @return True if this notification has messages,
     * false otherwise.
     */
    public boolean hasMessages();
    
    /**
     * Add to this notification all the messages contained in the notification in argument.
     * @param notification The notification whose messages must be added. 
     */
    public void addAllMessages(Notification notification);
}

The most important thing to note is that you can add generic messages and assign them a notification type: ERROR, WARNING or INFO.
This actually classify your messages and let clients do different actions based on the notification type.

How to integrate this with our CompositeSpecification?

First, let us modify the base Specification interface:

public interface Specification<O> {
    
    /**
     * Specification evaluation method.
     *
     * @param object The object to evaluate.
     * @return True if satisfied, false otherwise.
     */
    public boolean evaluate(O object);
    
    /**
     * Specification evaluation method, with a Notification object for collecting error messages.
     *
     * @param object The object to evaluate.
     * @param notification A notification object where errors regarding specification evaluation will be put.<br>
     * It can be left <code>null</code> if not used.
     * @return True if satisfied, false otherwise.
     */
    public boolean evaluate(O object, Notification notification);
    
    /**
     * Add a notification message to be notified by this specification.
     *
     * @param message The message to add.
     * @param type The notification type of the message.
     * @param whenSatisfied True if the message must be notified when the specification gets satisfied,
     * false if notified when unsatisfied.
     */
    public void addNotificationMessage(Message message, Notification.Type type, boolean whenSatisfied);
    
    /**
     * Remove a notification message.
     *
     * @param message The message to remove.
     * @param type The notification type of the message.
     * @param whenSatisfied True if the message was to be notified once satisfied,
     * false otherwise.
     * @return True if removed.
     */
    public boolean removeNotificationMessage(Message message, Notification.Type type, boolean whenSatisfied);
}

Now you have:

• The old evaluate(Object o) method, to be used when you're not interested in notifications.


• A new evaluate(Object o, Notification n) method, where the Notification object in argument will collect message notifications fired by the specification.


• Te addNotificationMessage(Message message, Notification.Type type, boolean whenSatisfied); method: it is used not only to add the message notifications the specification can fire, but also to define their notification type and when to fire them.
  Doing so, you can specify what (and what type of) message notifications to fire when the specification gets satisfied, and what to fire when not satisfied.

We've finally arrived to the new CompositeSpecification.
Here I'll show only the CompositeSpecification interface: I'm not going to show the complete code for managing Notifications because it would clutter all the blog entry.
All this stuff will be released soon as part of an Open Source project, so those interested will be able soon to take a look at the whole implementation.

Here is the refined CompositeSpecification interface:

public interface CompositeSpecification<S, O> extends Specification<O> {
    
    /**
     * Apply the logical <code>and</code> operator to this composite specification and another, supplied, composite specificaton.
     * @param specification The other composite specification.
     */
    public CompositeSpecification and(CompositeSpecification<S, O> specification);

    /**
     * Apply the logical <code>and</code> operator to this composite specification and the supplied one.
     * @param specification The supplied specification to compose.
     */
    public CompositeSpecification and(S specification);

    /**
     * Apply the logical, negated, <code>and</code> operator to this composite specification and another, supplied, composite specificaton.
     * @param specification The other composite specification.
     */
    public CompositeSpecification andNot(CompositeSpecification<S, O> specification);

    /**
     * Apply the logical, negated, <code>and</code> operator to this composite specification and the supplied one.
     * @param specification The supplied specification to compose.
     */
    public CompositeSpecification andNot(S specification);

    /**
     * Start composing the specification.<br>
     * This is the first method to be called for composition.
     * 
     * @param specification The actual specification to compose.
     */
    public CompositeSpecification compose(S specification);

    /**
     * Add a notification message to the last composed specification.
     * @param message The message to add.
     * @param type The notification type of the message.
     * @param whenSatisfied True if the message must be notified when the specification gets satisfied,
     * false if notified when unsatisfied.
     */
    public CompositeSpecification withMessage(Message message, Notification.Type type, boolean whenSatisfied);
    
    /**
     * Composite specification evaluation.
     * 
     * @param object The object to evaluate.
     */
    public boolean evaluate(O object);

    /**
     * Apply the logical <code>or</code> operator to this composite specification and another, supplied, composite specificaton.
     * @param specification The other composite specification.
     */
    public CompositeSpecification or(CompositeSpecification<S, O> specification);

    /**
     * Apply the logical <code>or</code> operator to this composite specification and the supplied one.
     * @param specification The supplied specification to compose.
     */
    public CompositeSpecification or(S specification);

    /**
     * Apply the logical, negated, <code>or</code> operator to this composite specification and another, supplied, composite specificaton.
     * @param specification The other composite specification.
     */
    public CompositeSpecification orNot(CompositeSpecification<S, O> specification);

    /**
     * Apply the logical, negated, <code>or</code> operator to this composite specification and the supplied one.
     * @param specification The actual specification to compose.
     */
    public CompositeSpecification orNot(S specification);
}

The most important things are:

• The evaluate(Object o, Notification n) method, inherited by the previously described Specification interface, to be used for collecting message notifications
  from all the composed specifications.


• The fluent-style CompositeSpecification withMessage(Message message, Notification.Type type, boolean whenSatisfied) method: it has to be used for defining a message notification fired by a composed specification (specifically, the last one added), its type and when it has to be fired.

So, considering our example classes (defined here), you can now write something like this:

CompositeSpecification<Example Specification> compositeSpecification = new CompositeSpecification<Specification>(ExampleSpecification.class, "isSatisfiedBy",   IOffice.class);

OfficeIdSpecification spec1 = new OfficeIdSpecification();
FullOfficeSpecification spec2 = new FullOfficeSpecification();

IOffice office1 = new Office();
IEmployee emp1 = new Employee();
office1.setOfficeId("o1");
emp1.setMatriculationCode("1");
office1.addEmployee(emp1);

Notification notification = ...;

compositeSpecification.compose(spec1).withMessage(new Message(...), Notification.Type.ERROR, false)
                      .andNot(spec2).withMessage(new Message(...), Notification.Type.WARNING, true)
                      .evaluate(office1, notification);

Here is how you can read the composite specification declaration: compose the specification defining the office id structure, with an error message notification to be fired when not satisfied, and the specification defining when the office is full, with a warning message notification to be fired when satisfied.
After evaluation, you'll have your notification object filled with all message notifications fired by the composite specification (obviously, if any).

Suggestions and every type of feedback are welcome!