Introduction

Wilfred Springer

Table of Contents

1. Introduction ................................................................................................................. 12. Declarative Binding ....................................................................................................... 13. Convention over configuration ........................................................................................ 34. More than just numbers ................................................................................................ 35. Composite content ....................................................................................................... 46. Inheritance .................................................................................................................. 57. Lists ........................................................................................................................... 68. Lazy loading lists .......................................................................................................... 69. Expressions ................................................................................................................. 710. Limbo ........................................................................................................................ 711. Conditionals ................................................................................................................ 812. Complex references ..................................................................................................... 813. Documentation ........................................................................................................... 9

1Introduction

Decoding a compressed data format in Java can be quite a mundane task. This chapter will hopefullyconvince you thatit does not need to be all that complicated. Preon aims to provide a simple andpowerful solution.This chapter will introduce the most important principles behind Preon. Don't expect this chapter tobe an exhaustivereference guide for everything Preon has to offer. Completeness is not consideredto be achieved if there is nothing else toadd; it is considered to be achieved if there is nothing left tobe taken out. Thesole objective of this chapter is to prevent surprises once you start to use Preon.

2Declarative Binding

Preon is not just a library allowing you to access bits in a bitstream, or a library that has a number of convenience mechansisms allowing you read data from a compressed bitstream encoded format. Itis much more than that, and - just like IoC - it obeys the Holywood paradigm: "don't call us, we callyou."If Preon would just have been a library of functions facilitating different compression mechanisms,then you would have been required to load the decoded data into your own data structures yourself.

Introduction2But Preon turns that arround: you just provide it the blueprints of the data structure, and Preon willmake sure the data gets loaded into the appropriate places.Now, the big question is of course: how does Preon know how to load data from a sequence of bitsand reconstruct a data structure? What is the recipe? It turns out, the recipe is the data structureitself; it's just classes and attributes, period. And in case it the information provided by the datastructure is not enough, we will just augment it using annotations.So, let's look at an example. Example 1, “First data structure” defines a data structure defining thecoordinates of the two points defining a rectangle, in some coordinate system.

Example 1. First data structure

class Rectangle {private int x1;private int y1;private int x2;private int y2;}

Let's just say that the data would be encoded on disk as four consecutive 32-bit integers. In that case,this is the way you would decode a Rectangle from a file:

byte[] buffer = new byte[] {0, 0, 0, 1,0, 0, 0, 2,0, 0, 0, 3,0, 0, 0, 4};Codec<Rectangle> codec = Codecs.create(Rectangle.class);Rectangle rect = Codecs.decode(codec, buffer);

That's how easy it is. Although... To be perfectly honest, the example is not entirely complete yet. If you would use the code as-is, you would not get anything at all. (Well, an empty Rectangle, maybe.)Problem is, Preon does

not

assume anything about your decoding requirements. In order to tellPreon that it needs to decode the x1, y1, x2 and y2 fields, you will need to explicitly state it in thedefinition of the data structure, like this:

Example 2. First data structure annotated

class Rectangle {@Bound private int x1;@Bound private int y1;@Bound private int x2;@Bound private int y2;}

If you run the same code now, you will get a populated Rectangle.

Introduction3

3Convention over configuration

So, binding a Java data structure to its encoded representation seems to be fairly easy. However,Preon intends to support bitstream encoded data. That is, in many cases you want don't want toallocate the full 32 bits for decoding an integer, and you would just rely on a couple of bits instead.Or what if you don't want big endian byte order, but little endian byte order instead?All of this turns out to be additional configuration only. If you just specify the @Bound annotation,you basically tell Preon to use its default mapping to decode an integer. And by default, it willassume big endian byte order, and decode an integer using 32 bits. If you want to change that, you just need to tell Preon to do so, using other annotations, or (sometimes) other annotation attributes.

Example 3. Encoding integers using two bytes

class Rectangle {@BoundNumber(size="16") private int x1;@BoundNumber(size="16") private int y1;@BoundNumber(size="16") private int x2;@BoundNumber(size="16") private int y2;}

Example 3, “Encoding integers using two bytes” changes the example given before to make Preonallocate only two bytes (16 bits) per number. ??? illustrates how to change byte order.

Example 4. Encoding integers using little endian byte order

class Rectangle {@BoundNumber(byteOrder=LittleEndian) private int x1;@BoundNumber(byteOrder=LittleEndian) private int y1;@BoundNumber(byteOrder=LittleEndian) private int x2;@BoundNumber(byteOrder=LittleEndian) private int y2;}

4More than just numbers

Preon is not just about decoding numbers. By default, it already supports much more than that. Hereare some examples:

// Will just read one bit, interpreting 1 as true, and 0 als false@Bound boolean visible;// Reads a String from a fixed number of bytes@BoundString(size="10") String value;// Reads a bit from the buffer, and interprets it as an enum value,// interpreting the number as its ordinal value.@BoundNumber(size="1") Type type;