tuwien.auto.calimero.dptxlator
Class DPTXlatorDateTime

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

public class DPTXlatorDateTime
extends DPTXlator

Translator for KNX DPTs with main number 19, type date with time.

The KNX data type width is 8 bytes.
The type contains date information (month, day of month, day of week), time information (hour, minute, second), additional time information (work-day, daylight saving time (DST)) and clock information (faulty clock, external clock synchronization signal). The field usage of work-day, year, date, time, day of week field is optional.
By default, on setting date/time information, only general range checks are performed, no check is done whether the information corresponds to a valid calendar time (see validate(). All field-methods behave in non-lenient time value mode, i.e. no value overflow is allowed and values are not normalized or adjusted using the next, larger field. (e.g. February, 29th will not result in March, 1st on no leap year).
This type permits the hour set to 24 (with minute and second only valid if 0), representing midnight of the old day, to handle time information used in schedule programs.

The default return value after creation is the calendar value equal to 1900/1/1 00:00:00 (year/month/day hh:mm:ss), no clock fault, not in daylight saving time, no external clock synchronization signal, day of week and work day fields are not used.

Field Summary

static int	CLOCK_FAULT Field number to query or change the clock fault information.
static int	CLOCK_SYNC Field number to query or change the external clock synchronization signal information.
static int	DATE Field number for get and set indicating whether the date field (month and day of month) is used.
static int	DAY_OF_WEEK Field number for get and set indicating whether the day of week field is used.
static int	DAYLIGHT Field number to query or change the daylight saving time (DST) information.
static DPT	DPT_DATE_TIME DPT ID 19.001, Date with time; values from 1900, 01/01 00:00:00 to 2155, 12/31 24:00:00.
static int	MAX_YEAR Maximum year representable by this type, year = 2155.
static int	MIN_YEAR Minimum year representable by this type, year = 1900.
static int	TIME Field number for get and set indicating whether the time field (hour, minute and second) is used.
static int	WORKDAY Field number for get and set indicating whether the work-day field is used; furthermore it is used to change the corresponding work-day value.
static int	YEAR Field number for get and set indicating whether the year field is used.

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

appendUnit, data, dpt, LOG_SERVICE, logger, typeSize

Constructor Summary

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

DPTXlatorDateTime(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.
boolean	getDateTimeFlag(int field) Returns the information value of field.
byte	getDay() Returns the day of month information.
byte	getDayOfWeek() Returns the day of week information.
byte	getHour() Returns the hour information.
byte	getMinute() Returns the minute information.
byte	getMonth() Returns the month 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 date and time information of the first date/time item in UTC milliseconds, using the system default Calendar.
short	getYear() Returns the year information.
boolean	isFaultyClock() Returns whether the date/time information is marked as corrupted.
boolean	isValidField(int field) Returns whether a field is valid, i.e. supported and used for date/time information.
void	setData(byte[] data, int offset) Sets the data array with KNX datapoint type items for translation.
void	setDate(int year, int month, int day) Sets year, month and day of month information of the first date/time item.
void	setDateTimeFlag(int field, boolean value) Sets date/time information for the given field of the first date/time item.
void	setDayOfWeek(int day) Sets the day of week of the first date/time item.
void	setFaultyClock(boolean fault) Sets the clock fault information field of the first date/time item.
void	setTime(int hour, int minute, int second) Sets the hour, minute and second information for the first date/time item.
void	setValidField(int field, boolean valid) Sets a date/time field of the first translation item to valid or not valid.
void	setValue(long milliseconds) Sets the date/time for the first date/time 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.
void	useValueFormat(boolean extended) Specifies the formatting to use for date/time string representations returned by the translator.
boolean	validate() Does a complete validity check on the contained date/time items.

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

CLOCK_FAULT

public static final int CLOCK_FAULT

Field number to query or change the clock fault information.

A clock fault indicates one or more corrupted date/time fields, for example due to power down of device, not configured clock, no reception of synchronization message, ... .

See Also:

setDateTimeFlag(int, boolean), getDateTimeFlag(int), Constant Field Values

CLOCK_SYNC

public static final int CLOCK_SYNC

Field number to query or change the external clock synchronization signal information.

In string values, this information can be specified by using "in sync" or "no sync" to set clock synchronization. Omitting this information defaults to no external clock synchronization signal.

See Also:

setDateTimeFlag(int, boolean), getDateTimeFlag(int), Constant Field Values

DATE

public static final int DATE

Field number for get and set indicating whether the date field (month and day of month) is used.

See Also:

setValidField(int, boolean), isValidField(int), Constant Field Values

DAY_OF_WEEK

public static final int DAY_OF_WEEK

Field number for get and set indicating whether the day of week field is used.

See Also:

setValidField(int, boolean), isValidField(int), Constant Field Values

DAYLIGHT

public static final int DAYLIGHT

Field number to query or change the daylight saving time (DST) information.

This field is for user information solely, any DST offset is already considered in the time field (i.e. the hour field contains the adjusted value).

If daylight saving time is used, this information can be specified in string values by using "DST" to denote daylight saving time.

See Also:

setDateTimeFlag(int, boolean), getDateTimeFlag(int), Constant Field Values

DPT_DATE_TIME

public static final DPT DPT_DATE_TIME

DPT ID 19.001, Date with time; values from 1900, 01/01 00:00:00 to 2155, 12/31 24:00:00.

MAX_YEAR

public static final int MAX_YEAR

Maximum year representable by this type, year = 2155.

See Also:

Constant Field Values

MIN_YEAR

public static final int MIN_YEAR

Minimum year representable by this type, year = 1900.

See Also:

Constant Field Values

TIME

public static final int TIME

Field number for get and set indicating whether the time field (hour, minute and second) is used.

See Also:

setValidField(int, boolean), isValidField(int), Constant Field Values

WORKDAY

public static final int WORKDAY

Field number for get and set indicating whether the work-day field is used; furthermore it is used to change the corresponding work-day value.

The work-day information can be specified in string values by using "workday" to denote a working day.

See Also:

setValidField(int, boolean), isValidField(int), setDateTimeFlag(int, boolean), getDateTimeFlag(int), Constant Field Values

YEAR

public static final int YEAR

Field number for get and set indicating whether the year field is used.

See Also:

setValidField(int, boolean), isValidField(int), Constant Field Values

Constructor Detail

DPTXlatorDateTime

public DPTXlatorDateTime(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

DPTXlatorDateTime

public DPTXlatorDateTime(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

getDateTimeFlag

public final boolean getDateTimeFlag(int field)

Returns the information value of field.

Allowed fields are CLOCK_FAULT, CLOCK_SYNC, WORKDAY and DAYLIGHT.

Parameters:

field - field number to query

Returns:

the field value as boolean, true if set, false otherwise

getDay

public final byte getDay()

Returns the day of month information.

The first day of month equals 1.

Returns:

day value, 0 < day <= 31, might be 0 on unused field

getDayOfWeek

public final byte getDayOfWeek()

Returns the day of week information.

The return of 0 corresponds to "any day", indicating the day of week is variable (used in scheduling). The first day of week is Monday with a value of 1.

Returns:

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

getHour

public final byte getHour()

Returns the hour information.

An hour value of 24 represents midnight of the old day, the corresponding minute and second are always 0.

Returns:

hour value, 0 <= hour <= 24

getMinute

public final byte getMinute()

Returns the minute information.

Returns:

minute value, 0 <= minute <= 59

getMonth

public final byte getMonth()

Returns the month information.

Returns:

month value, 0 < month <= 12, might be 0 on unused field

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 date with time translator type

See Also:

DPTXlator.getSubTypesStatic()

getValueMilliseconds

public final long getValueMilliseconds()
                                throws KNXFormatException

Returns the date and time information of the first date/time item in UTC milliseconds, using the system default Calendar.

The method uses the year, month, day, DST and, optionally, hour, minute, second and day of week field for calculation.
On unused time field, 00:00:00 is used. If year, month or day field is unused (see isValidField(int), or the field values do not represent a valid calendar time, an exception is thrown. If time equals 24:00:00, it is represented as 23:59:59.999, since the time ambiguity of midnight is resolved as midnight belonging to the next day (00:00:00) in the used calendar. However, no field values itself is changed permanently.
The used calendar is obtained by Calendar.getInstance(), and the calculation is done in non-lenient mode.

Returns:

the date/time in milliseconds as long,

Throws:

KNXFormatException - on required, but not set fields, if date/time information does not represent a valid calendar time,

getYear

public final short getYear()

Returns the year information.

Returns:

year value, 0 <= second <= 59

isFaultyClock

public final boolean isFaultyClock()

Returns whether the date/time information is marked as corrupted.

It should always queried first, before accessing further date/time information, to assure correct values.

Returns:

true on clock fault, false otherwise

See Also:

getDateTimeFlag(int), CLOCK_FAULT

isValidField

public final boolean isValidField(int field)

Returns whether a field is valid, i.e. supported and used for date/time information.

Only data of valid fields are required to be set or examined. A field set to not valid shall be ignored, it is not supported and contains no valid data.
Possible fields allowed to be set valid or not valid are YEAR, DATE, TIME, DAY_OF_WEEK and WORKDAY.

Parameters:

field - field number

Returns:

true if field is supported and in use, false otherwise

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

setDate

public final void setDate(int year,
                          int month,
                          int day)

Sets year, month and day of month information of the first date/time item.

This method does not reset other item data or discard other translation items.

Parameters:

year - year value, 1900 <= year <= 2155

month - month value, 1 <= month <= 12

day - day value, 1 <= day <= 31

setDateTimeFlag

public final void setDateTimeFlag(int field,
                                  boolean value)

Sets date/time information for the given field of the first date/time item.

Allowed fields are CLOCK_FAULT, CLOCK_SYNC, WORKDAY and DAYLIGHT.
This method does not reset other item data or discard other translation items.

Parameters:

field - field number

value - true to set the information flag, false to clear

setDayOfWeek

public final void setDayOfWeek(int day)

Sets the day of week of the first date/time item.

A day of week value of 0 corresponds to "any day", indicating the day of week is variable (used in scheduling). The first day of week is Monday with a value of 1.
This method does not reset other item data or discard other translation items.

Parameters:

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

setFaultyClock

public final void setFaultyClock(boolean fault)

Sets the clock fault information field of the first date/time item.

Equal to invoking setDateTimeFlag(int, boolean) with field CLOCK_FAULT.
This method does not reset other item data or discard other translation items.

Parameters:

fault - true if clock is faulty, false otherwise

See Also:

setDateTimeFlag(int, boolean), CLOCK_FAULT

setTime

public final void setTime(int hour,
                          int minute,
                          int second)

Sets the hour, minute and second information for the first date/time item.

On a hour value of 24, values of minute and second have to be 0.
This method does not reset other item data or discard other translation items.

Parameters:

hour - hour value, 0 <= hour <= 24

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

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

setValidField

public final void setValidField(int field,
                                boolean valid)

Sets a date/time field of the first translation item to valid or not valid.

A field which is valid, i.e. contains valid data, has to be set true, otherwise the field should be set not valid with false.
Possible fields allowed to be set valid or not valid are YEAR, DATE, TIME, DAY_OF_WEEK and WORKDAY.

Parameters:

field - field number

valid - true if field is supported and contains valid data, false otherwise

setValue

public final void setValue(long milliseconds)

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

Following fields are set: year, month, day, day of week, hour, minute, second, daylight time. All according fields are set to used state.
The value is interpreted by a calendar obtained by Calendar.getInstance().
The new value item replaces any other items contained in this translator.

Parameters:

milliseconds - time value in milliseconds, as used by 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 final void useValueFormat(boolean extended)

Specifies the formatting to use for date/time string representations returned by the translator.

A string in extended format contains all valid information of the date/time type. In extended format, additionally the day of week, daylight time, work-day and clock synchronization signal information is considered in the output format. Otherwise this fields are always ignored, i.e only clock fault, year, month, day, hour, minute and second will get used, if valid.

The used format is extended by default.

Parameters:

extended - string format to use, true for extended format

validate

public final boolean validate()

Does a complete validity check on the contained date/time items.

An item is valid if all used fields correspond to a valid calendar time. The check is only performed if at least year and date fields are used.
After modifying date/time fields, this method has to be called again if validation is required.
It returns the result of the validity checks performed on the date/time items.

Comparison of the two kinds of validity:
When setting individual parts of a date/time, only the KNX requirements for the DPT are checked, as requested by the DPT specification. For example, this includes a common range check of a value. So set items always match these KNX value ranges.
This validation method checks if the date/time fields represent a valid calendar time, which is a much stronger requirement.

Returns:

true if date/times are valid, false otherwise