Under The Hood

What's going on behind the scenes?

Wilfred Springer

Table of Contents

1. Codec .......................................................................................................................... 12. CodecFactory ............................................................................................................... 22.1. CompoundCodecFactory ...................................................................................... 52.2. WholeNumberCodecFactory ................................................................................. 52.3. BooleanCodecFactory ......................................................................................... 62.4. ObjectCodecFactory ........................................................................................... 62.5. ListCodecFactory ................................................................................................ 73. Binding ....................................................................................................................... 74. CodecDecorator ........................................................................................................... 84.1. LazyLoadingCodecDecorator ................................................................................. 84.2. SlicingCodecDecorator ........................................................................................ 8The previous chapter introduced a couple of simple introductory cases, showing some of the tricksthe framework has up its sleeves if you do not feel the desire to customize anything. While you werereading that chapter, you might have already gone like "hmmm, that's sweet, but unfortunately itdoesn't work in my corner case". If that's what you thought, then this is the chapter you need.In this chapter, I will explain what is actually goingon under the hood, in order to understand howto extend the framework yourself. The focus in this chapter is on four major abstractions: theCodec interface itself, the CodecFactory interface, the Binding interface and the CodecDecoratorinterface. In addition to discussing the actual interface, this chapter will also discuss some of theimplementations, in order to help you to understand how everything fits together.

1Codec

Let's first revisit the Codecinterface. In the previous chapter, we already talked about the way youuse this interface. In fact, we said that you better use the Codecs convenience class in all cases. If you do that, then there is actually very little to know about the Codec interface itself. It just magicallyworks.However, if you want to extend the framework yourself, then this is the

first

interface you reallyneed to understand, since this is probably the interface you need to implement.

Figure 1. Codec Interface

public interface Codec<T> {

Under The Hood2

T decode(BitBuffer buffer, Resolver resolver, Builder builder)throws DecodingException;int getSize(Resolver resolver);Expression<Integer, Resolver> getSize();CodecDescriptor getCodecDescriptor();Class<?>[] getTypes();Class<?> getType();}

The

decode(BitBuffer, Resolver, Builder)

is obviously the operation that will decode datafrom the

BitBuffer

into an instance of

.The

Resolver

allows the

Codec

to resolve references used in Preon annotations.The Codec interface is the interface implemented by objects that are able to decode data from aBitBuffer and to encode data into a BitBuffer

. In addition to that, the Codec needs to be able tomake some sort of prediction on the number of bits occupied by the encoded data. And last but notleast, the Codec needs to be able to return a CodecDescriptor, used for rendering documents with adescription of the Codec.When I just said that Codecs are capable of decoding data from a BitBuffer, you could have actuallyread 'decoding an object from a BitBuffer'. Codecs are associated to a single type, and are expectedto return only a single instances of that type from the BitBuffer.In many cases, your objects will hold references to many other objects. Does that mean that a singleCodec needs to be able to recursively traverse the object graph and understand how to decode eachof the individual members of the objects that it encounters?The answer to that question is both yes and no. "Yes", since whenever you invoke decode on theCodec, it needs to be able to reproduce all objects that are referenced by the object that is goingto be returned. "No", since the Codec does not have to understand all of that itself. It can simplydelegate to other Codecs, one for every type of attribute it encounters.If you are decoding an object, you

could

actually use the Codec interface directly. If you create aninstance using the

Codecs

class, they just magically know what to do. We just learned that Codecsconstructed like this, will most likely delegate their work to other Codecs, which in turn will mostlikely delegate their work to other Codecs, and so on and so forth. This way, the Codec both

hides

achain of responsibility, but is also able to act as a

link

inside a chain of responsibility.

2CodecFactory

The previous section ended with stating that a single Codec most likely delegates to other Codecs,which in turn delegate to other Codecs, etc. Obviously, each Codec has to be constructed before itcan be used. All of these instances are created as a result of the create() method on Codecs. But howdoes the Codecs class know which ones to create?As you might have already have guessed by its name, it is of course the CodecFactory. TheCodecFactory a single operation, that is expected to be able to return Codec from the context passedin, or return

null

The latter is currently not supported yet, but it's not unlikely that it's going to be implemented in the future.

Under The Hood3

Figure 2. CodecFactory Interface

public interface CodecFactory {<T> Codec<T> create(AnnotatedElement metadata,Class<T> type,ResolverContext context);}

Almost every type of Codec you will ever use, will be created by a CodecFactory. If you are searchingthe Preon codebase for the different type of Codecs supported by it, then chances are you willstumble across CodecFactories only. And if you want to extend the framework with your ownCodecs, the thing you actually need to pass to the Codecs class is a CodecFactory, and not a Codec.The CodecFactory needs to be able to create a Codec from three parameters passed in. The type of object expected, a socalled ResolverContext and metadata. If the Codec is used to decode data to beinjected in a field, then the metadata provides access to the annotations defined on that field

.The third parameter (ResolverContext) is a Limbo ReferenceContext. This is the object that supportsyour CodecFactory in creating references to the context of the field for which it is currently trying tocreate a reference.

Example 1. Expression sample

class Stuff {@Bound int nrOfThings;@BoundList(size="nrThings") Thing[] things;}

Let's take the class above as an example, and assume that your CodecFactory needs to see if it isable to construct a Codec for the "things" field. The annotation contains an expression defining thenumber of "things" in the array. However, the

size

annotation attribute is just a String.In order to be able to turn the expresion "nrOfThings" into something usable, we need to turn thatexpression into something we can actually evaluate - in this case, a Limbo Expression object. And if there is a problem with this expression, we obviously want to find out early.

In general, the CodecFactory should not rely on the assumption that the metadata passed in is based on a field. It should just treat it as anumber of hints suggesting how to decode data.