Client API

The Client API allows to create a generic User Application and use it to send Buffers to a CDS. The Client API won't show any Client Interface but will allow to manage the communication wityh the Server, including receiving Server widget or exception events.

This allows to send Buffers and receive events to the Server programmatically.

Creation of the API

The API will use internally a J661 Client. To create the API, you must:

• Get the unique instance of the APIFactory
• Create a StatefullAPI using a client configuration properties file
• Eventually parse some Definition Files

For example:

      APIFactory factory = APIFactory.getInstance();
      StatefullAPI api = factory.newStatefullAPI(properties);
      api.parseDF(df);

Referencing extensions

Referencing extensions for the API can be performed exactly in the same way it would be done with the J661 Client itself, by referencing the path of the extensions for the extensions property in the configuration properties file. For example:

      extensions=myExtension.jar

Parsing Definition Files options

There are two ways to parse Definition Files:

• Parsing Definition Files and return true if the parsing was successful
• Parsing Definition Files and return the list of layers which are the result of the parsing

For example:

      api.parseDF(df);
      List<ARINCLayer> layers = api.getLayersList(df);

Creation of the API with a Windowing configuration

With a properties file specifying a windowing configuration, it is not necessary to parse the Definition Files defined for the cockpit, the API will automatically parse those defined for the cockpit configuration. For example:

      graphics=DefGraphics.xml
      ui=LookAndFeel.xml
      pictures=DefPictures.xml
      lf=JavaFX
      supplement=3
      serverInputPort=8080
      serverOutputPort=8081
      serverInputSize=50000
      serverOutputSize=200
      server.autoVisible=true
      windowManager=windows
      server.windows=simpleWindow.xml
      server.computeLayerSize=false

API runtime

Overview

You must note that the communication will only be possible after the API has been connected. Also sending commands and requests is done in two phases:

• First the Buffer is populated with commands and requests
• Then the content of the Buffer is sent

For example:

      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_VISIBLE, true);
      api.sendAll();

ARINC 661 keywords

The list of ARINC 661 keywords (widget IDs, widget parameters, widget event IDs, ARINC 661 enum values) for the standard are availabel with the arinc661.client.api.ARINC661 interface. For example, the value of the A661_POS_X keyword is available by arinc661.client.api.ARINC661.A661_POS_X.

Connect to the Server

      api.connect();

Disconnect to the Server

      api.disconnect();

Set a Request for a Layer

Suppose that we want a layer to be visible. For example:

      api.setLayerRequest(LAYER_ID, ARINC661.A661_REQ_LAYER_VISIBLE, true);

Set values for widgets parameters

Suppose that we want a layer to be visible. For example:

      api.setWidgetParameter(APPLI_ID, LAYER_ID, LABEL_ID_1, ARINC661.A661_POS_X, 5000);
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_VISIBLE, true);
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_STRING, "CANNIBAL CORPSE");
      api.setWidgetParameter(LAYER_ID, LABEL_ID_1, ARINC661.A661_STYLE_SET, 12);
      api.sendAll();

Listen to layers or widget events

Example when listening for a A661_EVT_SELECTION event on a PushButton:

      api.addWidgetEventListener(LAYER_ID, PUSHBUTTON_ID, new ARINCEventListener() {
      public void eventReceived(ARINCEvent evt) {
      WidgetEvent widgetEvt = (WidgetEvent) evt;
      System.out.println("Button Pressed");
      }
      });

To check the event ID, check the associated event ID. For example, to check if the cursor enters or exists the area of an A661_CURSOR_OVER widget:

      api.addWidgetEventListener(LAYER_ID, CURSOROVER_ID, new ARINCEventListener() {
      public void eventReceived(ARINCEvent evt) {
      WidgetEvent widgetEvt = (WidgetEvent) evt;
      if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
      System.out.println("Cursor Enter");
      } else if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_EXIT) {
      System.out.println("Cursor Exit");
      }
      });

If the event has associated valeus, you can retrieve these values with the getFirstValue() or getValues() methods on the WidgetEvent class. For example, to get the PosX and PosY coordinates of the cursor relative to the A661_CURSOR_OVER widget:

      api.addWidgetEventListener(LAYER_ID, CURSOROVER_ID, new ARINCEventListener() {
      public void eventReceived(ARINCEvent evt) {
      WidgetEvent widgetEvt = (WidgetEvent) evt;
      if (widgetEvt.getEventID() == ARINC661.A661_EVT_CURSOR_ENTER) {
      long posX = (long)widgetEvt.getValues.get(0);
      long posY = (long)widgetEvt.getValues.get(1);
      System.out.println("Cursor Enter at " + posY + " and " + posY);
      }
      });

Sending raw byte data for a Channel

It is possible to send directly raw byte data for a Channel rather than setting each widget parameter^[1]

It is unlikely that you will need this option though

. For example:

      api.sendBuffer(<Channel ID>, <byte array>, >byte array length>);

Sending a BufferOfMapItems

The API has a helper class which can simplify the sending of BufferOfMapItems to the CDS. See client API for MapItems.

Buffer sending frequency cap

It is possible to cap the frequency of the Buffers sent by the API to a Server (uncapped by default). This can be set by the configuration though the client.layersUpdateCap property.

This sets the minimum time in ms between two Buffers sent by the Client API. If this value is greater than 0, Buffers sending will be merged until the update cap has been reached. The default value is -1, meaning that there is not update cap at all for Buffers sending.

The usage of this property is not to bother about the Buffer sending rate by the Client API. For example, one could call call the sendAll() method every 2 ms, but only perform the sending every 40 ms to the Server.

Locking

The StatefullAPI is optionally lockable, to allow for a safe use by more than one Thread. Clients of the API will block until the lock has been released. This can for example manage safely a Use Case when the UA updates widgets parameters regularly (such as temperature values, or a MapHorz content) in a Thread, and change widgets parameters when answering to user events.

Using the API on design-time only

It is possible to get an API just to get the structure of the Definition Files, without wanting to be able to use it at runtime. In that case, the factory should be specified as silent:

      APIFactory factory = APIFactory.getInstance();
      factory.setSilent(true);
      StatefullAPI api = factory.newStatefullAPI(properties);

Parsing the Layers is still possible. For example:

      List<ARINCLayer> layers = api.getLayersList(df);