Events

Events in MECEAP works through Spring, for a CustomRoot is not necessary set @EnableScheduling nor @EnableAsync, they are already active.

We reccomend all the events classes extend BaseApplicationEvent class to avoid desserialization problems that may occur because of Java Serializer/Desserializer.

Distributed and Persistent Events

MECEAP implements distributed and persistent queue and topic events using ActiveMQ. However, anything related directly to ActiveMQ or Spring JMS should not be used, there are abstract annotations to be used in Spring Application Events to make a queue or a topic.

Queue Events

A Queue implements load balancer semantics. A single message will be received by exactly one consumer. If there are no consumers available at the time the message is sent it will be kept until a consumer is available that can process the message. If a consumer receives a message and does not acknowledge it before closing then the message will be redelivered to another consumer. A queue can have many consumers with messages load balanced across the available consumers.

Annotation to mark an Application Event as queue:

public @interface MessagingQueue {
    /**
     * MessageGroup Id, it`s like parallel exclusive message, the message is exclusive inside this group.
     * This annotation supports Spel Expression
     * @see <a href="http://activemq.apache.org/message-groups.html">MessageGroups</a>
     */
    String messageGroup() default "";
    /**
     * With this set, it avoid duplicated pending messages
     * This annotation supports Spel Expression
     */
    String uniqueId() default  "";
    /**
     * Used to set an identification to the message.
     * Supports Spel Expression to be used
     */
    String identification() default "";
}

An example of a Queue Application Event:

@MessagingQueue(messageGroup = "${issueDoc.header.reporter.name}", uniqueId = "${issueDoc.id}", identification = "Issue #${issueDoc.id}")
public class IssueDocSavedEvent extends BaseApplicationEvent {

    private IssueDoc issueDoc;

    public IssueDocSavedEvent(Object source, IssueDoc issueDoc) {
        super(source);
        this.issueDoc = issueDoc;
    }

    public IssueDoc getIssueDoc() {
        return issueDoc;
    }
}

Topic Events

Topic implements publish and subscribe semantics. When you publish a message it goes to all the subscribers who are interested - so zero to many subscribers will receive a copy of the message. Only subscribers who had an active subscription at the time the broker receives the message will get a copy of the message.

Annotation to mark an Application Event as topic:

public @interface MessagingTopic {
    /**
     * Set if message is persistent
     * @see <a href="http://activemq.apache.org/what-is-the-difference-between-persistent-and-non-persistent-delivery.html">Persistent Delivery</a>
     */
    boolean persistent() default true;

    /**
     * All listeners will process the message except the listener in the same Context as producer
     */
    boolean avoidEcho() default false;
    /**
     * Used to set an identification to the message.
     * Supports Spel Expression to be used
     */
    String identification() default "";
}

An example of a Topic Application Event:

@MessagingTopic(persistent = false)
public class IssueDocIndexEvent extends BaseApplicationEvent {

    private IssueDoc issueDoc;

    public IssueDocIndexEvent(Object source, IssueDoc issueDoc) {
        super(source);
        this.issueDoc = issueDoc;
    }

    public IssueDoc getIssueDoc() {
        return issueDoc;
    }
}

Monitoring

There is a page in CEAP Admin to admin queues, messages. This page can be access by Permissions: - PERM_SYS_QUEUE_MESSAGES_SYSTEM: For System Roles, list queue messages from all Applications - PERM_SYS_QUEUE_MESSAGES: List queue messages - PERM_SYS_QUEUE_MESSAGES_REMOVE: Remove a message from a queue - PERM_SYS_QUEUE_MESSAGES_RETRY: Reprocess/Retry a message from a queue

When a message throws an error, the system tries to process it 5 times, after this the message is sent to a DLQ (Dead Letter Queue) with the same queue name with the prefix 'DLQ.', there a message can be reprocessed (sending to original queue again) or deleted. It's not possible to the processed messages, only the processed counter.