Skip to content

IoT Time Series Client for Java

Introduction

The IoT TimeSeries Java client allows you to interact with time series data related to assets. Refer to IoT Time Series for more information about the service.

Further implementation of the IOT TimeSeries SDK library has been shown in a sample project that you can download and test in local or on Insights Hub application. Please refer to this repository: industrial-iot-java-sdk-examples

Hint

In the IoT context, assets are referred to as entity and aspects as propertyset.
Placeholders in the following samples are indicated by angular brackets < >.

Time Series Operations

Client Name: TimeSeriesClient

Read Time Series Data

This section shows two options for achieving the following behavior:

  • Read time series data for a single aspect of an asset.
  • Return data for a specified time range.
  • Return the latest value if no range is provided.
  • Return time series data for selected fields and limit.
// Construct the TimeSeriesClient object
TimeSeriesClient timeseries_client = TimeSeriesClient.builder()
                                        .mindsphereCredentials(<credentials>)
                                        .restClientConfig(<config>)
                                        .build();


List<TimeseriesData> timeseriesDataList = null;

try {
  String from_time = "2018-01-24T05:03:41.363Z";
  String to_time = "2018-01-24T05:04:41.363Z";
  Integer limit = 100;
  String select = null;

  timeseriesDataList = timeseries_client.getTimeseries(<entity_id>, <property_set_name>, from_time, to_time, limit, select);
} catch (MindsphereException e) {
  // Exception handling
}

Alternatively, use the GetTimeseriesRequest model.

// Construct the TimeSeriesClient object as shown above
GetTimeseriesRequest request_object = new GetTimeseriesRequest();
request_object.setEntity(<entity_id>);
request_object.setPropertysetname(<property_set_name>);
request_object.setFrom(<from_time>);
request_object.setTo(<to_time>);

List<TimeseriesData> timeseries_data_list = null;
try {
  timeseries_data_list = timeseries_client.getTimeseries(request_object);
} catch (MindsphereException e) {
  // Exception handling
}

Read Latest Time Series Data

This section shows two options for reading the latest value of time series data for a single aspect of an asset.

// Construct the TimeSeriesClient object as shown above
List<TimeseriesData> timeseries_data = null;
try {
    timeseries_data = timeseries_client.getTimeseries(<entity_id>, <property_set_name>, null, null, null, <select>);
} catch (MindsphereException e) {
    // Exception handling
}

Alternatively, use the GetTimeseriesRequest model.

// Construct the TimeSeriesClient object as shown above
GetTimeseriesRequest request_object = new GetTimeseriesRequest();
request_object.setEntity(<entity_id>);
request_object.setPropertysetname(<property_set_name>);

List<TimeseriesData> timeseries_data = null;
try {
    timeseries_data = timeseries_client.getTimeseries(request_object);
} catch (MindsphereException e) {
    // Exception handling
}

Write Time Series Data

This section shows two options for writing time series data for a single aspect of an asset. This overwrites existing time series data.

Note

The maximum size of a write payload is 1 MB.

// Construct the TimeSeriesClient object as shown above

// Create a list of the Timeseries objects to be added
List<Timeseries> time_series_data_list = new ArrayList<>();

// Create a Timeseries object
Timeseries time_series_object = new Timeseries();
time_series_object.setTime(Instant.now().toString());

// Create a map to add timeseries values to variables of the entity
Map<String, Object> data_map = time_series_object.getFields();
data_map.put("FRWheel", 99);
data_map.put("FLWheel", 98);

// Add the Timeseries object to the list
time_series_data_list.add(time_series_object);

try {
  timeseries_client.putTimeSeries(<entity_id>, <property_set_name>, time_series_data_list);
} catch (MindsphereException e) {
// Exception handling
}

Alternatively, use the PutTimeseriesRequest model.

// Create a list of the Timeseries objects as shown above
PutTimeseriesRequest request_object = new PutTimeseriesRequest();
request_object.setEntity(<entity_id>);
request_object.setPropertysetname(<property_set_name>);
request_object.setTimeseries(time_series_data_list);

try {
  timeseries_client.putTimeSeries(request_object);
} catch (MindsphereException e) {
// Exception handling
}

Delete Time Series Data

This section shows two options for deleting time series data from an aspect of an asset within a given time range. This also deletes data for all variables within an aspect.

Note

Only data of up to 6 months can be deleted at once.

// Construct the TimeSeriesClient object as shown above
try {
  timeseries_client.deleteTimeSeries(<entity_id>, <property_set_name>, <from_time>, <to_time>);
} catch (MindsphereException e) {
  // Exception handling
}

Alternatively, use the DeleteTimeseriesRequest model.

// Construct the TimeSeriesClient object as shown above
DeleteTimeseriesRequest request_object = new DeleteTimeseriesRequest();
request_object.setEntity(<entity_id>);
request_object.setPropertysetname(<property_set_name>);
request_object.setFrom(<from_time>);
request_object.setTo(<to_time>);

try {
  timeseries_client.deleteTimeSeries(request_object);
} catch (MindsphereException e) {
  // Exception handling
}

Last update: February 23, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.