Messaging topics

Besides services, Brutusin-RPC allows the developer to create Topics, a programming model based on the Publish–subscribe pattern that lets the applications define client-side functionality that can be triggered on the certain sever events.

In this framework, Topics are implemented over Websockets.

##Server code Brutusin-RPC topics offer an additional message filtering capability to the standard publish–subscribe model. A filter parameter can be defined to discriminate among subscribers of a topic, that is, messages are delivered only to those topic subscribers that satisfy the filtering criteria.

###Topic implementation A Brutusin-RPC topic is an instance of a class extending org.brutusin.rpc.websocket.Topic<F,M>, being F the filter class, and M the message class.

These are the principal methods to consider when implementing a topic:

• public abstract Set<WritableSession> getSubscribers(F filter). This is the only method required to be implemented. Returns the subset of subscribers that satisfy the filtering criteria.
• public final Set<WritableSession> getSubscribers() Returns the whole collection of active topic subscribers.
• protected void onSubscribe/onUnsubscribe(WritableSession session) These two methods are auxiliary methods that subclasses can implement to be keep track by themselves of the actual subscribers of the topic, and create data structures better suited for a efficient topic filtering than iterating over the whole collection of subscribers.

###Publishing from actions

Actions publish messages to topics using the method

• public final void fire(F filter, M message)

###Topic registration

Topics are registered the same way as services: using Spring. See Component Registration wiki for more details.

##Client subscription

Topic subscription and unsubscription are implemented by the buitin Websocket services rpc.topics.subscribe rpc.topics.unsubscribe respectively. The Javascript API handles this interactions and provides a high level API to the developer:

• wsk.subscribe(topic, callback)
• wsk.unsubscribe(topic, callback)

being:

• topic: The topic id
• callback: A callback function to be notified with the topics messages (function(message))

##Testing

As services, Topics can be tested directly from a simple main() execution, opening the functional testing module with the topic detail and a auto generated publisher service.

public static void main(String[] args) {
	Server.test(new TopicTest());
}

##Example

public class TopicTest extends Topic<Void, String>{

    @Override
    public Set<WritableSession> getSubscribers(Void f) {
        return getSubscribers();
    }
    
    public static void main(String[] args) {
        Server.test(new TopicTest());
    }
}