Platform State service

The PlatformState service provides a set of predefined states, which can further be extended by custom ones, if needed.

More information about the API is available at: Platform State Utility JSON-RPC API

The PlatformState Service provides the following features:

• Defines a "platform state" – the state that all bundles are currently allowed to be in. It is similar to the state of the system bundle, but extends the active state with some additional values.
• Manages the correct order of state transitions.
• Bundles must be able to request a platform state, when they need to perform operations associated with this state.
• Bundles must be able to receive platform change state events.
  • When a bundle requests a state, it must start listening for a state change. Only when the platform state changes to the requested value, the bundle can perform its the operations.
  • Bundles can use platform state events for other purposes; For example, the Validator bundle can listen for the updating/restoring state to request the validating state.
• States must have timeouts. When a state timeout expires, the platform goes to the next state, even if the bundles that requested the state have not performed all their operations.

The Platform State service should be used only by bundles that are part of the core functionality of the platform – as the state of these bundles defines the state of the platform. Bundles that are part of a user application should only use the services that their functionality depends on.

Registering bundle

This service is registered by System bundle.

Platform states

During the lifecycle of an OSGi framework the installed components (bundles or applications) go through different states. The OSGi specification defines several standard states and the framework implements several other called "user states".

Each state has an associated integer value, in the range of 0 to Integer.MAX_VALUE. These values are used to both identify the state, and to define the priorities of the state and consequently defining the order of state transitions.

There are two types of states:

• OSGi default platform states – starting, active, stopping
• User platform states – initializing, updating, restoring, backup, validating, busy

Figure 1. Framework lifecycle platform states:

OSGi default platform states

These are the OSGi defined states: starting, stopping, active. These states can not be requested by bundles.

• Starting

  The platform starts in starting state. The state ends when all bundles are started.

Refer to the "Framework startup" section in the Starting the framework for details on the process.

• Active

  The platform goes into this state when the starting state has ended, and no other states are requested. The state ends when a bundle requests a state change, or when the framework starts to shut down.

• Stopping

  The stopping state starts when the framework receives a shutdown request and the current state is active. If the current state is not active, the shutdown will wait for the state to change to active.

The values for the states are:

• starting = 0
• active = 100
• stopping = value of the property Integer.MAX_VALUE

User platform states

In order for the platform to enter one of these states, the state must be explicitly requested by a bundle.

The following user states are available:

• Initializing

  Some bundles need additional initialization. It may take more time than a standard bundle start-up should take, and/or depend on other services being present. So the bundle performs it asynchronously, after the FW STARTED event has been sent.

• Updating

  The bundle is being updated by a management agent.

• Restoring

  The BackupAdmin service is performing a restore operation (that involves this bundle). The bundle’s functionality must be shut down, and then reinitialized.

Refer to the Auto Restore section in the BackupAdmin service document for details on auto restore process.

• Backup

  The BackupAdmin service is performing a backup operation that involves this bundle. The bundle’s functionality might be shut down, and then reinitialized.

• Validating

  After starting all bundles, the framework might want to run a validation procedure – checking if all required bundles are started, all required services are registered, etc. This is usually performed after an OSGi image or firmware update, but could also be triggered manually.

• Busy

  Some bundles are performing operations that might affect the performance of the other bundles – operations that, for example, are consuming too much CPU time.

If multiple states are requested concurrently, the framework makes sure that the state sequence is always in the correct order, for example: updating > restoring > initializing > validating. The order is defined by the int value of the state.

For user states with values < active (100), states with lower values have bigger priority; and so the platform state will change from starting (0) up to active (100).

For user states with values > active (100), states with higher values have higher priority; and so the platform state will change from the highest requested user state, down to active.

A user state begins when it was requested by a bundle and:

• The current state is active, or
• The current state has ended, and no higher state was requested

A user state ends when:

• All the bundles that requested it have finished their work, or
• The specified timeout expires

When a user state ends, the platform chooses the next state, based on the following rules:

• If no other user states were requested, the next state is active
• If user states with values < active were requested, the next state is the one with the lowest value.
• If user states with values > active were requested, the next state is the one with the highest value.

The values for the user states are:

• backup = 5
• updating = 10
• restoring = 20
• initializing = 30
• validating = 40
• busy = 120

Security

If security is switched on the framework the PlatformState service will be protected with the standard OSGi ServicePermission. The security policy must be configured in such a way that only the core bundles can access it. There are no further fine grained access definitions.

Implementation

The PlatformState service is registered by the system bundle.

It provides the following methods:

/** Return the current platform state */
public int getPlatformState()

/** Called by a component to request a state change */
public void requestState(int state)

To receive platform state changes, a bundle can implement and register the PlatformStateListener. The interface defines the methods:

/** Notification for a state change */public void stateChanged(int state)

/** Returns the max time that the component needs to work in this state */
public long getTimeout(int state)

Additionally, service events can be used to receive platform state changes: The platform state service is registered with the mbs.platform.state=<current_state> registration property. Platform state changes can be tracked by listening for service events (modified) for this service.

When a platform state changes the following operations are performed:

• The value of the mbs.platform.state property is changed, and a service event is sent for that change.
• If the sending of the service modified event takes more than the core timeout (default is 30 seconds), a timeout warning is logged
• The platform state service impl gets all PlatformStateListener, ordered by their ranking and service id, and notifies them one by one
• If a callback takes more time than the value returned by the corresponding getTimeout method, a timeout warning is logged, and the next listener is notified
• When the event is sent to all PlatformStateListener, the state is over, the platform state moves to the next state (if this was a user or active state, the platform stays in it)