tuwien.auto.calimero.mgmt
Class PropertyClient

java.lang.Object
  tuwien.auto.calimero.mgmt.PropertyClient

public class PropertyClient
extends java.lang.Object

A client to access properties in interface objects of a device.

This can be done in different ways, to specify the kind of access a property adapter is supplied on creation of the property client. The implementation of the PropertyAdapter interface methods don't need to be synchronized for use by this property client.

Properties can be retrieved or set in the device, property descriptions can be read and scans of properties can be done.
If desired, the property data type of a property element is used to return an appropriate DPT translator or the ready formatted string representation.
The DPT translators used are requested from PropertyTypes by default, or, if property definitions were loaded, there will be a lookup in these data at first (i.e. loaded property definitions take priority over the default PDT to DPT mapping).

It is possible to load property definitions with information about KNX properties from a resource to be used by the property client for lookup requests and property type translation. Also, definitions can be saved to a resource. A global resource handler takes care of working with the resource where these definitions are stored. Loaded definitions are shared with all property clients.
Loading of such definitions is not required for a client to work, i.e. might be done optionally by the user.

By default, the resource handler uses a xml property file structure.
XML file layout:
<propertyDefinitions>
<object type=(object-type:number | "global")>
<property pid=PID:number pidName=PID-name:string name=friendly-name:string pdt=PDT:number [dpt=DPT-ID:string] rw=("R"|"W"|"R/W"|"R(/W"):string writeEnabled=("0"|"1"|"0/1"):string>
<usage>
usage description and additional information
</usage>
</property>
...next property
</object>
...next object
</propertyDefinitions>

Attribute values of type number might be written in hexadecimal form by prepending "0x". The optional attribute "dpt" is to specify a DPT to use for the property, it will be used in preference before the default DPT assigned to the PDT.
The attribute "pdt" might have a value of "<tbd>", standing for "to be defined", in this case the PDT value used by the property client is -1.

Reduced Property Interfaces:
When working with reduced property interfaces, the user has to be aware of the limitations and act accordingly.

Some KNX devices only support a 5 Bit field for storing the Property Data Type (PDT), i.e. they only use a PDT identifier up to value 0x1F. When accessing property descriptions in the interface object (for example, using getDescription(int, int)), not all existing PDTs can be transmitted. Consequently, for properties that are formatted according any of the higher PDTs, "alternative PDTs" get used. Following implementations are known to support only a 5 Bit PDT in the description:

• mask 0x0020
• mask 0x0021
• mask 0x0701

In general, it is not possible for the property client to deduce the actual type to use for encoding/decoding values from such an "alternative PDT". For these cases, the property client has to rely on property definitions supplied by the user through loadDefinitions(String).

A note on property descriptions:
With a local device management adapter, not all information is supported when reading a description, or is not supported by the protocol at all. In particular, no access levels for read/write (i.e. access is always done with maximum rights) and no property data type (PDT) are available. Also, the maximum number of elements allowed in the property is not available (only the current number of elements).
All methods for property access invoked after a close of the property client will throw a KNXIllegalStateException.

See Also:

PropertyAdapter, PropertyTypes

Nested Class Summary

static interface	PropertyClient.PID Contains constants definitions of the property IDs for global properties (server object type = global) and PIDs of the KNXnet/IP parameter object (server object type 11).
static class	PropertyClient.Property Stores property definition information of one property, used for type translation and property lookup by a property client.
static class	PropertyClient.PropertyKey Key value in the map returned by getDefinitions().
static interface	PropertyClient.ResourceHandler Provides an interface to load property definitions from a resource, and store property definitions into a resource.

Constructor Summary

PropertyClient(PropertyAdapter adapter)
Creates a new property client using the specified adapter for accessing device properties.

Method Summary

void	close() Closes the property client and the used adapter.
static java.util.Map	getDefinitions() Returns the property definitions used by property clients, if definitions were loaded.
Description	getDescription(int objIndex, int pid) Gets the property description based on the property ID.
Description	getDescriptionByIndex(int objIndex, int propIndex) Gets the property description based on the property index.
static java.lang.String	getObjectTypeName(int objType) Returns the object type name associated to the requested object type.
java.lang.String	getProperty(int objIndex, int pid) Gets the first property element using the associated property data type of the requested property.
byte[]	getProperty(int objIndex, int pid, int start, int elements) Gets one or more elements of a property.
DPTXlator	getPropertyTranslated(int objIndex, int pid, int start, int elements) Gets one or more elements of a property with the returned data set in a DPT translator of the associated data type.
boolean	isOpen() Returns whether the adapter used for property access is opened.
static void	loadDefinitions(java.lang.String resource) Loads property definitions from a resource using the global set PropertyClient.ResourceHandler.
static void	saveDefinitions(java.lang.String resource) Saves all loaded property definitions in the property client to a resource using the global set PropertyClient.ResourceHandler.
java.util.List	scanProperties(boolean allProperties) Does a property description scan of the properties in all interface objects.
java.util.List	scanProperties(int objIndex, boolean allProperties) Does a property description scan of the properties of one interface object.
void	setProperty(int objIndex, int pid, int start, int elements, byte[] data) Sets one or more elements of a property.
void	setProperty(int objIndex, int pid, int start, java.lang.String value) Sets one element of a property, with the value given as string representation.
static void	setResourceHandler(PropertyClient.ResourceHandler handler) Sets a new default property resource handler used in the load / save methods by all property clients.

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertyClient

public PropertyClient(PropertyAdapter adapter)
               throws KNXFormatException

Creates a new property client using the specified adapter for accessing device properties.

The property client obtains ownership of the adapter.
The log service used by this property client is named "PC " + adapter.getName().

Parameters:

adapter - property adapter object

Throws:

KNXFormatException - on missing DPT for translating interface object types ( DPTXlator2ByteUnsigned.DPT_PROP_DATATYPE)

Method Detail

close

public void close()

Closes the property client and the used adapter.

getDefinitions

public static java.util.Map getDefinitions()

Returns the property definitions used by property clients, if definitions were loaded.

The returned map is synchronized and a reference to the one used by all property clients. Property definitions might be added or removed as required. Note that modifications will influence lookup behavior of all property client instances.
A map key is of type PropertyClient.PropertyKey, a map value is of type PropertyClient.Property.

Returns:

property map, or null if no definitions loaded

getDescription

public Description getDescription(int objIndex,
                                  int pid)
                           throws KNXException

Gets the property description based on the property ID.

It is not always possible to supply all description information:
If a description read is done using a property identifier (PID) like in this method, the description response is not required to contain the correct property index associated with the PID, even though recommended. The default index is 0 then.

Parameters:

objIndex - interface object index in the device

pid - property identifier, pid > 0

Returns:

the property description

Throws:

KNXException - on adapter errors while querying the description

getDescriptionByIndex

public Description getDescriptionByIndex(int objIndex,
                                         int propIndex)
                                  throws KNXException

Gets the property description based on the property index.

Parameters:

objIndex - interface object index in the device

propIndex - property index in the object

Returns:

a property description object

Throws:

KNXException - on adapter errors while querying the description

getObjectTypeName

public static java.lang.String getObjectTypeName(int objType)

Returns the object type name associated to the requested object type.

Parameters:

objType - object type to get name for

Returns:

object type name as string

getProperty

public java.lang.String getProperty(int objIndex,
                                    int pid)
                             throws KNXException

Gets the first property element using the associated property data type of the requested property.

Parameters:

objIndex - interface object index in the device

pid - property identifier

Returns:

property element value represented as string

Throws:

KNXException - on adapter errors while querying the property element or data type translation problems

getProperty

public byte[] getProperty(int objIndex,
                          int pid,
                          int start,
                          int elements)
                   throws KNXException

Gets one or more elements of a property.

Parameters:

objIndex - interface object index in the device

pid - property identifier

start - index of the first array element to get

elements - number of elements to get in the property

Returns:

byte array holding the retrieved element data

Throws:

KNXException - on adapter errors while querying the property element

getPropertyTranslated

public DPTXlator getPropertyTranslated(int objIndex,
                                       int pid,
                                       int start,
                                       int elements)
                                throws KNXException

Gets one or more elements of a property with the returned data set in a DPT translator of the associated data type.

Parameters:

objIndex - interface object index in the device

pid - property identifier

start - index of the first array element to get

elements - number of elements to get in the property

Returns:

a DPT translator containing the returned the element data

Throws:

KNXException - on adapter errors while querying the property element or data type translation problems

isOpen

public final boolean isOpen()

Returns whether the adapter used for property access is opened.

Returns:

true on open adapter, false on closed adapter

loadDefinitions

public static void loadDefinitions(java.lang.String resource)
                            throws KNXException

Loads property definitions from a resource using the global set PropertyClient.ResourceHandler.

The loaded definitions are used by all property client objects.

Parameters:

resource - the identifier of a resource to load

Throws:

KNXException - on errors in the property resource handler

saveDefinitions

public static void saveDefinitions(java.lang.String resource)
                            throws KNXException

Saves all loaded property definitions in the property client to a resource using the global set PropertyClient.ResourceHandler.

Parameters:

resource - the identifier of a resource for saving

Throws:

KNXException - on errors in the property resource handler

scanProperties

public java.util.List scanProperties(boolean allProperties)
                              throws KNXException

Does a property description scan of the properties in all interface objects.

Parameters:

allProperties - true to scan all property descriptions in the interface objects, false to only scan the object type descriptions, i.e. (PropertyClient.PID.OBJECT_TYPE)

Returns:

a list containing the property descriptions of type Description

Throws:

KNXException - on adapter errors while querying the descriptions

scanProperties

public java.util.List scanProperties(int objIndex,
                                     boolean allProperties)
                              throws KNXException

Does a property description scan of the properties of one interface object.

Parameters:

objIndex - interface object index in the device

allProperties - true to scan all property descriptions in the interface objects, false to only scan the object type descriptions, i.e. (PropertyClient.PID.OBJECT_TYPE)

Returns:

a list containing the property descriptions of type Description

Throws:

KNXException - on adapter errors while querying the descriptions

setProperty

public void setProperty(int objIndex,
                        int pid,
                        int start,
                        int elements,
                        byte[] data)
                 throws KNXException

Sets one or more elements of a property.

Parameters:

objIndex - interface object index in the device

pid - property identifier

start - index of the first array element to set

elements - number of elements to set in the property

data - byte array holding the element data

Throws:

KNXException - on adapter errors while setting the property elements

setProperty

public void setProperty(int objIndex,
                        int pid,
                        int start,
                        java.lang.String value)
                 throws KNXException

Sets one element of a property, with the value given as string representation.

The value is translated according the associated property data type.

Parameters:

objIndex - interface object index in the device

pid - property identifier

start - index of the array element to set

value - string representation of the element value

Throws:

KNXException - on adapter errors while setting the property elements or translation problems

setResourceHandler

public static void setResourceHandler(PropertyClient.ResourceHandler handler)

Sets a new default property resource handler used in the load / save methods by all property clients.

By default, a xml property file handler is used.

Parameters:

handler - the new property storage handler, or null to use the client default handler