Components of the Connector

The Connector SDK provides the configuration file as Config.json which is a part of the Connector code. This config file contains the JSON objects as configurations. These JSON objects further, contain attributes which are placeholders for providing configurations or parameters for the functions executing certain functionalities in the SDK code.

This configuration file is the central instance of each connector. It defines the workflow by defining which verticles are used in which order. It needs to be created in the root directory of the Connector project.

The name can be arbitrarily chosen. The JSON objects defined in config.json consists of two fields: verticles and deploymentOrder. The former defines the specific verticles (i.e. processing components) of the connector consisting of their configuration. The latter defines the order in which they are deployed.

Verticles

The verticles form the central processing chain of your connector. Verticles are chunks of code deployed and run by Vert.x. A verticle will run on the Event Loop (WHICH SHOULD NEVER BE BLOCKED!!) and will contain a reference to the Vert.x instance that created it. With this instance any Vert.x functionalities like the EventBus, WebClients etc. can be created or used and custom logic for using them or reacting to events/changes (using the EventBus verticles can exchange messages with each other) can be provided. They can be thought of as the actors in Actor model. For more information on verticles or core Vert.x concepts check the documentation.

One verticle will usually create some output which is then put on the event bus and thus forwarded to the next verticle for further processing (outputAddress), which will in turn create another output from its input (inputAddress) and so on. The data format (as in the schema) used for passing data within the chain is basically arbitrary. However, the default implementations of the SDK expect a specific input type (as in the object type used for the communication between the verticles) and produce a specific output type, so you will need to adhere to these standards if you use them. It is recommended to use JSON as your data format whenever and as early as possible.

A typical connector may consist of the following:

1. An InboundTriggerVerticle: This is relevant for connectors that poll a data source at regular intervals. Connectors that are called from the outside don’t need this. This verticle as well as a few other possible examples can be found in the SDK.
2. An InboundVerticle: This is the actual start of the processing chain. For verticles that poll a data source this will be triggered by an event from the InboundTriggerVerticle. Another possibility is for the connector to offer an endpoint which may be called by a web request from the outside HttpServerVerticle. The result will then be put on the vert.x-EventBus for processing. A few inbound verticles can be found in the SDK.
3. The PreProcessorVerticle which will transform the incoming data into a format more appropriate for use by the verticles down the pipeline. This is usually done by a chain of commands that you must specify (the reasons for using a chain of commands instead of simply another verticle is that currently only one instance of the same type can be used for verticles, which is not true for commands). The **PreProcessor ** verticles exist in the SDK, but the Commands used by them can be also found in the SDK.
4. The ProcessingVerticle which does processing required for all the events. Consumes the message from the PreProcessor, performs custom processing on the message and forwards the result to the following verticle making sure that all events contain a timestamp. Note that at this point at the latest the data must be in JSON format. Use either the DefaultProcessingVerticle (which only ensures that the message has a timestamp) or extend the AbstractProcessingVerticle for a custom solution. These verticles can also be found in the SDK.
5. The SDKConnectorVerticle which will:

• Configure the Outbound module, specifying which events are to be forwarded to which addresses.

• Create and manage SensorEvents, Sensors and Categories.

• • It can also be used to register the EventType, described by a Json Schema definition, if the appropriate sensorEventFactory SensorEventFactoryExtendedJsonSchemaImpl is used.

• Forward SensorEvents to an EventSender and an EventSenderLogger.

6. An EventSenderVerticle which will forward the sensor events to the Inbound module

7. An EventSenderVerticleLogger which will log said events

The verticles described in points 5 – 7 are all part of the connector-sdk-core package.