tuwien.auto.calimero.datapoint
Class StateDP

java.lang.Object
  tuwien.auto.calimero.datapoint.Datapoint
      tuwien.auto.calimero.datapoint.StateDP

public class StateDP
extends Datapoint

Represents a state based KNX datapoint.

State based datapoint interaction leads to transitions between states (so a datapoint value associated to a certain datapoint represents a particular state over an amount of time). The state of such a datapoint can be updated/invalidated by different (i.e. more than one) KNX group addresses. An address marked as updating the state of this datapoint will allow KNX indication and response messages with that destination address to set a new datapoint state value. An address marked as invalidating the state of this datapoint will allow KNX indication messages with that destination address to delete any state value information of the datapoint.
This datapoint does not check for mutually exclusive containment of an address in one of those both categories. The behavior when adding a KNX group address to both updating and invalidating the datapoint state is undefined.

Constructor Summary

StateDP(GroupAddress main, java.lang.String name)
Creates a new state based datapoint with a name.

StateDP(GroupAddress main, java.lang.String name, java.util.Collection invalidatingAddresses, java.util.Collection updatingAddresses)
Creates a new state based datapoint and adds invalidating and updating addresses.

StateDP(GroupAddress main, java.lang.String name, int mainNumber, java.lang.String dptID)
Creates a new datapoint with a name and specifies datapoint translation type.

StateDP(XMLReader r)
Creates a new state based datapoint from XML input.

Method Summary

void	add(GroupAddress a, boolean isUpdating) Adds a group address to this datapoint to indicate that KNX messages with that address are allowed to alter the associated datapoint state (i.e. a state value related to this datapoint).
java.util.Collection	getAddresses(boolean updatingAddresses) Returns the collection of KNX group addresses which are allowed to alter the state of this datapoint.
int	getExpirationTimeout() Returns the expiration timeout for datapoint state values related to this datapoint.
boolean	isInvalidating(GroupAddress a) Returns whether KNX indication messages with destination group address a will invalidate the associated datapoint state of this datapoint.
boolean	isUpdating(GroupAddress a) Returns whether KNX indication or response messages with destination address a will update the associated datapoint state of this datapoint.
void	remove(GroupAddress a, boolean fromUpdating) Removes a state updating/invalidating group address from this datapoint.
void	setExpirationTimeout(int timeout) Sets the expiration timeout for datapoint state values related to this datapoint.
java.lang.String	toString()

Methods inherited from class tuwien.auto.calimero.datapoint.Datapoint

create, getDPT, getMainAddress, getMainNumber, getName, getPriority, isStateBased, save, setDPT, setName, setPriority

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

StateDP

public StateDP(GroupAddress main,
               java.lang.String name)

Creates a new state based datapoint with a name.

Parameters:

main - the group address used to identify this datapoint

name - user defined datapoint name

StateDP

public StateDP(GroupAddress main,
               java.lang.String name,
               java.util.Collection invalidatingAddresses,
               java.util.Collection updatingAddresses)

Creates a new state based datapoint and adds invalidating and updating addresses.

Parameters:

main - the group address used to identify this datapoint

name - user defined datapoint name

invalidatingAddresses - KNX group addresses, whose indication messages invalidate this datapoint state

updatingAddresses - KNX group addresses, whose indication and response messages lead to an update of this datapoint state

StateDP

public StateDP(GroupAddress main,
               java.lang.String name,
               int mainNumber,
               java.lang.String dptID)

Creates a new datapoint with a name and specifies datapoint translation type.

Parameters:

main - the group address used to identify this datapoint

name - user defined datapoint name

mainNumber - main number of the data type used for translation of a datapoint value; if the used dptID argument unambiguously identifies a DPT translator, main number might be left 0

dptID - the datapoint type ID used for translation in a DPT translator

StateDP

public StateDP(XMLReader r)
        throws KNXMLException

Creates a new state based datapoint from XML input.

If the current XML element position is no start tag, the next element tag is read. The datapoint element is then expected to be the current element in the reader.

Parameters:

r - a XML reader

Throws:

KNXMLException - if the XML element is no datapoint or could not be read correctly

Method Detail

add

public final void add(GroupAddress a,
                      boolean isUpdating)

Adds a group address to this datapoint to indicate that KNX messages with that address are allowed to alter the associated datapoint state (i.e. a state value related to this datapoint).

A group address can be marked as updating a state or invalidating a state. An address is added at most once to each category.

Parameters:

a - the KNX group address to add

isUpdating - true to mark the address as updating this datapoint state, false to mark it as state invalidating

getAddresses

public java.util.Collection getAddresses(boolean updatingAddresses)

Returns the collection of KNX group addresses which are allowed to alter the state of this datapoint.

Parameters:

updatingAddresses - true if the updating addresses should be returned, false for the invalidating addresses

Returns:

an unmodifiable collection with entries of type GroupAddress

getExpirationTimeout

public final int getExpirationTimeout()

Returns the expiration timeout for datapoint state values related to this datapoint.

If no timeout limit is set, 0 is returned.

Returns:

timeout in seconds, 0 for no timeout set

isInvalidating

public final boolean isInvalidating(GroupAddress a)

Returns whether KNX indication messages with destination group address a will invalidate the associated datapoint state of this datapoint.

Parameters:

a - the address to check

Returns:

true iff address is invalidating, false otherwise

isUpdating

public final boolean isUpdating(GroupAddress a)

Returns whether KNX indication or response messages with destination address a will update the associated datapoint state of this datapoint.

Parameters:

a - the address to check

Returns:

true iff address is updating, false otherwise

remove

public final void remove(GroupAddress a,
                         boolean fromUpdating)

Removes a state updating/invalidating group address from this datapoint.

The group address is no longer contained in the corresponding updating/invalidating category.

Parameters:

a - the KNX group address to remove

fromUpdating - true to remove from updating this datapoint state, false to remove from invalidating this datapoint state

setExpirationTimeout

public final void setExpirationTimeout(int timeout)

Sets the expiration timeout for datapoint state values related to this datapoint.

This timeout specifies how long a local datapoint value is considered valid since it was received or got updated the last time inside Calimero.
When working with state values related to this datapoint, this timeout should be queried using getExpirationTimeout() to check whether there is a timeout set, and a value can still be considered valid / up to date. An expired state value is not intended to be used anymore, it should be discarded and requested/updated from the KNX network.
A timeout of 0 indicates no timeout limit set.

Parameters:

timeout - timeout in seconds, 0 for no timeout limit

toString

public java.lang.String toString()

Overrides:

toString in class Datapoint