FIM Access

Overview

The FIM Access (see FIMAccess in the API) is a helper object available to all scripts executed through OSGiScriptEngine created by OSGiScriptEngineManager. It is available to scripts through Core.getFim() field and can be accessed in most script languages simply as "mbs.fim".

The FIM Access aims to simplify the work with Functional Items in scripts. It has methods for accessing Functional Items and a method for registering AbstractFunctionalItem in OSGi Registry.

Accessing Functional Items

Items Map

The FIMAccess.getItems() method returns a map which maps Functional Items to their UIDs. In most script languages the items map can be accessed simply as "mbs.fim.items", as shown in the following script:

var item = mbs.fim.items ["demo.js.fi"]

print(item.UID +  " state is " + item.state)

List Items

The FIMAccess.listItems(String ldapFilter) method takes as an argument an LDAP filter and returns the Functional Items instances which registration properties match the given filter:

mbs.fim.listItems("(objectClass=*BinarySwitch)").forEach(function(item) {  
  item.toggle()

  print(" - " + item.UID +  " -> " + item.state)  
})

The above example assumes that Nashorn JavaScript Engine (which comes with Java 1.8+) is used. More specifically, the example makes use of Nashorn's forEach method.

Utility Methods

The functional item properties and operations can be accessed directly through the item object (e.g. print(item.state), item.toggle()). However it is useful to access them by name too, for example:

• if the property/operation name is passed as parameter to the script;
• if the meta-data name of property is different than the corresponding Java object field.

Therefore the FIMAccess provides the following methods:

Get Property

The FIMAccess.get(FunctionalItem item, String property) and the FIMAccess.get(String itemUID, String property) methods return property value by its name. Internally these methods call FunctionalItemInvoker.getProperty(FunctionalItem item, String property). Here is an example of property getter methods:

var temperature = mbs.fim.get('termometer.uid', 'temperature')

var binarySwitch = mbs.fim.items ['binary.switch.uid']

var state = mbs.fim.get(binarySwitch, 'state')

Set Property

Similarly to the get property methods, the FIMAccess.set(FunctionalItem item, String property, Object value) and the FIMAccess.set(String itemUID, String property, Object value) can be used to set property value referencing it by name. Internally they call FunctionalItemInvoker.setProperty(FunctionalItem item, String property, Object value). An example of property setter methods is presented below:

mbs.fim.set('dimmer.uid', 'level', 0)

var dimmer = mbs.fim.items ['dimmer.uid']

mbs.fim.set(dimmer, 'level', 50)

Invoke Operation

The FIMAccess.invoke(FunctionalItem item, String operation, Object... parameters) and the FIMAccess.invoke(String itemUID, String operation, Object... parameters) can be used to invoke operations by name. These methods delegate the actual invocation to FunctionalItemInvoker.invokeOperation(FunctionalItem item, String operation, Object... parameters). Below is an example of how to invoke an operation by name:

mbs.fim.invoke('binary.switch.uid', 'toggle')

var binarySwitch = mbs.fim.items ['binary.switch.uid']

mbs.fim.invoke(binarySwitch, 'toggle')

Methods taking functional item UID as an argument will throw IllegalArgumentException if item with the given UID is not available or not visible to the caller, due to lack of appropriate permissions.

Functional Item Helper and Invoker

The FunctionalItemInvoker contains also some other useful methods for working with functional item properties and methods. It is provided to script through FIMAccess.getInvoker() and in scripts can be accessed simply as mbs.fim.invoker.

Similarly, the FunctionalItemHelper is available through the FIMAccess.getHelper() and in scripts can be accessed as mbs.fim.helper. It contains many useful methods for working with functional items meta-data.

To use the utility methods/fields the caller must have org.osgi.framework.ServicePermission("com.prosyst.mbs.services.fim.util.FunctionalItemHelper", "get")permission.

Registering Functional Item

The FIMAccess.register(AbstractFunctionalItem item) method takes as an argument the AbstractFunctionalItem instance and simply calls AbstractFunctionalItem.register(BundleContext, FunctionalItemAdminSpi) with the context of the bundle on behalf of which the script is executed, and the FunctionalItemAdminSpi instance from the service registry. The following script provides an example of registering a functional item:

var AbstractFunctionalItem = Java.type('com.prosyst.mbs.services.fim.spi.AbstractFunctionalItem');
var BinarySwitch = Java.type('com.prosyst.mbs.scripting.demo.fim.access.BinarySwitch')
var FIExtender = Java.extend(AbstractFunctionalItem, BinarySwitch);

var item=  new FIExtender('demo.js.fi'){

  state : BinarySwitch.State.ON,

  getState : function() {
     return this.state;
  },
  
  setState : function(newState) {
     var oldState =  this.state;
     this.state = newState;
    obj_super.propertyChanged("state", newState, oldState, false);
  },

  toggle : function() {
     if (this.state == BinarySwitch.State.ON) {
       this.turnOff();
    }  else {
       this.turnOn();
    }      
  },

  turnOff : function() {
     this.setState(BinarySwitch.State.OFF);
  },

  turnOn : function() {
    this.setState(BinarySwitch.State.ON);
  }
    
}

obj_super = Java.super(item)
  
mbs.fim.register(item)

The above example assumes that Nashorn JavaScript Engine (which comes with Java 1.8+) is used. More specifically, the example makes use of Nashorn's Java object and its type, extend and super methods.

The usage of the FIM Access helper object is demonstrated in Scripting Functional Item Management Demo and in the demo scripts located in the /scripts Bosch IoT Gateway Software Runtime folder.