Skip to main content

Configuring Message Types

The MessageTypes tag defines the message types supported by the AMPS instance. A single AMPS instance can support multiple message types.

As mentioned in the Default Message Types section, MessageType definitions for fix, nvfix, xml, json, bflat, msgpack, bson, and binary are automatically loaded by AMPS. You only need to define a new MessageType for these types if the settings for the message type need to be changed (for example, to create a custom FIX-based type that changes the FieldSeparator of the message).

The MessageTypes tag can contain multiple MessageType definitions. To add more than one message type to the message types that are loaded by default, include multiple MessageType tags.

AMPS loads the capability to use Google protocol buffer (protobuf) messages by default. To use protocol buffer messages, you configure one or more message types that use the protobuf module and load the .proto files that define the format of the messages you will be processing with AMPS.

AMPS also supports the ability to create a composite message type by combining a number of existing message types. Composite message types are defined using the MessageType configuration element.

Described below are the configuration items available for a MessageType. Expand each item for more details.

Name (required)

This element defines the name for the message type.

The name is used to specify MessageType in other sections such as Transport, TransactionLog and the elements of the SOW section.

By default, AMPS loads message types for fix, nvfix, json, bflat, msgpack, bson, xml and binary. It is typically not necessary to configure these types for use.

Other message types, such as Google protocol buffers, are available by default, but require configuration to be used.

Module

This element specifies the name of the module that will be loaded for this message type.

By default, AMPS loads the modules that implement the following message types: fix, nvfix, json, bflat, msgpack, bson, xml, protobuf, and binary.

AMPS supports creating composite message types out of existing message types using the composite-global and composite-local modules, which are loaded by default.

AMPSVersionCompliance

Sets the version compatibility for FIX messages that AMPS sends to the /AMPS/SOWStats topic.

AMPS accepts three values for this option:

  • 2 creates messages that use the FIX field tags used by AMPS 2.X.
  • 4 creates messages that use the default FIX field tags (the values used in AMPS 4.X). With this version, FIX messages use different field numbering for /AMPS/SOWStats and /AMPS/ClientStatus messages.
  • 5 creates messages that use a unified set of FIX tags. When this option is set to 5, AMPS uses consistent field numbering between /AMPS/SOWStats and /AMPS/ClientStatus messages (which is only available on versions 5.X and later).

For message types other than FIX, there is no difference between 4 and 5.

These message types were not supported in AMPS 2.X. AMPS provides reasonable values for these message types when this value is set to 2, but there is no backward compatibility to enforce.

For most cases, you can leave this option set to the default. If you are using a system that requires consistent FIX tags across messages, set this parameter to 5. If you are using an existing system that expects AMPS 2.X tags, set this parameter to 2.

Default: 4 (for compatibility with the largest number of existing installations)

Options

Options to pass to a custom message type module.

AMPS does not specify the format or type of the items within an Options element. AMPS simply parses the XML and then sends the XML to the module. If you are configuring a custom message type, see the documentation for that message type module for details.

Message Type Specific Options​

Below are the configuration items that apply to specific message types.

FIX/NVFIX Options​

Described below are the options that apply to fix and nvfix message types. Expand each item for more details.

FieldSeparator

Applies to fix and nvfix message types.

Sequence of characters used to separate field items in a FIX message.

Note: This field is the ASCII value of the char sequence.

HeaderSeparator

Applies to fix and nvfix message types.

Sequence of characters used to separate the header from the body in a FIX message.

Note: This field is the ASCII value of the char sequence.

MessageSeparator

Applies to fix and nvfix message types.

Sequence of characters used to separate message items in the body in a FIX message.

Note: This field is the ASCII value of the char sequence.

The example below defines a FIX-based message type with custom separators.

<MessageTypes>
    <MessageType>
        <Name>fix-custom</Name>
        <Module>fix</Module>
        <!-- The following are FIX specific options. -->
        <FieldSeparator>1</FieldSeparator>
        <HeaderSeparator>2</HeaderSeparator>
        <MessageSeparator>5</MessageSeparator>
    </MessageType>
</MessageTypes>

JSON Option​

Described below is the option that applies to the json message type. Expand the item for more details.

EarlyTerminationOptimization

Applies to the json message type.

By default, AMPS includes an optimization to allow the server to only partially parse JSON messages. This may result in unexpected behavior for some messages.

For example, given a message such as { "code" : 1, "data" : "some data", "code" : 2 }, AMPS will report the value of code as 1 when this optimization is active. To ensure consistent results, in this mode AMPS always reports the first value for a field even when AMPS fully parses the message.

When set to false, the optimization is disabled. AMPS will fully parse all JSON messages and report the last value for a field. For the message above, AMPS would report the value of code as 2.

Default: true

The example below disables the optimization:

    <MessageType>
        <Name>json-custom</Name>
        <Module>json</Module>
        <EarlyTerminationOptimization>false</EarlyTerminationOptimization>
    </MessageType>

Composite-Local and Composite-Global Option​

The MessageType entries for the composite message can be any AMPS message type, including both the built-in types and any previously defined message type.

Once the new composite message type is created, you can use the new type in the configuration file.

Described below is the option that applies to composite-local or composite-global message types. Expand the item for more details.

MessageType (required)

Applies to message types that use the composite-local or composite-global modules.

For composite message types, the MessageType definition must contain one or more message type declarations that specify the types that the composite message type contains.

For example, the MessageType element below declares a new composite message type named images. The new type contains a json document at the beginning of the message, followed by two uninterpreted binary message parts. AMPS will combine the XPath identifiers for all message parts into a single set of identifiers. Notice that, because only one part of the message type is parsable, using composite-global simplifies the identifiers for the message.

<MessageTypes>
    <MessageType>
        <Name>images</Name>
        <Module>composite-global</Module>
        <MessageType>json</MessageType>
        <MessageType>binary</MessageType>
        <MessageType>binary</MessageType>
    </MessageType>
</MessageTypes>

The example below defines a composite message type that combines a json message and a custom-payload message:

<MessageTypes>
    <MessageType>
        <Name>custom-composite</Name>
        <Module>composite-local</Module>
        <MessageType>json</MessageType>
        <MessageType>custom-payload</MessageType>
    </MessageType>
</MessageTypes>

Google Protocol Buffer Options​

To use a protobuf message, you must first edit the configuration file to include a new MessageType. Then, specify the path to the protobuf file and the name of the protobuf file itself inside the MessageType.

Each message type references a ProtoFile, and specifies a single top-level type from the file. The ProtoFile may include other files through the standard protocol buffer include mechanism. Likewise, the top-level type may be any valid protocol buffer definition, including definitions that contain other types.

Once the protocol buffer MessageType is created as described above, you must either create a Transport that specifies that message type exactly, or you must create a Transport that can accept any known message type and ensure that the client specifies the new message type (in the example case, my-protobuf-message) in the connect string.

Described below are the options that apply to protobuf message types. Expand each item for more details.

Type (required)

Applies to message types that use the protobuf module.

The name of the type within the .proto file to use for this message type. The name must be package-qualified (for example, my.package.Message would load the type Message within the package my.package).

Obsolete usage - A previous meaning of this element was made obsolete in AMPS 4.0 and later versions. That usage was replaced by the Module directive.

ProtoPath (required)

Applies to message types that use the protobuf module.

The path in which to search for .proto files. The content of this element has the following syntax:

<strong>alias ; full-path</strong>

The alias provides a short identifier to use when searching for .proto files. The full-path is the path that is substituted for that identifier.

A configuration may omit the alias, and simply provide the path. For example, to use the path /mnt/repository/protodefs when no alias is provided, you would declare a ProtoPath of:

<strong> /mnt/repository/protodefs</strong>

or

<strong> ;/mnt/repository/protodefs</strong>

The following ProtoPath declaration sets proto-archive as an alias for /mnt/shared/protofiles:

<strong>proto-archive;/mnt/shared/protofiles</strong>

AMPS uses the aliases provided in this configuration item when processing import statements within the loaded .proto files, with the empty alias used for import statements that do not specify a path alias.

For example, given the definitions above, this import statement:

<strong>import "proto-archive/AType.proto";</strong>

will load the file at /mnt/shared/protofiles/AType.proto, while the import statement:

<strong>import "MyFavoriteType.proto";</strong>

will load the file at /mnt/repository/protodefs/MyFavoriteType.proto.

If no ProtoPath declaration sets an empty alias, all imports processed by AMPS must use one of the aliases set for the instance, or AMPS will fail to find the specified file.

Unless your existing definitions use an aliasing scheme, it is most convenient to set the empty alias.

You may specify any number of ProtoPath declarations.

ProtoFile (required)

Applies to message types that use the protobuf module.

The name of the .proto file to use for this message type. To use an alias, prefix the name of the file with the alias.

For example, if your ProtoPath declarations have created the proto-archive alias for the directory where your .proto files are stored, you could use the following to access the my-messages.proto file in that directory.

<strong>proto-archive/my-messages.proto</strong>

Below is a sample configuration of a protobuf message type:

<MessageTypes>
    <MessageType>
        <Name>my-protobuf-messages</Name>
        <Module>protobuf</Module>
        <ProtoPath>proto-archive;/mnt/shared/protofiles</ProtoPath>
        <ProtoFile>proto-archive/person.proto</ProtoFile>
        <Type>MyNamespace.Message</Type>
    </MessageType>
</MessageTypes>

Custom Message Types​

The example below defines a custom message type. The Module in this case - type-module, must be the Name of a Module specified in the Modules section of the configuration file.

<MessageTypes>
    <MessageType>
        <Name>custom-payload</Name>
        <Module>type-module</Module>
    </MessageType>
</MessageTypes>