V
- the type of the AbstractVirtualDevice instancepublic abstract class AbstractVirtualDevice<V extends AbstractVirtualDevice<V>>
extends java.lang.Object
The AbstractVirtualDevice API is common to both the enterprise client and the device client. The semantics of the API are also the same. The processing model on the enterprise client is different, however, from the processing model on the device client.
On the enterprise client, an enterprise application calls the
AbstractVirtualDevice
set methods in order to affect a change on
the physical device. The enterprise client application receives
confirmation of that the change was accepted via a
ChangeCallback
.
The ChangeCallback
indicates to the enterprise client that
the value of the attribute on the device has changed. This callback may
come as a result of the enterprise client calling set
on the
attribute, or it may come unsolicited as a result of the device-client
updating the value from the physical device.
The enterprise client may also receive an
ErrorCallback
if the attribute value change was not accepted. This could be because the
request timed out, the connection failed, or the change was explicitly
rejected. The ErrorCallback
indicates to the enterprise client
that it should roll-back the attribute value to the last known value.
On the device client, the application will call set
on a
AbstractVirtualDevice
attribute. This will cause a message to
be sent to the server. The ErrorCallback
is invoked if there
is an error sending the message to the server.
Any enterprise application that is monitoring the device
will be notified via the ChangeCallback
that the value has
changed. When the client-library receives a request from the server, the
request is forwarded to a handler which invokes the
ChangeCallback
on
the requested attribute. A GET
request simply calls get()
on the attribute.
Modifier and Type | Class and Description |
---|---|
static interface |
AbstractVirtualDevice.ChangeCallback<V>
A callback interface for receiving an event when the value
of an attribute has changed.
|
static class |
AbstractVirtualDevice.ChangeEvent<V>
An event passed to the
onChange callback to
indicate one or more attribute values have changed. |
static interface |
AbstractVirtualDevice.ErrorCallback<V>
A callback interface for receiving notification of an error when setting
the value of an attribute.
|
static class |
AbstractVirtualDevice.ErrorEvent<V>
An event passed to the
onError callback to indicate an
error has occurred when setting one or more attributes. |
static class |
AbstractVirtualDevice.Event<V>
An event passed to a callback.
|
static class |
AbstractVirtualDevice.NamedValue<T>
A name-value pair in an event.
|
Modifier and Type | Method and Description |
---|---|
abstract void |
finish()
Causes the values set in an update transaction to be sent to the
server and clears the update-transaction mark.
|
abstract <T> T |
get(java.lang.String attributeName)
Get the value of an attribute.
|
abstract DeviceModel |
getDeviceModel()
Get the device model of this device object.
|
abstract java.lang.String |
getEndpointId()
Get the endpoint id of the device.
|
abstract <T> T |
getLastKnown(java.lang.String attributeName)
Get the last known value of an attribute.
|
abstract <T> V |
set(java.lang.String attributeName,
T value)
Set the value of an attribute.
|
abstract void |
setOnChange(AbstractVirtualDevice.ChangeCallback<?> callback)
Set a callback that is invoked when the value of any attribute in the
device model changes.
|
abstract void |
setOnChange(java.lang.String attributeName,
AbstractVirtualDevice.ChangeCallback<V> callback)
Set a callback that is invoked when the value of the given attribute in the
device model changes.
|
abstract void |
setOnError(AbstractVirtualDevice.ErrorCallback<?> callback)
Set a callback that is invoked if an error occurs when setting the
value of any attribute in the device model.
|
abstract void |
setOnError(java.lang.String attributeName,
AbstractVirtualDevice.ErrorCallback<V> callback)
Set a callback that is invoked if an error occurs when setting the
value of the given attribute in the device model.
|
abstract V |
update()
Set a mark for beginning an update transaction.
|
public abstract DeviceModel getDeviceModel()
public abstract java.lang.String getEndpointId()
public abstract <T> T get(java.lang.String attributeName)
T
- the type of the attribute valueattributeName
- the name of an attribute from the device type modeljava.lang.ClassCastException
- if the attribute is not the correct return typejava.lang.IllegalArgumentException
- if the attribute is not in the model,
or attributeName
is null
public abstract <T> T getLastKnown(java.lang.String attributeName)
In the case where the enterprise client sets the value of an attribute,
the last known value is the value before an
onChange
event is received for the attribute. In the event the attribute value
could not be set, the current value is rolled back to the last known value.
For a device client, the last known value is always the same as the current value. The last known value is held by the AbstractVirtualDevice instance. No REST API call is made to the server.
T
- the type of the attribute valueattributeName
- the name of an attribute from the device type modeljava.lang.ClassCastException
- if the attribute is not the correct return typejava.lang.IllegalArgumentException
- if the attribute is not in the model,
or attributeName
is null
public abstract <T> V set(java.lang.String attributeName, T value)
AbstractVirtualDevice
state with the physical device.
This results in a REST API call to the server. For an enterprise
client, an endpoint resource REST API call is made to the server. For
a device client, an endpoint DATA message REST API call is made to the
server.
The value is validated according to the constraints in the device model.
If the value is not valid, an IllegalArgumentException is raised.T
- the type of the attribute valueattributeName
- the name of an attribute from the device type modelvalue
- the value to setjava.lang.IllegalArgumentException
- if the value is not valid,
the attribute is not in the model,
or attributeName
is null
java.lang.UnsupportedOperationException
- if the attribute is read-onlypublic abstract V update()
update
call allows more than one
value to be set on this AbstractVirtualDevice
object without
sending values to the server. The values are sent to the server when the
finish()
method is called, which also marks the end of the
update transaction.
For examplevirtualDevice.update().set("min", 10).set("max", 20).finish();
finish()
public abstract void finish()
update()
public abstract void setOnChange(java.lang.String attributeName, AbstractVirtualDevice.ChangeCallback<V> callback)
null
.
Note that it is possible to set a callback for a specific attribute and
to set a callback for all attributes via setOnChange(AbstractVirtualDevice.ChangeCallback)
.
If there is a callback for the specific attribute and for all attributes,
both callbacks will be invoked.
attributeName
- the name of an attribute from the device type modelcallback
- a callback to invoke when an attribute value changes,
if null
, the existing callback will be removedjava.lang.IllegalArgumentException
- if the attribute is not in the model,
or attributeName
is null
setOnChange(AbstractVirtualDevice.ChangeCallback)
public abstract void setOnChange(AbstractVirtualDevice.ChangeCallback<?> callback)
null
.
Note that it is possible to set a callback for all attributes and to set
a callback for a specific attribute via setOnChange(String,AbstractVirtualDevice.ChangeCallback)
.
If there is a callback for the specific attribute and for all attributes,
both callbacks will be invoked.
callback
- a callback to invoke when an attribute value changes,
if null
, the existing callback will be removedsetOnChange(String, AbstractVirtualDevice.ChangeCallback)
public abstract void setOnError(java.lang.String attributeName, AbstractVirtualDevice.ErrorCallback<V> callback)
ErrorCallback
should match the data type of the attribute.
The callback may be null
.
Note that it is possible to set a callback for a specific attribute and
to set a callback for all attributes via setOnError(AbstractVirtualDevice.ErrorCallback)
.
If there is a callback for the specific attribute and for all attributes,
both callbacks will be invoked.
attributeName
- the name of an attribute from the device modelcallback
- a callback to invoke when there is an error setting the
attribute value, if null
, the existing callback will be removedjava.lang.IllegalArgumentException
- if the attribute is not in the model,
or attributeName
is null
setOnError(AbstractVirtualDevice.ErrorCallback)
public abstract void setOnError(AbstractVirtualDevice.ErrorCallback<?> callback)
null
.
Note that it is possible to set a callback for all attributes and to set
a callback for a specific attribute via setOnError(String, AbstractVirtualDevice.ErrorCallback)
.
If there is a callback for the specific attribute and for all attributes,
both callbacks will be invoked.
callback
- a callback to invoke when there is an error setting a
value, if null
, the existing callback will be removedsetOnError(String, AbstractVirtualDevice.ErrorCallback)