ActivityLifecycleMonitor

interface ActivityLifecycleMonitor


Interface for tests to use when they need to query the activity lifecycle state.

Activity lifecycle changes occur only on the UI thread - therefore listeners registered with an ActivityLifecycleMonitor should expect to be invoked on the UI thread. The direct query methods can only be called on the UI thread because otherwise they would not be able to return consistent responses.

Retrieve instances of the monitor through ActivityLifecycleMonitorRegistry.

Detecting these lifecycle states requires support from Instrumentation, therefore do not expect an instance to be present under any arbitrary instrumentation.

Summary

Public methods

abstract @NonNull void

Adds a new callback that will be notified when lifecycle changes occur.

abstract @NonNull Collection<@NonNull Activity>

Returns all activities in a given stage of their lifecycle.

abstract @NonNull Stage
getLifecycleStageOf(@NonNull Activity activity)

Returns the current lifecycle stage of a given activity.

abstract @NonNull void

Removes a previously registered lifecycle callback.

Public methods

addLifecycleCallback

@NonNull
public abstract void addLifecycleCallback(@NonNull ActivityLifecycleCallback callback)

Adds a new callback that will be notified when lifecycle changes occur.

Implementors will not hold a strong ref to the callback, the code which registers callbacks is responsible for this. Code which registers callbacks should responsibly remove their callback when it is no longer needed.

Callbacks are executed on the main thread of the application, and should take care not to block or otherwise perform expensive operations as it will directly impact the application.

Parameters
@NonNull ActivityLifecycleCallback callback

an ActivityLifecycleCallback

getActivitiesInStage

@NonNull
public abstract Collection<@NonNull Activity> getActivitiesInStage(@NonNull Stage stage)

Returns all activities in a given stage of their lifecycle.

This method can only return a consistant and correct answer from the main thread, therefore callers should always invoke it from the main thread and implementors are free to throw an exception if the call is not made on the main thread.

Implementors should ensure this method returns a consistant response if called from a lifecycle callback also registered with this monitor (eg: it would be horriblely wrong if a callback sees PAUSED and calls this method with the PAUSED and does not see its activity in the response.

Callers should be aware that the monitor implementation may not hold strong references to the Activities in the application. Therefore stages which are considered end stages or eligible for garbage collection on low memory situations may not return an instance of a particular activity if it has been garbage collected.

Parameters
@NonNull Stage stage

the stage to query for.

Returns
Collection<@NonNull Activity>

a snapshot Collection of activities in the given stage. This collection may be empty.

Throws
java.lang.IllegalStateException

if called from outside the main thread.

getLifecycleStageOf

@NonNull
public abstract Stage getLifecycleStageOf(@NonNull Activity activity)

Returns the current lifecycle stage of a given activity.

This method can only return a consistent and correct answer from the main thread, therefore callers should always invoke it from the main thread and implementors are free to throw an exception if the call is not made on the main thread.

Implementors should ensure this method returns a consistent response if called from a lifecycle callback also registered with this monitor (eg: it would be horriblely wrong if a callback sees PAUSED and calls this method with the same activity and gets RESUMED.

Parameters
@NonNull Activity activity

an activity in this application.

Returns
Stage

the lifecycle stage this activity is in.

Throws
java.lang.IllegalArgumentException

if activity is unknown to the monitor.

java.lang.NullPointerException

if activity is null.

java.lang.IllegalStateException

if called off the main thread.

removeLifecycleCallback

@NonNull
public abstract void removeLifecycleCallback(@NonNull ActivityLifecycleCallback callback)

Removes a previously registered lifecycle callback.