ContextUnderstanderService


public abstract class ContextUnderstanderService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.personalcontext.understander.ContextUnderstanderService


This is the base class for understander services to implement, handling service details.

An understander takes hints provided to the Personal Context system and interprets them. This usually means taking one or more hints, running them through models, and generating zero or more ContextInsights based on the hints.

The Personal Context service will manage the lifetime of this service, and this service may be stopped if not utilized for some time. Services should start as rapidly as possible to minimize latency in the Personal Context workflow.

You must declare the service in the AndroidManifest of the app hosting the service with the ERROR(Manifest.permission.BIND_CONTEXT_COMPONENT_SERVICE/android.Manifest.permission#BIND_CONTEXT_COMPONENT_SERVICE Manifest.permission.BIND_CONTEXT_COMPONENT_SERVICE) permission, and include an intent filter with the necessary action indicating that it is a ContextUnderstanderService (SERVICE_INTERFACE). The application must have the ERROR(Manifest.permission.PERSONAL_CONTEXT_RECEIVE_HINTS/android.Manifest.permission#PERSONAL_CONTEXT_RECEIVE_HINTS Manifest.permission.PERSONAL_CONTEXT_RECEIVE_HINTS) and ERROR(Manifest.permission.PERSONAL_CONTEXT_PUBLISH_INSIGHTS/android.Manifest.permission#PERSONAL_CONTEXT_PUBLISH_INSIGHTS Manifest.permission.PERSONAL_CONTEXT_PUBLISH_INSIGHTS) permissions.

For example:

    <uses-permission
        android:name="android.permission.PERSONAL_CONTEXT_RECEIVE_HINTS"/>
    <uses-permission
        android:name="android.permission.PERSONAL_CONTEXT_PUBLISH_INSIGHTS"/>

    <service android:name=".ExampleContextUnderstanderService"
            android:exported="true"
            android:permission="android.permission.BIND_CONTEXT_COMPONENT_SERVICE">
        <intent-filter>
            <action android:name=
"android.service.personalcontext.understander.ContextUnderstanderService" />
        </intent-filter>
    </service>

Agent understanders can also provide interactive embedded visualizations to display in client apps that request them. An understander is an agent understander if it was registered with ERROR(/android.service.personalcontext.PersonalContextManager.UnderstanderType#UNDERSTANDER_TYPE_AGENT).

Requests for visualization are surfaced in the onUnderstand(UnderstandRequest) call as an ERROR(PersonalContextManager.DESTINATION_EMBEDDED/android.service.personalcontext.PersonalContextManager#DESTINATION_EMBEDDED PersonalContextManager.DESTINATION_EMBEDDED) in the request. The understander can establish the session by providing a InsightVisualizerSession in the UnderstandResult. All calls on the provided session will be executed on the Executor configured via setExecutor(Executor), or on the main looper by default.

Summary

Constants

String SERVICE_INTERFACE

The Intent action that must be declared as handled by the service.

Inherited constants

Public constructors

ContextUnderstanderService()

Public methods

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onConnected()

Called when the understander has been configured and is ready to receive insights.

void onHandleEvent(String packageName, InsightEvent event)

Override this method to receive logging events for actions taken on the insight.

UnderstandResult onUnderstand(UnderstandRequest request)

Called when a new hint is available.

final void setExecutor(Executor executor)

Sets the executor to be used when methods are invoked on this service.

Inherited methods

Constants

SERVICE_INTERFACE

Added in version 37.2
public static final String SERVICE_INTERFACE

The Intent action that must be declared as handled by the service.

Constant Value: "android.service.personalcontext.understander.ContextUnderstanderService"

Public constructors

ContextUnderstanderService

public ContextUnderstanderService ()

Public methods

onBind

Added in version 37.2
public final IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: This value may be null.

Returns
IBinder This value may be null.

onConnected

Added in version 37.2
public void onConnected ()

Called when the understander has been configured and is ready to receive insights. Any actions related to this method should complete before returning.

onHandleEvent

Added in version 37.2
public void onHandleEvent (String packageName, 
                InsightEvent event)

Override this method to receive logging events for actions taken on the insight.

Invoked when an event has been reported on a ContextInsight originally published by this ContextUnderstanderService.

Parameters
packageName String: the package of the application reporting the event.
This value cannot be null.

event InsightEvent: The reported InsightEvent.
This value cannot be null.

onUnderstand

Added in version 37.2
public UnderstandResult onUnderstand (UnderstandRequest request)

Called when a new hint is available.

As each hint is provided to the Personal Context system it will be forwarded on to understanding components. The understander can take these hints, cache them between calls, and use one or more hints together to generate ContextInsights.

Parameters
request UnderstandRequest: The UnderstandRequest details.
This value cannot be null.

Returns
UnderstandResult an UnderstandResult that this ContextUnderstanderService generated by processing the incoming hints.
This value cannot be null.

setExecutor

Added in version 37.2
public final void setExecutor (Executor executor)

Sets the executor to be used when methods are invoked on this service. By default, an Executor running on the main looper is used. This method should be called within Service.onCreate().

Parameters
executor Executor: The Executor to run calls on.