Defining Functional Items

Guide on how to define Functional Items.

Functional Items (FI) enable controlling different processes in a unified way. For example turn ON/OFF Devices, Enable/Disable Automation rules, Enable/Disable GUI features (e.g. disable write process during data restore), enable/disable access of Users. In order to do so you need to create base Interface (In the example below the Interface is "BinarySwitch") that has property "STATE" (that can be changed to ON/OFF or Enable/Disable) and a set of operations (e.g. turnOn/turnOff/toggle).

Each Functional Item must extend the "FunctionalItem" Interface (fim.FI) in order to define its supported properties and operations. One Functional Item Interface can extend another Functional Item Interface also, defining additional properties and operations. Each Functional Item implementation provides support of all the properties and operations defined in a Functional Item Interface.

Interfaces may have many different Java implementations that are controlling the different processes. Implementations may have many instances. It is mandatory that each implementation instance is registered as an OSGi service and has Unique ID (UID). For more information check Java API. Each Implementation has to support the properties defined in the Interface.

In the following example we can see the different implementations of the "BinarySwitch" Interface.

fim>$ls -f (objectClass=*BinarySwitch)
#   UID                                     Name                      Functional Item Interfaces
-----------------------------------------------------------------------------------------------------------------------
1   demo:fim:BinarySwitch:1                 BS Room 1                 com.prosyst.mbs.demo.fim.BinarySwitch
2   demo:fim:BinarySwitchExt:1                                        com.prosyst.mbs.demo.fim.BinarySwitchExt
                                                                      com.prosyst.mbs.demo.fim.BinarySwitch

For more information please check the FIM Demo.

Each Interface contains a set of Properties and Operations and has to be annotated as Item (Description and FI Version are recommended, but not required).

Example:

@Item
@Name("Binary Switch")
@Version("2.0.0")
@Description("Binary Switch test")
public interface BinarySwitch extends FunctionalItem {

Supported Types

The data type of a functional item property or operation argument and return type can be one of the following types:

• Primitive types as well as their Java object representation.
• String
• Numeric types (i.e. the types which extend Number and have):
  • 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) is provided by toString() method of the created instance.
• Bean (custom types used to encapsulate many objects in a single type). The bean properties (fields) can be of any of the allowed types, including nesting a bean inside another bean. Note that infinite circular object references are not supported and such bean instances could not be managed.

  In order to ensure the ability to save, store and restore their state, each bean has to provide:

  • Getter methods. For example a method public int getState() should be added for getting the value of a field with name "state" and type int. If the getter has a different name, it should be annotated with Getter . All getter methods should be additionally annotated in order to define additional metadata as field description, value range, etc. (the same way as the functional item properties). Note that the Ignore annotated methods are skipped. If there are no getters, toString() method should be used.
  • One of the following creation options, listed by priority:
    • Factory service for its creation: TypeFactory .
    • Public static method valueOf that takes a single String argument. The bean should provide a toString() method that returns the same value as the valueOf parameter needed for its creation.
    • Public constructor with parameters for all of its fields. Note: If there are fields with same java types, the constructor should be annotated with Constructor to define the order of fields that are initialized with the parameters. Adding an annotation Constructor to a public constructor will give it a higher priority than a static method valueOf.
• Enums - a java Enum or a type annotated with Enum .
• FunctionalItem types (i.e. this class or another Item annotated interface).
• Arrays of a supported type.
• Collections (Collection , Set or List) of one of the supported types.
• Maps (Map) with String keys and values of one of the supported types (all values should be the same type).

How to Define Properties

Each Functional Item Property is characterized by:

• type – The type of this Functional Item property. If not specified, the type of this functional item is derived from the getter method return type if access is readable or from the setter method parameter type if access is writable. If not specified, the access is both readable and writable and the getter method return type does not match the setter method parameter type a compile time error is generated. If not specified and the access is just eventable a compile time error is generated.
• access – Shows the access level of the FI. Its value is composed of appended letter flags, e.g. "RWE" – "R" stands for readable, "W" – for writable and "E" – for eventable.

  "R" – Readable FI property means that it will be present in the Map of FI properties returned by the corresponding getter method.

  "W" – Writable FI property means that the value can be changed with setter.

  "E" – Eventable FI property means that the implementation will throw and event when the property is changed.

  If not specified, the default access level is set to "RE".

The following example shows definition of Property Metadata with the default level of access "RE":

public enum State {

    /*** Defines the switched off state. ***/

    OFF("Switched Off"),

    /*** Defines the switched on state. ***/

    ON("Switched On");

    ...

  }

  /*** Property name used for binary switch state. ***/

  @Property

  @Description("Switch state.")

  public static final String PROPERTY_STATE = "state"; //$NON-NLS-1$

  /*** This method returns the current binary switch state. ***/

  public State getState();

If different level of access is needed then it can be specified additionally:

@Property(access = "RWE")

If FI access is set to Eventable in case of Operation executions it throws information for the event (to be able to view the event information one must be subscribed for events):

fim>$subscribe -t * /*** Subscription to all events. ***/
Subscription ID: 1

fim>$sub
#    Topics              Filter                        Include
-----------------------------------------------------------------------------------------------------------------------
1    REG
     UNREG
     PROP
     OPER

fim>$ex demo:fim:BinarySwitch:1 toggle
Operation executed successfully.
No result returned.
fim>$FI EVENT HANDLER: 1
-----------------------------------------------------------------------------------------------------------------------
FI EVENT                                  PROPERTY_CHANGED
event.topics      

                    com/prosyst/mbs/services/fim/FunctionalItemEvent/PROPERTY_CHANGED
objectClass      

             [com.prosyst.mbs.demo.fim.BinarySwitch,com.prosyst.mbs.services.fim.FunctionalItem]
property.name                             state
property.value.new                        Switched On
property.value.old                        Switched Off
timestamp                                 1426926411766
uid                                       demo:fim:BinarySwitch:1

How to Define Operations

Functional Item Operations define the available operations that may be executed over a Functional Item.

For example "turnOn", "turnOff", "toggle":

  /*** This method turns on the binary switch. ***/
  @Operation
  @Description("Turns on the binary switch.")
  public void turnOn();

  /*** This method turns off the binary switch. ***/
  @Operation
  @Description("Turns off the binary switch.")
  public void turnOff();

  /*** Toggles the current state of the binary switch.  ***/
  @Operation
  @Description("Toggles the current state.")
  public void toggle();

Abstract Functional Item

For more convenient implementation of Functional Items there is Abstract Functional Item which is part of com.prosyst.mbs.services.fim.spi. Abstract Functional Item has part of the base methods already implemented. It creates an abstract implementation of FunctionalItem interface which provides utilities for service registration, retrieving the properties and operations meta information and sending property changed events. The class is not thread safety.

Abstract Functional Items requires:

• Framework Database to store data.
• Event Admin to throw events on property change.