IInteractiveComponent

​

Interface IInteractiveComponent

interface IInteractiveComponent

Extends com.amazon.apmf.IStandard An interactive lifecycle component is one which interacts with the user by displaying content on the screen.

​

Methods

​

onStart()

void onStart(com.amazon.kepler.runtime.IComponentInstance* instance, com.amazon.kepler.messaging.IMessage* message)

This callback is invoked when an interactive component is first launched. When this method is invoked, components must do all required initializations and preparations required for it to be later brought to the foreground. This includes using IRestorationManager to restore the component state, if applicable. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

message

com.amazon.kepler.messaging.IMessage* — Required The message which resulted in this instance of the component being launched.

---

​

onForeground()

void onForeground(com.amazon.kepler.runtime.IComponentInstance* instance)

This callback notifies the component that it is being moved to the foreground and it can now perform actions required to display content on the screen. After this callback, the component instance is interactable until the component is moved to the background. Failure to do so results in the component process being forcefully terminated for breach of its lifecycle contract. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

---

​

onBackground()

void onBackground(com.amazon.kepler.runtime.IComponentInstance* instance)

This callback is invoked when a component is being moved out of the foreground. The component instance is no longer visible or interactable after this callback. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

---

​

onStop()

void onStop(com.amazon.kepler.runtime.IComponentInstance* instance)

This callback is invoked when a component instance is going to be stopped; its process may be terminated at any point after this callback is invoked. Note that under most circumstances the component receives this callback before termination, but under some circumstances the process may be forcefully killed before this callback can be invoked. For instance, a component may be forcefully killed if the device is under critical memory pressure and needs to quickly reclaim resources or if the component fails to respond to callbacks in a timely manner. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

---

​

onNewLaunch()

void onNewLaunch(com.amazon.kepler.runtime.IComponentInstance* instance, com.amazon.kepler.messaging.IMessage* message)

When a user requests to launch an interactive singleton component and there is already an instance of the component running, that existing instance receives an onNewLaunch callback. If the component is in the background, it receives an onForeground callback after the onNewLaunch callback. If it is already in the foreground, it does not get another onForeground callback after the onNewLaunch callback. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

message

com.amazon.kepler.messaging.IMessage* — Required The message which resulted in this instance of the component being re-launched.

---

​

onSaveState()

void onSaveState(com.amazon.kepler.runtime.IComponentInstance* instance)

This callback is invoked after an interactive component goes to background. The component is encouraged to perform progressive state saving starting as early as the onStart callback. When this callback is invoked the component has one final chance to save relevant state through the IRestorationManager. Upon returning from this callback, IRestorationManager backs up the state to prevent data loss from process death. Its recommended to store any UI related data as part of this workflow. The callback occurs on the application’s main thread, so if other threads are responsible for collecting state, ensure that that work is completed before returning from this callback. Note that this callback is not invoked in application crash scenarios. Restoration is not possible until onSaveState is able to execute successfully. If the component is unable to complete its callback successfully, it may throw an exception. Exceptions lead to application termination.

​

Parameters

instance

com.amazon.kepler.runtime.IComponentInstance* — Required An object representing this instance of the component.

---