Splitting org.eclipse.ui

["Kai-Uwe Maetzel" <Kai-Uwe_Maetzel@xxxxxxx>]

Attached please find a document describing the details of splitting
org.eclipse.ui into several plug-ins and fragments.  We want to start with
the split as soon as the build submission for tomorrow's integration build
is done. This will be tomorrow morning ZRH time.  Please release all
changes you want to have preserved and don't release any code to
org.eclipse.ui after the build submission until the transition to the new
structure is complete. I'll send out a message as soon as we are done.
Please notice that splitting org.eclipse.ui is work in progress even beyond
this initial transition. Future changes should be less disruptive.  Clients
of the current version of org.eclipse.ui are not affected.

Kai

(See attached file: Description.html)

Title: Plug-in Separation Notes

Splitting org.eclipse.ui

Kai-Uwe Maetzel, Daniel Megert

Overview

This documents describes how the plug-in org.eclipse.ui
is split into a combination of plug-ins and fragments. There are three
major reasons for splitting the plug-in:

• introduce a UI independent text infrastructure
• decouple the build processes of Platform Text and Platform UI
• prepare Platform UI to achieve the following midterm goals:
• using SWT/JFace for building Eclipse independent applications
• free the workbench from dependencies from IResource
• provide the IResource dependent standard components of the workbench as a separate plug-in

State of Splitting

The new structure is not yet final. It is a starting point for the Platform
UI team and the Platform Text team to evolve the system towards a stable
and mature structure. It is expected that the number of plug-ins and fragments
can be kept stable whereas package fragments and classes will probably
be moved around. For now, the UI independent text infrastructure (org.eclipse.text) should
be considered the only new plug-in that can be listed as prerequisite and
that offers API. The other plug-ins and fragments are for now implementation
details of org.eclipse.ui. This will change as the structure becomes
more stable i.e. some of the new plug-ins will become API.

Structure

Splitting as been guided by the approach to consider
plug-ins as packaging units and therefore to use plug-ins only when an according
packaging can be anticipated. Thus, classes that are expected to be shipped 
together should not be in different plug-ins. This approach keeps the class
loading overhead caused by the splitting lower than putting every possible
unit into its own plug-in. Classes of a plug-in and its fragments are loaded
by the same class loader. Taking this approach we end up having six plug-ins
and two fragments.

• org.eclipse.text (owned by Platform Text)
• contains the UI independent text infrastructure, i.e., IDocument and its satellites
• no prerequisites
• org.eclipse.jface (owned by Platform UI)
• contains everything of JFace that does not depend on IProgressMonitor and IStatus
• plugin.xml requires:
• org.apache.xerces
• org.eclipse.core.resources
• org.eclipse.swt (needs to be exported)
  
• build path dependencies:
  
• org.apache.xerces
• org.eclipse.swt
• org.eclipse.jface.text (Fragment of org.eclipse.jface owned by Platform Text)
• contains the UI part of the text infrastructure, i.e. TextViewer and its satellites
• needs to be further cleaned up to remove any dependency on IProgressMonitor
• plugin.xml requires:
• org.eclipse.text
  
• buildpath dependencies:
• org.eclipse.jface
  
• org.eclipse.text
• org.eclipse.core.runtime
• org.eclipse.ui.workbench (owned by Platform UI)
• contains Workbench UI framework and the "empty" workbench
• plugin.xml requires:
• org.apache.xerces
• org.eclipse.core.resources
• org.eclipse.update.core
• org.eclipse.help
• org.eclipse.swt
• org.eclipse.jface
  
• build path dependencies:
  
• org.apache.xerces
• org.eclipse.core.boot
• org.eclipse.core.runtime
• org.eclipse.core.resources
• org.eclipse.update.core
• org.eclipse.help
• org.eclipse.swt
• org.eclipse.jface
• org.eclipse.jface.text
  
• org.eclipse.ui.workbench.texteditor (Fragment of org.eclipse.workbench owned by Platform Text)
• contains the text editor framework except three TaskList dependent actions
• plugin.xml requires:
• org.eclipse.text
• build path dependencies:
  
• org.eclipse.ui.workbench
• org.eclipse.jface
• org.eclipse.jface.text
• org.eclipse.text
• org.eclipse.core.runtime
• org.eclipse.core.resources
• org.eclipse.ui.views (owned by Platform UI)
• contains all the standard view like Navigator and Task List
• plugin.xml requires:
• org.eclipse.core.resources
• org.eclipse.help
• org.eclipse.swt
• org.eclipse.jface
• org.eclipse.ui.workbench
  
• build path dependencies:
  
• org.eclipse.core.resources
• org.eclipse.core.runtime
• org.eclipse.help
• org.eclipse.jface
• org.eclipse.ui.workbench
• org.eclipse.ui.editors (owned by Platform Text)
• contains the default text editor plus a few common but Task List dependent actions
• plugin.xml requires:
• org.eclipse.ui.views
• org.eclipse.ui.workbench
• org.eclipse.jface
  
• org.eclipse.core.resources
• org.eclipse.text
• org.eclipse.update.core
  
• build path dependencies:
  
• org.eclipse.ui.views
• org.eclipse.ui.workbench
• org.eclipse.ui.workbench.texteditor
• org.eclipse.core.resources
• org.eclipse.core.runtime
• org.eclipse.core.boot
  
• org.eclipse.jface
• org.eclipse.jface.text
• org.eclipse.text
• org.eclipse.update.core
  
• org.eclipse.ui (owned by Platform UI)
• ensures backward compatibility
• defines all extension points and contributions
• build path dependencies:
  
• requires and exports all of the above components
• org.eclipse.swt (needs to be exported)
• org.eclipse.core.runtime
  

Required Changes

• The Workbench plug-in contains a SystemSummaryEditor which depends on editor. To fix this the system summary editor and  its content provider have been moved to the org.eclipse.ui.editors plug-in while the SystemSummaryEditorInput and the SystemSummaryEditorInputFactory go to the org.eclipse.ui.workbench plug-in. The system summary editor ID ("org.eclipse.ui.SystemSummaryEditor") used in Workbench.openSystemSummaryEditor() must be declared inside Workbench. In addition this method should show a dialog if the editor for this ID can not be found.
• Some CUs have unused imports which cause errors. Removing the unused imports solves this problem.
• The wizards have to be moved from standard components to the org.eclipse.workbench plug-in. The resulting org.eclipse.views plug-in only contains views.
• The ResourceSorter must be copied from the navigator package to the dialogs package in org.eclipse.views. This is  needed to break the link from org.eclipse.ui.workbench to org.eclipse.ui.views. Having a navigator package in the workbench plug-in is no option.
• The visibility of several classes had to be changed from package visible to public because of the resulting package fragments scattered over different plug-ins. Examples are:
• org.eclipse.ui.internal.PlatformUIPreferenceListener
• org.eclipse.jface.text.TextUtilities
• all fields of org.eclipse.jface.text.DocumentEvent
• org.eclipse.jface.text.DefaultLineTracker had to be changed to not use SWT constants
• The text editor framework of org.eclipse.ui.workbench.texteditor may not depend on a view such as the task list. The package must be split and the task list dependent part goes into the org.eclipse.ui.editors plug-in. NLSing has to be split as well.

The following changes need to be made in order to get a JFace framework
which only depends on SWT:

• move progress monitor code to org.eclipse.ui.workbench:
• move wizard package to org.eclipse.ui.workbench (due to IProgressMonitor)
• move operation package to org.eclipse.ui.workbench (due to IProgressMonitor)
• move org.eclipse.jface.window.ApplicationWindow to org.eclipse.ui.workbench (due to IStatus and NullProgressMonitor)
• move org.eclipse.jface.util.SafeRunnable to org.eclipse.workbench (due to ISafeRunnable)
• move org.eclipse.jface.dialogs.ErrorDialog to org.eclipse.workbench (due to IStatus)

Note: There remains a dependency to Xcerces due to org.eclipse.jface.dialogs.DialogSettings.

Open Issues

• Workbench.openSystemSummaryEditor() use a predefined editor id for the system summary editor. The SystemSummaryEditor registers itself under this id. This introduces an implicit upward reference.
• Because some calls can't be redirected due to their final declaration corresponding stored preferences might get lost .
• The source folder names are preserved. In the future a source folder can be renamed to "src" if it is the only one in the project.
• Icons are duplicated in org.eclipse.ui.workbench and org.eclipse.ui
• The plugin.xml of org.eclipse.ui contains all contributions and extension points.. Because of the implicit prefixing of extension point declarations these cannot be moved easily .
• org.eclipse.ui.workbench is "cluttered" with actions and menus that would more naturally belong to views. Moving those actions has not been investigated.
• AbstractTextEditor does no longer preregister the "Add Task" action
• The reconciler code in org.eclipse.jface.text needs to be freed from its dependency of IProgressMonitor. Until then it depends on org.eclipse.core.runtime.
• The dependencies on IProgressMonitor, IStatus and ISafeRunnable cause the need for splitting JFace and JFace Text: offending code has been moved to org.eclipse.ui.workbench/JFace Extensions. It would also be possible to either accept a dependency on org.eclipse.core.runtime or to move those classes into a separate plug-in.

Consequences

The consequences of this new structure are mostly visible in the build
process and the workspace setup. It is necessary to update all plug-ins and fragments in the
map files with the correct version numbers. The build process responsibility
is distributed according to the ownership of the plug-ins and fragments.