Finsemble: Finsemble Lifecycle Events

Finsemble Lifecycle Events

The finsemble library has several events that your components and clients can listen for. As we add events to the library, we will update this list.

onReady

The FSBL onReady event is fired when all registered clients have completed their initialization. Any code depending on the entire library being initialized (e.g., rendering a react component), should be executed inside of the onReady callback. At this point, openfin and Finsemble are both ready to be used.

FSBL.addEventListener('onReady', function(){
    //do things
});

As of version 1.2, clients also have an onReady event. You can attach callbacks to this event in the same way that you attach a callback to the FSBL library.

FSBL.Clients.WindowClient.addEventListener('onReady', function(){
    //do things with the window client.
});

FSBL.Clients.WindowClient.onReady(function(){
    //do things. Equivalent to the code above.
})

onShutdown

The onShutdown event was introduced in version 1.2. This is an optional method that your services, and components can tap in to. It allows you to do any cleanup actions on application shutdown. To handle any egregiously-long cleanup tasks, you can set a timeout in your config. The default is 10 seconds. To change this, simply make sure the "shutdownTimeout" property in configs/application/config.json to a number, in milliseconds.

Next, we'll show you a couple of examples that tap in to onShutdown, then we'll go over how it works behind the scenes.

Examples

In a component


//LauncherService will send out a request to every component asking them to complete any shutdown actions. This callback is invoked if the component is open when the application quits.
FSBL.addEventListener('onShutdown', function() {
    return new Promise(function(resolve, reject){
        cleanUpMyMess()
            .then(resolve)
            .catch(reject);
    });
});

In a service

//Asynchronous callback onShutdown
myService.onShutdown(function(){
    return new Promise(function(resolve, reject){
        saveToDatabase()
            .then(resolve)
            .catch(reject);
    });
});

//Synchronous callback
myService.onShutdown(function cleanup1 (){
    //callback will work asynchronously even if you pass in a non-promise.
    closeWindows();
    deleteLocalStorage();
    return;
});

myService.onShutdown(function cleanup2 (){
    //`onShutdown` can handle more than one callback. They can be a mix of promises an non-promises
    return new Promise(function(resolve, reject){
        doAsync()
            .then(resolve)
            .catch(reject);
    });
});

The mechanics of onShutdown

When FSBL.shutdownApplication() is invoked, it sends a message to the core application, our serviceManager. onShutdown is completed in three stages.

  1. Our serviceManager fires a message to every service that's online. This is called the shutdownRequest.
  2. When the service receives the request, it returns a shutdownResponse. This response tells the service manager whether it should wait for cleanup methods to complete before killing the application. This is all handled under the hood. If a service registers any onShutdown event handlers, a response is sent to the serviceManager telling it to wait.
  3. If the service has any cleanup methods, it sends off shutdownComplete when they've finished. If there are no registered onShutdown event handlers, this message is sent immediately after the shutdownResponse.

Example Flow - LauncherService

  1. App requests shutdown
  2. serviceManager requests that all services cleanup. All services begin cleaning up.
  3. LauncherService receives message, tells the service Manager to wait until all of the components it launched have had time to shut down. It then sends a message to every component, notifying them to complete any onShutdown event handlers.
  4. All components have responded, so LauncherService fires off onShutdownComplete.
  5. When all services have completed shutdown, the app quits.