Skip to content

Using the Java SDK

The KX Insights Platform Java SDK can be used to ingest data into the KX Insights Platform over the Reliable Transport (RT) protocol.

This section details how to get started with the Java SDK. For examples on how to use it to publish data into the KX Insights Platform see documentation on the sample program.

Downloading the Java SDK

The Java SDK and a sample program can be downloaded from the KX Insights Nexus registry.

Note

The SDKs are only supported on Linux running on x86 architectures. We currently do not support Windows or OsX.

No installation is required, just download the zip file and unzip. The jar file contains everything required to use the Java SDK.

Environment variables

The Java SDK uses the following environment variables:

variable description
RT_REP_DIR Path where the replicator can be extracted to. It must be possible to execute a program from this location.
KXI_CONFIG_URL The URL that this program will call to find the endpoint(s) it will need to connect to. This is in the form https://{INSIGHTS_HOSTNAME}/informationservice/details/{KC_CLIENT_ID}.
RT_LOG_PATH The location where the RT messages streams will be written to.

Supported data types

The following data types are supported by the Java SDK:

q type name q type number java type schema notation example
boolean -1 Boolean 'boolean' true
guid -2 UUID 'guid' 0f14d0ab-9605-4a62-a9e4-5ed26688389b
byte -4 Byte 'byte' 0xF4
short -5 Short 'short' 5
int -6 Integer 'int' or 'integer' 56789
long -7 Long 'long' 12345678
real -8 Float 'real' 2.5
float -9 Double 'float' 89.3
char -10 Character 'char' d
symbol -11 String 'symbol' LLOY
timestamp -12 java.sql.Timestamp 'timestamp' or 'ts' 2000.01.01D00:00:00.200000000
month -13 kx.c.Month 'month' 2002.02m
date -14 java.sql.Date 'date' 1999.12.31
datetime -15 java.util.Date 'datetime' 12.31,1999.12.31T23:59:59.999
timespan -16 kx.c.Timespan 'timespan' 00:00:00.000000000
minute -17 kc.c.Minute 'minute' 00:00
second -18 kx.c.Second 'second' 00:00:00
time -19 java.sql.Time 'time' 00:00:00
string 10 char[] 'string' "this is a string"

symbol type

Only make text columns into symbols when the fields will be drawn from a small, reasonably stable domain and there is significant repetition in their use. When in doubt, start with a string column. It is much easier to convert a string column to symbols than it is to remove symbols from the sym list.

time type

Because java.sql.Time does not have milliseconds, some precision will be lost if this type is used.

Using the Java SDK in your own application

To publish data to the KX Insights Platform using the Java SDK as part of your own application you need to use the RTClient class. This class reads all the information needed to connect to the KX Insights Platform from the environment and publishes the data into the Platform.

For details on a sample program which publishes data into the KX Insights Platform see here.

Initializing

To start a new RtClient object in Java, just do the following:

RtClient client = new RtClient("https://{INSIGHTS_HOSTNAME}/informationservice/details/{KC_CLIENT_ID}");
client.start();

If you want to want to pull the configuration url from the KXI_CONFIG_URL environment variable rather passing it into the constructor you can use the StreamingClientFactory:

StreamingClientFactory scf = new StreamingClientFactory(new HttpsConfigRequestor(parser));
StreamingClient client = scf.getStreamingClient();
client.start()

Publishing data

An example of publishing data can be seen in the BulkLoader.java class.

private void wrapDataAndPushToTopic(Flip row) throws RtClientException, RtConfigException
{
    Object[] unwrappedMsg = {RtClient.BULK_LOAD_MSGNAME, tableName, row};
    client.pasync("insert", unwrappedMsg);
}

RtClient.BULK_LOAD_MSGNAME is in the .b format.

The .b format is a 2D array, where the first dimension is the row number, and the second is the column number."

Alternatively you can just use the BulkLoader class to publish data. It will handle turning 2-dimensional arrays into Flip objects before sending them into the KX Insights Platform. You can make one like this (example taken from RandomDataSample.java):

String[] columns = new String[] { "Time", "SensorName", "Voltage", "Current" };
BulkLoader tw = new BulkLoader(tableName, client, columns);

Then you can just pass in 2D arrays, where the first dimension is the row number, and the second is the column number.

Random rand = new Random();
Timestamp now = new Timestamp(System.currentTimeMillis());
for (int i = 0; i < numEntries; i++)
 {
    Object[][] tableToSend = new Object[NUM_SENSORS][];
    for (int j = 0; j < NUM_SENSORS; j++)
    {
        tableToSend[j] = new Object[columns.length];
        tableToSend[j][0] = now;
        tableToSend[j][1] = String.format("Sensor_%d", j);
        tableToSend[j][2] = rand.nextFloat() * 240.0f;
        tableToSend[j][3] = rand.nextFloat() * 10.0f;
        System.out.printf("Writing line, %s, %s, %f, %f\n",
        tableToSend[j][0], tableToSend[j][1], tableToSend[j][2], tableToSend[j][3]);
    }

    tw.writeTable(tableToSend);
}

Terminating

Once you are done with the client you must call stop() on the RTClient object.

client.stop()