@Composite for Unpacking COFF Data

A while ago, I compared Preon with Erlang’s bit syntax. I looked at one one of the examples from "Programming Erlang" in particular; an example that illustrates how to decode MPEG headers using Erlang. However, this is not the only example in that chapter, so I decided to take a stab at one of the other examples as well.

The second example from the bit syntax chapter in "Programming Erlang" is about unpacking COFF data. The thing about COFF is that it doesn’t have an IDL-alike language or anything for defining the data structures: all you have is the definition of C++ data structures, such as the one below:
[c]
typedef struct _IMAGE_RESOURCE_DIRECTORY {
DWORD Characteristics;
DWORD TimeDateStamp;
WORD MajorVersion;
WORD MinorVersion;
WORD NumberOfNamedEntries;
WORD NumberOfIdEntries;
} IMAGE_RESOURCE_DIRECTORY, *PIMAGE_RESOURCE_DIRECTORY;
[/c]
In his book, Joe Armstrong explains that using Erlang’s bit syntax and macro solutions, you would be able to unpack COFF data characterized by the C++ struct above using the Erlang code listed below.
[source]
unpack_image_resourcedirectory(Dir) ->
<<Characteristics : ?DWORD,
TimeDateStamp : ?DWORD,
MajorVersion : ?WORD,
MinorVersion : ?WORD,
NumberOfNamedEntries : ?WORD,
NumberOfIdEntries : ?WORD, /binary>> = Dir,
…
[/source]
The key message here is that Erlang not only allows you to unpack binary data easily, but that it also allows you to express that clearly maps to the only source of definition of the data structure: the C++ API.
Now, if you would use Preon only, the C++ data structure above would translate to this:
[java]
class ImageResourceDirectory {
@BoundNumber(size="32") long characteristics;
@BoundNumber(size="32") long timeDateStamp;
@BoundNumber(size="16") int majorVersion;
@BoundNumber(size="16") int minorVersion;
@BoundNumber(size="16") int numberOfNamedEntries;
@BoundNumber(size="16") int numberOfIdEntries;
}
[/java]
… and you would be able to decode it by this:
[java]
Codec<ImageResourceDirectory> codec = Codecs.create(ImageResourceDirectory.class);
Codecs.decode(codec, …);
[/java]
Now, that’s not bad, but it doesn’t have that similarity to the original C++ API code the Erlang example has. However, using Andrew Philips’ @Composite framework, you would actually be able to write this:
[java]
class ImageResourceDirectory {
@DWORD long characteristics;
@DWORD long timeDateStamp;
@WORD int majorVersion;
@WORD int minorVersion;
@WORD int numberOfNamedEntries;
@WORD int numberOfIdEntries;
}
[/java]
… which is already a lot closer to the original C++ struct than what we had before.
Support for @Composite has not been included in Preon yet. At first sight, there appear to be two ways to deal with it. First of all, it could be build into the framework, by the AnnotatedElements interface all over the place. That should work, and it might actually be the most sensible thing to do.
However, there may be an alternative way to get it woven in. Preon already defines a CodecDecorator interface that allows you wrap Codec implementations around Codec instances created. Looking at that, I started to think that it might actually be quite attractive to also define a CodecFactoryDecorator, wrapping CodecFactories around other CodecFactories in the chain of responsibility.
[java]
public interface CodecFactory {
<T> Codec<T> create(AnnotatedElement metadata, Class<T> type,
ResolverContext context);
}
[/java]
The wrappers created by the CodecFactoryDecorator would be able to intercept any reference to annotations passed down below down the chain, and replace it with an AnnotatedElement that uses AnnotatedElements to gain access to the annotations. As a consequence, CodecFactories responsible for creating the actual Codec from metadata passed in would get to see Preon annotations only, instead of the @DWORD and @WORD annotations.
It’s just a thought. None of this has been implemented yet. Feel free to comment. Expect to see some more of this in the future.