Skip to content

DSLink Development Guide

Jump to bottom
Aaron edited this page Jul 8, 2019 · 10 revisions

Warning

Only use org.iot.dsa APIs, do not use or depend on anything in com.* packages.

Please utilize the Javadocs for the core sdk. The more they're used, they better they'll get.

Overview

The purpose of this document is to guide the reader through the development of Java DSA links using this SDK. Developers will build links using the org.iot.dsa.* packages found in the dslink-v2 module.

Creating a Link

These are the major steps you'll take when creating a link:

  1. Copy the example link.
  2. Create application nodes.

Copy Example Link

Copy the dslink-java-v2-example project to create a new repository. It's README provides detailed instructions for customization.

The example link is a very simple but fully functioning link with a single main node. It is recommended you get that running against a broker before continuing with this documentation.

Create Application Nodes

DSNode subclasses are where application specific logic is bound to the link architecture.

This guide provides information about org.iot.dsa.node.DSNode.

All links must create a main node. It is the hook for the rest of your functionality.

Main Node

All links require a main node and it must subclass org.iot.dsa.dslink.DSMainNode. The convention is to name the class MainNode and it's package must be unique from any other MainNodes (other links) so multiple links can be run in the same process.

When a link launches the first time, the type of the main node is looked up dslink.json. The config main-node must store the fully qualified class name of the root node.

Actions

Actions allow allow responders to expose functionality in DSA that can't be modeled as node or values.

This guide provides information about actions.

Metadata

Metadata can be information such as units for number types and ranges for enums.

When the system collects metadata about an object, it uses these steps:

  1. If the target value or node implements org.iot.dsa.node.DSIMetadata. it will be given the opportunity to provide metadata first.
  2. Then getMetadata on the parent node will be called with the DSInfo representing the child. This will be useful when nodes want to store user editable metadata.

To simplify configuring metadata, use the utility class org.iot.dsa.node.DSMetadata.

Timers and Threads

Use org.iot.dsa.DSRuntime.

Please avoid using Java executors if possible. In the future we will probably monitor DSRuntime to help determine when a system is becoming overloaded.

Creating your own threads for long lived activities is perfectly acceptable but not necessary.

Logging

The SDK uses Java Util Logging (JUL). A high performance async logger is automatically installed as the root logger.

DSNode subclasses org.iot.dsa.logging.DSLogger. It has many variations on the following methods for logging:

  • trace
  • debug
  • info
  • warn
  • error

The most efficient logging will not submit a log message if the level isn't enabled. This is how it is normally achieved with JUL:

    if (myLogger.isLoggable(Level.FINE)) {
        myLogger.fine(someMessage());
    }

DSLogger enables the same but with more concise syntax:

  trace(trace() ? someMessage() : null);

DSA has it's own log levels (there can be links in many different languages). Standard Java log level are mapped into it, but try to use the DSA levels:

Level Guidelines

DSA Level = Java Level

  • trace = Level.FINEST;
  • debug = Level.FINER;
  • info = Level.INFO;
  • warn = Level.WARNING;
  • error = Level.SEVERE;

Home

Developer Docs

User Docs

Clone this wiki locally