Architecture > Configuration Guide

Relay

Relay Properties

Note: To run the ami relay, include relay in the list of components found in the the ami.components property, ex: ami.components=relay

Relay General Properties

• ami.relay.id: Sets the unique name of the relay. This is used to distinguish relays on the front end (when there are multiple relays connected to a single center). Each relay should have a unique id
• ami.port: Sets the port that applications connect to on the Relay's host machine. The default port is 3289. See AMI Realtime Messages for a specification of the messages the Relay expects in this port. When set to -1, the socket is not started and refuses any connections to the relay.
• ami.port.bindaddr: Optional. Specifies the network interface that the ami.port server port be bound to
• ami.port.keystore.file: The path to the key store file, generated using java's keytool.
• ami.port.keystore.password: The password associated with the key store file.
• ami.port.wait.for.center: The duration to wait for center to start up
• ami.port.whitelist: Provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<comma_delimited_list_of_hostname_patterns> or plugin: <class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
• ami.datasource.plugins: A comma delimited list of java classes that implement the com.f1.ami.amicommon.AmiDatasourcePlugin interface. See Custom Java Plugins for details
• ami.center.port: Sets the port of the primary instance of ami center
• ami.center.host: Sets the hostname of the primary instance of ami center
• ami.centers: A comma delimited list of centers' host:port to connect to. You can optionally prefix host:port with an alias in the form alias=host:port, in which case the alias will be used to reference the center within the relay.routes file. If an alias is not provided, then the alias is the host:port. Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
• ami.center.[name].keystore.file: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
• ami.center.[name].keystore.contents.base64: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
• ami.center.[name].keystore.password: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
• ami.relay.persist.dir: Where to store the recovery journal files, if ami.relay.guaranteed.messaging.enabled is set to true. Default is ./persist
• ami.relay.guaranteed.messaging.enabled: If true, the relay will use a store and forward journal to record messages to disk prior to an ACK message being sent to the originating client. The journal can also be used to deliver messages to late-subscribing Ami Centers. Default is false.
• ami.relay.routes.file: a file containing routing tables used for controlling which real-time streaming messages are sent to which center(s). Default is data/relay.routes See Relay Routes File below for details. Note, if a file is not found, a placeholder file with instructions will be created there.
• ami.log.messages: If set to true, all messages sent into and out of ami relay to/from other applications will be logged to a file
• ami.send.cr: If set to true, by default the relay will send a CR back on each response, in addition to a new line

Relay.routes File

The relay can be connected to any number of centers (see ami.centers)). By default, as messages are sent from an external source into a relay they are forwarded to all centers. By adding rules to the relay.routes file (see ami.relay.routes.file) you can control which centers are receiving messages based on any parameters within a message and/or the structure of the message itself. Each line within the file is an isolated rule.

To support dynamic routing, changes to this file during runtime will take effect immediately

Each line in the relay routes file is an isolated rule, with the following format:

ROUTE_NAME;PRIORITY;MESSAGE_TYPES;OBJECT_TYPES;PARAM_TYPES;EXPRESSION;ROUTE_LIST;SUCCESS_ACTION;FAIL_ACTION;SKIP_ACTION

Parameter	Description
ROUTE_NAME	Unique name of rule
PRIORITY	Higher priority rules execute first. Lower numbers have higher priority, with 0 being the highest priority. Ties are determined using alphabetical route name
MESSAGE_TYPES	Comma delimited list of messages types, only O (object), D (delete), C (Command) and S (Status) are supported, * - all types
OBJECT_TYPES	Comma delimited list of types to evaluate by this rule. Blank - skip rule, * - all types
PARAM_TYPES	Comma delimited list of param types for the rule in the format: Name Type [nonull]
EXPRESSION	Expression to evaluate, must return boolean, true return value indicates rule succeeded
ROUTE_LIST	Comma delimited list of centers to send message to. Blank - no centers, * - all servers
ON_TRUE	Action if Expression returns true: BREAK - stop evaluating rules, blank or CONTINUE - continue evaluating next rule
ON_FALSE	Action if Expression returns false or null: BREAK - stop evaluating rules, blank or CONTINUE - Continue evaluating next rule

Starting at the highest priority rule (lowest number), if the MESSAGE_TYPES and OBJECT_TYPES and PARAM_TYPES match the message, then the fields defined in the PARAM_TYPES are extracted from the message and passed into the EXPRESSION. If the expression returns true then the message is sent to all centers in the ROUTE_LIST. The ON_TRUE, ON_FALSE determine what to do next respective to the outcome.

Notes:

• Lines starting with a pound (#) are considered comments and skipped
• A particular message will only be sent to a particular center at most once, regardless of how many rules it matches

Example

#For NewOrder and Cancel messages with a symbol, route based on symbol. For all other messages router to all centers
RULE0;0;O,D;NewOrder,Cancel;Symbol String nonull;symbol < "F";Center0;BREAK;
RULE1;1;O,D;NewOrder,Cancel;Symbol String nonull;symbol < "Q";Center1;BREAK;
RULE2;2;O,D;NewOrder,Cancel;Symbol String nonull;true;Center2,Center3;BREAK;
RULE3;3;*;*;;true;*;BREAK;

Example messages:

O|T="NewOrder"|Symbol="AAPL"     <== will be sent Center0
O|T="NewOrder"|Symbol="IBM"      <== will be sent Center1
O|T="NewOrder"|Symbol="ZVZZT"    <== will be sent to both Center2,Center3