Activity Manager Concepts and Interfaces

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

Entities

Activity Manager: A service to manage and persist the activities generated by the core components and extensions.

@mozilla.org/activity-process;1: The default implementation of a Process activity. It knows how to deal with predefined activity types. In the majority of the cases the consumer of the activity management system can initiate this component and use for its purpose.

@mozilla.org/activity-event;1: The default implementation of an Event activity. It knows how to deal with predefined activity types. In the majority of the cases the consumer of the activity management system can initiate this component and use for its purpose.

Activity Initiator: An entity that generates the activity, such as a component of TB or an Extension. It is internal to the activity and can be anything represented by a nsISupports interface. It is optional for user defined activities.
- For example, sync activity stores the reference of nsIAutoSyncManager service in this property to be used by nsIActivityCancelable implementation in order to cancel the activity.

Activity Context: A context given by the initiator. This property is used by the Activity Manager UI to group the activities sharing the same contextType and contextVal values. Context type can be one of the predefined contexts or an user defined one. Activity Manager knows how to show the Context Display Text of predefined types. For user defined types, either the user should register an implementation of nsIActivityContextDisplayHelper, or should pass the display text to contextVal property of the activity.
- Predefined contexts are;
  - Account: it groups the activities by given nsIMsgIncomingServer. For example if the contextType is 'account' and contextVal is (nsIMsgIncomingServer of myname@gmail.com acocunt) then all activities belong to this server show up under the same group. See Account Activity.
  - Smtp: Similarly, it groups the activities by given smtp server.
  - Calendar: It groups the activities by the calendar. Since there is only one calendar, contextVal can be omitted.
  - Addressbook: It groups the activities by the addressbook. contextVal should represents the proper address book.

Activity Type: Type of the activity. Can be one of the predefined types or an user defined one. Activity Manager knows how to localize and display the predefined types on the UI. For user defined types, either the user should provide the localized texts or should provide a ...(Not sure we need an interface here) interface.
- Predefined activity types are:
  - send: Sending an email.
  - sync: Synchronizing the local store with the server.
  - copy: Copying messages from one location to another.
  - move: Moving messages from one location to another.
  - delete: Deleting messages.
  - add_item: Generic item adding activity. Can be adding a new contact to the address book, or a new event to the calendar.
  - remove_item: Similar to add_item type.
  - update: Updating a folder (?? probably we don't need that)
  - compacting: Compacting a folder.
  - indexing: Indexing the messages in a folder (OS indexing service integration component or gloda are possible initiators of this type).
  - undo: Undo operation on an activity event.

Processes: Processes are activities that happens in a time-span with possibility of failure. They are distinct entities, and they are not mapped to Events automatically because of the following reasons;
- Initiator could prefer to generate multiple processes but one event for the activity. For example, Auto-sync manager generates a process each time it syncs a folder but only one "Account is syncd" event when the account is fully syncd with the server.
- One-shot activities do not require processes. For example Addressbook generates an add_item event each time the user adds a new contact to the address book without generating a process for it.
- Processes are not persisted by Activity Manager.

Event: Events are not Processes in COMPLETED state. They are distinct entities, and they represents a finished and undoable (if nsIActivityUndoable is provided) activity. Events are persisted by Activity Manager.

Subject List: A list of the entities are subject to the activity. It can store any activity specific entity. It is optional.
- For example, Move operation stores source and target folders in this list to be used by nsIActivityRetyable and/or nsIActivityUndoable implementations of the activity, if provided.

UI elements:
- Context Display Text: The short description of the context. User defined contexts should be localized by nsIActivityContextDisplayHelper::getContextDisplayText() implementation. Predefined contexts are localized by Activity Manager.
- Display Text: The short description of the activity. Should be localized during the initialization of the activity by the initiator. i.e. "Synchronizing Folder 'bugs'".
- Status Text: The text describing the status of the activity. Should be localized by the entity setting the progress of the activity. i.e. "100 of 300 messages"
- Progress bar: Self explanatory

Interfaces

nsIActivityMgrListener: The implementor of this interface gets notified when an activity is added/removed to/from the activities list managed by Activity Manager.

nsIActivityManager: Keeps the list of the recent Processes and Events. It is also responsible of serialization/deserialization of the Events. Activity Manager doesn't add/remove activities but might change the state of the activities.

nsIActivity: Base interface for both nsIActivityProcess and nsIActivityEvent. Exposes common properties and methods.

nsIActivityProcess: Processes activity types should implement this interface. Possible states are:
- ACTIVITY_NOTSTARTED: State of an uninitialized activity. Represents an invalid activity.
- ACTIVITY_INPROGESS: Initial state for a successfully initialized process activity. The progress of the activity can only be set in this state.
- ACTIVITY_COMPLETED: Activity is successfully completed (Finished). The activity should be removed from the activity list by the initiator.
- ACTIVITY_FAILED: Activity failed due to an error. At this point, the initiator can set the state to ACTIVITY_WAITINGFORRETRY, if nsIActivityRetryable is supported.
- ACTIVITY_CANCELED: Activity is canceled by the user. This is possible if the activity supports nsIActivityCancelable interface.
- ACTIVITY_PAUSED: Activity is paused by the user. This is possible if the activity supports nsIActivityPausable interface.
- ACTIVITY_WAITINGFORINPUT: A failure has been occurred, and the user needs to provides data to recover from the problem, such as account credentials, password etc..
- ACTIVITY_WAITINGFORRETRY: A failure has been occurred and the activity is waiting to be retried by the user, or by the Activity Manager.

nsIActivityEvent:Event activity types should implement this interface. ACTIVITY_COMPLETED is the only valid state for this type.

nsIActivityListener: The implementor of this interface gets notified when the activity in question changes state or changes progress.

nsIActivityPausable: If provided with the activity, it allows the user to pause/resume the activity during its progress. Processes only.

nsIActivityRetryable: If provided with the activity, it allows the user to retry the failed activity. Processes only.

nsIActivityCancelable: If provided with the activity, it allows the user to cancel the activity. Processes only.

nsIActivityUndoable: If provided with the activity, it allows the user to undo the operation subject of the event. Persisted Events cannot be undo. This feature will be supported in the future when we have a better undo mechanism in place.

Extending the Activity System

If the default implementation of nsIActivityProcess and nsIActivityEvent are not sufficient for the activity initiator, it can provides its own implementation to extend the capabilities. Default implementations can be found in nsActivity.js file.

If the activity initiator would like to extend the default UI representation of the activity types, it can provides its own XBL elements for its own activity types. All custom activity XBL elements should inherit from "activity-base" binding. For XBL sample please see activity.xml and activity.css files.

Scenarios

Adding an activity for junk processing
Adding an activity with cancelable capability

User:Emre/tb/activitymanagerInterface

Contents

Activity Manager Concepts and Interfaces

Entities

Interfaces

Extending the Activity System

Scenarios

Relevant Links

Relevant Bugs