AMI Client Interface to Realtime Backend API

Overview

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

Setup

Overview

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.

Configuration

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)

com.f1.ami.client.AmiClient

com.f1.ami.client.AmiClientListener

com.f1.ami.client.AmiCommandDef

Example - Java Code

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.ami.client.RawAmiClient;
import com.f1.utils.OH;

public class TestAmiClient 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 TestAmiClient(client));
        client.start("localhost", 3289, "demo", OPTION_AUTO_PROCESS_INCOMING);
        while (true)
            OH.sleep(1000); // Keep process alive
    }

    private AmiClient client;

    public TestAmiClient(AmiClient client) {
        this.client = client;
    }

    @Override
    public void onMessageReceived(AmiClient source, long now, int seqnum, int status, CharSequence message) {
        System.out.println("Message received: " + message);
    }

    @Override
    public void onMessageSent(AmiClient source, CharSequence message) {
        System.out.println("Message sent: " + message);
    }

    @Override
    public void onConnect(AmiClient source) {
        System.out.println("Connected");
    }

    @Override
    public void onDisconnect(AmiClient source) {
        System.out.println("Disconnected");
    }

    @Override
    public void onLoggedIn(AmiClient source) {
        // We’ve successfully connected an logged in, let’s register stuff.
        System.out.println("Logged in");
        // Send message
        this.client.startObjectMessage("SampleOrders", "1");
        // Send as String
        // addMessageParamString(String key, String value)
        this.amiClient.addMessageParamString("Order", data.get("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)
        this.amiClient.addMessageParamJson("Table", map);
        // Send as binary
        // addMessageParamBinary(String key, byte[] value)
        this.amiClient.addMessageParamBinary("Val", val);
        // Send as num
        // addMessageParamBinary(String key, CharSequence value)
        this.amiClient.addMessageParamEnum("Num", num)
        // Send as object
        // addMessageParamObject(String key, Object value)
        this.amiClient.addMessageParamObject("Data", obj);
        this.client.sendMessageAndFlush();
      
        // Send command
        AmiClientCommandDef def = new AmiClientCommandDef("sample_cmd_def");
        def.setConditions(AmiClientCommandDef.CONDITION_USER_CLICK);
        this.client.sendCommandDefinition(def);
        this.client.flush();
        System.out.println("Sent command");
    }

    @Override
    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");
        client.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

startObjectMessage

AmiClient startObjectMessage(String type, CharSequence id)

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

startObjectMessage

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.

addMessageParamObject

void addMessageParamObject(String key, Object value)

addMessageParams

AmiClient addMessageParams(Map<String, Object> params)

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

sendMessage

boolean sendMessage()

Finalize and send the current message, returns true if successful

flush

void flush()

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

sendMessageAndFlush

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.

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

Class AmiClientCommandDef

AmiClientCommandDef(String id)

Creates a new command

Class AmiClient

sendCommandDefinition

void sendCommandDefinition(AmiClientCommandDef def)

Send a command (C) declaration

Processing Command Callbacks

Command callbacks are processed using the AmiClientListener onCommand() method. See Real-time Messaging API - Outbound Instruction Type - Object (R)

Class AmiClient

startResponseMessage

AmiClient startResponseMessage(String origRequestId, int status, String message)

Start a response (R) message.