Function service provides specific device operations and properties. Each function service must implement this interface. In additional to this interface, the implementation can provide own:

• properties;
• operations.

The function service is registered in the service registry with these service properties:

• SERVICE_UID - mandatory service property. The property value contains the function unique identifier.
• SERVICE_DEVICE_UID - optional service property. The property value is the Functional Device identifiers. The function belongs to those devices.
• SERVICE_REFERENCE_UIDS - optional service property. The property value contains the reference function unique identifiers.
• SERVICE_TYPE - mandatory service property. The property value is the function type.
• SERVICE_VERSION - optional service property. The property value contains the function version.
• SERVICE_DESCRIPTION - optional service property. The property value is the function description.
• SERVICE_OPERATION_NAMES - optional service property. The property is missing when there are no function operations and property must be set when there are function operations. The property value is the function operation names.
• SERVICE_PROPERTY_NAMES - optional service property. The property is missing when there are no function properties and property must be set when there are function properties. The property value is the function property names.

On start up, the Function services are registered before the Device services. It's possible that SERVICE_DEVICE_UID point to missing services at the moment of the registration. The reverse order is used when the services are unregistered. Function services are unregistered last after Device services.

The Function service should be registered only under the function class hierarchy. Other classes can be used if there are no ambiguous representations. For example, an ambiguous representation can be a function registered under two independent function classes like BinarySwitch and Meter. In this example, both functions support the same property state with different meaning. getPropertyMetadata(String propertyName) method cannot determinate which property is requested. It can be BinarySwitch state or Meter state.

To simplify the generic function discovery, the Function interface must be used for the service registration. In this way, the generic applications can easily find all services, which are functions in the service registry. Because of this rule, this registration is not allowed:

context.registerService(MeterV1.class.getName(), this, regProps);

If the implementation would like to mark that there is a function, but no specific function interface exists, the registration can be:

context.registerService(Function.class.getName(), this, regProps);

Note that such functions usually don't have operations and properties.

The function properties must be integrated according to these rules:

• Getter methods must be available for all properties with PropertyMetadata#ACCESS_READABLE access.
• Getter method must return a subclass of FunctionData.
• Setter methods must be available for all properties with PropertyMetadata#ACCESS_WRITABLE access.
• Setter methods can be any combination of:
  • Setter method which accepts a subclass of FunctionData.
  • Setter method which accepts the values used by the FunctionData subclass, if there are no equal types.
  It's possible to have only one or both of them. Examples:
  • There is MyFunctionData bean with BigDecimal value for a data property. Valid setters are setData(MyFunctionData data) and setData(BigDecimal data).
  • There is MySecondFunctionData bean with BigDecimal prefix and BigDecimal suffix for a data property. The prefix and suffix are using equal types and we cannot have a setter with the values used by MySecondFunctionData. The only one possible setter is setData(MySecondFunctionData data).
• No methods are required for properties with PropertyMetadata#ACCESS_EVENTABLE access.

The accessor method names must be defined according JavaBeans specification.

The function operations are java methods, which cannot override the property accessor methods. They can have zero or more parameters and zero or one return value.

Operation arguments and function properties are restricted by the same set of rules. The data type can be one of the following types:

• Java primitive type or corresponding reference type.
• java.lang.String.
• Numerical type i.e. the type which extends java.lang.Number. The numerical type must follow these conventions:
  • The type must provide a public static method called valueOf that returns an instance of the given type and takes a single String argument or a public constructor which takes a single String argument.
  • The String argument from the previous bullet can be provided by toString() method of the instance.
• Beans, but the beans properties must use those rules. Java Beans are defined in JavaBeans specification.
• java.util.Maps. The keys can be java.lang.String. The values of a single type follow these rules.
• Arrays of defined types.

The properties metadata is accessible with getPropertyMetadata(String). The operations metadata is accessible with getOperationMetadata(String).

In order to provide common behavior, all functions must follow a set of common rules related to the implementation of their setters, getters, operations and events:

• The setter method must be executed synchronously. If the underlying protocol can return response to the setter call, it must be awaited. It simplifies the property value modifications and doesn't require asynchronous callback.
• The operation method must be executed synchronously. If the underlying protocol can return an operation confirmation or response, they must be awaited. It simplifies the operation execution and doesn't require asynchronous callback.
• The getter must return the last know cached property value. The device implementation is responsible to keep that value up to date. It'll speed up the applications when the function property values are collected. The same cached value can be shared between a few requests instead of a few calls to the real device.
• The function operations, getters and setters must not override java.lang.Object and this interface methods.