Package org.osgi.service.dal

Interface Function

All Known Subinterfaces:
Alarm, BooleanControl, BooleanSensor, Keypad, Meter, MultiLevelControl, MultiLevelSensor, WakeUp
public interface Function
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.

  • Field Details

    • SERVICE_UID

      static final String SERVICE_UID
      The service property value contains the function unique identifier. It's a mandatory property. The value type is java.lang.String. To simplify the unique identifier generation, the property value must follow the rule:

      function UID ::= device-id ':' function-id

      function UID - function unique identifier

      device-id - the value of the Device.SERVICE_UID Device service property

      function-id - function identifier in the scope of the device

      If the function is not bound to a device, the function unique identifier can be device independent.

      See Also:

    • SERVICE_TYPE

      static final String SERVICE_TYPE
      The service property value contains the function type. It's an optional property. For example, the sensor function can have different types like temperature, pressure, etc. The value type is java.lang.String.

      Organizations that want to use function types that do not clash with OSGi Working Group defined types should prefix their types in own namespace.

      The type doesn't mandate specific function interface. It can be used with different functions.

      See Also:

    • SERVICE_VERSION

      static final String SERVICE_VERSION
      The service property value contains the function version. That version can point to specific implementation version and vary in the different vendor implementations. It's an optional property. The value type is java.lang.String.
      See Also:

    • SERVICE_DEVICE_UID

      static final String SERVICE_DEVICE_UID
      The service property value contains the device unique identifier. The function belongs to this device. It's an optional property. The value type is java.lang.String.
      See Also:

    • SERVICE_REFERENCE_UIDS

      static final String SERVICE_REFERENCE_UIDS
      The service property value contains the reference function unique identifiers. It's an optional property. The value type is java.lang.String[]. It can be used to represent different relationships between the functions.
      See Also:

    • SERVICE_DESCRIPTION

      static final String SERVICE_DESCRIPTION
      The service property value contains the function description. It's an optional property. The value type is java.lang.String.
      See Also:

    • SERVICE_PROPERTY_NAMES

      static final String SERVICE_PROPERTY_NAMES
      The service property value contains the function property names. It's an optional property. The property is missing when there are no function properties and property must be set when there are function properties. The value type is java.lang.String[]. It's not possible to exist two or more function properties with the same name.
      See Also:

    • SERVICE_OPERATION_NAMES

      static final String SERVICE_OPERATION_NAMES
      The service property value contains the function operation names. It's an optional property. The property is missing when there are no function operations and property must be set when there are function operations. The value type is java.lang.String[]. It's not possible to exist two or more function operations with the same name i.e. the operation overloading is not allowed.
      See Also:

  • Method Details

    • getPropertyMetadata

      PropertyMetadata getPropertyMetadata(String propertyName)
      Provides metadata about the function property.

      This method must continue to return the property metadata after the function service has been unregistered.

      Parameters:
      propertyName - The function property name, for which metadata is requested.
      Returns:
      The property metadata for the given property name. null if the property metadata is not available.
      Throws:
      IllegalArgumentException - If the function property with the specified name is not available.

    • getOperationMetadata

      OperationMetadata getOperationMetadata(String operationName)
      Provides metadata about the function operation.

      This method must continue to return the operation metadata after the function service has been unregistered.

      Parameters:
      operationName - The function operation name, for which metadata is requested.
      Returns:
      The operation metadata for the given operation name. null if the operation metadata is not available.
      Throws:
      IllegalArgumentException - If the function operation with the specified name is not available.

    • getServiceProperty

      Object getServiceProperty(String propKey)
      Returns the current value of the specified property. The method will return the same value as ServiceReference.getProperty(String) for the service reference of this function.

      This method must continue to return property values after the device function service has been unregistered.

      Parameters:
      propKey - The property key.
      Returns:
      The property value or null if the property key cannot be mapped to a value.

    • getServicePropertyKeys

      String[] getServicePropertyKeys()
      Returns an array with all function service property keys. The method will return the same value as ServiceReference.getPropertyKeys() for the service reference of this function. The result cannot be null .
      Returns:
      An array with all function service property keys, cannot be null.