Mylyn/Porting Guide/3.0

Migrating from Mylyn 2.x to 3.0

Note: This porting guide is work in progress. Feel free to add contents.

This porting guide is intended to support developers porting connectors from Mylyn 2.x to Mylyn 3.x. In addition to the abbreviated pseudo code examples in this guide it is recommended to refer to the Bugzilla, Trac and JIRA connector implementations that are part of the Mylyn code base.

Migrating Tasks and Queries

In Mylyn 3.0 the data model of the task list has changed. Elements in the task list are now managed by the tasks framework and connectors do not extend AbstractTask or AbstractRepositoryQuery with their own implementation. Task list externalization that previously required connectors to provide an implementation of AbstractTaskListFactory is now encapsulated in the framework.

In order to migrate the Mylyn 2.x tasklist.xml.zip to the new tasks.xml.zip file connectors need to extend AbstractTaskListMigrator. When a Mylyn 2.x task list is read the migrator is invoked for migrating query and tasks elements. The migration is only done once. The task list migrator is registered through the org.eclipse.mylyn.tasks.ui.repositories extension point:

<extension id="org.eclipse.mylyn.web.repository" name="Generic web-based access (Advanced)" point="org.eclipse.mylyn.tasks.ui.repositories"> <connectorCore ... /> <connectorUi ... /> <taskListFactory class="org.eclipse.mylyn.internal.web.tasks.WebTaskListFactory" id="org.eclipse.mylyn.web.tasklist.taskListFactory"/> </extension>

<extension id="org.eclipse.mylyn.web.repository" name="Generic web-based access (Advanced)" point="org.eclipse.mylyn.tasks.ui.repositories"> <connectorCore ... /> <connectorUi ... /> <taskListMigrator class="org.eclipse.mylyn.internal.web.tasks.WebTaskListMigrator"> </taskListMigrator> </extension>

The implementating of AbstractTaskListFactory.createTask() has moved to AbstractTaskListMigrator.migrateTask(). Instead of creating an instance of a custom task class connector set custom state on task classes through the setAttribute() method.

Whether task data is up to date is now managed by the connector. The reference implementations use the last modification time stamp of task data to determine if a task is stale. In Mylyn 2.x the last modification time stamp was not stored in the task list but the last read time stamp which is the connector specific string that was stored in the DATE_MODIFICATION attribute on task data was set on a task when it was opened. The last read time stamp is not used anymore and must be migrated if connectors intend to use this as the last modification time stamp. Please note that the last read time stamp may not be set or not accurately reflect the last modification stamp of the latest downloaded task, e.g. when a task is new or when the latest state has not been read.

Connectors that used to override AbstractTask.getTaskKey() need to explicitly set the task key during migration. It is initialized to the task id by default:

class JiraTaskListMigrator {
	@Override
	public void migrateTask(ITask task, Element element) {
		task.setModificationDate(JiraUtil.stringToDate(element.getAttribute(KEY_LAST_MOD_DATE)));
		task.setTaskKey(element.getAttribute(KEY_KEY));
	}

Connectors that used to override AbstractTask.isLocal() must now implement AbstractRepositoryConnector.hasLocalCompletionState() instead.

Tip: AbstractTaskListFactory contains most of the information necessary to implement AbstractTaskListMigrator. For the migrateTask() and migrateQuery() methods, any data you use to set on your connector specific element must now be set as attributes on either the task or query being migrated. Use the task.setAttribute(String, String) method to set your connector specific key value pairs.

Porting Query Synchronization

In Mylyn 2.x AbstractRepositoryConnector.markStaleTasks() was invoked to indicate the start of a task list or query synchronization. The method has been replaced by preSynchronization() and postSynchronization() which have ISynchronizationSession paramater. The synchronization session is state associated with a particular synchronization. It has getters that specify details about the type synchronization.

Migrating markStaleTasks() to preSynchronization()

Previously AbstractTask.setStale() was used to indicate that a task requires synchronization. This is now done by invoking ISynchronizationSession.markStale(ITask). Connectors that fetch task data in preSynchronization() can store the data by invoking session.putTaskData().

The boolean return value of markStaleTasks() has been replaced by IsynchronizationSession.setNeedsPerformQueries(). The default is to perform queries but connectors may set the flag to false to indicate that the task list is up to date.

Porting performQuery()

The IqueryHitCollector interface has been replaced by TaskDataCollector which only accepts task data. Connectors that used to return AbstractTask may now use the framework class TaskMapper which provides a default schema for task data:

TaskData data = createTaskData(repository, id);
TaskMapper mapper = new TaskMapper(data, true);
mapper.setTaskUrl(taskPrefix + id);
mapper.setSummary(description);
mapper.setValue(KEY_TASK_PREFIX, taskPrefix);
resultCollector.accept(data);

The task framework will invoke AbstractRepositoryConnector.hasTaskChanged() for each returned TaskData object. Connectors may use a task property or a custom attribute to determine if the task data is up to date. TaskMapper has a method that compares attribute values on the task class with the values on task data to determine if a task has changed:

return new TaskMapper(taskData).hasChanges(task);

Migrating getSynchronizationTimestamp() to postSynchronization()

The default implementation of AbstractRepositoryConnector.getSynchronizationTimestamp() used to return the most recent modification time stamp of all tasks synchronized by a query. Connectors must now provide an implementation in postSynchronization() to persist synchronization information.

Migrating updateTaskFromQueryHit() to updateTaskFromTaskData()

Since the task data collector now only accepts task data connectors must implement updateTaskFromTaskData(). If the default task schema is used TaskMapper.apply() may be sufficient:

TaskMapper mapper = new TaskMapper(taskData);
mapper.applyTo(task);

API Changes

Plug-in Refactorings

• org.eclipse.mylyn.web.core is now org.eclipse.mylyn.commons.net
• Core classes from org.eclipse.mylyn.monitor.core was split in order to make API not coupled to the Monitor component be reusable independently, now in the new org.eclipse.mylyn.commons.core plug-in.
• org.eclipse.mylyn.commons.ui is a new API for common UI components that are not coupled to the rest of Mylyn.

Changed Extension Points

• org.eclipse.mylyn.tasks.ui.editors
  • hyperLinkDetector has been removed, use org.eclipse.ui.workbench.texteditor.hyperlinkDetectors instead and set targetId to org.eclipse.mylyn.tasks.ui.TaskEditor
  • editorFactory has been removed, use pageFactory instead

• repositories
  • taskListFactory has been removed, use taskListMirgrator instead
  • connectorCore
    • userManaged has been removed, override isUserManaged() in AbstractRepositoryConnector instead
  • connectorUi
    • customNotifications has been removed, override isCustomNotification() in AbstractRepositoryConnectorUi instead

New Context API

• AbstractFocusViewAction.updateEnablementWithContextActivation(): override to return false for focus actions that are not related to context activations (e.g. the Task List).

• AbstractFocusViewAction.setLinkingActionEnabled(boolean): should be overridden if view provides linking

Removed Context API

• ActivityTimerThread has been removed
• BrowseFilteredAction has been moved to an internal package
• ContextCorePlugin has been moved to an internal package and replaced by ContextCore
• ContextUiPlugin has been moved to an internal package and replaced by ContextUi
• IActivityTimerListener has been removed
• IInteractionContextListener has been renamed to AbstractContextListener
• InteractionContextReader has been moved to an internal package
• InteractionContextWriter has been moved to an internal package
• MonitorUiPlugin has been moved to an internal package and replaced by MonitorUi
• ResourcesUiPlugin has been moved to an internal package and replaced by ResourcesUi
• The active/auto folding preference has been removed, you can reuse the one from JavaUiBridgePlugin or use your own preference

New Monitor API

• MonitorUiPlugin.getMonitoredWindows(): use insteand of PlatformUI.getWorkbench().getWorkbenchWindows()
• MonitorUiPlugin.getLaunchingWorkbenchWindow(): use to get the first active window when the monitor started.

Removed Monitor API

• IMylarMonitorLifecycleListener has been renamed to IMonitorLifecycleListener
• ReportGenerator has been moved to an internal package

Changed Team API

• org.eclipse.mylyn.tasks.core.ILinkedTaskInfo is now org.eclipse.mylyn.team.ui.AbstractTaskReference
  • getComment() has been renamed to getText()

Removed Tasks API

Some deprecated types and methods have been moved to the internal package org.eclipse.mylyn.internal.tasks.core.deprecated. This package is not intended as a backwards compatibility layer and is expected to be removed as part of the 3.1 release.

• AbstractAttachmentHandler has been removed, use AbstractTaskAttachmentHandler instead
  • MESSAGE_ATTACHMENTS_NOT_SUPPORTED has been removed
  • MYLAR_CONTEXT_DESCRIPTION has been removed
  • MYLAR_CONTEXT_DESCRIPTION_LEGACY has been removed
  • MYLAR_CONTEXT_FILENAME has been removed
  • attachContextAttachments() has been moved to the internal class AttachmentUtil
  • getContextAttachments() has been moved to the internal class AttachmentUtil
  • hasRepositoryContext() has been moved to the internal class AttachmentUtil
  • retrieveContext() has been moved to the internal class AttachmentUtil

• AbstractAttributeFactory has been removed, use TaskAttributeMapper instead

• AbstractDuplicateDetector has been moved to tasks.core

• AbstractEditQueryWizard has been renamed to AbstractRepositoryQueryWizard

• AbstractNewRepositoryTaskEditor has been removed, use AbstractTaskEditorPage instead

• AbstractRepositoryConnector
  • init() has been removed
  • getAttachmentHandler() has been renamed to getTaskAttachmentHandler()
  • createTaskFromExistingId() has been removed
  • createTaskFromTaskData() has been removed, use updateTaskFromTaskData() instead
  • createTask() has been removed, use RepositoryModel.createTask() instead
  • getPepositoryPropertyNames() has been removed
  • getTemplate() has been removed, use RepositoryTemplateManager instead
  • hasTaskPropertyChanged() has been removed
  • updateTaskFromRepository() has been removed, use updateTaskFromTaskData() instead
  • updateTaskFromQueryHit() has been removed, use updateTaskFromTaskData() instead
  • markStaleTasks() has been removed, override preSynchronization() instead
  • removeTemplate() has been removed, use RepositoryTemplateManager instead
  • updateAttributes() has been renamed to updateRepositoryConfiguration()
  • setUserManaged() has been removed, override isUserManaged()<code> instead

• <code>AbstractRepositoryConnectorUi
  • forceSubtaskHierarchy() has been removed, override hasStrictSubtaskHierarchy() instead
  • getLegendItems() has been renamed to getLegendElements()
  • getNewTaskWizard(TaskRepository) has been removed, use getNewTaskWizard(TaskRepository, ITaskMapping) instead
  • getTaskKindLabel(RepositoryTaskData) has been removed
  • getTaskListElementIcon() has been removed, override getImageDescriptor() instead
  • isCustomNotificationHandling() has been removed, override hasCustomNotificationHandling() instead
  • openEditQueryDialog(AbstractRepositoryQuery) has been moved to the internal class TasksUiInternal
  • openRepositoryTask() has been moved to the internal class TasksUiInternal
  • setCustomNotificationHandling() has been removed, override hasCustomNotificationHandling() instead
  • supportsDueDates(AbstractTask) has been removed, override AbstractRepositoryConnector.hasRepositoryDueDate() instead

• AbstractRepositoryQuery has been removed, use IRepositoryQuery instead
  • getRepositoryKind() has been renamed to getConnectorKind()

• AbstractRepositoryQueryPage has been moved to org.eclipse.mylyn.tasks.ui.wizards

• AbstractRepositoryTaskEditor has been removed, use AbstractTaskEditorPage instead

• AbstractRepositoryQueryWizard has been removed, use RepositoryQueryWizard instead

• AbstractTask has been removed, use ITask instead
  • hasValidUrl() has been moved to TasksUiInternal.isValidUrl()
  • setCompleted() has been removed, a non-null completion date indicates a task is complete

• AttributeContainer has been removed, use TaskAttribute instead

• AuthenticatedProxy has been moved to an internal package

• DatePicker has been moved to org.eclipse.mylyn.commons.ui

• DateSelectionDialog has been moved to org.eclipse.mylyn.commons.ui

• FileAttachment has been removed, use AbstractTaskAttachmentSource instead

• GzipGetMethod has been moved to an internal package

• GzipPostMethod has been moved to an internal package

• IStatusHandler has been removed, use AbstractErrorReporter instead

• ITaskCollector has been removed, use TaskDataCollector instead

• ITaskFactory has been removed

• ITaskRepositoryListener has been renamed to IRepositoryListener

• ITaskListChangeListener has been moved to an internal package

• NewTaskEditorInput has been removed, use TaskEditorInput instead

• QueryHitCollector has been removed, use TaskDataCollector instead

• RepositoryAttachment has been removed, use TaskAttachmentMapper instead

• RepositoryOperation has been removed, use TaskOperationMapper instead

• RepositorySearchResult has been moved to an internal package

• RepositoryTaskData has been removed, use TaskData instead

• RepositoryTaskEditorInput has been removed, use TaskEditorInput instead

• SearchHitCollector has been moved to an internal package

• SslProtocolSocketFactory has been moved to an internal package

• StatusHandler
  • addDefaultStatusHandler(IStatusHandler) has been removed
  • addStatusHandler(IStatusHandler) has been removed
  • fail(Throwable,String,boolean) has been removed
  • fail(Throwable,String,boolean,int) has been removed
  • getDefaultStatusHandler() has been removed
  • getStatusHandler() has been removed
  • log(String,Object) has been removed
  • log(Throwable,String) has been removed
  • setDefaultStatusHandler(IStatusHandler) has been removed
  • removeStatusHandler(IStatusHandler) has been removed

• TaskActivityManager
  • getInstance() has been removed, use TasksUiPlugin.getTaskActivityManager() instead
  • init() has been replaced by a public constructor

• TaskFormPage
  • actionContributor has been removed

• TaskFactory has been removed

• TaskListManager has been moved to an internal package and replaced by ITaskListManager
  • task activity related methods have been removed (see TaskActivityManager)

• TaskRepositoryManager has been moved to an internal package and replaced by ITaskRepositoryManager

• TaskEditor
  • configureContextMenuManager(MenuManager,TextViewer) has been removed
  • getAdapterDelegate() has been removed
  • getContributor() has been removed
  • refreshEditorContents() has been renamed to refreshPages()

• TaskList has been moved to an internal package and replaced by ITaskList

• TaskSelection has been removed, use ITaskMapping instead

• TasksUiProxyChangeListener has been removed

• TasksUiUtil
  • closeEditorInActivePage(ITask,boolean) has been moved to the internal class TasksUiInternal
  • getActiveRepositoryTaskEditor() has been moved to the internal class TasksUiInternal
  • isAnimationsEnabled() has been moved to the internal class TasksUiInternal
  • openEditor(TaskCategory) has been moved to the internal class TasksUiInternal
  • openEditor(AbstractTask, boolean) has been replaced by openTask(ITask)
  • openEditor(AbstractTask, boolean, boolean) has been replaced by openTask(ITask)
  • openEditor(AbstractTask, String) has been replaced by openTask(ITask)
  • openUrl(String, boolean) has been replaced by openTask(String) and openUrl(String)
  • refreshAndOpenTaskListElement() has been moved to the internal class TasksUiInternal
  • showPreferencesPage(String, IPreferencePAge) has been removed

• TrustAllTrustManager has been moved to an internal package

• WebClientLog has been removed

• WebClientUtil has been removed, use WebUtil instead

• WebCorePlugin has been moved to an internal package

• WebHyperlink has been moved to an internal package