tuwien.auto.calimero.dptxlator
Class DPTXlatorTime

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

public class DPTXlatorTime
extends DPTXlator

Translator for KNX DPTs with main number 10, type time.

The KNX data type width is 3 bytes.
The type contains time information (hour, minute, second), together with an (optional) day of week. If no day of week is supplied or available, the value encoding "no-day" is used and returned by default. Otherwise, short day name values are used (Mon, Tue, Wed, Thu, Fri, Sat, Sun). Take care when applying user defined time formats, that the "no-day" identifier is not a supported calendar time format symbol, only a KNX DPT specific.
Where required in time calculation, the used calendar is based on the current time in the default time zone with the default locale. All time information behaves in non-lenient mode, i.e. no value overflow is allowed and values are not normalized or adjusted using the next, larger field.

The default return value after creation is no-day, 00:00:00.

Field Summary

static DPT

DPT_TIMEOFDAY DPT ID 10.001, Time of day; values from no-day, 00:00:00 to Sun, 23:59:59.

Fields inherited from class tuwien.auto.calimero.dptxlator.DPTXlator

appendUnit, data, dpt, LOG_SERVICE, logger, typeSize

Constructor Summary

DPTXlatorTime(DPT dpt)
Creates a translator for the given datapoint type.

DPTXlatorTime(java.lang.String dptID)
Creates a translator for the given datapoint type ID.

Method Summary

java.lang.String[]	getAllValues() Returns all translation items as strings currently contained in this translator.
byte[]	getData(byte[] dst, int offset) Copies KNX DPT value items stored by this translator into dst, starting at offset.
byte	getDayOfWeek() Returns the day of week information.
byte	getHour() Returns the hour information.
byte	getMinute() Returns the minute information.
byte	getSecond() Returns the second information.
java.util.Map	getSubTypes() Returns all available, implemented subtypes for the translator.
protected static java.util.Map	getSubTypesStatic()
long	getValueMilliseconds() Returns the time information in UTC milliseconds, using the translator default calendar.
void	setData(byte[] data, int offset) Sets the data array with KNX datapoint type items for translation.
void	setValue(int dayOfWeek, int hour, int minute, int second) Sets the day of week, hour, minute and second information for the first time item.
void	setValue(long milliseconds) Sets the time for the first item using UTC millisecond information.
protected 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.
static void	useValueFormat(java.lang.String pattern) Sets a user defined time value format used by all instances of this class.

Methods inherited from class tuwien.auto.calimero.dptxlator.DPTXlator

getData, getItems, getType, getTypeSize, getValue, setAppendUnit, setData, setTypeID, setValue, setValues, toString

Methods inherited from class java.lang.Object

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

Field Detail

DPT_TIMEOFDAY

public static final DPT DPT_TIMEOFDAY

DPT ID 10.001, Time of day; values from no-day, 00:00:00 to Sun, 23:59:59.

Constructor Detail

DPTXlatorTime

public DPTXlatorTime(DPT dpt)
              throws KNXFormatException

Creates a translator for the given datapoint type.

Parameters:

dpt - the requested datapoint type

Throws:

KNXFormatException - on not supported or not available DPT

DPTXlatorTime

public DPTXlatorTime(java.lang.String dptID)
              throws KNXFormatException

Creates a translator for the given datapoint type ID.

Parameters:

dptID - available implemented datapoint type ID

Throws:

KNXFormatException - on wrong formatted or not expected (available) dptID

Method Detail

getAllValues

public java.lang.String[] getAllValues()

Description copied from class: DPTXlator

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).

Specified by:

getAllValues in class DPTXlator

Returns:

an array of strings with values represented as strings

See Also:

DPTXlator.getValue()

getData

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

Description copied from class: DPTXlator

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.

Specified by:

getData in class DPTXlator

Parameters:

dst - byte array for storing DPT values

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

Returns:

dst

getDayOfWeek

public final byte getDayOfWeek()

Returns the day of week information.

The return of 0 corresponds to "no-day", indicating the day of week is not used. The first day of week is Monday with a value of 1, Sunday has a value of 7.

Returns:

day of week value, 0 <= day of week <= 7

getHour

public final byte getHour()

Returns the hour information.

Returns:

hour value, 0 <= hour <= 23

getMinute

public final byte getMinute()

Returns the minute information.

Returns:

minute value, 0 <= minute <= 59

getSecond

public final byte getSecond()

Returns the second information.

Returns:

second value, 0 <= second <= 59

getSubTypes

public java.util.Map getSubTypes()

Description copied from class: DPTXlator

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.

Specified by:

getSubTypes in class DPTXlator

Returns:

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

getSubTypesStatic

protected static java.util.Map getSubTypesStatic()

Returns:

the subtypes of the time translator type

See Also:

DPTXlator.getSubTypesStatic()

getValueMilliseconds

public final long getValueMilliseconds()

Returns the time information in UTC milliseconds, using the translator default calendar.

The method uses day of week, hour, minute and second information for calculation.
Note, since this is UTC time information, the initially returned local time 00:00:00 does therefore not corresponding to 0 milliseconds, except in the case when the local time zone is GMT.

Returns:

the time in milliseconds as long, as used in Calendar

setData

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

Description copied from class: DPTXlator

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.

Specified by:

setData in class DPTXlator

Parameters:

data - byte array containing KNX DPT item(s)

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

setValue

public final void setValue(int dayOfWeek,
                           int hour,
                           int minute,
                           int second)

Sets the day of week, hour, minute and second information for the first time item.

Any other items in the translator are discarded on successful set.
A day of week value of 0 corresponds to "no-day", indicating the day of week is not used. The first day of week is Monday with a value of 1, the last day is Sunday with a value of 7.

Parameters:

dayOfWeek - day of week, 0 <= day <= 7

hour - hour value, 0 <= hour <= 23

minute - minute value, 0 <= minute <= 59

second - second value, 0 <= second <= 59

setValue

public final void setValue(long milliseconds)

Sets the time for the first item using UTC millisecond information.

The milliseconds is interpreted with the translator default calendar.

Parameters:

milliseconds - time value in milliseconds, as used in Calendar

toDPT

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

Description copied from class: DPTXlator

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.

Specified by:

toDPT in class DPTXlator

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

useValueFormat

public static final void useValueFormat(java.lang.String pattern)

Sets a user defined time value format used by all instances of this class.

The pattern is specified according to SimpleDateFormat. Subsequent time information, supplied and returned in textual representation, will use a layout formatted according this pattern.
Note, the format will rely on calendar default time symbols (i.e. language for example), and does not support the KNX DPT identifier "no-day" for day of week. This identifier can not be used therefore.

Parameters:

pattern - the new pattern specifying the value time format, null to reset to default value format