com.webos.service.activitymanager

API Summary

Monitors various parts of the system and does actions when the corresponding events happen. Activities can also be used to schedule work periodically or at particular times.

The Activity Manager is responsible for coordinating work in the system. This includes work currently being done and work that is scheduled to be done at some point in the future. The primary unit of control is the Activity, which represents some specific item of work in the system - such as syncing an email account or a game that is being played.

The Activity Manager will track H/W and S/W through Activity and notify when the specified events occur. If there is a dynamic service that needs to wake up when certain conditions are met, Activity Manager is the best choice.

An Activity can have the state shown in the diagram above. What the Activity does for each state is as follows.

• creating
  • The create method is called and the activity is creating.
• created 
  • The activity was created successfully. 
  • When the create method is called with {'start' : true}, the activity automatically moves to unsatisfied state.
• starting
  • The start method is called and the activity is starting.
  • In this step, the activity will subscribe requirements, triggers, and schedule.
• unsatisfied
  • The activity waits for all conditions to be satisfied - requirements, triggers and schedule.
  • The activity in unsatisfied state can be paused by the pause method.
• pausing
  • The pause method is called and the activity is pausing.
• paused
  • The activity is paused.
  • In this state, the activity does not move to the satisfied state, although all conditions are satisfied.
  • The activity can move to unsatisfied state by start method.
• satisfying
  • All conditions of the activity are satisfying. 
  • An activity in unsatisfied state automatically moves to this state without an API call.
• satisfied
  • All conditions of the activity are satisfied.
  • There is nothing to do special.
• expiring
  • The activity is expiring.
  • The activity will call the callback method and unsubscribe triggers and cancel schedule.
• expired
  • The activity is over.
  • All callbacks are handled successfully.
  • If the activity is not set to continuous property, the activity is in expired state forever.
  • If its parent wants to start it again, the parent should call complete method with {'restart ': true}.
  • If parent does not want to restart it, then it must call the cancel method.
• restarting
  • The activity is restarting.
  • There are two ways to restart an activity.
    • One is to call the complete method with {'restart' : true}.
    • Another is to give the continuous property to true when creating the activity. If the activity was created with continuous property, the activity will move to unsatisfied state as soon as receive the callback response.
• failing
  • An error occurs during activity job and the activity is failing.
  • Any activity in any state can move to this state, if an error occurs.
  • Make sure that Triggers or Callbacks do not fail for any reason. Their failure will move the activity immediately to this state.
• failed
  • The activity has failed, and the activity manager cannot do anything anymore.
  • The parent should call cancel method to destroy the activity.
• destroying
  • The cancel method is called and the activity is destroying.
  • The cancel method can be called in any activity state,
• destroyed
  • The activity is destroyed.
  • In this state, the activity will be excluded from being managed by the activity manager.

create

Description

Attempt to start the specified Activity, either moving its state from 'created' to 'starting', or from 'paused' to 'resuming'.

Parameters

Call Returns

Example

Description

Terminate the specified Activity and optionally restart it with(or without) new callback, schedule or trigger. Only the Activity's parent can call this method. Other subscribers to the Activity receive a "complete" event.

If the Activity is persistent (i.e., persist in the Type object is set to true), the db8 is updated before the call returns.

Note: The invocations to callback/triggers are constrained by ACG security model. It means that Activity Manager can invoke trigger/callback when both Activity Manager and activity creator have the permissions to those methods. Otherwise, the method fails with the error "'com.webos.service.activitymanager' doesn't have rights to call callback/trigger".

Parameters

Call Returns

Example

Description

Terminate the specified Activity and send a "cancel" event to all subscribers to this Activity. This method succeeds if the Activity exists.

Parameters

Call Returns

Example

Description

Stop the specified Activity and send a "stop" event to subscribers to this Activity. This method succeeds if the Activity exists.

This method is exactly the same as cancel method. It is recommended to use cancel to avoid confusion.

Parameters

Call Returns

Example

Description

The Activity Manager considers the creator of the Activity as a parent.

Therefore, the creator of the activity does not need to adopt the Activity to be a parent.

An app or a service registers its willingness to become an Activity's parent, which means becoming an adopter.

• If there are adopters, all subscribers to this Activity receives an "orphan" event and the Activity is adopted to the new parent, one of the adopters. 
• If there are no waiting adopters, all subscribers to this Activity receives a "cancel" event and the Activity disappears immediately.

Parameters

Call Returns

Subscription Returns

Example

Description

Allow a parent to free an Activity and notify other subscribers. The Activity is cancelled unless one of its non-parent subscribers adopts it and becomes the new parent. For a completely safe transfer, a subscribing app or service, prior to the release, should already have called the adopt method.

Parameters

Call Returns

Example

Description

Suspend the work on the specified Activity and place the Activity in pause state.

NOTE: An activity can be paused only if it is in the unsatisfied state. Use the getActivityInfo method to check the state of an activity. 

Parameters

Call Returns

Example

Description

Gets information of Activities.

If activityId or activityName is given, getActivityInfo only returns information about that activity.

Conversely, if activityId or activityName is not given, getActivityInfo returns all undestroyed activities.

Parameters

Call Returns

Example

Description

Gets Activity Manager related information such as:

• Activity Manager state - queued and leaked activities
• List of activities for which power is currently locked
• Supported requirements

Parameters

None

Call Returns

Example

Activity

Represent everything about an Activity-name, type, state, requirements, schedule, trigger, callback, id,creator, adopters, processes, flows, and associations. 

Callback

The Callback object specifies a method to be called, and optionally arguments that should be passed to that method when the activity moves from 'satisfied' state to 'expiring'.

If the callback method fails::

• For normal (non-continuous) activity: activity is moved to 'failed' state.
• For continuous activity: activity moved to 'unsatisfied' state.

To change the behavior when callback fails, use the 'ignoreReturn' property.

InfoActivity

Activity information

InfoCreator

Creator information

InfoQueue

List of Activities for which power is currently locked.

InfoRequirement

Supported requirement information

Parent

Requirement

The Requirements are preconditions that the Activity Manager will ensure are met before an Activity will be run. Any number of requirements may be specified for a single Activity, and all must be met in order for the Activity to move to the satisfied state. Requirements can transition from the met state back to unmet if the condition the particular requirement is monitoring for no longer holds true.

The Requirements available on the system can be queried using getManagerInfo method.

Example :
luna-send -n 1 -f luna://com.webos.service.activitymanager/create '{
    "activity": {
        "requirements": {"bootup": true, "internet": true},
        "name": "browser-restart", "description": "", "type": {"foreground": true},
        "callback": {"method": "luna://com.webos.service.applicationmanager/launch", "params": {"id": "com.webos.app.enactbrowser"}},
        "trigger": {"method":"luna://com.webos.service.applicationmanager/getAppLifeStatus", "params": {"subscribe": true},
                      "where": {"and":[{"op": "=", "prop": "appId", "val": "com.webos.app.enactbrowser"}, {"op": "=", "prop": "status", "val":"stop"}]}}
    },
    "replace": true,
    "start": true
}'

Schedule

The Schedule object will define the time-based requirements for an Activity. If Schedule is specified, the schedule must be met before the Activity move to satisfied state.

NOTE : Some properties of Schedule may be changed.

1. Basic schedule

"schedule": {
    // Start time. Time format is a subset of ISO 8601.
    // That is, "YYYY-MM-DD HH:MM:SS" for local, or "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",
}

2. Smart interval

Smart intervals align all Activities operating with that period to the same start times, allowing them to batch up and avoid unnecessary device wakeups, potentially saving significant amounts of power.

"schedule": {
    // Time between events, in seconds.
    // For a smart interval, the interval must be an even multiple of days,
    // or one of the following: 12h, 6h, 3h, 1h, 30m, 15m, 10m, or 5m.
    "interval": "5m"
}

3. Precise interval

"schedule": {
    // Specifies that the Interval should occur at the precisely specified start time, and every given interval thereafter.
    "precise": true,

    // Start time. Time format is a subset of ISO 8601.
    // That is "YYYY-MM-DD HH:MM:SS" for local, and "YYYY-MM-DD HH:MM:SSZ" for UTC.
    "start": "2017-03-01 21:00:00",

    // End time for the interval (NOTE. This does not work currently.)
    [ "end": "2017-03-01 22:00:00", ]

    // Time between events, in seconds.
    // Specifies the number of days, hours, minutes, and seconds between executions of the Activity.
    // They must be specified in order, but any can be left out.  Any interval is valid.
    "interval": "1m",
}

Trigger

Activities with Triggers do not become runnable until an event occurs on a subscribed method. In addition, other requirements or scheduling constraints may also need to be met before the Activity is runnable. When the Activity starts, the specified method is called with "subscribe=true", and any additional arguments the Activity creator provides. If another Activity has previously been created and started with an identical Trigger, with the same method and arguments, then the Activity Manager may utilize its existing subscription to monitor the Triggering event, unless "unique" is true in the Trigger specification.

NOTE: Key Trigger and Compare Trigger are deprecated.

1. Key Trigger is triggered when the specified key exists.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true, "extraInfo": true },
    "key": "foregroundAppInfo"
}

2. Compare Trigger is triggered when the specified key & value pair in compare are matched.

"trigger": {
    "method": "luna://com.webos.service.applicationmanager/getForegroundAppInfo",
    "params": { "subscribe": true },
    "compare": { "appId": "com.webos.app.enactbrowser" }
}

3. Where Trigger is triggered when the conditions of where clauses are satisfied.

3-1. Single Trigger

"trigger": {
    "method": "luna://com.webos.service.connectionmanager/getstatus",
    "params": { "subscribe": true },
    "where": { "prop": "isInternetConnectionAvailable", "op": "=", "val": true }
}

3-2. Multiple Trigger can be combined by 'and' or 'or'

"trigger": {
    "and": [
        {
            ....
        },
        {
            "method": "luna://com.webos.service.applicationmanager/getAppLifeStatus",
            "params": { "subscribe": true },
            "where": { "and": [
                { "op": "=", "prop": "appId", "val": "com.webos.app.enactbrowser" },
                { "op": "=", "prop": "status", "val": "close" }
            ]}
        },
        {
            ....
        },
    ]
}

The Activity Manager will unsubscribe all subscriptions of Triggers, if the Activity arrives 'satisfied' state, and re-subscribe Triggers when 'restarting'.

WARNING

Do NOT ignore the trigger information returned in a callback. If an error is returned to the method specified for a Trigger, then the Trigger fires immediately. This could happen if, for example, the parameters passed to the method were invalid or wrong. If the Trigger callback re-starts the Activity, i.e., in the case of a db8 watch, then the potential exists for an infinite loop. Check for errors.

NOTE. As the 'failed' state is added, if an error is returned from the Trigger method, the Activity will move to 'failed' state without calling Callback in the next version.

Keep the mutual exclusion among the "key", "compare", and "where" properties. They are incompatible with each other.

Type

Indicate how the Activity is handled.

Forground or Background

Default attributes are associated with background and foreground Activities:

Foreground Activities are high priority and immediate- They cannot be queued and begin running when their prerequisites are met.
Background Activities are low priority and not immediate- They are runnable, but queued until necessary resources become available.

Whether an activity is foreground or background should only be set once. The default is foreground. If your app specifies foreground or background, do NOT set the advanced attributes like "immediate" and "priority". If you set them, the Activity Manager will NOT create the Activity. If you do not set either foreground or background, then you MUST set "immediate" and "priority".

NOTE. Do not use background. If background is set, the Activity may not run at all.

Persistent Activity

If "persist" is true, the Activity continues across device reboots. These Activities are atomically updated and re-scheduled across version updates and device or services crashes. However, note that the Activity Manager does not have any visibility into what your activity is actually doing, so if your app is in the middle of doing something in response to a fired activity, the Activity Manager has no awareness of that. In other words, the state of an activity, such as "paused", is not saved; instead, what happens is that activity specifications are reloaded as if you had just called "create" for it.

Explicit Activity

If "explicit" is true, the Activity can only be terminated with a stop, cancel, or complete call. If the parent of an explicit Activity unsubscribes, and no other adopter is available, then, instead of being cancelled (the default) the Activity is moved back to the ready state and its callback is invoked.

Schema

Note: All fields are optional, but if you do not set "foreground" or "background", then you must set "immediate" and "priority".