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 Finsemble 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 into. 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 ten seconds. To change this, simply set 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 service manager. onShutdown is completed in three stages.

  1. Our Service Manager fires a message to every service that is 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 clean-up 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 service manager telling it to wait.
  3. If the service has any clean-up 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. Service Manager requests that all services clean up. All services begin cleaning up.
  3. Launcher Service 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 Launcher Service fires off onShutdownComplete.
  5. When all services have completed shutdown, the app quits.

Further reading

Learn more about how Finsemble sends and receives events by reading about the Router.

Check out the Build Process for details about middleware that interfaces with clients and components.