Skip to main content

Connectivity

KeySession​

The KeySession is the main entry point to the KeySquare API, it provides connectivity to the platform. Once created, methods on the session can be used to publish and subscribe to data.

See javadoc for more details on KeySession.

Session Creation​

KeySession is constructed taking a KeySessionContext:

KeySessionContext context = new KeySessionContext();
context.setApplicationName("<application-name>");
context.setKeyAccessUrl("http://<key-access-host>:6800");
context.setTransportMode(TransportMode.TCP);

KeySession session = KeySessionFactory.create(context);
  • Minimally, you should set
    • ApplicationName
      • ApplicaitonName should be unique across applications using the KeySquare platform
    • KeyAccessUrl
      • Applications will register in to a KeyAccess server. This can be configured to be highly available and you should speak to your KeySquare representative to consider your particular load balancing scenarios
    • Transport mode
      • There are two transport modes supported
        • UDP_IPC
          • This should be used if your application is in the same vicinity as the core KeySquare platform with multicast visibilty to the Sequencer
          • If running on the same box as the Sequencer, this will fall back to IPC resulting in the lowest latency and highest throughput we can offer
          • If running on a different box to the Sequencer, this will use UDP multicast for communication to the Sequencer
        • TCP
          • If your application is not within UDP multicast visiblity of the main KeySquare platform, TCP communication is required
    • ApiKey
      • Your admin should provide an API key for your application to register against the platform
  • Notably, you should consider
    • ApplicationIdleStrategy
      • KeySquare applications use the Agrona Agent concurrency model to execute units of work on threads. This offers a number of benefits over straightforward Java threads in that work is executed in structured resource-controlled manner. The key variable is how frequently a thread will poll for additional work known as the IdleStrategy. Differing IdleStrategies offer trade offs between CPU utilisation and latency. KeySquare defaults clients to a relaxed IdleStrategy (SleepingMillisIdleStrategy). If your application is latency sensitive, we recommend using a BusySpinIdleStrategy or NoOpIdleStrategy which will continuously poll for additional work resulting in the lowest latency processing at the cost of burning a CPU core.

Session Startup​

The session can be started by invoking the start method. This will connect the application to the platform.

session.start();

KeySessionListener​

The KeySessionListener receives KeySession lifecycle events including:

  • Connection/Reconnection events
  • Disconnection events
  • PostProcess
    • Within a KeySquare work duty cycle, applications can be configured to consume KS_APP_TRANSPORT_EVENT_LIMIT (default is 1000) events at a time. The considerations around this limit are mainly latency driven with secondary concerns around conflation. A lower number will result in lower latency to the application observing the inbound event potentially at the cost of overall throughput. Another consideration is the implementation of conflation. If you want to conflate events, you could store and process KS_APP_TRANSPORT_EVENT_LIMIT events at time. At the end of a duty cycle, the postProcess method allowing you to deal with the conflated workload.

In addition to lifecycle, a number of default handlers are provided, e.g.

Should the application receive an event type that has not been registered, a default handler will log a warning

    LoggerFactory.getLogger(KeySessionListener.class).warn("Received message, but no message dispatcher was registered: {}",
        messageHeaderDecoder);

This behaviour can be overriden by overriding the process method on KeySessionListener.

See javadoc for more details on KeySessionListener.