DLESTXETX Framing Decoder Encoder

DLESTXETX Framing Decoder/Encoder

This framing decoder extracts packets from a stream of bytes. Imagine a TCP stream of bytes coming in in arbitrary chunks. The received byte chunks are not necessarily of the same size as they have been sent.

For instance, a sender might send the following packets (separated by spaces): aaaa bb cccccccc ddd. The sequence of bytes transmitted could be received as follows: a aa abbcc ccc cccd dd. A frequent task is hence to split a stream of bytes into a sequence of packets.

A very robust, simple and self-resynchronizing framing is byte stuffing. This (de-)framing mechanism has for instance been used by HDLC (http://en.wikipedia.org/wiki/High-Level_Data_Link_Control).

This framing decoder/encoder implements a byte stuffing decoder based on a DLE STX ... DLE ETX framing.

##Mode of operation This framing mechanism uses the special ASCII characters 0x10 (called DLE or Data Link Escape), 0x02 (STX, Start of Text), 0x03 (ETX, End of Text). Each packet is framed as between "DLE STX" and "DLE ETX" as follows: DLE STX ...arbitrary.bytes.of.payload... DLE ETX.

So, when sending a packet on a stream, just transmit "DLE STX", then the payload of bytes (the content of the packet), and finally "DLE ETX". When sending the payload data, each DLE character must be doubled (i.e., DLE becomes DLE DLE). Image you want to transmit the payload "0x10", the final packet is 0x10 0x02 0x10 0x10 0x10 0x03 (or DLE STX DLE DLE DLE ETX).

A receiver must therefore look for packet start (i.e. DLE STX), read the payload and remove the second DLE if two consecutive ones are received (de-stuffing), and continue buffering until DLE ETX is found. If something goes wrong (e.g., because the stream uses UDP and not TCP and some packets have gone lost), the receiver can always resynchronize to the next start of a packet easily by discarding anything until then.

Usage

Send instances of org.jboss.netty.buffer.ChannelBuffer (called payload in the following) downstream and this encoder will create a new instance of ChannelBuffer which frames the contents of payload as described above. Any occurrences of DLE in payload will be byte stuffed.

If the decoder is placed into a pipeline, it will read data from the pipeline until a full packet has been received. Any byte-stuffed DLEs are changed back to single DLEs in the resulting payload. Once a packet has been received, the payload is sent upstream as an instance of ChannelBuffer.