Skip to content
Architecture > Configuration Guide

Relay Properties

This document contains a list of configurable properties for the Relay component and their uses.

For other components, please see these pages:

  • Common (properties applicable across all AMI applications)
  • Center (properties specific to the Center component)
  • Web (properties specific to the Web component)
  • WebBalancer and WebManager (properties for managing connections to 3forge Web)

General Relay Properties

Note

Property default values that are prefixed with a # are optional or must be configured by the user before use.

To run the Relay, you must include relay in the list of components found in the the ami.components property in local.properties: 

1
ami.components=center,web,relay

By default, all three components are running. To run just the Relay component: 

1
ami.components=relay

Relay Connection

Properties on configuring how connections can be made to a Relay

ami.relay.id

Default:
1
# ami.relay.id=relay_0
Description:
  • Sets the name of the Relay
  • This is useful for identification if multiple Relays are connected to a single Center

Note

Each Relay should have a unique ID

ami.port

Default:
1
ami.port=3289
Description:
  • Sets the port that applications connect to on the Relay's host machine
  • Messages must follow the format specified on this page
  • Set to -1 to disable

ami.port.bindaddr

Default:
1
# ami.port.bindaddr=<network_interface>
Description:
  • Specifies the network interface that the ami.port server port is bound to

ami.port.keystore.file

Default:
1
# ami.port.keystore.file=/path/to/keystore/created/by/java/keytool
Description:
  • Path to the keystore file (using Oracle keytool)
  • Use with the ami.port.keystore.password property

ami.port.keystore.password

Default:
1
# ami.port.keystore.password=<password>
Description:
  • Password associated to the keystore file

ami.port.whitelist

Default:
1
# ami.port.whitelist=<options>
Description:
  • Provides either a list of permitted hostname patterns, or a plugin for blocking/granting access based on foreign network address

  • Options syntax:

    1. file: file:<file_containing_a_hostname_patterns_per_line\>
    2. text: text:<newline_delimited_list_of_hostname_patterns>
    3. plugin: plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin\>

ami.port.wait.for.center

Default:
1
ami.port.wait.for.center=true
Description:
  • The duration to wait for the Center to start up

ami.datasource.plugins

Default:

1
ami.datasource.plugins=...
See the full list here:

Datasource adapter list 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    com.f1.ami.plugins.mysql.AmiMysqlDatasourcePlugin,\
        com.f1.ami.center.ds.AmiKxDatasourcePlugin,\
        com.f1.ami.center.ds.AmiFlatFileDatasourcePlugin,\
        com.f1.ami.center.ds.AmiShellDatasourcePlugin,\
        com.f1.ami.center.ds.AmiAmiDbDatasourcePlugin,\
        com.f1.ami.center.ds.AmiGenericJdbcDatasourcePlugin,\
        com.f1.ami.plugins.postgresql.AmiPostgresqlDatasourcePlugin,\
        com.f1.ami.plugins.oracle.AmiOracleDatasourcePlugin,\
        com.f1.ami.plugins.excel.AmiExcelDatasourcePlugin,\
        com.f1.ami.plugins.db2.AmiDb2DatasourcePlugin,\
        com.f1.ami.plugins.ssh.AmiSshDatasourcePlugin,\
        com.f1.ami.plugins.ssh.AmiSftpDatasourcePlugin,\
        com.f1.ami.center.ds.AmiQuandlDatasourcePlugin,\
        com.f1.ami.center.ds.AmiFredDatasourcePlugin,\
        com.f1.ami.center.ds.AmiOneTickDatasourcePlugin,\
        com.f1.ami.plugins.restapi.AmiRestAPIDatasourcePlugin,\
        com.f1.ami.plugins.sqlite.AmiSqLiteDatasourcePlugin
Description:
  • Default datasource adapters are provided by 3forge and implement the AmiDatasourcePlugin interface
  • For custom adapters that we do not provide, see this documentation to write your own

ami.center.host

Default:
1
ami.center.host=localhost
Description:
  • Sets the hostname of the primary Center instance this Relay is connected to

ami.center.port

Default:
1
ami.center.port=3270
Description:
  • Sets the port of the primary Center instance this Relay is connected to

ami.centers

Default:
1
# ami.centers=center1=host:port,...
Description:
  • Comma delimted list of centers' host:port to connect to
  • You can optionally prefix a 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 dashboard
  • Note, the first supplied URL is considered the primary center. e.g:
    1. ami.centers=myprimary=localhost:3270,other=some.host.com:3270

ami.center.<NAME>.keystore.file

Default:
1
# ami.center.<NAME>.keystore.file=/path/to/keystore/created/by/java/keytool
Description:
  • Supply if the Center is using an SSL connection
  • Path to the keystore file (using Oracle keytool)
  • NAME is the Center's name as it appears in ami.centers property
  • Use either with ami.center.<NAME>.keystore.contents.base64 or ami.center.<NAME>.keystore.password

ami.center.<NAME>.keystore.password

Default:
1
# ami.center.<NAME>.keystore.password=<password>
Description:
  • Supply if the Center is using an SSL connection
  • Password associated to the keystore file in ami.center.<NAME>.keystore.file
  • NAME is the Center name as it appears in ami.centers property

ami.center.<NAME>.contents.base64

Default:
1
# ami.center.<NAME>.contents.base64=<base64_key>
Description:
  • Alternative to supplying the keystore file if the Center is using an SSL connection
  • Supply the contents of a keystore as base64
  • NAME is the Center name as it appears in ami.centers property

Relay Logging

ami.relay.guaranteed.messaging.enabled

Default:
1
ami.relay.guaranteed.messaging.enabled=false
Description:
  • 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 Centers

ami.relay.persist.dir

Default:
1
# ami.relay.persist.dir=./persist
Description:
  • Where to store the recovery journal files if ami.relay.guaranteed.messaging.enabled is set to true

ami.log.messages

Default:
1
ami.log.messages=true
Description:
  • If set to true, all messages sent into and out of the Relay to/from other applications will be logged to a file

ami.send.cr

Default:
1
# ami.send.cr=true
Description:
  • If set to true, the relay will send a CR back on each response, in addition to a new line

Email

3forge can be used to send emails. For an overview of how this works, see the interoperability guide.

To configure email settings, you will need to know the SMTP information of your email provider.

At a minimum, you will need to provide the following configuration:

1
2
3
4
email.client.host=<your_email_client_host>
email.client.port=<your_email_client_port>
email.client.username=<your_email_username@email_client>
email.client.password=<your_email_password>

A full list of available properties is listed below.

Email Properties

email.client.host

Default:
1
# email.client.host=<your_email_client_host>
Description:
  • SMTP server to connect to

email.client.port

Default:
1
# email.client.port=<your_email_client_port>
Description:
  • The SMTP server port to connect to

email.client.username

Default:
1
# email.client.username=<your_email_username@email_client>
Description:
  • Email account username

email.client.password

Default:
1
# email.client.password=<your_email_password>
Description:
  • Email account password

email.client.authentication.enabled

Default:
1
# email.client.authentication.enabled=true
Description:
  • Attempts to authenticate user by default

email.client.ssl.enabled

Default:
1
# email.client.ssl.enabled=false
Description:
  • Attempts to connect via SSL if enabled

email.client.ssl.protocols

Default:
1
# email.client.ssl.protocols=
Description:
  • Specifies which SSL protocol the email client is using
  • Equivalent to the JavaMail property mail.smtp.ssl.protocols and has the same valid options

email.client.start.tls.enabled

Default:
1
email.client.start.tls.enabled=true
Description:
  • Attempts to connect via TLS if supported by the server

email.client.retries.count

Default:
1
email.client.retries.count=3
Description:
  • Number of attempts to reconnect to SMTP server if connection fails

email.client.exit.on.error

Default:
1
email.client.exit.on.error=true
Description:
  • Determines whether to exit 3forge if there is an email connection error
  • Set to false to keep 3forge running even if email connection fails

email.client.connection.timeout

Default:
1
email.client.connection.timeout=-1
Description:
  • Upon losing connection with the email client, how long to wait before timing it out
  • Default behavior disables timeout

email.client.timeout

Default:
1
email.client.timeout=-1
Description:
  • How long to wait before timing out the email client
  • Default behavior disables timeout

email.client.write.timeout

Default:
1
email.client.write.timeout=-1
Description:
  • How long to wait before timing out a write operation
  • Default behavior disables timeout

email.client.debug.enabled

Default:
1
email.client.debug.enabled=false
Description:
  • If set to true, allows 3forge to add email-related information to the log

Relay Transformations

By default, Relays connected to multiple Centers will send messages to all Centers.

It is possible to route messages only to specific Centers, or implement transformations to map messages to a specific format before reaching a given center to avoid redundant calculations.

To set up Relay transformations, you will need the following files:

  • relay.transforms

    • Defines the transformations of some Relay message.

  • relay.routes

    • Defines which Centers the messages are routed to.

  • <SOME_FILE>.relay.dictionary

    • Defines the specific mapping of some Relay message.

These files are used to define any transformation logic the Relay should perform before sending messages to the Center, and which Centers they should be sent to.

The configurable properties for using Relay transformations is listed below.

Relay Transformation Properties

ami.relay.transforms.file

Default:
1
ami.relay.transforms.file=data/relay.transforms
Description:
  • File containing Relay transformation rules to be applied
  • See the relay.transforms file below for details

ami.relay.transforms.debug

Default:
1
ami.relay.transforms.debug=false
Description:
  • Optional logging file

ami.relay.dictionary.files

Default:
1
ami.relay.dictionary.files=data/*.relay.dictionary
Description:
  • Files containing dictionaries for Relay transform mappings
  • Alternatively can be supplied as a comma-delimited list of different dictionary files
  • See the relay.transforms and Dictionary Files sections below for details

ami.relay.routes.file

Default:
1
ami.relay.routes.file=data/relay.routes
Description:
  • File containing routing tables used for controlling which real-time streaming messages are sent to which center(s)
  • See the Relay Routes file below for details
  • If a file is not found, a placeholder with instructions will be created

ami.relay.routes.debug

Default:
1
ami.relay.routes.debug=false
Description:
  • Optional logging file.

ami.relay.disable.functions

Default:
1
ami.relay.disable.functions=readBinaryFile,writeBinaryFile
Description:
  • Comma-delimited list of AmiScript functions to disable in Relay
  • Leave blank to enable all functions
  • We recommend using the default values if using a WebManager

relay.transforms File

Relay transformations are applied to messages that are arriving from some feed handler before they are routed and then processed by a Center.

This reduces overall computation by the Center by ensuring messages are in the correct format for each Center they are intended for.

Relay transformations are defined in the relay.transforms file where each line describes a transformation rule with the format:

1
TRANSFORM_NAME;PRIORITY;OBJECT_TYPES;DICTIONARY;EXPRESSION;OPTIONS;ON_TRUE;ON_FALSE

Each parameter is detailed below.

Parameter Description
TRANSFORM_NAME Unique name of the transform.
PRIORITY Highest priority executes first. Lower numbers have higher priority, with 0 being the highest priority. Ties determined using alphabetical route name.
OBJECT_TYPES Comma delimited list of types (T=...) to evaluate by this transform. Blank - skip rule, * - all types, Use Target=Source to map.
DICTIONARY Optional dictionary to apply form transforming fields. If empty, no field transforms are applied.
EXPRESSION Expression to evaluate on source values, must return boolean. True return value indicates rule succeeded.
OPTIONS Comma delimited list of options: PASSTHROUGH - Include unmapped fields in the output.
ON_TRUE Action if Table matches: BREAK - stop evaluating rules, blank - continue evaluating next rule.
ON_FALSE Action if Table does not match: BREAK - stop evaluating rules, blank - Continue evaluating next rule.

Dictionary Files

To specify the actual mapping, a transform rule uses requires a dictionary file in the format <some_dictionary>.relay.dictionary.

This should contain the mapping for any transform methods that are called in relay.transforms (corresponding to the DICTIONARY parameter). For example:

1
RawFix { price = `44`;}

This transforms a message with an input parameter of "44" to be processed by the Center with the key "price" instead.

Dictionaries can also be used to extend one another. For example:

1
2
FixDictionary extends RawFix{ String `55`; sym=`55`.toUpper(); now=timestamp(); }
RawFix { price=`44`; }

FixDictionary extends the RawFix dictionary so that it also maps the input key "55" to a column titled "sym" and then capitalizes the input string using the Center method toUpper().

Relay transformations can apply Center methods, such as timestamp(). To see a full list of accepted methods for Relay transformations, run the command SHOW METHODS; in the AMIDB Shell Tool.

Example

In the amione/data directory, create a sample.relay.dictionary file with the following dictionaries: 

1
2
3
4
5
6
RawFix { price=`44`; }
FixDictionary extends RawFix { String `55`; sym=`55`.toUpper(); }

TimeString {
  time = formatDate(timestamp(),"MM-dd-yy HH:mm:ss", "GMT");
}

In relay.transforms, add the following lines: 

1
2
Transform_fix;0;*;FixDictionary;true;PASSTHROUGH;;
Transform_number;0;*;TimeString;true;PASSTHROUGH;;

Fix-style messages will be inserted into a3forge table with two transformations applied:

  1. Transforms the headers into "price" and "sym."
  2. Takes the time the message was sent and converts it into a readable date format.

Send the following message to the relay via the configured ami.port (this is 3289 by default):

1
O|I="01"|T="sample_fix"|44=0.99|55="3forge"

This will create a table "sample_fix" in the Center and insert the following row.

relay.routes File

Any number of Relays can be connected to any number of Centers that have been specified in the properties (ami.centers). By default, as messages are sent from an external source into a Relay, they are forwarded to all Centers.

To determine if messages should be sent to specific Centers, rules can be added to the relay.routes file. This allows you to control which Centers are receiving messages based on some parameters within a message and/or the structure of the message itself.

Note

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:

1
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 logic should be exectued next dependant on the outcome.

Notes

  • Lines starting with a hash (#) 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

1
2
3
4
5
#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:

1
2
3
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