UpdateManager

public class UpdateManager
extends Object

java.lang.Object
   ↳ com.google.android.things.update.UpdateManager


The UpdateManager allows an application or service to control how updates are automatically applied to the device. Updating a device involves performing the following operations:

  1. Checking for an available software update
  2. Downloading and applying an update
  3. Rebooting the device into the new software version

The UpdateManager defines a set of Policies that are used to determine which of these steps are taken automatically, and which need to be initiated by the device's application software.

When creating a policy using the UpdatePolicy.Builder, a deadline value also needs to be specified using setApplyDeadline(long, TimeUnit). When using a policy other than POLICY_APPLY_AND_REBOOT, this deadline governs how long the UpdateManager will wait for before it will automatically apply the update (if not already applied) and then reboot into the updated software. Depending on the needs of the application, examples values are: 1 day, 1 week, 30 days.

This provides a safety net so that developers can be certain that updates will eventually be applied, even if the device is using a policy that restricts automatically applying an update, rebooting the device, or both.

The current policy that's in use is returned as part of the UpdateManagerStatus that is returned by getStatus()

The UpdateManager supports a series of different usage scenarios. To automatically apply updates and reboot as they come available, use POLICY_APPLY_AND_REBOOT:

     UpdateManager.getInstance().setPolicy(
         new UpdatePolicy.Builder()
             .setPolicy(POLICY_APPLY_AND_REBOOT)
             .setUpdateDeadline(1, TimeUnit.DAYS)
             .build());

 

For a device that should not reboot at an arbitrary time use POLICY_APPLY_ONLY and then schedule the reboot at a time that is more convenient for the device:

     UpdateManager mUpdateManager = UpdateManager.getInstance();

     mUpdateManager.setPolicy(
         new UpdatePolicy.Builder()
             .setPolicy(POLICY_APPLY_ONLY)
             .setUpdateDeadline(2, TimeUnit.DAYS)
             .build());

     mUpdateManager.addStatusListener( updateManagerStatus -> {
         if (updateManagerStatus.currentState == UpdateManagerStatus.STATE_UPDATED_NEEDS_REBOOT) {
             scheduleRebootAtMidnight();
         }
     });

 

For devices that may only be updated by the direct action of a person or remote management system, an UpdatePolicy can be constructed with POLICY_CHECKS_ONLY and a very long deadline (years). When doing so, the application MUST use performUpdateNow(int) with POLICY_APPLY_ONLY or POLICY_APPLY_AND_REBOOT to trigger an update to be acted on.

Summary

Public methods

void addStatusListener(StatusListener listener)

Register a StatusListener with the UpdateManager.

String getChannel()

Return the update channel that the device is using for update checks.

static UpdateManager getInstance()

Returns the UpdateManager instance for this application.

UpdateManagerStatus getStatus()

Return the latest UpdateManagerStatus.

boolean performUpdateNow(int policy)

Immediately check for an available software update, and act on that update per the given policy.

void removeStatusListener(StatusListener listener)

Unregister a StatusListener from the UpdateManager.

void setChannel(String channel)

Set the update channel that the device should be on.

void setPolicy(UpdatePolicy policy)

Set the UpdatePolicy that the UpdateManager is to use.

Inherited methods

From class java.lang.Object

Public methods

addStatusListener

void addStatusListener (StatusListener listener)

Register a StatusListener with the UpdateManager.

Parameters
listener StatusListener: The listener to call with progress updates.

getChannel

String getChannel ()

Return the update channel that the device is using for update checks. e.g "stable-channel", "beta-channel", etc.

Returns
String The current update channel.

getInstance

UpdateManager getInstance ()

Returns the UpdateManager instance for this application.

Returns
UpdateManager The UpdateManager instance.

getStatus

UpdateManagerStatus getStatus ()

Return the latest UpdateManagerStatus.

Returns
UpdateManagerStatus The latest UpdateManagerStatus.

Throws
IllegalStateException if the UpdateManager service is not ready

performUpdateNow

boolean performUpdateNow (int policy)

Immediately check for an available software update, and act on that update per the given policy.

Calls to this method override the policy set via setPolicy(UpdatePolicy).

If this is called while an update (or check) is already in progress, this will return false to indicate that the request to perform and update was not acted on.

Parameters
policy int: The policy to use for the operation

Returns
boolean True if the update check has been successfully started.

Throws
IllegalArgumentException if an invalid value is specified for policy
IllegalStateException if the UpdateManager service is not ready

removeStatusListener

void removeStatusListener (StatusListener listener)

Unregister a StatusListener from the UpdateManager.

Parameters
listener StatusListener: The listener to unregister.

setChannel

void setChannel (String channel)

Set the update channel that the device should be on.

NOTE: When changing channel, the device automatically factory resets as part of the next update (the update to the version from the new channel).

Parameters
channel String: The new update channel.

setPolicy

void setPolicy (UpdatePolicy policy)

Set the UpdatePolicy that the UpdateManager is to use.

Parameters
policy UpdatePolicy: The UpdatePolicy to follow.

Throws
IllegalStateException if the UpdateManager service is not ready.