Functional Item Events

Description of the Functional Item Events subscription mechanism.

Overview

Functional Items Management uses the OSGi Event Admin service to publish events asynchronously on:

• registration and unregistration of Functional Items
• changing property value of eventable property
• operations execution

Each event contains the properties describing the event and all the Functional Item attributes also.

The FunctionalItemEventConstants interface defines a set of constants related to FunctionalItem events.

Event Topic Constants

• Constant defining the package of the event, used in the event topic. See FIM_PACKAGE.

  static final String FIM_PACKAGE = "com/prosyst/mbs/services/fim/FunctionalItemEvent/";

• Constant that could be used for subscription for all the Functional Items Management event topics. See TOPIC_ALL.

  static final String TOPIC_ALL = FIM_PACKAGE + '*';

• Constant for event topic that denotes that new functional item is registered (added) in the system. See TOPIC_REGISTERED.

  static final String TOPIC_REGISTERED = FIM_PACKAGE + "REGISTERED";

• Constant for event topic that denotes that a functional item is unregistered (removed) from the system. See TOPIC_UNREGISTERED.

  static final String TOPIC_UNREGISTERED = FIM_PACKAGE + "UNREGISTERED";

• Constant for event topic that denotes that a functional item property is changed. See TOPIC_PROPERTY_CHANGED.

  static final String TOPIC_PROPERTY_CHANGED = FIM_PACKAGE + "PROPERTY_CHANGED";

• Constant defining an event topic. Denotes that a functional item operation has been executed. See TOPIC_OPERATION_EXECUTED.

  static final String TOPIC_OPERATION_EXECUTED = FIM_PACKAGE + "OPERATION_EXECUTED";

Additional Property Constants

• Constant defining the event property for a functional item property name. This property is defined only when the topic of the event is TOPIC_PROPERTY_CHANGED and holds the name of the functional item property which has changed its value. The value of this property is type String. For more information see FunctionalItemEventConstants.

  static final String PROPERTY_NAME = "property.name";

• Constant defining the event property for functional item property value. This property is defined only when the topic of the event is TOPIC_PROPERTY_CHANGED and holds the value of the changed functional item property. The type of value is the same as the type of the FI property (defined by the FI interface).

  static final String PROPERTY_NEW_VALUE = "property.value.new";

• Constant defining the event property for the previous functional item property value. This property is defined only when the topic of the event is TOPIC_PROPERTY_CHANGED and holds the old value of the changed functional item property. The type of value is the same as the type of the FI property (defined by the FI interface).

  static final String PROPERTY_OLD_VALUE = "property.value.old";

• Constant defining the event property for a functional item operation name. This property is defined only when the topic of the event is TOPIC_OPERATION_EXECUTED and holds the name of the operation which has been executed. Each FunctionalItem interface defines the operation events that are published during its life-cycle.

  static final String OPERATION_NAME = "operation.name";

Other Constants Related to FunctionalItem Events

• FunctionalItem.UID: uid – Constant for Functional Item UID attributes name. It is unique for the whole system and used as mandatory attributes of FunctionalItem services. The value of this property is type String.
• FunctionalItem.NAME: name – Constant for Functional Item name attributes name. It is used as attributes of FunctionalItem services and to fire event with topic FunctionalItemEventConstants.TOPIC_PROPERTY_CHANGED on functional item name change. The value of this property is type String.
• FunctionalItem.TAGS: tags – Constant for Functional Item tags attributes name. It is used as attributes of FunctionalItem services and to fire event with topic FunctionalItemEventConstants.TOPIC_PROPERTY_CHANGED on functional item tags change. The value of this property is type Set<String>.
• FunctionalItem.OBJECT_CLASS Constant for identifying all of the Functional Item interface names under which a Functional Item instance is registered in the Framework: the class name of the main functional item interface, all inherited interfaces and the com.prosyst.mbs.services.fim.FunctionalItem as last element. The value of this property is type List<String>.
• Additional FunctionalItem attributes, defined by FunctionalItem.getAttributes().

FunctionalItemEvent Utility

The FunctionalItemEvent is a utility, part of the com.prosyst.mbs.services.fim.util package, that wraps a Functional Item Management event under the com/prosyst/mbs/services/fim/FunctionalItemEvent/ event topic. The constructor creates a FunctionalItemEvent for an event which topic is part of FunctionalItemEventConstants.FIM_PACKAGE, and the utility can be used for simple access to the added event properties.

Bellow you can find an example how to get the UID, old and new value of the property when using the FunctionalItemEvent.

    ...
    FunctionalItemEvent stateEvent = new FunctionalItemEvent(event);
    final String uid = stateEvent.getUID();
    final State oldState = stateEvent.getPropertyChangedOldValue();
    final State newState = stateEvent.getPropertyChangedNewValue();

    System.out.println("Binary switch '" + uid + "' state was changed from '"
      + oldState + "' to '" + newState + '\'');
  }

Examples

If Functional Item 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):

• If you want to subscribe for events you can subscribe for events on a particular topic (i.e. "REGISTERED", "UNREGISTERED", "PROPERTY_CHANGED", "OPERATION_EXECUTED") or you can subscribe for all Functional Item Events (*). For example sub -t REG or sub -t * (alternatively you can use the full command subscribe).
• You can check all current subscriptions by simply typing sub or subscribe.

  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

The OSGi EventAdmin service is used to send events when a new group is added, removed, group items are changed, etc. For example, to receive events when functional item is added as subgroup of a group, the application must register EventHandler with topic FunctionalItemEventConstants.TOPIC_PROPERTY_CHANGED and event property Constants.OBJECTCLASS that has value com.prosyst.mbs.services.fim.groups.Group. If a group is successfully created/removed an operation executed event is fired with topic FunctionalItemEventConstants.TOPIC_OPERATION_EXECUTED.

It contains the properties:

• FunctionalItemEventConstants.OPERATION_NAME with FunctionalItemFactory.OPERATION_CREATE / FunctionalItemFactory.OPERATION_REMOVE value
• Group.ITEM with the UID of the added/removed group
• all additional properties specified for the events with FunctionalItemEventConstants.TOPIC_OPERATION_EXECUTED topic

In order to receive the event the subscriber should have FunctionalItemPermission.ACCESS_TYPE_VALUE_READ for Group.ITEMS property. Additionally, Group.ADD_ITEM / Group.REMOVE_ITEM operation executed events are fired for each group that the created/removed group is added to/removed from.

fim>$FI EVENT HANDLER: 1
-----------------------------------------------------------------------------------------------------------------------
FI EVENT                    REGISTERED
event.topics                com/prosyst/mbs/services/fim/FunctionalItemEvent/REGISTERED
factory.uid                 fim:group:admin
objectClass                 {com.prosyst.mbs.services.fim.groups.Group,com.prosyst.mbs.services.fim.FunctionalItem}
timestamp                   1428044123721
uid                         fim:group:24
FI EVENT HANDLER: 1
-----------------------------------------------------------------------------------------------------------------------
FI EVENT                    OPERATION_EXECUTED
event.topics                com/prosyst/mbs/services/fim/FunctionalItemEvent/OPERATION_EXECUTED
item                        fim:group:24
name                        Group Admin
objectClass                 {com.prosyst.mbs.services.fim.groups.GroupAdmin,com.prosyst.mbs.services.fim.FunctionalItemFactory,com.prosyst.mbs.services.fim.FunctionalItem}
operation.name              create
supportedClasses            {com.prosyst.mbs.services.fim.groups.Group}
timestamp                   1428044123721
uid                         fim:group:admin