User:Emre/tb/activitymanagerInterface

Activity Manager Interface

	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.

TBD

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

Activity Manager Interfaces

• Activity Initiator: The entity that generates the activity. It is internal

An initiator is an optional property of the activity set during the initialization. It is internal to the activity and not used by Activity Manager. Can be any XPCOM components related to the activity.

is optional and internal to the activity.

Initiator is required to be an XPCOM component and support nsISupports interface. It is stored in the

• nsIActivity: Base interface for both nsIActivityProcess and nsIActivityEvent. Exposes common properties and methods.
• nsIActivityProcess: Exposes an interface for Processes activity types. Possible states for Processes are:
  • ACTIVITY_NOTSTARTED: State of an uninitialized activity. Represents an invalid activity.
  • ACTIVITY_INPROGESS: Initial state for successfully initialized process activities (Active). This state can be set by the implementer of the acti

• • ACTIVITY_COMPLETED: Activity is successfully completed (Finished).
  • ACTIVITY_FAILED: Activity failed due to an error. This state is transient and once the activity is set to this state, Activity Manager

This state is transient and the activity is required to be set either to ACTIVITY_WAITINGFORINPUT or ACTIVITY_WAITINGFORRETRY by Activity Manager based on recovery interfaces supported by the activity such as nsIActivityRetyable.

• • ACTIVITY_CANCELED: Activity is canceled by the user. Allows
  • ACTIVITY_PAUSED
  • ACTIVITY_WAITINGFORINPUT
  • ACTIVITY_WAITINGFORRETRY

• nsIActivityEvent:
• Activity Context:

Scenarios

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

Relevant Links

• https://wiki.mozilla.org/Thunderbird:Activity_Manager
• https://wiki.mozilla.org/Thunderbird:Activity_Manager/Window
• https://wiki.mozilla.org/Thunderbird:Interactive_Status_Bar