AggreGate SDK

The open-source AggreGate Software Development Kit (SDK) provides the ability to extend AggreGate Platform and integrate it with the other enterprise systems. AggreGate SDK is a set of open-source modules that provide compatibility with different operating systems. The modules are implemented in Java programming language. There are two different version of AggreGate Java SDK available:

  • AggreGate Java SDK for Java SE

  • AggreGate Java SDK for Android (Dalvik JVM)

AggreGate SDK includes the following components:

Driver vs Agent

We're often asked what is the difference between Device Driver and Java-based Agent, so here is the brief explanation:

  • Device Driver's Java code is a part of AggreGate Server, it is executed inside servers Java Virtual Machine (JVM). Agent is a standalone Java application that runs on a separate PC.

  • Device Driver uses native protocol (usually based on IP or serial communications) to interact with devices, while Agents communicate with AggreGate Server using AggreGate Protocol.

AggreGate SDK Distribution Package

The AggreGate SDK is available as a ZIP archive that contains:

  • Source code for the SDK (/agggregate-api/src folder)

  • Several demos of SDK usage:

    • /demo-api folder

    • /demo-agent folder

    • /demo-driver folder

    • /demo-plugin folder

    • /context-demo-web-app folder

  • Functional and Unit tests for the demos (/<demo name>/src/test folders)

  • Javadocs (/docs folder), including documentation for all demos.

  • Pre-built Java Archive (JAR) with SDK classes (/libs/aggregate-api.jar)

  • Necessary third-party libraries (/libs/aggregate-api-libs.jar)

AggreGate SDK Quick Start

How to get started programmatically interacting with AggreGate server instances.

Download and Configure Environment

  • Download and unpack the SDK distribution zip archive. The AggreGate SDK is available through the same distribution channels as the AggreGate server.

  • Ensure that Java Development Kit (JDK) is installed and available through either the PATH or JAVA_HOME environmental variable of the machine that will be running the solutions built with the SDK.

  • Set up a running instance of AggreGate server. By default, all the examples are configured to interact with a server on localhost:8080 using credentials login: admin and password: admin. The final example below explains how to change this configuration to access remote servers with different credentials.

List Examples

  • Navigate to the directory where the SDK was extracted and run the gradlew binary with argument :demo-api:tasks.

    • For Unix-like systems: ./gradlew :demo-api:tasks

    • For Windows: gradlew.bat :demo-api:tasks

The output should indicate the available examples:

Playground tasks 
---------------- 
ExecuteAction 
GetServerVersion 
ManageDevices
ManageUsers

Running Example Tasks

  • Tasks can be run using the gradlew binary and the argument :demo-api:<task name>. To run the GetServerVersion example, run the following:

    • For Unix-like systems: ./gradlew :demo-api:GetServerVersion

    • Windows: gradlew.bat :demo-api:GetServerVersion

The output should be something similar to the following:

> Task :demo-api:GetServerVersion
15:51:34,979 INFO  ag.test         Server version: 6.31.00

Further Development

  • To see how the tasks are structured and experiment with editing them, open any of the demo-api/src/main/java/examples/api/<task name>.java files in a text editor or IDE.

  • Any changes to the file can be tested by saving the file and running the task using the gradlew binary.

  • For example, by updating the following line in any of the tasks, it is possible to change the server address and connection credentials in order to connect to a remote server, or connect with a different user. 

    // Provide correct server address/port and name/password of server user to log in as
    RemoteServer rls = new RemoteServer("localhost", RemoteServer.DEFAULT_PORT, "admin", "admin");

The included examples show a variety of use cases for interacting with an AggreGate server, and should be helpful in developing solutions for custom use cases.

Using the SDK in Java Applications

To use the AggreGate SDK for an application, you have to add the following java archives (JARs) from the /libs folder of the Distribution Package to the classpath of your Java application:

  • aggregate-api.jar

  • aggregate-api-libs.jar

The first archive contains AggreGate-specific code, while the second one contains the third-party libraries used by the SDK.

Further Information for Javadocs and Sources

For detailed information on specific classes and interfaces included in the SDK refer to:

  • Javadocs located in the /docs folder of SDK distribution package

  • Source code located in the /aggregate-api/src folder of SDK distribution package

Java Version

Most AggreGate Server and AggreGate Client distributions include a bundled JVM. Any Java VMs installed in the OS are not used by default. Thus, any custom modules should be compiled for the version of Java used by server/client. This version can be found in system requirements (server requirements, client requirements).

Was this page helpful?