Changing and Pushing Property Values
Property values change as your device collects data. The Java SDK uses a VTQ (value, time, quality) structure for properties. Property changes may result from device interrupts as well as polled values.
The event handlers of the SDK let you know when you have synchronized with the ThingWorx Platform. Once synchronization is complete, you can start pushing data to the platform. The rest of this topic explains how to send property value changes to the ThingWorx Platform and how to set the maximum size of the queue for property updates. Click a section title to display its content:
Using Methods to Change Property Values
You can programmatically change the value of a property by calling one of the methods described in the following table. It is important to keep in mind that you are not changing values on the platform using these methods. You are setting the values of the properties at the device, in memory only. Examples of using these methods follow the table.
Method | Description |
|---|---|
setPropertyVTQ | Sets the value of a property using a VTQ (value, time, and quality) structure. This method takes the following parameters: • name — The name of the property. • value — The primitive that contains the new value. • forceChange — Set this value to true to force the value to be sent to the ThingWorx Platform, even if it has not changed. Use this option to send the first value or a value immediately after the device reconnects. |
setPropertyValue | Sets the value of a property, using a primitive type. This method takes the following parameters: • name — The name of the property. • value — The VTQ (value, time, and quality) for the value of the property. |
setProperty | Sets the value of a property from an object. • name — The name of the property. • value — An object that represents the value to set. The value is cast to the type of property, if possible. Otherwise, an exception is thrown. |
Setting the Maximum Queue Size for Property Updates
The default maximum queue size is 100 properties (VTQ's) per Thing. This size is configurable. After creating your VirtualThing, call the method getPendingEvents() to return the PendingEvents object. Use the setMaximumQueueSzie(int Value) method of the PendingEvents object to change the maximum queue size from 100 to the number you require.
 | Keep in mind that these stored values are taken right out of your JVM heap space. If you change the maximum queue size, your JVM may slow down or quit if you do not empty this queue by calling updateSubscribedProperties() to send your values to the ThingWorx Platform. |
Examples of Using the Methods to Change Property Values
Here are examples of using these methods to change the value of a property from within an instance of the VirtualThing class:
//setPropertyVTQ
VTQ vtq = new VTQ();
vtq.setValue(new NumberPrimitive(123.456));
vtq.setTime(new DateTime());
vtq.setQuality(QualityStatus.GOOD);
super.setPropertyVTQ("MyProperty", vtq);
//setPropertyValue
NumberPrimitive value = new NumberPrimitive(123.456);
super.setPropertyValue("MyProperty", value);
//setProperty
super.setProperty("MyProperty", 123.456);
Here is example of using SetPropertyValue to set the values of two properties. This example is from the SteamThing.java sample:
this.setPropertyValue("Temperature", new IntegerPrimitive(temperature));
this.setPropertyValue("Humidity", new IntegerPrimitive(humidity));
Pushing Data
If you just make service calls to update your data, property subscription allows your ThingWorx Platform to ask for property values it wants and update them automatically. The subscribed property management suite provides convenient features such as
• Allowing changes to be delivered in batches
• Pushing changes only when values change, based on a configurable threshold
• Allowing changes to be folded or reduced
It is important to keep in mind that, in the Java SDK, all properties are “subscribed” properties in that you must call the updateSubscribedProperties method on the VirtualThing class to push the updated values of properties to the ThingWorx Platform. If you do not call this method, the property updates are not sent to the ThingWorx Platform. In the example SteamSensor application properties are first scanned at the device and processed. The example source file, SteamThing.java, provides an example of calling this method, using timeouts in milliseconds:
super.updateSubscribedProperties(15000);
Synchronizing State After Property Changes
When a bind or a configuration of the bound properties on a Thing has changed on the ThingWorx Platform, the synchronizeState() method is called. Here is an example of this method from the SteamSensor application, SteamThing.java file:
public void synchronizeState() {
readyToSend = true;
// Send the property values to ThingWorx when a synchronization is required
// This is more important for a solution that does not push its properties on a regular basis
super.syncProperties();
}