This filter is one of the most important one. In many case, writing a MINA based application without having such a filter added is not really meaningful.
Here is a list of all the handled events in this filter :
event |
Handled |
Description |
---|---|---|
exceptionCaught |
|
N/A |
filterClose |
|
N/A |
filterSetTrafficMask |
|
Will be removed |
filterWrite |
|
|
onPostRemove |
|
Invoked when the filter is removed from the chain |
onPreAdd |
|
Invoked when this filter is added to the chain |
sessionOpened |
|
Useless. May be removed |
messageReceived |
|
A message has been read and need to be decoded |
messageSent |
|
??? |
sessionClosed |
|
An event received when the session has been closed |
sessionCreated |
|
An event received when a new session has been created |
sessionIdle |
|
N/A |
In order to be able to encode or decode a message, we need to pass the filter a factory, which will be used to create those two parts of the codec :
The factory is pretty simple. It offers two methods :
We can see that those two methods have a single parameter, an IoSession, which is a bad idea. A codec should not depend on a session. In fact, not a single codec uses this session, and I think that it should be removed.
Moreover, it forces the encoded and decoder instances to be created only when the first message is received, which can be a hassle, as ithe encoder/decoder creation has to be synchronized. It would be way better to create those instances when the filter is created.
It's also possible to pass the encoder and decoder directly, as a factory will be created internally to encapsulate those two methods.
The current handling for this event is pretty simple : it stores the Encoder and Decoder instances in the session attributes.
The encoder and decoder are stateless, we don't need to pass a session object to the getEncoder/Decoder() methods.
Thre is another problem : if we add this codec in the chain after the session has been created, then the encoder and decoder are never added into the session attributes, which is bad. This is addressed in
https://issues.apache.org/jira/browse/DIRMINA-635
This event is received when the session is closed. We have to remove the Encoder and Decoder instances from the session's attributes, and to dispose those elements. As we may have remaining messages to decode, we have to process them first.
We have different cases, as of MINA 2.0.0-M3 :
I'm not sure that we should decode anything when we receive a sessionClosed message : The session is already closed, and any other treatment may violate the client's will.
This event is received when we try to insert this filter during a session. What it does is very simple :
- Checks that the filter is not already present in the chain. If so, generates an exception
- Initialize the encoder and decoder.
Nothing much to tell about this simple handler
This event is received when this filter is removed from the chain. We simply :
Nothing much to tell about this simple handler
This is the heart of the decoding part. We receive some bytes, and we must produce some messages out of it. Again, we have many cases to consider :
We also have a special case : we received an object which is not a byte buffer.
Seems like a nonsense to me. How possibly can we go through the decoder with something we don't want to decode ?
Generally speaking, the way the decoder works is exposed in the following pseudo-code :
The callback system is a bit annoying. The idea is that once the decoder has found a message, it pushes it into a queue, and at the end, we have to do a flush() on the resulting queue : the callback holds the decoded message and the mechanism to process them (here, to call the next filter).
I think it would be way easier to get a list of decoded messages as a return from the decoder, and then loop on this list in order to keep the logic into the Codec filter, instead of delegating this logic to an external class.
A better solution, IMHO, would be to call the decoder, which will return a message or nothing (if we don't have enough bytes), and push this message to the next filter, until we can't decode anything else :
while ( ( message = decode( bytes ) ) != null ) {
nextFilter.messageReceive( message )
}
Another aspect would be to make the decoder to push the result as a stream, which will be handled by the next filter : this will allow a multi-layered decoder to be written. Decoding ASN.1 encoded PDU will typically benefit from such an approach.
Let's now analyze those 6 cases.
We just do nothing in this case. We don't even have to call the next filter.
I don't think this is a possible case, as this filter will be invoked after some bytes has been read from the socket. Anyway ...
In this case - as in the other case when we have remaining bytes - everything will depend on the capacity the decoder has to keep a transitioanl state until we can decode the message with some more bytes. The decoder has to be stateful, which all the decoder aren't.
In many cases, we must rely on a cumulative decoder, which will gather bytes up to a boundary (like a \n, for instance). The decoding process will be done in two steps :
This is not that easy, considering that many protocol do not define a clear boundary, or make it complicated to find it. For instance :
We may need to have a stateful decoder to avoid such problems, but we won't discuss this aspect here.
So what we do is to call the decoder, and if we didn't got an exception, we just call the callback which will do nothing.
This is an easy case : we simply have to decode the message, and send it to the next filter, before returning.
We have to loop after having processed the first message. We will generate an exception if the decoder can't handle partial messages, or isntead stores the remaining bytes in a context associated with the session, waiting for more bytes to come.
This is the exact same case as (3), but we will loop for each message, sending them one by one to the next filter.
We loop on each messages, as in (5), and fallback to case (2)