2.1.x vs 2.0.x differences

The way an application is informed that a session has been secured (ie, the SSL/TLS handshake has been successfully completed) was to use a notification system. A specific message was pushed for that purpose, up to the client application to check that message. It forced the application implementer to inject a special session attribute (SslFilter.USE_NOTIFICATION), which is a bit heavy.

It was decided to change that and make it easier for the application to get this information. The idea was to add a new event being propagated to the IoHandler interface, up to the application to react to such an event or not.

Secure session detection in Apache MINA 2.0.x

The following application code is to be used if the application needs to know if the session has been secured or not:

connector.setHandler(new IoHandlerAdapter() {
    @Override
    public void sessionCreated(IoSession session) throws Exception {
        // Add the SSL notification in the session's attribute liste
        session.setAttribute(SslFilter.USE_NOTIFICATION, Boolean.TRUE);
    }
    ...
    @Override
    public void messageReceived(IoSession session, Object message) throws Exception {
        // Check if the 'fake' session secured message notification has been received
        if (message == SslFilter.SESSION_SECURED) {
            counter.countDown();
        }
    }
} 

As we can see in this piece of code, this is a two step process:

• first we have to inform our session that we want to be informed about the secured status
• second we have to check for every received message if the session has been secured

This is a bit clumsy, as the check has to be done in the messageReceived event, which is clearly mixing concepts (the remote peer never sends such a message)

Secure session detection in Apache MINA 2.1.x

The idea was to extend the IoHandler interface with a generic event method that can be used to be informed about whatever type of event the session is subject to, beside the already processed events (session created, closed, etc).

The SslHandler code has been modified to fire this event when the session has been secured, using a dedicated event, SslEvent.SECURED. We also have modified the SslFilter code to generate a event when the session is not anymore secured, sending the SslEvent.UNSECURED event.

The following code show the difference with the previous code :

connector.setHandler(new IoHandlerAdapter() {
    @Override
    public void event(IoSession session, FilterEvent event) throws Exception {
        if (event == SslEvent.SECURED ) {
            // DO whatever the application needs to do when the session is secured
        }
    }
}

As we can see, we don’t need to initialize the session telling it to inform the application through a notification: this will be done no matter what.

Why is it API incompatible ?

The event addition in the IoHandler interface does not break your code: we always have an abstract implementation that will handle the events if your application does not.

The real issue is that if your application was using the Notification mechanism for that purpose, the new version will not send you this specific message(SslFilter.SESSION_SECURED).

Migration

This is pretty straightforward :

• get rid of the notification declaration by removing the session.setAttribute(SslFilter.USE_NOTIFICATION, Boolean.TRUE) code.
• implement the event(IoSession session, FilterEvent event) method in your application handler, checking for the SslEvent.SECURED/SslEvent.UNSECURED specific events.

and that’s it !

Future evolution

The added event mechanism could be used to other purposes, and that includes user specific needs. It’s possible to write a specific filter that will send a dedicated FilterEvent instance, for the application to process it.