platform-text/development/splitting/PrereleaseNote.html

<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"><html><head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.76 [en] (Windows NT 5.0; U) [Netscape]"><title>Plug-in Separation Notes</title></head><body>

<center>
<h1>
Splitting org.eclipse.ui</h1></center>

<center>
  <address> Kai-Uwe Maetzel, Daniel Megert</address>
  <address>23th September 2002</address>
  <address></address>
</center>

<h3>
Overview</h3>
This documents describes how the plug-in <tt>org.eclipse.ui</tt>
is split into a combination of plug-ins and fragments. There are three
major reasons for splitting the plug-in:
<ul>
<li>
introduce a UI independent text infrastructure</li>

<li>
decouple the build processes of Platform Text and Platform UI</li>

<li>
prepare Platform UI to achieve the following midterm goals:</li>

<ul>
<li>
using SWT/JFace for building Eclipse independent applications</li>

<li>
free the workbench from dependencies from IResource</li>

<li>
provide the IResource dependent standard components of the workbench as
a separate plug-in</li>
</ul>
</ul>

<h3>
State of Splitting</h3>
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 <tt>org.eclipse.ui</tt>. This will change as the structure becomes
more stable i.e. some of the new plug-ins will become API.
<h3>
Structure</h3>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&nbsp;
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.<ul>
<li>
<b>org.eclipse.text (owned by Platform Text)</b></li>

<ul>
<li>
contains the UI independent text infrastructure, i.e., IDocument and its satellites</li>

<li>
no prerequisites</li>
</ul>

<li>
<b>org.eclipse.jface (owned by Platform UI)</b></li>

<ul>
<li>
contains everything of JFace that does not depend on IProgressMonitor and
IStatus</li>

    <li>plugin.xml requires:</li>
    <ul>
      <li>org.apache.xerces</li>
      
      <li>org.eclipse.swt (needs to be exported)<br>
      </li>
    </ul>
    <li>
build path dependencies:<br>
    </li>


<ul>
<li>
org.apache.xerces</li>

<li>
org.eclipse.swt&nbsp;(needs to be exported)</li>
</ul>
</ul>

<li>
<b>org.eclipse.jface.text (Fragment of org.eclipse.jface owned by Platform
Text)</b></li>

<ul>
<li>
contains the UI part of the text infrastructure, i.e. TextViewer and its satellites</li>

<li>
needs to be further cleaned up to remove any dependency on <tt>IProgressMonitor</tt></li><li>plugin.xml requires:</li>
    <ul>
      <li>org.eclipse.text<br>
      </li>
    </ul>


<li>buildpath dependencies:</li>

<ul>
<li>org.eclipse.jface<br>
</li><li>
org.eclipse.text</li>


<li>
org.eclipse.core.runtime</li>
</ul>
</ul>

<li>
<b>org.eclipse.ui.workbench (owned by Platform UI)</b></li>

<ul>
<li>
contains Workbench UI framework and the "empty" workbench</li>

    <li>plugin.xml requires:</li>
    <ul>
      <li>org.apache.xerces</li>
      <li>org.eclipse.core.resources</li>
      <li>org.eclipse.update.core</li>
      <li>org.eclipse.help</li>
      
      <li>org.eclipse.jface<br>
      </li>
    </ul>
    <li>
build path dependencies:<br>
    </li>


<ul>
<li>
org.apache.xerces</li>

      <li>
org.eclipse.core.boot</li>
      <li>
org.eclipse.core.runtime</li>


<li>
org.eclipse.core.resources</li>

<li>
org.eclipse.update.core</li>

<li>
org.eclipse.help</li>



      <li>
org.eclipse.jface</li>
      <li>org.eclipse.jface.text<br>
      </li>

</ul>
</ul>

<li>
<b>org.eclipse.ui.workbench.texteditor (Fragment of org.eclipse.workbench
owned by Platform Text)</b></li>

<ul>
<li>
contains the text editor framework except three TaskList dependent actions</li><li>plugin.xml requires:</li>
    <ul>
      <li>
org.eclipse.text</li>
    </ul>


    <li>
build path dependencies:<br>
    </li>


<ul>
<li>
org.eclipse.ui.workbench</li>

<li>
org.eclipse.jface</li>

<li>
org.eclipse.jface.text</li>



<li>
org.eclipse.text</li>

<li>
org.eclipse.core.runtime</li>

<li>
org.eclipse.core.resources</li>
</ul>
</ul>

<li>
<b>org.eclipse.ui.views (owned by Platform UI)</b></li>

<ul>
<li>
contains all the standard view like Navigator and Task List</li><li>plugin.xml requires:</li>
    <ul>
      <li>org.eclipse.core.resources</li>
      <li>org.eclipse.help</li>
      
      <li>org.eclipse.jface</li>
      <li>org.eclipse.ui.workbench<br>
      </li>
    </ul>


    <li>
build path dependencies:<br>
    </li>


<ul>
<li>
org.eclipse.core.resources</li>

<li>
org.eclipse.core.runtime</li>

<li>
org.eclipse.help</li>

<li>
org.eclipse.jface</li>

<li>
org.eclipse.ui.workbench</li>
</ul>
</ul>

<li>
<b>org.eclipse.ui.editors (owned by Platform Text)</b></li>

<ul>
<li>
contains the default text editor plus a few common but Task List dependent
actions</li><li>plugin.xml requires:</li>
    <ul>
      <li>org.eclipse.ui.views</li>
      <li>org.eclipse.ui.workbench</li>
      <li>org.eclipse.jface<br>
      </li>
      <li>org.eclipse.core.resources</li>
      <li>org.eclipse.text</li>
      <li>org.eclipse.update.core<br>
      </li>
    </ul>


    <li>
build path dependencies:<br>
    </li>


<ul>
      <li>
org.eclipse.ui.views</li>
      <li>
org.eclipse.ui.workbench</li>
      <li>
org.eclipse.ui.workbench.texteditor</li>


<li>
org.eclipse.core.resources</li>

<li>
org.eclipse.core.runtime</li><li>org.eclipse.core.boot<br>
      </li>


<li>
org.eclipse.jface</li>

<li>
org.eclipse.jface.text</li>

<li>
org.eclipse.text</li><li>org.eclipse.update.core<br>
      </li>

</ul>
</ul>

<li>
<b>org.eclipse.ui (owned by Platform UI)</b></li>

<ul>
<li>
ensures backward compatibility</li>

<li>
defines all extension points and contributions</li>

    <li>
build path dependencies:<br>
    </li>
    <ul>
      <li>
requires and <i>exports</i> all of the above components</li>
      <li>org.eclipse.swt (needs to be exported in build path and plugin.xml)</li>
      <li>org.eclipse.core.runtime<br>
      </li>
    </ul>

</ul>
</ul>

<h3>
Required Changes</h3>

<ul>
<li>
The Workbench plug-in contains a <tt>SystemSummaryEditor</tt><i> </i>which
depends on editor. To fix this the system summary editor and&nbsp; its
content provider have been moved to the <b>org.eclipse.ui.editors </b>plug-in
while the <tt>SystemSummaryEditorInput</tt> and the <tt>SystemSummaryEditorInputFactory</tt>
go to the <b>org.eclipse.ui.workbench</b> plug-in. The system summary editor
ID ("<tt>org.eclipse.ui.SystemSummaryEditor</tt>") used in <tt>Workbench.openSystemSummaryEditor()</tt>
must be declared inside <tt>Workbench.
</tt>In addition this method should
show a dialog if the editor for this ID can not be found.</li>

<li>
Some CUs have unused imports which cause errors. Removing the unused imports
solves this problem.</li>

<li>
The wizards have to be moved from standard components to the <b>org.eclipse.workbench</b>
plug-in. The resulting <b>org.eclipse.views</b> plug-in only contains views.</li>

<li>
The <tt>ResourceSorter</tt> must be <i>copied</i> from the navigator package
to the dialogs package in <b>org.eclipse.views</b>. This is&nbsp; needed
to break the link from <b>org.eclipse.ui.workbench</b> to <b>org.eclipse.ui.views.</b>
Having a navigator package in the workbench plug-in is no option.</li>

<li>
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:</li>

<ul>
<li>
<tt>org.eclipse.ui.internal.PlatformUIPreferenceListener</tt></li>

<li>
<tt>org.eclipse.jface.text.TextUtilities</tt></li>

<li>
all fields of <tt>org.eclipse.jface.text.DocumentEvent</tt></li>
</ul>

<li>
<tt>org.eclipse.jface.text.DefaultLineTracker </tt>had to be changed to
not use SWT constants</li>

<li>
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 <b>org.eclipse.ui.editors</b> plug-in. NLSing has to be split as well.</li>
</ul>
The following changes need to be made in order to get a JFace framework
which only depends on SWT:
<ul>
<li>
move progress monitor code to <b>org.eclipse.ui.workbench</b>:</li>

<ul>
<li>
move <i><tt>wizard</tt> package</i> to <b>org.eclipse.ui.workbench</b>
(due to <tt>IProgressMonitor</tt>)</li>
</ul>

<ul>
<li>
move <i><tt>operation</tt> package</i> to <b>org.eclipse.ui.workbench</b>
(due to <tt>IProgressMonitor</tt>)</li>
</ul>

<ul>
<li>
move <i><tt>org.eclipse.jface.window.ApplicationWindow</tt></i> to <b>org.eclipse.ui.workbench</b>
(due to <tt>IStatus</tt> and <tt>NullProgressMonitor</tt>)</li>
</ul>

<li>
move <i><tt>org.eclipse.jface.util.SafeRunnable</tt></i> to <b>org.eclipse.workbench</b>
(due to <tt>ISafeRunnable</tt>)</li>

<li>
move <i><tt>org.eclipse.jface.dialogs.ErrorDialog</tt></i> to <b>org.eclipse.workbench</b>
(due to <tt>IStatus</tt>)</li>
</ul>
Note: There remains a dependency to <b>Xcerces</b> due to <i><tt>org.eclipse.jface.dialogs.DialogSettings</tt></i>.
<br>&nbsp;
<h3>
Open Issues</h3>

<ul>
<li>
<tt>Workbench.openSystemSummaryEditor()</tt> use a predefined editor id
for the system summary editor. The <tt>SystemSummaryEditor</tt> registers
itself under this id. This introduces an implicit upward reference.</li>

<li>
Because some calls
can't be redirected due to their <i>final</i> declaration corresponding <i>stored preferences</i> might get lost .</li>

<li>
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.</li>

<li>
<i>Icons are duplicated</i> in <b>org.eclipse.ui.workbench</b> and <b>org.eclipse.ui</b></li>

<li>
The <tt>plugin.xml</tt> of <b>org.eclipse.ui<i> </i></b><i>contains all
contributions and extension points.</i>. Because of the implicit prefixing
of extension point declarations these cannot be moved easily .</li>

<li>
<b>org.eclipse.ui.workbench</b> is "cluttered" with actions
and menus that would more naturally belong to views. Moving those
actions has not been investigated.</li>

<li>
<tt>AbstractTextEditor</tt> does no longer preregister the "Add Task" action</li>

<li>
The reconciler code in <tt>org.eclipse.jface.text</tt> needs to be freed
from its dependency of <tt>IProgressMonitor. </tt>Until then it depends on <code>org.eclipse.core.runtime</code>.</li>

<li>
The dependencies on <tt>IProgressMonitor</tt>, <tt>IStatus</tt> and <tt>ISafeRunnable</tt>
cause the need for splitting JFace and JFace Text: offending code has been moved to <code>org.eclipse.ui.workbench/JFace Extensions</code>. It would also be possible
to either accept a dependency on <b>org.eclipse.core.runtime</b> or to
move those classes into a separate plug-in.</li>
</ul>

<h3>
Consequences</h3>
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.
<br>&nbsp;<br>
<br>
</body></html>