3.3.1 - Dynamic headers

Not all headers are all that simple. Some headers have optional sub headers and fields within them. Some headers are variable length and may contain array's of fields or structures.

As mentioned in previous section, headers extends JBuffer class. In actuality they extend JHeader class which extends JBuffer class. The JHeader is in between the actual protocol definition and the buffer from which it reads data out of. When a header is peered in the JPacket.getHeader() method, at the time everything has been setup for the header, a hook is called to allow the protocol do any special processing it requires.

Specifically the method JHeader.decode() is called. By default this method doesn't do anything for the general case, but it can be override by a protocol header and that is where the header can use any custom logic for optional headers. Since a header is a normal java class, the developer of the definition is able to create any additional methods, fields both public and private, store additional flags, etc. Anything that will allow the protocol header to remember its dynamic state. If the header does keep private or private data in the class instance, the developer needs to make sure that this data is reset within every decode call, or peering. Remember that these header instances are reused from one packet to the next. It is essential that the header instance be reset to a known state to accurately reflect its new state with a new packet.

Dynamic headers, that have optional fields, typically offer additional accessor methods that can check if a particlar fields is present or not. Since public fields and methods are documented by javadoc just like any other class, the developer of the protocol header can include any such support methods but needs to make sure that those methods and fields are properly documented in javadocs.