MAX Avro Messaging (MaXaM) User Manual

About This Manual

What this manual is:

• This manual describes MaXaM specific message queueing/delivery features exposed via STOMP
• This manual describes how MaXaM / MaXaM users utilise Avro including usage of the Avro Schema Registry.
• This manual describes the usage of the Avro GenericEnvelope to encapsulate the actual AvroMessageBody and a set of message headers, including the AvroSchemaFingerprint in a STOMP frame.

What this manual is not:

• This manual does not describe how to use STOMP itself, which is well documented
• This manual does not describe Avro which is also well documented.
• This manual does not describe any specific MAXsys Avro message schema or usage.
• This manual does not describe any specific MAXsys Service or STOMP Destination.

Components

MaXaM is MAX's Avro Messaging system. It consists of:

• A message exchange (also known as a broker or gateway) which acts as an intermediary between machines or software components that need to exchange data.
• A storage service accessed via the gateway that maintains shared, live state.
• A schema registry service that allows those communicating components to obtain the information needed to correctly convert messages to/from the Avro encoding used.
• A simple Enrolment service to allow clients to obtain a certificate and register to access MaXaM services.

Terminology

The terminology used to describe messaging in MaXaM is described in Messaging Terminology

Concepts

MaXaM and the APIs exposed via it use a consistent conceptual model for push based delivery of current state from publishers to subscribers. This model is described in MaXaM Concepts

STOMP

STOMP is used to allow easier connection to and interoperation with MaXaM than would be achieved using a pure Avro solution. The interface to MaXaM is specified in terms of STOMP. Other/internal MaXaM interfaces are not described in this specification, but transparently interoperate with the STOMP interface. STOMP is used because it is a very simple protocol that directly supports a publish/subscribe messaging model more suited to efficiently delivering the APIs required than a request/response protocol such as HTTP.

See Stomp Usage for details.

Avro Usage

Avro is an open serialisation format that provides a very efficient binary representation of data, has bindings to a wide range of languages, and includes the ability to translate between Avro binary and a JSON representation. The use of a well defined Avro schema for each Avro message body helps to ensure each API message is tightly defined. The use of a generic Avro envelope to encapsulate the message body, schema identifier and other metadata related to each message allows a variety of APIs to be delivered within a consistent and efficient framework.

See Avro Usage for details.

MAXsys Venue API Conventions

MaXaM is used in MAXsys venues to deliver a range of in venue API services. The specifics of the APIs are described in the Avanced Venue Data Access Overview but all follow conventions described in Venue API Conventions.