gov.lbl.dsd.sea.nio.util
Class COBSCodec

java.lang.Object
  gov.lbl.dsd.sea.nio.util.COBSCodec

public class COBSCodec

extends Object

Encoder/Decoder implementing Consistent Overhead Byte Stuffing (COBS) for efficient, reliable, unambigous packet framing regardless of packet content, making it is easy for applications to recover from malformed packet payloads.

For details, see the paper . In case the link is broken, get it from the paper's author .

Quoting from the paper: "When packet data is sent over any serial medium, a protocol is needed by which to demarcate packet boundaries. This is done by using a special bit-sequence or character value to indicate where the boundaries between packets fall. Data stuffing is the process that transforms the packet data before transmission to eliminate any accidental occurrences of that special framing marker, so that when the receiver detects the marker, it knows, without any ambiguity, that it does indeed indicate a boundary between packets.

COBS takes an input consisting of bytes in the range [0,255] and produces an output consisting of bytes only in the range [1,255]. Having eliminated all zero bytes from the data, a zero byte can now be used unambiguously to mark boundaries between packets.

This allows the receiver to synchronize reliably with the beginning of the next packet, even after an error. It also allows new listeners to join a broadcast stream at any time and without failing to receive and decode the very next error free packet.

With COBS all packets up to 254 bytes in length are encoded with an overhead of exactly one byte. For packets over 254 bytes in length the overhead is at most one byte for every 254 bytes of packet data. The maximum overhead is therefore roughly 0.4% of the packet size, rounded up to a whole number of bytes. COBS encoding has low overhead (on average 0.23% of the packet size, rounded up to a whole number of bytes) and furthermore, for packets of any given length, the amount of overhead is virtually constant, regardless of the packet contents."

This class implements the original COBS algorithm, not the COBS/ZPE variant.

There holds: decode(encode(src)) = src.

Performance Note: The JDK 1.5 server VM runs decode(encode(src)) at about 125 MB/s throughput on a commodity PC (2 GHz Pentium 4). Encoding is the bottleneck, decoding is extremely cheap. Obviously, this is way more efficient than Base64 encoding or similar application level byte stuffing mechanisms.

Version:

$Revision: 1.3 $, $Date: 2004/08/08 05:10:17 $

Method Summary

static byte[]	decode(byte[] src) Returns the decoded representation of the given bytes.
static void	decode(byte[] src, int from, int to, ArrayByteList dest) Adds (appends) the decoded representation of the range src[from..to) to the given destination list.
static byte[]	encode(byte[] src) Returns the encoded representation of the given bytes.
static void	encode(byte[] src, int from, int to, ArrayByteList dest) Adds (appends) the encoded representation of the range src[from..to) to the given destination list.
static int	maxEncodedSize(int size) Returns the maximum amount of bytes an ecoding of size bytes takes in the worst case.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

encode

public static byte[] encode(byte[] src)

Returns the encoded representation of the given bytes. Inefficient method, but easy to use and understand.

Parameters:

src - the bytes to encode

Returns:

the encoded bytes.

encode

public static void encode(byte[] src,
                          int from,
                          int to,
                          ArrayByteList dest)

Adds (appends) the encoded representation of the range src[from..to) to the given destination list.

Parameters:

src - the bytes to encode

from - the first byte to encode (inclusive)

to - the last byte to encode (exclusive)

dest - the destination list to append to

maxEncodedSize

public static int maxEncodedSize(int size)

Returns the maximum amount of bytes an ecoding of size bytes takes in the worst case.

decode

public static byte[] decode(byte[] src)
                     throws IOException

Returns the decoded representation of the given bytes. Inefficient method, but easy to use and understand.

Parameters:

src - the bytes to decode

Returns:

the decoded bytes.

Throws:

IOException

decode

public static void decode(byte[] src,
                          int from,
                          int to,
                          ArrayByteList dest)
                   throws IOException

Adds (appends) the decoded representation of the range src[from..to) to the given destination list.

Parameters:

src - the bytes to decode

from - the first byte to decode (inclusive)

to - the last byte to decode (exclusive)

dest - the destination list to append to

Throws:

IOException - if src data is corrupt (encoded erroneously)