tuwien.auto.calimero.buffer
Interface Configuration

public interface Configuration

Configuration with settings associated with one network buffer.

Each network buffer is represented by one or more configurations, maintaining settings to accomplish a certain buffering task. Users of the configuration have the ability to adjust and to control the filter mechanism used for KNX messages, to specify the cache (using some arbitrary replacement policy) and to control buffer activity, and set or query configuration related information.
Different configurations associated with one network buffer are independent of each other.

Nested Class Summary

static interface	Configuration.NetworkFilter Filter applied on incoming KNX messages from the KNX network.
static interface	Configuration.RequestFilter Filter applied on requests to the network buffer from users or components working with the network buffer.

Method Summary

void	activate(boolean activate) Sets the buffer activation state of the network buffer controlled by this configuration.
KNXNetworkLink	getBaseLink() Returns the KNX network link used to create this configuration.
KNXNetworkLink	getBufferedLink() Returns the buffered network link for the network buffer of this configuration.
Cache	getCache() Returns the currently used cache object or null, if no cache was set.
DatapointModel	getDatapointModel() Returns the datapoint model set for this configuration, if any.
Configuration.NetworkFilter	getNetworkFilter() Returns the filter applied on incoming messages from the KNX network.
Configuration.RequestFilter	getRequestFilter() Returns the filter responsible for handling requests.
boolean	isActive() Returns whether the network buffer is activated.
void	setCache(Cache c) Sets the cache to be used in this configuration for buffering KNX messages.
void	setDatapointModel(DatapointModel model) Sets a datapoint model for this configuration.
void	setFilter(Configuration.NetworkFilter nf, Configuration.RequestFilter rf) Sets the filters to be applied on incoming messages from the KNX network or to answer requests to the network buffer from the user or other components.
void	setQueryBufferOnly(boolean bufferOnly) Sets the answer behavior for queries of a buffered network link.

Method Detail

activate

void activate(boolean activate)

Sets the buffer activation state of the network buffer controlled by this configuration.

The activation state controls whether filters are applied on new (incoming) KNX messages, allowing new messages to be buffered. Note that this does not affect already buffered content nor the behavior of the buffered link (for example when doing a send to the KNX network or requesting a buffered message). So a deactivated buffer effectively prevents new KNX messages to get cached.
If the network buffer gets activated and no cache was set in the first place, a default cache might be created to be used for subsequent caching operations. A deactivation will not remove or empty any cached contents.

Parameters:

activate - true to activate the buffer, false otherwise

getBaseLink

KNXNetworkLink getBaseLink()

Returns the KNX network link used to create this configuration.

Returns:

the KNX network link

getBufferedLink

KNXNetworkLink getBufferedLink()

Returns the buffered network link for the network buffer of this configuration.

A buffered link uses the base network link to access the KNX network, with additional handling for group read requests before issuing a send: the network buffer is queried whether it contains a KNX message for the requested KNX group address. If it does, the buffered message is returned skipping the read request to the base link (no access to the KNX network is done). Otherwise the read request is forwarded to the base link, which sends the request to the KNX network.
If possible, the buffered link checks the expiration timeout of a state based datapoint value using StateDP.getExpirationTimeout(), and on expired value requests an update from the KNX network.
So a buffered link utilizes the network buffer as shortcut for group communication by adding these buffer queries (when thinking in ways of design patterns, the buffered link would be a decorator object).

The buffered link behavior might be of advantage when doing process communication. For frequently queried datapoint states this might save bandwidth on the KNX network and shorten the response time of the answer.

Calling close() on the returned buffered link deactivates this configuration and will also close the base network link.

Returns:

the buffered KNX network link

getCache

Cache getCache()

Returns the currently used cache object or null, if no cache was set.

Returns:

the cache, or null if no cache in use

getDatapointModel

DatapointModel getDatapointModel()

Returns the datapoint model set for this configuration, if any.

Returns:

datapoint model or null

getNetworkFilter

Configuration.NetworkFilter getNetworkFilter()

Returns the filter applied on incoming messages from the KNX network.

If no filter was set in the first place, null is returned.

Returns:

the network filter or null

getRequestFilter

Configuration.RequestFilter getRequestFilter()

Returns the filter responsible for handling requests.

If no filter was set in the first place, null is returned.

Returns:

the request filter or null

isActive

boolean isActive()

Returns whether the network buffer is activated.

Returns:

true iff buffer is active, false otherwise

setCache

void setCache(Cache c)

Sets the cache to be used in this configuration for buffering KNX messages.

A set cache object will be used by this configuration, until the cache is removed or another cache is set. Contents of a cache are only modified through the filters set in the configuration. So, for example, a configuration will never try to empty cache contents not used anymore, when buffering is deactivated.
Setting a new cache does not change the buffering activation state (for example enable caching if not already enabled). Use activate(boolean) for this. To remove a currently used cache, invoke with argument null. Applying this method to a null argument will always deactivate buffering to prevent filters trying to access a non existing cache object.

Parameters:

c - cache to use subsequently for buffering message; use null to remove the currently used cache, if any (this also deactivates buffering)

setDatapointModel

void setDatapointModel(DatapointModel model)

Sets a datapoint model for this configuration.

The supplied model will not get modified in any way by this configuration.

Parameters:

model - datapoint model containing an arrangement with datapoints of interest; use null to remove a currently set model (if any)

setFilter

void setFilter(Configuration.NetworkFilter nf,
               Configuration.RequestFilter rf)

Sets the filters to be applied on incoming messages from the KNX network or to answer requests to the network buffer from the user or other components.

Parameters:

nf - network filter for incoming KNX messages

rf - the filter to handle requests

setQueryBufferOnly

void setQueryBufferOnly(boolean bufferOnly)

Sets the answer behavior for queries of a buffered network link.

This method allows to control the behavior, whether queries which can not be answered from the network buffer should be forwarded to the KNX network or not.
By default, queries are forwarded to the KNX network whenever necessary, and not restricted to the network buffer (bufferOnly defaults to false).
Setting this behavior does not influence nor prevent write requests to the KNX network.
If this option is enabled (queries will get answered from network buffer only), a KNXTimeoutException thrown by the invoked method in the buffered network link indicates that the buffer can not answer the query.

When issuing a read request from a buffered link, the network buffer is checked at first, whether an answer to the request is found there. If the query is not answered successfully from the buffer, the request is passed on to the KNX network.

A use case where a limitation of queries to the network buffer might be applied, is when fetching data for a table or a visualization in a graphical user interface. It usually does not matter, whether some entries are present at the beginning or not. This will prevent a peak in the KNX network load when reading a big amount of data, and it will speed up the initializing with already buffered data. Missing, but required data entries might be explicitly queried on demand by the user.

Parameters:

bufferOnly - true to limit all queries to network buffer, false to forward unanswered queries to the KNX network

See Also:

getBufferedLink()