JavaScript Library

Overview

The FIM JavaScript library facilitates the development of JavaScript client applications that operate with Functional items. It works only in the web browser, because it uses browser specific APIs.

In order to access the JavaScript Library, use the following URL: http://<host>:<port>/fim/fim.js, where <host>:<port> are the ones used by the targeted Bosch IoT Gateway Software runtime.

This will allow you to retrieve Functional Items, invoke their operations, reading and changing their properties values, and also to receive events on any property change.

The FIM JavaScript Library is also available as a npm package, which can be found in runtime/osgi/lib/web/fim/npm directory.

FIM JavaScript Library Basic Guidelines

Event Mechanism

A loosely coupled subscribe/publish eventing mechanism is based respectively on the Subscribable and Publisher interfaces.

• Subscribable interface – enables event subscriptions.

An event subscription is made by providing a channel and a callback, which will be invoked when an event is received for the given channel. The interface has two methods for creating subscriptions:

• subscribe – returns a disposable subscription.
• subscribeOnce – returns a disposable subscription, that will be disposed automatically after the first event is received.

• Publisher interface – enables message publishing.

A message is published by providing a channel and optionally a message. The interface has two methods:

• publish – publishes a message.
• publishAsync – schedules a message to be published.

See in JavaScript API docs: Subscribable, Publisher, Disposable.

Functional Item Manager

The FunctionalItemManager is responsible for storing and managing a collection of IFunctionalItem instances. It can be created without any arguments, but the activateAsync method must be invoked always before using the manager. It activates the manager by loading the aggregated metadata (on first call only), activates the data service and subscribes for updates. activateAsync can be invoked multiple times.

Example:

var manager = new FunctionalItemManager();
manager.activateAsync().then(() => {
    //Functional item manager is activated
});

Getting Items

The methods, that the manager exposes, allow getting IFunctionalItem or a collection of IFunctionalItem instances by UID or by LDAP filter. The FunctionalItemManager methods allow getting items:

• Asynchronously from the remote API:
  • getFunctionalItemByIdAsync
  • getFunctionalItemsByIdAsync
  • getFunctionalItemsByFilterAsync
• From the cache:
  • getFunctionalItemById
  • getFunctionalItemsById

Note that the methods, which return Functional items from the cache, will not make remote API calls, if the item is missing. In this case, null will be returned. All other get methods, that have the 'Async' suffix, make remote calls and depending on the passed options, the cache is checked before the remote call. The 'async' methods return a promise that fulfils the requested IFunctionalItem.

See in JavaScript API docs: FunctionalItemRequestOptions.

Example:

manager.getFunctionalItemById('fim:group:admin'); //null, because the cache is still empty
manager.getFunctionalItemByIdAsync('fim:group:admin').then((item) => {
   console.log(item); //FunctionalItem {uid: "fim:group:admin", ...}
});

Functional Items Generation

The FunctionalItemManager generates functional item objects, that implement the IFunctionalItem interface. The generated items are cached.

Functional Items Factory

FunctionalItemsFactory allows generation of functional items, registration of constructor functions that return an IFunctionalItem, and registration of initialization functions.

• A constructor function is registered for a given object class - it is used by the create method for generating a functional item with this object class. One constructor per object class can be registered and it can be overridden. A valid functional item constructor is described by the FunctionalItemConstructor interface.
• An initialization function is a function that is called after the creation of every new IFunctionalItem instance. One function per object class can be registered and it can be overridden. For registration purposes it is possible to pass a whole function or just a function name. If a function name is provided, it is considered that the function is on the current functional item instance.

The create method accepts a FunctionalItemDTO and metadata, and returns an IFunctionalItem. It retrieves the object class from the FunctionalItemDTO and finds the appropriate constructor and initialization functions for generating the item. In order to ensure that a constructor/initialization function for the object class is available, it loops through the FunctionalItemDTO's objectClass property and checks for every object class if a registered constructor/initialization function exists. If none is found, it returns the default ones.

See in JavaScript API docs: FunctionalItemsFactory, FunctionalItemConstructor, FunctionalItemDTO.

Events Subscription

The FunctionalItemManager is Subscribable - it allows event subscription for the following events, that the manager processes:

• When an item's property is changed;
• When an item is added to the collection;
• When an item is removed from the collection;
• When an operation is executed;

The subscribe and subscribeOnce methods do not make remote subscriptions - they make local subscriptions for the events that the manager processes. The following aliases are available:

• functional-item-property-changed
• functional-item-registered
• functional-item-unregistered
• functional-item-operation-executed

The event handlers are invoked with event object, which has functions for retrieving different data from the event (the changed property name, the executed operation, getting the items UID, object class, factory UID and others). For different events, there are different get methods, that are applicable - for example if you receive "operation-executed" event and you invoke getPropertyName, it will return undefined.

Example:

//manager is existing FunctinalItemManager instance
var subscription = manager.subscribe(("functional-item-property-changed", (eo) => {
    //process the event object
    eo.getPropertyName(); //the name of the changed property
});

//dispose the subscription
subscription.dispose();

See in JavaScript API docs: FunctionalItemManager, FunctionalItemEventObject, FunctionalItemManagerRemoteEventAlias, FunctionalItemManagerUpdateParameters.

Dispose Method

The FunctionalItemManager has a dispose() method, that releases the resources used by the manager (DataService instance, cache, MetadataManager, pending event subscriptions). You should call this method, when you are done with the manager - once the method is called, the instance becomes unusable.

Example:

var manager = new FunctionalItemManager();
manager.dispose();

JavaScript Functional Items

In the context of the FIM JavaScript Library, a valid functional item is every object that implements the IFunctionalItem interface. The IFunctionalItem has the following properties:

• uid – the functional item's UID;
• name – the functional item's name;
• tags – the functional item's tags;
• mainObjectClass – the functional item's object class;
• otherObjectClasses – other object classes that are implemented by the item;
• properties – all properties specific for the item;
• attributes – the functional item's attributes. By default it is empty, but it can be filled with user defined or FIM specific attributes;
• metadata – the functional item's metadata;
• generationErrors – generation errors, that may occur when an item is generated;

Also, the base FunctionalItem class exposes other properties, events, static properties and helper methods.

See in JavaScript API docs: IFunctionalItem, FunctionalItem.

Get and Set Property

Assume that in the examples the variable FI is a generated IFunctionalItem.

Functional item properties are accessible - a property can be retrieved and depending on its write access, it can be changed.

• The getPropertyAsync method makes a remote call and it returns a Promise, that is resolved with the property value. The method calls setProperty to update the functional item representation and property-changed events may be fired. The method can be used only for properties with read access.
• The setPropertyAsync method makes a remote call, it returns a Promise and the Promise is resolved, when the property is set. The method can be used only for properties with write access. Note that it doesn't set the value on the functional item representation.

Example:

fi.getPropertyAsync('name').then((value) => { //makes remote call
   //can process the value
   console.log(value); //"Group Admin"
});
fi.setPropertyAsync('name', 'myNewName');   //sets the value remotely

Invoking Operations

Functional item operations can be executed with an invokeOperationAsync method. The parameters are the operation name and the operation arguments (if any). The method makes a call to the API and returns a Promise containing the result.

Example:

fi.invokeOperationAsync('remove', ['fim:group:1']).then((result) => {
   //do something after the operation is executed
});

Event Subscription

A Functional item is Subscribable and Publisher. The following channels are available:

• unregistered - will be triggered, when the item is unregistered. This event is fired once per instance at most , no matter if you subscribe through subscribe or subscribeOnce method.
• property-changed - will be triggered, when the item's property is changed. The event handler will receive an event object, that contains the property name, new value and old value.
• operation-executed - will be triggered, when the item's operation is executed. The event handler will receive an event object that contains custom data entries.

Example:

fi.subscribeOnce("property-changed", (eo) => {
  //after event is received, the event subscription is disposed
});

var propertyChangedSubscription = fi.subscribe("property-changed", (eo) => {
  console.log(eo.newValue); //new property value
  console.log(eo.oldValue); //old property value
  console.log(eo.getPropertyName()) //property name
});

propertyChangedSubscription.dispose(); //"property-changed" events will be no more handled

fi.subscribe("operation-executed", (eo) => {
  console.log(eo.getOperationName()); //the name of the executed operation
});

See in JavaScript API docs: Disposable, FunctionalItemEventObject.

Metadata

The metadata is used by the application to obtain information about functional items, properties, operations and value types. The different metadata objects are cached by the MetadataManager and while the FunctionalItemManager receives events for updating its cache, the MetadataManager does not receive remote events. The metadata changes are identified by the version property that exists on the metadata object. If the remote call for getting metadata is forced (the cache will not be checked), the version property is used for comparison between the new metadata and the cached one. If there is a difference, the new metadata is used.

The different types of metadata are:

• TypeMetadata – defines the type of a single value. It has different TypeMetadata types:
  • NUMERIC – it specifies numeric types and the TypeMetadata has three more properties - min, step and max constraints.
  • GENERIC – it specifies generic types. It can be boolean, string and char.
  • ENUM – it specifies enumeration types and the TypeMetadata has an enumeration property, holding the constants for the enumeration.
  • BEAN – it specifies that the value is of type bean and it described by BeanMetadata.
  • ITEM – it specifies that the value holds an item. The value holds the item's UID.
• FieldMetadata – extends TypeMetadata and gives information about a single field of BeanMetadata and FunctionalItemCreationMetadata.
• FunctionalItemMetadata – gives information for generating IFunctionalItem. (Required properties are: name, objectClass and version) Also, it contains metadata describing the item's properties and operations:
  • FunctionalItemPropertyMetadata – gives information about the IFunctionalItem property and its value constraints.
  • FunctionalItemOperationMetadata – gives information about the IFunctionalItem operation - the number of parameters, parameters metadata, the returned value's metadata. It ensures that the operation is invoked correctly.
• FunctionalItemCreationMetadata – gives information for creating IFunctionalItem. Also, it contains FieldMetadata, describing the item's fields.
• BeanMetadata – gives information about Bean type - its class name, version and fields (described by FieldMetadata). The version identifies the metadata changes for the bean's class name.
• BeanCreationMetadata – extends BeanMetadata and it is used for Bean creation.

See in JavaScript API docs: FunctionalItemMetadata, FunctionalItemPropertyMetadata, FunctionalItemOperationMetadata, FieldMetadata, BeanMetadata, BeanCreationMetadata, TypeMetadata.

FIM JavaScript Library Intermediate Guidelines

Data Service

A DataService is responsible for all remote communications.

Status Property

The DataService has a status property, which indicates what components (flags) of the data service are turned on at the moment. The property is a mask that is formed from the following flags:

• 0 (None) – none of the flags are turned on.
• 1 (RemoteServiceAvailable) – indicates that the remote service is currently available.
• 2 (RealTimeUpdates) – indicates that real time updates are currently on.
• 4 (RemoteServiceTracked) – indicates that the availability of the remote service is being tracked.

See the following example.

Activation (activateAsync)

If the status property does not satisfy your needs, before using a DataService instance, its activateAsync method should be called. The method activates the data service with the provided settings, if such are not provided – it is activated with the currently applied. The available settings for activation are:

• checkRemoteService – instructs the service to perform remote service availability check (by default: false).
• realTimeUpdates – instructs the service to open the remote events subscription source (by default: true).
• trackRemoteService – instructs the service to track remote service availability (by default: false; requires realTimeUpdates to be true).

The manager has activeStatus property – it is a mask, which is formed according to the provided activation settings. The status and activeStatus properties can be compared after the activation process and if they are different - the DataService activation fails.

Example:

var ds = new DataService();
   var dataServiceActivationSettings = {
      checkRemoteService: true,
      realTimeUpdates: true,
      trackRemoteServices: true
   };

   ds.activateAsync(dataServiceActivationSettings).then(() => {
       //DataService activation succeeded and ds.status === ds.activeStatus
       console.log(ds.status); //"7"
   }).catch((reason) => {
      //DataService activation failed and ds.status !== ds.activeStatus
      //Let's say, that the check for remote service returns information, that the service is not available. In this case:
      console.log(ds.status); //"1"
      console.log(ds.activeStatus); //"7"
   });

Deactivation (deactivateAsync)

The DataService has a deactivateAsync method that deactivates the service, which is the same as you pass all the settings set to false.

Event Subscription

The DataSerivce is Subscribable and RemoteSubscribable and it exposes the remote event topics for functional item registered/unregistered/property changed/operation executed events.

• subscribe and subscribeOnce – makes subscription for the provided topic. There are two predefined topics:
  • status-changed – an event is received, when the data service's status property is changed.
  • message – a message is received for every remote event that is processed by the DataService.
• subscribeAsync – makes remote event subscriptions. The subscription process is asynchronous and the method parameters are:
  • topic – the topic with/without filter. See RemoteEventSubscriptionParameters for available patterns.
  • callback – will be invoked, when an event is received.
  • interruptionCallback – will be invoked, when the remote subscription gets interrupted by some external error after a successful subscription.

See in JavaScript API docs: IDataService, DataServiceActivationSettings, DataServiceStatus, RemoteSubscribable, RemoteEventSubscriptionParameters.

Functional Item

Get, Set and Create IFunctionalItem Property

The properties of the functional item representation can be accessed without doing remote API calls. These methods work only with the item's representation and their implementation can be overridden by the provided ModelLibrary.

• getProperty – by default, the value is returned from the item's properties field.
• setProperty – by default, it sets the new value and it can fire "property-changed" events. It is mainly used internally for updating a property value on "property-changed" events.
• createProperty – by default, it adds the new property in the properties field. It is used internally for item initialization - it is called once for every property.

Example:

fi.createProperty('myProp', 'foo');
fi.getProperty('myProp');           //"foo"
fi.setProperty('myProp', 'bar');
fi.properties['myProp'];            //"bar"

Helper Functions

The static methods work with the provided FunctionalItem, IFunctionalItem or FunctionalItemDTO object. Most of them make remote calls without doing client side validation, while the instance methods validate the input parameters on the basis of the provided metadata e.g. the metadata is not checked for the property existence. At any time you can:

• set property (FunctionalItem.setPropertyAsync);
• get property (FunctionalItem.getPropertyAsync);
• get main object class; It will get it from the provided IFunctionalItem or FunctionalItemDTO instance. (FunctionalItem.getObjectClass);
• get other object classes; It will get it from the provided IFunctionalItem or FunctionalItemDTO instance. (FunctionalItem.getOtherObjectClasses);
• invoke operation (FunctionalItem.invokeOperationAsync);

Static Properties

The static property FunctionalItem.constants helps in constructing LDAP filters or parsing the raw JSON response. It also has a few more static properties that will not be necessary in common use cases.

Functional Item Manager

You can modify a manager instance after creating it. Here is how:

• You can provide your own DataService and/or MetadataManager instances to be used.

Example:

var ds = new CustomDataService();
var metadataManager = new CustomMetadataManager();

var manager = new FunctionalItemManager({
   dataService: ds,
   metadataManager: metadataManager
});

• The FunctionalItemManager exposes four event handlers:
  • functionalItemRegisteredEventHandler
  • functionalItemUnegisteredEventHandler
  • functionalItemPropertyChangedEventHandler
  • functionalItemOperationExecutedEventHandler

These handlers are called, if a remote subscription is made and the corresponding event is received. You can override these handlers and provide your own implementation at any time.

Example:

var manager = new FunctionalItemManager();
manager.functionalItemPropertyChangedEventHandler = () => {}; //when a "functional-item-property-changed" event is received - nothing will be done.
manager.activateAsync().then(() => {
   //manager is activated
});

• subscribeForUpdatesAsync method creates remote subscriptions and when an event is received, the appropriate handler is called. The method optionally accepts an alias or aliases for FIM remote event topic (See FunctionalItemManagerUpdateParameters for available patterns). If a topic is not provided, the specified topics in realTimeUpdates.updateParameters are used. If the manager has a missing realTimeUpdates.updateParameters setting, is set to [functional-item-property-changed, functional-item-unregistered, functional-item-operation-executed] by default. This method is called internally during the activation process of the manager and it can be used for restoring updates when the subscription gets interrupted. See the next example.

See in JavaScript API docs: FunctionalItemManagerConfiguration, FunctionalItemManagerUpdateParameters.

• handleRemoteEventsSubscriptionInterruption handler. It is invoked when the remote subscription gets interrupted e.g. subscription expiration, web socket closed, long polling failed and other. By default, is does nothing, but it can be used for recovery strategy - there are a lot of scenarios, that can be implemented in this case.

Example:

var interruptionsCount = 0;

manager.handleRemoteEventsSubscriptionInterruption = (reason) => {
   interruptionsCount++;
   if (interruptionsCount === 3) {
      console.log('Subscription process failed multiple times.');
   }
  
   //restore subscriptions. See next paragraph.
   manager.subscribeForUpdatesAsync().then(() => {
      //subscription/s done
   });

};

• You can turn off the real time updates. By default, they are turned on, which means that the manager makes remote subscriptions and sets event handlers for functional-item-property-changed, functional-item-unregistered and functional-item-operation-executed events. When you turn off the auto updates, a remote subscription is not made and events are not received:

Example:

var manager = new FunctionalItemManager({
   realTimeUpdates: {
      off: true
   }
});

manager.activateAsync().then(() => {
   //manager is activated, without remote subscription
});

• You can force the manager to load pregenerated metadata. By default, this option is set to true and the manager's initialization function is to load the metadata.

Example:

var manager = new FunctionalItemManager({loadPregeneratedMetadata: false });

There are a few more options that can be found in the documentation.

See in JavaScript API docs: FunctionalItemManagerConfiguration.

Custom Ajax Adapter

You can provide your own implementation of the Ajax Adapter, which can be used by the DataService or any other FIM 'primitive' to make remote HTTP calls.

Implementation

The custom Ajax Adapter must implement the standard Ajax FIM 'interface':

• name – the adapter ID and the key under which it is registered.
• initialize() – it should be called before the adapter is used. Any initializing logic, that should be run once per instance, should be provided here. Even if the instance is created, but not initialized, it will not be used.
• ajax() – the method that makes HTTP calls, when invoked. It will receive an Ajax configuration object.
• requestInterceptor – you can optionally assign a function to this property that will be called prior to every HTTP request. This assigned function receives the Ajax request information and will modify it, if needed.

Example:

class SimpleAjaxAdapter {

constructor() {

    this.name = 'simple-ajax-adapter'; //id of the adapter

  }

  initialize() {

      //all initializing logic should be here

  }

  ajax(config) {

     //construct and send ajax request

  }

}

Registration

After the implementation, the Ajax Adapter needs to be registered by calling the registerAdapter method on the config object (used for registering, initializing and retrieving adapter implementations). The name of the standard FIM 'interface' ("ajax" in this case) and a constructor function that returns an instance of the specified 'interface' need to be provided to the registerAdapter method. Multiple implementations can be registered under a specific standard FIM 'interface'.

Example:

config.registerAdapter('ajax', SimpleAjaxAdapter);

Initialization

The custom Ajax adapter needs to be initialized before the activation of the FunctionalItemManager or any other FIM 'primitive' that makes HTTP requests. The adapter is initialized after the config.initialezeAdapterInstance method is invoked. The name of the standard FIM 'interface' ("ajax" in this case) and the custom adapter's name/ID need to be provided, as well as a boolean value that indicates whether this is a default (standard FIM 'interface') adapter, or not. This boolean value is true by default and overrides the default instance. TheinitialezeAdapterInstance method returns an initialized instance of the specific adapter, which means that config.getAdapterInstance does not need to be called.

Example:

var ajaxAdapter = config.initializeAdapterInstance('ajax', 'simple-ajax-adapter',  true);

// a "requestInterceptor" can be add  if needed

ajaxAdapter.requestInterceptor = (requestInfo) => {

    // modify/check the request information before the http call

};

See in JavaScript API docs: Ajax, AjaxRequestInfo, AjaxConfig, Config.

Additional Web Frameworks Data Binding Support

The library offers extension points that allow modification of the FunctionalItem so that the Data Binding Model of the framework of use fits better. Two adapters are provided out-of-the-box:

• default – suitable for cases where the Data Binding does not require special structures.
• Knockout – transforms properties into Observables.

Some of the supported frameworks are:

• Angular
• Aurelia
• Knockout
• Vue

Setting up Additional Web Frameworks

By Implementing a Custom ManagedFunctionalItem

The first approach is to implement a custom ManagedFunctionalItem and register it in the FunctionalItemManager. With this procedure the focus should be on the getProperty, setPropety and createProperty. For more information please check the JavaScript API documentation.

One way to implement a custom ManagedFunctionalItem is to extend the FunctionalItem class and override the getProperty, setPropety and createProperty.

By implementing a ModelLibrary

A Model Library Adapter instance needs to be initialized via an identifier for registration - modelLibrary. The ModelLibrary interface is using the singleton pattern and works with the following hooks:

• initializeConstructor – it is called once for every FunctionalItemConstructor. It can modify the getProperty and setProperty before an instance is created.
• initializeInstance – it is called once for every new FunctionalItem instance. Since the instance is already created only post modifications are possible.

Knockout is provided out-of-the-box by the ModelLIbrary adapter and works with the initializeConstructor hook.

Angular users can switch to Observables by using one of the two above-mentioned approaches.

See in JavaScript API docs: FunctionalItemManager, ModelLibrary, ManagedFunctionalItem.

API reference

For more information and detailed API reference please visit the JavaScript API documentation.