Jump to: navigation, search

Difference between revisions of "Mylyn/Porting Guide"

(Porting from 2.0 to 3.0)
(35 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
[[Category:Mylyn]]  
 
[[Category:Mylyn]]  
  
'''NOTE:''' Mylyn 3.0 changes are currently in progress, and we recommend building against the [http://wiki.eclipse.org/index.php/Mylyn_Contributor_Reference#Checkout Mylyn 2.x stream].  See {{bug|227660}} for the plan and for details.  If interested in API progress, we recommend adding a watch for this page and a CC for that bug.
+
= General =
  
= Porting from 1.0 to 2.0 =
+
Mylyn follows the Eclipse conventions for [[Version_Numbering|version numbering]] and guarantees [[Evolving_Java-based_APIs|binary backwards compatibility]] for minor releases. Internals are binary backwards compatible between service releases.
  
See the <b>[[Mylyn Porting Guide 2.0]]</b>
+
API enhancements can be tracked by searching the source code for the corresponding @since JavaDoc tags or by querying for bugs that have [api] in their summary.
  
= Porting from 2.0 to 3.0 =
+
= Pending API changes in 3.10 =
  
'''[https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=%5Bapi%5D&classification=Tools&product=Mylyn&target_milestone=3.0&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P1&priority=P2&priority=P3&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= | Remaining API bugs for 3.0]'''
+
= Porting from 3.8 to 3.9 =
  
== Migrating Data ==
+
== Mylyn Reviews ==
* Migration of LastReadTimeStamp
+
* Migration of date formats when using attribute mappers
+
* Migration of TaskData
+
  
== Plug-in Refactorings ==
+
The Reviews framework has had a major update which resulted in changes to the core model and API. In consequence, the version was updated to 2.0.
  
* <code>org.eclipse.mylyn.web.core</code> is now <code>org.eclipse.mylyn.commons.net</code>
+
= Porting from 3.7 to 3.8 =
* Core classes from <code>org.eclipse.mylyn.monitor.core</code> was split in order to make API not coupled to the Monitor component be reusable independently, now in the new <code>org.eclipse.mylyn.commons.core</code> plug-in.
+
* <code>org.eclipse.mylyn.commons.ui</code> is a new API for common UI components that are not coupled to the rest of Mylyn.
+
  
== Changed Extension Points ==
+
No API changes that affect integrators.
  
* <code>org.eclipse.mylyn.tasks.ui.editors</code>
+
= Porting from 3.6 to 3.7 =
** <code>hyperLinkDetector</code> has been removed, use <code>org.eclipse.ui.workbench.texteditor.hyperlinkDetectors</code> instead and set <code>targetId</code> to <code>org.eclipse.mylyn.tasks.ui.TaskEditor</code>
+
** <code>editorFactory</code> has been removed, use <code>pageFactory</code> instead
+
  
* <code>repositories</code>
+
== Mylyn Commons ==
** <code>taskListFactory</code> has been removed, use <code>taskListMirgrator</code> instead
+
** <code>connectorCore</code>
+
*** <code>userManaged</code> has been removed, override <code>isUserManaged()</code> in <code>AbstractRepositoryConnector</code> instead
+
** <code>connectorUi</code>
+
*** <code>customNotifications</code> has been removed, override <code>isCustomNotification()</code> in <code>AbstractRepositoryConnectorUi</code> instead
+
  
== Changed Team API ==
+
* {{bug|305782}} Restructuring of Mylyn Commons features
  
* <code>org.eclipse.mylyn.tasks.core.ILinkedTaskInfo</code> is now <code>org.eclipse.mylyn.team.ui.AbstractTaskReference</code>
+
The Mylyn Commons components were restructured and provisional packages were promoted to API. Several bundle IDs, package names and extension IDs were changed in the process. Classes in provisional packages were kept but marked as deprecated and will be removed in a future release. None of the changes break API backwards compatibility but integrations that consumed internal packages or extensions points may need to be adapted.
** <code>getComment()</code> has been renamed to <code>getText()</code>
+
  
== New Tasks API ==
+
The following bundles were renamed:
  
* <code>AbstractRenderingEngine</code> has been added for converting Wiki syntax to HTML
+
org.eclipse.mylyn.commons.identity      -> org.eclipse.mylyn.commons.identity.core
 +
org.eclipse.mylyn.commons.notifications -> org.eclipse.mylyn.commons.notifications.ui
 +
org.eclipse.mylyn.commons.repositories  -> org.eclipse.mylyn.commons.repositories.core
 +
org.eclipse.mylyn.commons.team          -> org.eclipse.mylyn.commons.repositories.ui
  
* <code>AbstractRepositoryQueryPage</code>
+
A complete list of renamed and added bundles can be found on bug 305782 on [https://bugs.eclipse.org/bugs/show_bug.cgi?id=305782#c13 comment 13].
** <code>setControlsEnabled(...)</code>: added - override to perform finer grain enablements if necessary
+
  
* <code>AbstractRepositoryTaskEditor</code> has been extended to provide HTML preview capabilities for repositories that support Wiki syntax in ticket descriptions and comments
+
The following packages were renamed:
  
== Removed Tasks API ==
+
org.eclipse.mylyn.commons.identity    -> org.eclipse.mylyn.commons.identity.core
 +
org.eclipse.mylyn.commons.repositories -> org.eclipse.mylyn.commons.repositories.core
 +
org.eclipse.mylyn.commons.ui.team      -> org.eclipse.mylyn.commons.repositories.ui
  
* <code>AbstractAttachmentHandler</code> has been deprecated, use <code>AbstractTaskAttachmentHandler</code> instead
+
The following provisional packages were promoted to API (see {{bug|360301}}):
** <code>MESSAGE_ATTACHMENTS_NOT_SUPPORTED</code> has been removed
+
** <code>MYLAR_CONTEXT_DESCRIPTION</code> has been removed
+
** <code>MYLAR_CONTEXT_DESCRIPTION_LEGACY</code> has been removed
+
** <code>MYLAR_CONTEXT_FILENAME</code> has been removed
+
** <code>attachContextAttachments()</code> has been moved to the internal class <code>AttachmentUtil</code>
+
** <code>getContextAttachments()</code> has been moved to the internal class <code>AttachmentUtil</code>
+
** <code>hasRepositoryContext()</code> has been moved to the internal class <code>AttachmentUtil</code>
+
** <code>retrieveContext()</code> has been moved to the internal class <code>AttachmentUtil</code>
+
  
* <code>AbstractAttributeFactory</code> has been deprecated, use <code>TaskAttributeMapper</code> instead
+
org.eclipse.mylyn.internal.provisional.commons.core        -> org.eclipse.mylyn.commons.core
 +
org.eclipse.mylyn.internal.provisional.commons.ui          -> org.eclipse.mylyn.commons.ui
 +
                                                            -> org.eclipse.mylyn.commons.workbench
 +
                                                            -> org.eclipse.mylyn.commons.workbench.browser
 +
                                                            -> org.eclipse.mylyn.commons.workbench.editors
 +
                                                            -> org.eclipse.mylyn.commons.workbench.forms
 +
                                                            -> org.eclipse.mylyn.commons.workbench.search
 +
org.eclipse.mylyn.internal.provisional.commons.ui.actions  -> org.eclipse.mylyn.commons.ui
 +
org.eclipse.mylyn.internal.provisional.commons.ui.commands -> org.eclipse.mylyn.commons.workbench.texteditor
 +
org.eclipse.mylyn.internal.provisional.commons.ui.dialogs  -> org.eclipse.mylyn.commons.ui.dialogs
 +
org.eclipse.mylyn.internal.provisional.commons.ui.editor  -> org.eclipse.mylyn.commons.workbench
  
* <code>AbstractDuplicateDetector</code> has been moved to tasks.core
+
In some cases provisional packages do not map directly to API packages but classes were distributed among several packages.
  
* <code>AbstractEditQueryWizard</code> has been renamed to <code>AbstractRepositoryQueryWizard</code>
+
The following extension points have moved:
  
* <code>AbstractNewRepositoryTaskEditor</code> has been deprecated, use <code>AbstractTaskEditorPage</code> instead
+
org.eclipse.mylyn.commons.team.newWizards -> org.eclipse.mylyn.commons.repositories.ui.newWizards
  
* <code>AbstractRepositoryConnector</code>
+
The following extension IDs have changed:
** All methods that used deprecated types have been moved to the internal class <code>AbstractLegacyRepositoryConnector</code>. Connectors that have not been ported to the new task data architecture may extend this class to continue using old APIs. Support for the old architecture may be '''removed at any time'''.
+
  
* <code>AbstractRepositoryConnectorUi</code>
+
org.eclipse.mylyn.commons.team.navigator.Repositories -> org.eclipse.mylyn.commons.repositories.ui.navigator.Repositories
** <code>getNewTaskWizard(TaskRepository)</code> has been removed, use <code>getNewTaskWizard(TaskRepository, ITaskMapping)</code> instead
+
org.eclipse.mylyn.commons.team.category              -> org.eclipse.mylyn.commons.repositories.ui.category.Team
** <code>getTaskKindLabel(RepositoryTaskData)</code> has been removed, use <code>getTaskKindLabel(AbstractTask)</code> instead
+
** <code>openEditQueryDialog(AbstractRepositoryQuery)</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>setCustomNotificationHandling()</code> has been removed, override <code>isCustomNotificationHandling()</code> instead
+
** <code>supportsDueDates(AbstractTask)</code> has been removed, override <code>AbstractRepositoryConnector.hasRepositoryDueDate()</code> instead
+
  
* <code>AbstractRepositoryQuery</code> has been deprecated, use <code>IRepositoryQuery</code> instead
+
= Porting from 3.0 to 3.6 =
** <code>getRepositoryKind()</code> has been renamed to <code>getConnectorKind()</code>
+
  
* <code>AbstractRepositoryQueryPage</code> has been moved to <code>org.eclipse.mylyn.tasks.ui.wizards</code>
+
See the <b>[[Mylyn/Porting Guide/3.x]]</b>
  
* <code>AbstractRepositoryTaskEditor</code> has been deprecated, use <code>AbstractTaskEditorPage</code> instead
+
= Porting from 2.0 to 3.0 =
  
* <code>AbstractRepositoryQueryWizard</code> has been removed, use <code>RepositoryQueryWizard</code> instead
+
See the <b>[[Mylyn/Porting Guide/3.0]]</b>
  
* <code>AbstractTask</code> has been deprecated, use <code>ITask</code> instead
 
** <code>hasValidUrl()</code> has been moved to <code>TasksUiInternal.isValidUrl()</code>
 
** <code>setCompleted()</code> has been removed, a non-null completion date indicates a task is complete
 
  
* <code>AttributeContainer</code> has been deprecated, use <code>TaskAttribute</code> instead
+
= Porting from 1.0 to 2.0 =
  
* <code>DatePicker</code> has been moved to <code>org.eclipse.mylyn.commons.ui</code>
+
See the <b>[[Mylyn Porting Guide 2.0]]</b>
 
+
* <code>DateSelectionDialog</code> has been moved to <code>org.eclipse.mylyn.commons.ui</code>
+
 
+
* <code>FileAttachment</code> has been deprecated, use <code>AbstractTaskAttachmentSource</code> instead
+
 
+
* <code>GzipGetMethod</code> has been moved to an internal package
+
 
+
* <code>GzipPostMethod</code> has been moved to an internal package
+
 
+
* <code>IStatusHandler</code> has been removed, use <code>AbstractErrorReporter</code> instead
+
 
+
* <code>ITaskCollector</code> has been deprecated, use <code>TaskDataCollector</code> instead
+
 
+
* <code>ITaskFactory</code> has been deprecated
+
 
+
* <code>NewTaskEditorInput</code> has been deprecated, use <code>TaskEditorInput</code> instead
+
 
+
* <code>QueryHitCollector</code> has been deprecated, use <code>TaskDataCollector</code> instead
+
 
+
* <code>RepositoryAttachment</code> has been deprecated, use <code>TaskAttachmentMapper</code> instead
+
 
+
* <code>RepositoryOperation</code> has been deprecated, use <code>TaskOperationMapper</code> instead
+
 
+
* <code>RepositorySearchResult</code> has been moved to an internal package
+
 
+
* <code>RepositoryTaskData</code> has been deprecated, use <code>TaskData</code> instead
+
 
+
* <code>RepositoryTaskEditorInput</code> has been deprecated, use <code>TaskEditorInput</code> instead
+
 
+
* <code>SearchHitCollector</code> has been moved to an internal package
+
 
+
* <code>SslProtocolSocketFactory</code> has been moved to an internal package
+
 
+
* <code>StatusHandler</code>
+
** <code>addDefaultStatusHandler(IStatusHandler)</code> has been removed
+
** <code>addStatusHandler(IStatusHandler)</code> has been removed
+
** <code>fail(Throwable,String,boolean)</code> has been removed
+
** <code>fail(Throwable,String,boolean,int)</code> has been removed
+
** <code>getDefaultStatusHandler()</code> has been removed
+
** <code>getStatusHandler()</code> has been removed
+
** <code>log(String,Object)</code> has been removed
+
** <code>log(Throwable,String)</code> has been removed
+
** <code>setDefaultStatusHandler(IStatusHandler)</code> has been removed
+
** <code>removeStatusHandler(IStatusHandler)</code> has been removed
+
 
+
* <code>TaskActivityManager</code>
+
** <code>getInstance()</code> has been removed, use <code>TasksUiPlugin.getTaskActivityManager()</code> instead
+
** <code>init()</code> has been replaced by a public constructor
+
 
+
* <code>TaskFormPage</code>
+
** <code>actionContributor</code> has been removed
+
 
+
* <code>TaskFactory</code> has been deprecated
+
 
+
* <code>TaskListManager</code> has been moved to an internal package and replaced by <code>ITaskListManager</code>
+
** task activity related methods have been removed (see <code>TaskActivityManager</code>)
+
 
+
* <code>TaskRepositoryManager</code> has been moved to an internal package and replaced by <code>ITaskRepositoryManager</code>
+
 
+
* <code>TaskEditor</code>
+
** <code>configureContextMenuManager(MenuManager,TextViewer)</code> has been removed
+
** <code>getAdapterDelegate()</code> has been removed
+
** <code>getContributor()</code> has been removed
+
 
+
* <code>TaskList</code> has been moved to an internal package and replaced by <code>ITaskList</code>
+
 
+
* <code>TaskSelection</code> has been deprecated, use <code>ITaskMapping</code> instead
+
 
+
* <code>TasksUiProxyChangeListener</code> has been removed
+
 
+
* <code>TasksUiUtil</code>
+
** <code>closeEditorInActivePage(ITask,boolean)</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>getActiveRepositoryTaskEditor()</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>isAnimationsEnabled()</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>openEditor(TaskCategory)</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>openEditor(AbstractTask, boolean)</code> has been replaced by <code>openTask(ITask)</code>
+
** <code>openEditor(AbstractTask, boolean, boolean)</code> has been replaced by <code>openTask(ITask)</code>
+
** <code>openEditor(AbstractTask, String)</code> has been replaced by <code>openTask(ITask)</code>
+
** <code>openUrl(String, boolean)</code> has been replaced by <code>openTask(String)</code> and <code>openUrl(String)</code>
+
** <code>refreshAndOpenTaskListElement()</code> has been moved to the internal class <code>TasksUiInternal</code>
+
** <code>showPreferencesPage(String, IPreferencePAge)</code> has been removed
+
 
+
* <code>TrustAllTrustManager</code> has been moved to an internal package
+
 
+
* <code>WebCorePlugin</code> has been moved to an internal package
+
 
+
== New Context API ==
+
 
+
* <code>AbstractFocusViewAction.updateEnablementWithContextActivation()</code>: override to return false for focus actions that are not related to context activations (e.g. the Task List).
+
 
+
* <code>AbstractFocusViewAction.setLinkingActionEnabled(boolean)</code>: should be overridden if view provides linking
+
 
+
== Removed Context API ==
+
 
+
* <code>IInteractionContextListener</code> was renamed to <code>AbstractContextListener</code>
+
* <code>BrowseFilteredAction</code> has been moved to an internal package
+
* <code>ContextCorePlugin</code> has been moved to an internal package and replaced by <code>ContextCore</code>
+
* <code>ContextUiPlugin</code> has been moved to an internal package and replaced by <code>ContextUi</code>
+
* <code>InteractionContextReader</code> has been moved to an internal package
+
* <code>InteractionContextWriter</code> has been moved to an internal package
+
* <code>MonitorUiPlugin</code> has been moved to an internal package and replaced by <code>MonitorUi</code>
+
* <code>ResourcesUiPlugin</code> has been moved to an internal package and replaced by <code>ResourcesUi</code>
+
 
+
== New Monitor API ==
+
 
+
* <code>MonitorUiPlugin.getMonitoredWindows()</code>: use insteand of <code>PlatformUI.getWorkbench().getWorkbenchWindows()</code>
+
* <code>MonitorUiPlugin.getLaunchingWorkbenchWindow()</code>: use to get the first active window when the monitor started.
+
 
+
== Removed Monitor API ==
+
 
+
* <code>IMylarMonitorLifecycleListener</code> has been renamed to <code>IMonitorLifecycleListener</code>
+
* <code>ReportGenerator</code> has been moved to an internal package
+
 
+
== Pending Changes ==
+
''This list is stale''.  Also see all source code tags titled "API-3.0"
+
* Refactor <code>TaskActivationHistory</code> into a <code>TaskActivityManager</code> that encapsulates both activity monitoring and activation history
+
* Merge ITaskActivityListener and ITaskActivityListner2
+
* Refactor ITaskActivityListener into ITaskActivationListener
+
* Move timing related methods to ITaskTimingListener
+
* Make <code>IMonitoredWindow</code> API and put alongside <code>IContextAwareEditor</code>
+
* Make API: <code>InteractionContextScaling</code>
+
* Add <code>InteractionContextScaling</code> parameter to <code>IInteractionContextReader.readContext(..)</code>
+
* Make a subset of <code>InteractionContextManager</code> API.
+

Revision as of 03:48, 6 September 2013


General

Mylyn follows the Eclipse conventions for version numbering and guarantees binary backwards compatibility for minor releases. Internals are binary backwards compatible between service releases.

API enhancements can be tracked by searching the source code for the corresponding @since JavaDoc tags or by querying for bugs that have [api] in their summary.

Pending API changes in 3.10

Porting from 3.8 to 3.9

Mylyn Reviews

The Reviews framework has had a major update which resulted in changes to the core model and API. In consequence, the version was updated to 2.0.

Porting from 3.7 to 3.8

No API changes that affect integrators.

Porting from 3.6 to 3.7

Mylyn Commons

  • bug 305782 Restructuring of Mylyn Commons features

The Mylyn Commons components were restructured and provisional packages were promoted to API. Several bundle IDs, package names and extension IDs were changed in the process. Classes in provisional packages were kept but marked as deprecated and will be removed in a future release. None of the changes break API backwards compatibility but integrations that consumed internal packages or extensions points may need to be adapted.

The following bundles were renamed:

org.eclipse.mylyn.commons.identity      -> org.eclipse.mylyn.commons.identity.core
org.eclipse.mylyn.commons.notifications -> org.eclipse.mylyn.commons.notifications.ui
org.eclipse.mylyn.commons.repositories  -> org.eclipse.mylyn.commons.repositories.core
org.eclipse.mylyn.commons.team          -> org.eclipse.mylyn.commons.repositories.ui

A complete list of renamed and added bundles can be found on bug 305782 on comment 13.

The following packages were renamed:

org.eclipse.mylyn.commons.identity     -> org.eclipse.mylyn.commons.identity.core
org.eclipse.mylyn.commons.repositories -> org.eclipse.mylyn.commons.repositories.core
org.eclipse.mylyn.commons.ui.team      -> org.eclipse.mylyn.commons.repositories.ui

The following provisional packages were promoted to API (see bug 360301):

org.eclipse.mylyn.internal.provisional.commons.core        -> org.eclipse.mylyn.commons.core
org.eclipse.mylyn.internal.provisional.commons.ui          -> org.eclipse.mylyn.commons.ui
                                                           -> org.eclipse.mylyn.commons.workbench
                                                           -> org.eclipse.mylyn.commons.workbench.browser
                                                           -> org.eclipse.mylyn.commons.workbench.editors
                                                           -> org.eclipse.mylyn.commons.workbench.forms
                                                           -> org.eclipse.mylyn.commons.workbench.search
org.eclipse.mylyn.internal.provisional.commons.ui.actions  -> org.eclipse.mylyn.commons.ui
org.eclipse.mylyn.internal.provisional.commons.ui.commands -> org.eclipse.mylyn.commons.workbench.texteditor
org.eclipse.mylyn.internal.provisional.commons.ui.dialogs  -> org.eclipse.mylyn.commons.ui.dialogs
org.eclipse.mylyn.internal.provisional.commons.ui.editor   -> org.eclipse.mylyn.commons.workbench

In some cases provisional packages do not map directly to API packages but classes were distributed among several packages.

The following extension points have moved:

org.eclipse.mylyn.commons.team.newWizards -> org.eclipse.mylyn.commons.repositories.ui.newWizards

The following extension IDs have changed:

org.eclipse.mylyn.commons.team.navigator.Repositories -> org.eclipse.mylyn.commons.repositories.ui.navigator.Repositories
org.eclipse.mylyn.commons.team.category               -> org.eclipse.mylyn.commons.repositories.ui.category.Team

Porting from 3.0 to 3.6

See the Mylyn/Porting Guide/3.x

Porting from 2.0 to 3.0

See the Mylyn/Porting Guide/3.0


Porting from 1.0 to 2.0

See the Mylyn Porting Guide 2.0