Message interceptors

mpermar edited this page Sep 1, 2011 · 2 revisions

Message Interceptors let developers to intercept Rayo messages before they are handled by the server or dispatched to the client applications. That way, service developers can add their custom logic to validate data, remove sensitive information or to enforce things like outbound dialing privileges and CDR.

Creating custom Message Interceptors

Developers can create their own Message Interceptors by implement the MessageFilter interface which defines only three methods:

public interface MessageFilter {
	public void handleCommandRequest(CallCommand command, FilterContext context);
	public void handleCommandResponse(Object response, FilterContext context);
	public void handleEvent(CallEvent event, FilterContext context);
}

Each of the MessageFilter methods reflect one of the three different Rayo Server objects that flow between the client and the server. The rules are the following:

  • handleCommandRequest: It is invoked after the Rayo command has been received and before it has been executed.
  • handleCommandResponse: It is invoked after the Command has been executed and before the Command response has been sent to the client.
  • handleEvent: It is invoked after the event has been handled and before it has been sent to the client.

Passing context data between message filters

Each MessageFilter method receives an instance of FilterContext. The filter context object is created by the Rayo Server and it can be used to share data across a chain of Message Interceptors. Each time an Event, Command Request or Command Response is processed, the Rayo Server will create a chain of Message Interceptors and will invoke these interceptors in sequence. For each of these invocations the Rayo Server does create a new instance of a filter context.

Therefore, you can use the setAttribute/getAttribute methods from the FilterContext class to pass context data between all your different Message Interceptors which may come very handy when you want to to isolate your business logic in different interceptor implementations.

Packaging and deploying custom Message Interceptors

As other Rayo services, custom Message Interceptors can be deployed very easily thanks to the Rayo Server SPI support. Once you have your Message Interceptor implementation ready, you need to package it in a JAR file. But before doing that, you need to add an SPI resource descriptor file. As you will see, this is not a very hard task. However you may find the official docs at Oracle's website.

Basically you need to create the following text file and add it to your JAR file:

   META-INF/services/com.rayo.server.filter.MessageFilter

And inside that text file you add one line for each of your implementations of the StorageService interface, like for example:

com.acme.company.BillingMessageFilter    # Will remove any sensitive data from SIP Headers

You can find an example of this META-INF file here.