Title: MINA 2.1.x vs MINA 2.0.x
Notice:    Licensed to the Apache Software Foundation (ASF) under one
           or more contributor license agreements.  See the NOTICE file
           distributed with this work for additional information
           regarding copyright ownership.  The ASF licenses this file
           to you under the Apache License, Version 2.0 (the
           "License"); you may not use this file except in compliance
           with the License.  You may obtain a copy of the License at
           .
             http://www.apache.org/licenses/LICENSE-2.0
           .
           Unless required by applicable law or agreed to in writing,
           software distributed under the License is distributed on an
           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
           KIND, either express or implied.  See the License for the
           specific language governing permissions and limitations
           under the License.

# 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 colmpleted) 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:

    :::java
    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 informaed 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 :

    :::java
    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.