UpdateInfoService
public abstract class UpdateInfoService extends Service
| java.lang.Object | ||||
| ↳ | android.content.Context | |||
| ↳ | android.content.ContextWrapper | |||
| ↳ | android.app.Service | |||
| ↳ | androidx.security.state.provider.UpdateInfoService | |||
Base class for implementing the AndroidX Security State Update Provider service.
This abstract class provides the foundational implementation for the IUpdateInfoService AIDL interface. It manages the complexity of serving security update information to client applications, enforcing a consistent contract for data freshness, resource usage, and observability.
Responsibilities
-
IPC Handling: Manages the AIDL binding process and verifies Intent actions.
-
Concurrency Control: Implements Double-Checked Locking to prevent "thundering herd" scenarios where multiple clients trigger parallel network requests.
-
Rate Limiting: Enforces a default throttling policy (e.g., maximum one check per hour) to protect backend infrastructure.
-
Caching: Automatically persists fetched results and freshness metadata to local storage.
Monitoring & Telemetry
To support high-scale hosts that require strict monitoring, this class provides a comprehensive set of observability hooks. Hosts can override these methods to integrate with their own logging infrastructure:
-
onRequestCompleted: Report granular performance metrics (latency, lock contention) and usage. -
onClientConnected/onClientDisconnected: Track service session lifecycles and adoption. -
onFetchFailed: Report backend errors and exceptions. -
dump: Debug internal state viaadb shell.
Host Implementation
Host applications (such as the System Updater, Google Play Store, or OEM-specific updaters) must extend this class and implement the fetchUpdates method to provide the actual network logic.
Manifest Declaration
To expose this service, you must declare it in your AndroidManifest.xml with the exported="true" attribute and an intent-filter for the UPDATE_INFO_SERVICE action:
<service
android:name=".MyUpdateInfoService"
android:exported="true">
<intent-filter>
<action android:name="androidx.security.state.provider.UPDATE_INFO_SERVICE" />
</intent-filter>
</service>
Summary
Public constructors |
|---|
Public methods |
|
|---|---|
void |
dump(FileDescriptor fd, PrintWriter writer, String[] args)Dumps the state of the service for debugging (e.g. |
final IBinder |
Called by the system when a client binds to the particular interface defined by the |
final boolean |
Called by the system when all clients have disconnected from the particular interface defined by the |
Protected methods |
|
|---|---|
abstract @NonNull List<@NonNull UpdateInfo> |
Performs the actual network request to fetch fresh updates from the backend. |
int |
Retrieves the UID of the calling process. |
void |
onClientConnected(@NonNull Intent intent)Called when a client binds to the particular interface defined by the |
void |
onClientDisconnected(Intent intent)Called when all clients have disconnected from the particular interface defined by the |
void |
Callback for handling exceptions that occur during the update check process. |
void |
onRequestCompleted(@NonNull UpdateCheckTelemetry telemetry)Called when a request completes. |
boolean |
Determines if the local cache is stale and a refresh should be attempted. |
boolean |
Checks if the operation should be throttled based on the rate limiter. |
Public constructors
Public methods
dump
public void dump(FileDescriptor fd, PrintWriter writer, String[] args)
Dumps the state of the service for debugging (e.g. adb shell dumpsys activity service).
This implementation provides a snapshot of the internal state, including:
-
Active Request Count: To detect stuck threads or high concurrency.
-
Global Last Check Time: The timestamp of the last successful service-wide sync (Service Health).
-
Throttling Status: Whether the rate limiter is currently blocking network requests.
-
Cached Updates: A complete list of stored updates with detailed metadata (Component, SPL, Provider, Published Date, Last Checked Time).
onBind
public final IBinder onBind(Intent intent)
Called by the system when a client binds to the particular interface defined by the intent.
This method verifies that the Intent action matches the expected contract (ACTION_BIND). If the action is missing or incorrect, the binding is rejected to ensure the service is not exposed unintentionally.
Lifecycle Note: Because the client library attaches unique data (the package name) to the intent, this method is called for every new client session, allowing the onClientConnected hook to reliably track individual connections.
| Parameters | |
|---|---|
Intent intent |
The Intent that was used to bind to this service. |
| Returns | |
|---|---|
IBinder |
The IBinder interface for clients to interact with the service, or |
onUnbind
public final boolean onUnbind(Intent intent)
Called by the system when all clients have disconnected from the particular interface defined by the intent.
This method is marked final to enforce the library's lifecycle contract. It performs two critical actions:
-
Triggers the
onClientDisconnectedhook, allowing the host to log the end of the session. -
Returns
false, which forces the Android system to callonBind(and thusonClientConnected) for all future connections. This simplifies telemetry by ensuring a consistent "Connect -> Disconnect" cycle without needing to handle theonRebindedge case.
| Parameters | |
|---|---|
Intent intent |
The Intent that was used to bind to this service. |
| Returns | |
|---|---|
boolean |
|
Protected methods
fetchUpdates
protected abstract @NonNull List<@NonNull UpdateInfo> fetchUpdates()
Performs the actual network request to fetch fresh updates from the backend.
Implementations of this method should:
-
Block until the network request completes.
-
Return the list of updates found.
-
Throw an exception if the network request fails (this will be caught and logged).
Note: This method is only called if shouldFetchUpdates returns true and the rate limiter allows the request.
| Returns | |
|---|---|
@NonNull List<@NonNull UpdateInfo> |
A list of |
getCallerUid
protected int getCallerUid()
Retrieves the UID of the calling process.
The default implementation delegates to android.os.Binder.getCallingUid. Host implementations using a proxy or broker architecture should override this to return the logical client UID instead of the broker's UID, ensuring correct attribution.
onClientConnected
protected void onClientConnected(@NonNull Intent intent)
Called when a client binds to the particular interface defined by the intent.
This method is invoked during onBind after the Intent action has been verified.
Usage: Override this method to log connection metrics (e.g., "Session Started") or track adoption trends.
Client Identity: The intent passed to this method typically contains the client's package name in the data URI (e.g., package:com.example.client). This allows you to identify which app is starting a session. Note that this value is self-reported by the client library and is useful for aggregate trends but less secure than the UpdateCheckTelemetry.callerUid captured in onRequestCompleted.
Lifecycle: Because the client library attaches unique data to the bind Intent, this method is called for every new client session, enabling accurate session counting.
onClientDisconnected
protected void onClientDisconnected(Intent intent)
Called when all clients have disconnected from the particular interface defined by the intent.
This method is invoked during onUnbind.
Usage: Override this method to log session ends (e.g., "Session Ended") to calculate session duration when paired with onClientConnected. You can also use this to perform per-client resource cleanup.
| Parameters | |
|---|---|
Intent intent |
The Intent that was used to bind to this service. It contains the same identification data as passed to |
onFetchFailed
protected void onFetchFailed(@NonNull Exception e)
Callback for handling exceptions that occur during the update check process.
This method is invoked if any step of the update logic fails, including:
-
Determining cache freshness (
shouldFetchUpdates). -
Recording rate-limit attempts.
-
Fetching data from the backend (
fetchUpdates). -
Persisting the results to local storage.
The default implementation logs the error to Logcat. Hosts can override this to report errors to their own telemetry or crash reporting systems.
onRequestCompleted
protected void onRequestCompleted(@NonNull UpdateCheckTelemetry telemetry)
Called when a request completes. Override this to log telemetry.
This hook is called for every request to listAvailableUpdates, regardless of whether it succeeded, failed, was throttled, or was served from the cache.
Usage: Use this hook to log granular performance metrics (latency histograms) and resource usage.
Attribution: The telemetry object contains the UpdateCheckTelemetry.callerUid, which is the Kernel-verified UID of the calling process. This is the authoritative source for attributing load (CPU/Network/Lock Contention) to specific client applications.
| Parameters | |
|---|---|
@NonNull UpdateCheckTelemetry telemetry |
The |
shouldFetchUpdates
protected boolean shouldFetchUpdates()
Determines if the local cache is stale and a refresh should be attempted.
The default implementation returns true if the data is older than 1 hour. Hosts can override this to implement custom caching policies (e.g., 4 hours, 24 hours).
| Returns | |
|---|---|
boolean |
|
shouldThrottle
protected boolean shouldThrottle()
Checks if the operation should be throttled based on the rate limiter.
The default implementation delegates to an internal rate limiter that enforces a cooling-off period (e.g., one check per hour). Hosts can override this to inject custom rate limiting logic (e.g., battery checks).
| Returns | |
|---|---|
boolean |
|