Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | Codec Connectivity Plug-ins | The String codec connectivity plug-in
 
The String codec connectivity plug-in
The String codec can be used for transports that are dealing with binary payloads or map payloads with binary data in one or more specific fields of the map which reflect the structure of the event. It provides the ability to perform bidirectional translations between binary format and string format. The codec is able to operate on arbitrary fields of the message, or the entire payload.
*The field of a message going from the host to the transport should be of java.lang.String (Java) or const char* (C++) type. The String codec translates the fields of such a message to the byte[] (Java) or buffer_t (C++) type.
*The field of a message going from the transport to the host should be of byte[] or buffer_t type. The String codec translates the fields of such a message to the java.lang.String or const char* type.
By default, the String codec does UTF-8 encoding and decoding of a string:
*When converting to a buffer_t or byte[], the end result is UTF-8 encoded.
*When converting to a java.lang.String or const char*, the String codec assumes that the source (buffer_t or byte[]) is UTF-8 encoded.
To reference the String codec, an entry such as the following is required in the connectivityPlugins section of the configuration file (see also Configuration file for connectivity plug-ins):
stringCodec:
libraryName: connectivity-string-codec
class: StringCodec
You then need to add the String codec into your connectivity chain with the configuration for that instance. An example configuration may look as follows:
startChains:
testChain:
- apama.eventString
- stringCodec:
nullTerminated: false
eventTypes:
- com.apamax.test.MyEventType
encoding: Latin-1
fields:
- metadata.foo
- payload.bar.baz
- payload.zot
- myBinaryTransport
The following configuration options are available for the String codec:
Configuration option
Description
nullTerminated
It is only permitted to set this option to true when the encoding is UTF-8. It only affects the conversion to bytes for messages sent from the host towards the transport. When messages are converted from bytes (on the transport side) to strings (on the host side), a terminating null character is always permitted but never required, regardless of the value of this configuration option.
If set to true, a null-terminator character is added to the end of the buffer when sending messages towards the transport.
If set to false, messages sent towards the transport do not include a null-terminator.
Default: false.
eventTypes
Specifies which event types this codec will handle. Messages with a type that is not listed or where sag.type is not set will be ignored by this codec. If omitted, the codec attempts to encode/decode the payload of all messages.
fields
The list of metadata or payload fields that are to be converted by this codec. Listed field that are not present in the event will be ignored by this codec. It is recommended that you prefix each field with either payload or metadata, for example: payload.myfield or metadata.myfield. If omitted, the codec attempts to encode the entire payload.
encoding
The character set to be used for encoding/decoding.
Default: UTF-8.
If charset is set in the metadata of a message (in either direction), this will quietly override the encoding option. For example, if the encoding option is set to Latin-1 and if the message carries charset in the metadata (for example, metadata.charset=CP1252), then the payload/metadata field or the entire payload of the message is converted using the character-set value of metadata.charset.