tuwien.auto.calimero.dptxlator
Class DPTXlator

java.lang.Object
  tuwien.auto.calimero.dptxlator.DPTXlator

Direct Known Subclasses:

DPTXlator2ByteFloat, DPTXlator2ByteUnsigned, DPTXlator3BitControlled, DPTXlator4ByteUnsigned, DPTXlator8BitUnsigned, DPTXlatorBoolean, DPTXlatorDate, DPTXlatorDateTime, DPTXlatorString, DPTXlatorTime

public abstract class DPTXlator
extends java.lang.Object

DPT translator interface for data conversion between KNX DPTs and java types.

A translator supports translation of more than one values / DPTs at the same time.
After creation, a translator initially contains at least one valid default item (i.e. value and data) representation for return through a getValue- or getData-like method call.

The naming convention used for translator methods is to use methods comprising "data" in its name for handling KNX data types (usually contained in byte arrays), while methods comprising "value" for handling java types.

A translator shall publish its supported subtypes as constants of type DPT through its interface.

Although there is no restriction on changing the datapoint type ID of a translator after creation (and consequently adjust all contained translation items to the new subtype), there seems no real requirement for this; therefore it is not implemented nor supported.

DPT translator implementations are not required to be thread safe. All translators provided in this package are not thread safe.

Field Summary

protected boolean	appendUnit Behavior regarding appending a DPT engineering unit.
protected short[]	data Array containing KNX data type values.
protected DPT	dpt The datapoint type set for the translator.
static java.lang.String	LOG_SERVICE Name of the log service used in DPT translators.
protected static LogService	logger Logger object for all translators.
protected int	typeSize Specifies the size of the data type in bytes, set 0 if type size <= 6 bits.

Constructor Summary

DPTXlator(int dataTypeSize)
Creates the new translator and initializes the data type size.

Method Summary

abstract java.lang.String[]	getAllValues() Returns all translation items as strings currently contained in this translator.
byte[]	getData() Returns a copy of all items stored by this translator translated into DPTs.
abstract byte[]	getData(byte[] dst, int offset) Copies KNX DPT value items stored by this translator into dst, starting at offset.
int	getItems() Returns the number of translation items currently in the translator.
abstract java.util.Map	getSubTypes() Returns all available, implemented subtypes for the translator.
protected static java.util.Map	getSubTypesStatic() Returns all available subtypes for the translator class, equal to getSubTypes(), every DPT translator has to implement this method.
DPT	getType() Returns the datapoint type used by the translator for translation.
int	getTypeSize() Returns the KNX data type size in bytes for one value item.
java.lang.String	getValue() Returns the first value stored by this translator formatted into a string, according to the subtype ID.
void	setAppendUnit(boolean append) Sets the behavior regarding appending a DPT engineering unit to items returned by this translator.
void	setData(byte[] data) See setData(byte[], int), with offset 0.
abstract void	setData(byte[] data, int offset) Sets the data array with KNX datapoint type items for translation.
protected void	setTypeID(java.util.Map availableTypes, java.lang.String dptID) Sets the DPT for the translator to use for translation, doing a lookup before in the translator's map containing the available, implemented datapoint types.
void	setValue(java.lang.String value) Translates the value according to the set datapoint ID.
void	setValues(java.lang.String[] values) Translates the array of strings according to the set datapoint ID.
protected abstract void	toDPT(java.lang.String value, short[] dst, int index) Translates a string value representation into KNX data type according the current DPT and stores the result into dst.
java.lang.String	toString() Returns a string of the used DPT together with all translation items currently contained in this translator.

Methods inherited from class java.lang.Object

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

Field Detail

appendUnit

protected boolean appendUnit

Behavior regarding appending a DPT engineering unit.

Methods capable of returning an item value together the engineering unit of the DPT, should append the unit on true, and omit any unit representation on false; default setting is true.
Only relevant for DPTs with an associated engineering unit.

data

protected short[] data

Array containing KNX data type values.

For every element entry, only the lower byte is allowed to be set. This way, it is possible to store and access unsigned bytes.
The length of the array indicates how much KNX data values are contained for conversion.

dpt

protected DPT dpt

The datapoint type set for the translator.

LOG_SERVICE

public static final java.lang.String LOG_SERVICE

Name of the log service used in DPT translators.

See Also:

Constant Field Values

logger

protected static final LogService logger

Logger object for all translators.

typeSize

protected final int typeSize

Specifies the size of the data type in bytes, set 0 if type size <= 6 bits.

It is used for calculating the number of items in the translator, and also by users for detecting an optimized (short) group structure format.

Constructor Detail

DPTXlator

public DPTXlator(int dataTypeSize)

Creates the new translator and initializes the data type size.

Parameters:

dataTypeSize - size in bytes of the KNX data type, use 0 if the type size <= 6 bits

Method Detail

getAllValues

public abstract java.lang.String[] getAllValues()

Returns all translation items as strings currently contained in this translator.

The items are ordered the same way handed to the translator in the first place (FIFO, increasing byte index).

Returns:

an array of strings with values represented as strings

See Also:

getValue()

getData

public byte[] getData()

Returns a copy of all items stored by this translator translated into DPTs.

Returns:

byte array with KNX DPT value items

getData

public abstract byte[] getData(byte[] dst,
                               int offset)

Copies KNX DPT value items stored by this translator into dst, starting at offset.

The number of items copied depends on the usable dst range, i.e. how much items completely fit into dst.length - offset. If the usable range is too short, no item is copied at all, and dst is not modified.
Datapoint types shorter than 1 bytes only change the affected lower bit positions, leaving the upper (high) bits of dst bytes untouched.

Parameters:

dst - byte array for storing DPT values

offset - offset into dst from where to start, 0 <= offset < dst.length

Returns:

dst

getItems

public int getItems()

Returns the number of translation items currently in the translator.

Returns:

items number

getSubTypes

public abstract java.util.Map getSubTypes()

Returns all available, implemented subtypes for the translator.

A subtype, identified through a sub number, specifies the available dimension, consisting of range and unit attributes. Together with the main type information this uniquely defines a datapoint type.
The datapoint type information is contained in a DPT object.

New or modified DPT information can be made available to the translator by adding entries to the map, likewise map entries might be removed. In other words, the map returned is the same used by the translators of one main type for DPT lookup. Changes to the map influence all translators of the same main type.
Changes of the DPT currently used by the translator take effect on the next new translator created using that DPT.
The map itself is not synchronized.

Returns:

subtypes as Map, key is the subtype ID of type string, value of type DPT

getSubTypesStatic

protected static java.util.Map getSubTypesStatic()

Returns all available subtypes for the translator class, equal to getSubTypes(), every DPT translator has to implement this method. It is used for subtype listings without creating a translator object.

Note, since this is a class method, static binding is used.
In particular, the method is invoked without reference to a particular object, and hidden by declarations with the same signature in a sub type. A correct invocation is done using the declared type that actually contains the method declaration returning the available sub types.

Returns:

subtypes as Map, key is the subtype ID of type string, value of type DPT

getType

public final DPT getType()

Returns the datapoint type used by the translator for translation.

The DPT distinguishes between the different subtypes available for a KNX data type. It specifies the dimension, consisting of range and unit attributes.

Returns:

datapoint type in a DPT

getTypeSize

public final int getTypeSize()

Returns the KNX data type size in bytes for one value item.

If the data type size is <= 6 bits, 0 is returned.

Returns:

type size in bytes, 0 for types <= 6 bits

getValue

public java.lang.String getValue()

Returns the first value stored by this translator formatted into a string, according to the subtype ID.

If the subtype has a unit of measurement, it is appended after the value according to setAppendUnit(boolean).

Returns:

a string representation of the value

See Also:

getType()

setAppendUnit

public final void setAppendUnit(boolean append)

Sets the behavior regarding appending a DPT engineering unit to items returned by this translator.

Translator methods capable of appending an available DPT unit will act according this setting.

Parameters:

append - true to append a DPT unit if any available, false to omit any unit

setData

public final void setData(byte[] data)

See setData(byte[], int), with offset 0.

Parameters:

data - byte array containing KNX DPT item(s)

setData

public abstract void setData(byte[] data,
                             int offset)

Sets the data array with KNX datapoint type items for translation.

The data array contains at least one DPT item, the new item(s) will replace any other items set in the translator before.
The number of items (KNX data values) for translation in data is inferred from the length of the usable data range:
items = (data.length - offset) / (length of KNX data type)

In general, the KNX data type width is implicitly known in the context where a translator is invoked (e.g. by appropriate DP configuration), therefore data.length will satisfy the minimum acceptable length. If this is not the case, KNXIllegalArgumentException has to be caught and handled in the caller's context.

Parameters:

data - byte array containing KNX DPT item(s)

offset - offset into data from where to start, 0 <= offset < data.length

Throws:

KNXIllegalArgumentException - if data.length - offset < data type width of this DPTXlator

setTypeID

protected void setTypeID(java.util.Map availableTypes,
                         java.lang.String dptID)
                  throws KNXFormatException

Sets the DPT for the translator to use for translation, doing a lookup before in the translator's map containing the available, implemented datapoint types.

Parameters:

availableTypes - map of the translator with available, implemented DPTs; the map key is a dptID string, map value is of type DPT

dptID - the ID as string of the datapoint type to set

Throws:

KNXFormatException - on DPT not available

setValue

public void setValue(java.lang.String value)
              throws KNXFormatException

Translates the value according to the set datapoint ID.

If, and only if, value can successfully be translated, it gets stored by the translator, replacing any old items. Textual commands contained in value are treated case insensitive.
The value string might have its unit of measure appended (units are case sensitive).

Parameters:

value - value represented as string for translation, case insensitive

Throws:

KNXFormatException - if value can't be translated due to wrong formatted content, or if valuedoesn't fit into KNX data type

setValues

public void setValues(java.lang.String[] values)
               throws KNXFormatException

Translates the array of strings according to the set datapoint ID.

If, and only if, all items in values can successfully be translated, they get stored by the translator, replacing any old items. On values.length == 0, no action is performed.
Textual commands contained in values are treated case insensitive.

Parameters:

values - string array holding values for translation

Throws:

KNXFormatException - if an item in values can't be translated due to a wrong formatted content, or if valuedoesn't fit into KNX data type

toDPT

protected abstract void toDPT(java.lang.String value,
                              short[] dst,
                              int index)
                       throws KNXFormatException

Translates a string value representation into KNX data type according the current DPT and stores the result into dst. The index parameter specifies the item index of the value. The translated KNX data is stored at the corresponding array offset in dst. Calculation of offset: offset = index * KNX data type size.

Parameters:

value - value to translate

dst - destination array for resulting KNX data

index - item index in destination array

Throws:

KNXFormatException - if value can't be translated due to wrong formatted content, or if valuedoesn't fit into KNX data type

toString

public java.lang.String toString()

Returns a string of the used DPT together with all translation items currently contained in this translator.

The string consists of a list of values in the order they are returned by getAllValues(). Adjacent items are separated as specified by AbstractCollection.toString().

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the translation values