AMI Client Interface to Realtime Backend API

From 3forge Documentation
Jump to navigation Jump to search


AMI provides developers a Java library to connect to the AMI Realtime Backend API via the AMI Client.



The AMI Client Listener is used to process messages and commands sent and received by the AMI Client.

The AMI Client connects to the AMI Realtime Backend API. Below is a simple example that sends a message and a command via the AMI Client and processes the command callback.


The hostname is the host where either AmiCenter or AmiRelay is running.

The port is configured via the property “ami.port” which typically is set to 3289.

Java interface (see javadoc for details)




Example - Java Code

package com.demo.runmaintest;

import java.util.Map;

import com.f1.ami.client.AmiClient;
import com.f1.ami.client.AmiClientCommandDef;
import com.f1.ami.client.AmiClientListener;
import com.f1.utils.OH;
import com.f1.utils.concurrent.HasherMap;

public class SampleClient implements AmiClientListener {
	public static final byte OPTION_AUTO_PROCESS_INCOMING = 2;

	public static void main(String a[]) throws Exception {
		AmiClient client = new AmiClient();
		client.addListener(new SampleClient(client));
		client.start("localhost", 3289, "demo", OPTION_AUTO_PROCESS_INCOMING);
		while (true)
			OH.sleep(1000); // Keep process alive

	private AmiClient amiClient;

	public SampleClient(AmiClient client) {
		this.amiClient = client;
	public void onMessageReceived(AmiClient source, long now, int seqnum, int status, CharSequence message) {
		System.out.println("Message received: " + message);
	public void onMessageSent(AmiClient source, CharSequence message) {
		System.out.println("Message sent: " + message);
	public void onConnect(AmiClient source) {
	public void onDisconnect(AmiClient source) {
	public void onLoggedIn(AmiClient amiClient) {
		// We’ve successfully connected an logged in, let’s register stuff.
		System.out.println("Logged in");
		// Send message
		this.amiClient.startObjectMessage("SampleOrders", "1");
		// Send as String
		// addMessageParamString(String key, String value)
		this.amiClient.addMessageParamString("Order", "Order");
		// Send as int
		// addMessageParamInt(String key, int value)
		this.amiClient.addMessageParamInt("Quantity", 1000);
		// Send as double
		// addMessageParamDouble(String key, double value)
		this.amiClient.addMessageParamDouble("Price", 2703.1995);
		// Send as long
		// addMessageParamLong(String key, long value)
		this.amiClient.addMessageParamLong("Price", (long) 2703.1995);
		// Send as float
		// addMessageParamFloat(String key, float value)
		this.amiClient.addMessageParamFloat("Volume", (float) 0.45466549498);
		// Send as boolean
		// addMessageParamBoolean(String key, boolean value)
		this.amiClient.addMessageParamBoolean("GTC", false);
		// Send as json object
		// addMessageParamJson(String key, Object value)
		Map map = new HasherMap<String, String>();
		this.amiClient.addMessageParamJson("Table", map);
		// Send as binary
		// addMessageParamBinary(String key, byte[] value)
		byte[] binary = "hello world".getBytes();
		this.amiClient.addMessageParamBinary("Val", binary);
		// Send as num
		// addMessageParamBinary(String key, CharSequence value)
		this.amiClient.addMessageParamEnum("Num", "ENUM");
		// Send as object
		// addMessageParamObject(String key, Object value)
		Object obj = new Object();
		this.amiClient.addMessageParamObject("Data", obj);

		// Register a  command
		AmiClientCommandDef def = new AmiClientCommandDef("sample_cmd_def");
		System.out.println("Sent command");
	public void onCommand(AmiClient source, String requestId, String cmd, String userName, String type, String id, Map<String, Object> params) {
		// Do business logic triggered by callback
		System.out.println("On command");
		source.startResponseMessage(requestId, 1, "Okay").addMessageParamLong("sample_user_callback", 45).sendMessageAndFlush();

Sending Objects

Once the AmiClient is connected to AMI Realtime Backend API, the client can start sending messages.

See Real-time Messaging API - Outbound Instruction Type - Object (O)

Class AmiClient


AmiClient startObjectMessage(String type, CharSequence id)

Starts an object (O) message. Param id is optional.


AmiClient startObjectMessage(String type, CharSequence id, long expiresOn)

Starts an object (O) message. Param id is optional. If the param expiresOn is: set to 0 the object does not expire, a positive value the object expires at an epoc absolute time, a negative value the object expires in an offset time(milliseconds) into the future.


void addMessageParamObject(String key, Object value)


AmiClient addMessageParams(Map<String, Object> params)

See com.f1.ami.client.AmiClient (javadoc for other addMessageParam[types])


boolean sendMessage()

Finalize and send the current message, returns true if successful


void flush()

Send pending message buffer to AMI, can be called at anytime


boolean sendMessageAndFlush()

Send pending message to AMI and block until the message is fully read by AMI, returns true if successful


Register Command

Commands can be created and registered to AMI via the AmiClientCommandDef class.

See Real-time Messaging API - Outbound Instruction Type - Object (C)

Example - Java Code

//Creates a new command
AmiClientCommandDef commandDef = new AmiClientCommandDef("COMMAND_ID");
//Sets the name of the command on the frontend
commandDef.setName("Command Name");
//Specifies when to show the command
//Specifies an additional param from the source table to be passed to the onCommand params
//Sends a command (C) declaration via the AMI Client

Processing Command Callbacks

Command callbacks are processed using the AmiClientListener onCommand() method.

See Real-time Messaging API - Outbound Instruction Type - Object (R)

Example - Java Code

public class SampleClient implements AmiClientListener {
	public void onCommand(AmiClient source, String requestId, String cmd, String userName, String type, String id, Map<String, Object> params) {
		String origRequestId = requestId;
		int status = 1;
		String message = "Okay";
		//Starts a response (R) message
		source.startResponseMessage(origRequestId, status, message);
		//Get additional params defined by AmiClientCommandDef.setFields
		long id = (long)params.get("id");
		source.addMessageParamLong("id", id);


The steps to set up the interface for the AmiClientAsServer is similar to the AmiClient interface.


To set it up, you will require the following configuration:$${},csocket

Example - Java Code

package com.f1.ami.client;

import java.util.Map;

public class AmiClientAsServerTest implements AmiClientAsServerFactory, AmiClientListener {
	public static void main(String a[]) throws IOException {
		new AmiClientAsServer(1234, null, null, new AmiClientAsServerTest());

	public void onClient(Socket socket, AmiClient client) throws IOException {
		client.start(socket, "demo", AmiClient.ENABLE_AUTO_PROCESS_INCOMING);
		client.startObjectMessage("ClientAsServer", null);
		client.addMessageParamString("key", "Hello!");
		client.addMessageParamLong("now", System.currentTimeMillis());
		client.addMessageParamDouble("now", System.currentTimeMillis());

	public void onMessageReceived(AmiClient rawClient, long now, int seqnum, int status, CharSequence message) {
		System.out.println("On Message Received: " + message);

	public void onMessageSent(AmiClient rawClient, CharSequence message) {
		// TODO Auto-generated method stub

	public void onConnect(AmiClient rawClient) {

	public void onDisconnect(AmiClient rawClient) {

	public void onCommand(AmiClient rawClient, String requestId, String cmd, String userName, String objectType, String objectId, Map<String, Object> params) {
		// TODO Auto-generated method stub

	public void onLoggedIn(AmiClient rawClient) {