This article describes the structure and characteristics of codecs in KaDeck Desktop and KaDeck Web. It is recommended to read this article carefully before developing a custom codec.
The structure of codecs
Codecs can be separated into two different parts:
- Decoding (message consumption)
- Encoding (message ingestion)
When records are waiting to be decoded, a consumption request is being issued. Analogously an ingestion request is being published when messages are waiting to be encoded.
Features and characteristics
Besides the apparent decoding and encoding functionalities, a codec in KaDeck has some unique characteristics:
- Lifecycle methods allow for preparation before the decoding and encoding process and when a new server connection is made. This is useful when integrating other (web) services to gather additional information required for the encoding/decoding process.
- Codec configuration objects give access to the details of the server configuration during the initialization and preparation phase.
- A custom codec can optionally be included in the Auto-Detection process, which gives the codec the chance to check if it is applicable for the decoding request.
A codec runs through several states that were designed to give you plenty of options even when having to deal with complex scenarios, such as calling a web service to retrieve data structures or doing some more advanced calculations before returning a result to KaDeck.
A codec is instantiated once a connection to a server in the server browser has been established.
For KaDeck Web developers, it is important to note that:
- Every user has their own set of codec instances during the whole session.
- When a user connects to a server, the user's codec instances are instantiated.
- States (e.g., a cache) can be shared across users using static fields.
The instantiation phase can be used to retrieve data from a remote location and to build up a new or update an existing cache.
When a new consumption or ingestion request is available, the preparation methods are executed.
There is a separate preparation method for ingestion requests and consumption requests.
These preparation methods should be used to prepare the data needed to decode or encode the records so they can be quickly accessed during the subsequent calls of the decoding or encoding methods, respectively.
The decoding or encoding
After the preparation phase, the decoding or encoding methods are called subsequently for every record of the consumption or ingestion request.
When the custom codec participates in the auto-detection process, throwing an exception inside the method for the first record skips this codec and marks it as "not applicable". If no exception is thrown and a value is returned, the consumption request will be assigned to the codec.