org.eclipse.platform.doc.isv/porting/3.0/faq.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.7 - (view) (download) (as text)

1 : johna 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 :     <html>
3 :    
4 :     <head>
5 : tod 1.4
6 :     <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
7 : tod 1.3
8 : johna 1.1 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
9 :     <meta http-equiv="Content-Style-Type" content="text/css">
10 : mvalenta 1.5 <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
11 : johna 1.1 <title>Eclipse 3.0 Plug-in Migration FAQ</title>
12 :     </head>
13 :    
14 :     <body>
15 :    
16 :     <h1>Eclipse 3.0 Plug-in Migration FAQ</h1>
17 : dmegert 1.6
18 :     <p><b>Why did Eclipse API change in incompatible ways between 2.1 and 3.0?</b></p>
19 : johna 1.1 <p>Eclipse 3.0 is an evolution of Eclipse 2.1. There were a few areas where we
20 :     could not evolve Eclipse while maintaining perfect compatibility across the
21 :     board. The four main sources of incompatibilities are:</p>
22 :     <ul>
23 :     <li>The Eclipse 3.0 runtime is now based on OSGi.</li>
24 :     <li>The Eclipse 3.0 UI workbench is now split into RCP and IDE parts.</li>
25 :     <li>The Xerces plug-in has been dropped from 3.0.</li>
26 :     <li>Eclipse 3.0 performs more work in background threads.</li>
27 :     </ul>
28 :     <p>The list of specific <a href="incompatibilities.html"> incompatibilities</a>.</p>
29 :     <p><b>Will a 2.1 plug-in work in Eclipse 3.0?</b></p>
30 :     <p>Yes, except in a few cases. If a plug-in relies only on Eclipse 2.1 APIs, then it will continue to work in
31 :     3.0. The very few exceptions are places in the API where the changes between 2.1
32 :     and 3.0 could not be done in any compatible way; if a plug-in uses one of these, it will not
33 :     work.</p>
34 :     <p><b>My 2.1 plug-in makes use of classes in internal packages. Will it still work in Eclipse 3.0?</b></p>
35 :     <p>If a plug-in relies on internal classes or behavior not specified in
36 :     the Eclipse 2.1 API, it's impossible to make blanket claims one way or the other
37 :     about whether the plug-in might work in 3.0. You'll need to try it.</p>
38 :     <p><b>How do I run my plug-in in Eclipse 3.0 without touching it?</b></p>
39 :     <p>Install your 2.1 plug-in in the eclipse/plugins/ subdirectory of an Eclipse
40 :     3.0-based product and restart Eclipse. Eclipse will recognize that the plug-in
41 :     is an unconverted 2.1 plug-in (by the header on the plugin.xml) and
42 :     automatically make adjustments to compensate for changes to Platform plug-in
43 :     dependencies and renamed Platform extension points.</p>
44 :     <p><b>Will a 2.1 plug-ins need to be changed to compile properly in Eclipse 3.0?</b></p>
45 :     <p>Yes in all cases. There are certain differences between Eclipse 2.1 and 3.0 that
46 :     necessitate changes to all plug-ins going forward. If you have a plug-in written
47 :     for 2.1 and wish to recompile it, it needs to be migrated to 3.0 before it can be developed further
48 :     for 3.0.</p>
49 :     <p><b>How do I migrate my plug-in to Eclipse 3.0?</b></p>
50 :     <p>Once you've loaded (or imported) your plug-in project into an Eclipse 3.0
51 :     workspace, use <b>PDE
52 :     Tools &gt; Migrate to 3.0</b> (project context menu) to convert the plug-in's manifest to the 3.0
53 :     format and automatically adjust the list of required Platform plug-ins and
54 :     references to Platform extension points that were renamed. In most cases, the code for the
55 :     plug-in should then compile and run successfully. The code for the plug-in
56 :     should then be reviewed to make sure that it is not dependent on one of the
57 :     areas of incompatible API change.</p>
58 :     <p><b>Can I trust that a plug-in will have compile errors or warnings if it relies on API
59 :     that has changed incompatibly?</b></p>
60 :     <p>No. There are some areas of incompatible change that do not get flagged by
61 :     the Java compiler.</p>
62 :     <p><b>Can I safely ignore warnings in the code coming from use of deprecated
63 :     API?</b></p>
64 :     <p>Yes, in the short term. Wherever possible, obsolete APIs are marked as
65 :     deprecated rather than being deleted outright and continue to work (albeit
66 :     possibly only under limited conditions). So while there is usually no urgency to
67 :     get off the deprecated API, the fact that it is now considered obsolete means
68 :     that there is now a better way to do something. Plug-ins should be weaned off
69 :     all usage to deprecated API at the earliest convenience.</p>
70 :     <p><b>Once I migrate my plug-in to Eclipse 3.0, can I still install and run the
71 :     resulting binary plug-in in Eclipse 2.1?</b></p>
72 :     <p>No. This is not supported, and probably wouldn't work due to the renamed
73 :     extension points.</p>
74 :     <p><b>What is the purpose of org.eclipse.core.runtime.compatibility?</b></p>
75 :     <p>The move in 3.0 to an OSGi-base runtime made some of the existing core
76 :     runtime APIs obsolete. Wherever possible, obsolete APIs in the
77 :     org.eclipse.core.runtime.* packages, along with the implementation behind it,
78 :     were moved from the org.eclipse.core.runtime plug-in to a new
79 :     org.eclipse.core.runtime.compatibility plug-in. By default, newly-created
80 :     plug-ins depend on org.eclipse.core.runtime and are expected to use only
81 :     non-deprecated runtime APIs. On the other hand, existing plug-ins migrating from
82 :     2.1 will depend by default on org.eclipse.core.runtime.compatibility and can
83 :     make use of the old APIs as well (the org.eclipse.core.runtime.compatibility
84 :     plug-in re-exports APIs of org.eclipse.core.runtime). While the
85 :     org.eclipse.core.runtime.compatibility plug-in is likely to be included in
86 :     Eclipse IDE configurations, it's dead wood that's unlikely to be included in
87 :     products based on RCP configurations.</p>
88 :     <p><b>What is the purpose of org.eclipse.ui.workbench.compatibility?</b></p>
89 :     <p>org.eclipse.ui.workbench.compatibility is a plug-in fragment that provides
90 :     enhanced binary compatibility for 2.1 plug-ins being run in an Eclipse 3.0-based
91 :     product. In 3.0, six methods with an explicit dependence on IFile or IMarker
92 :     were moved from the org.eclipse.ui.IWorkbenchPage interface in order to cleanly
93 :     separate the workbench from workspace and resources. The
94 :     org.eclipse.ui.workbench.compatibility fragment arranges to add back these
95 :     methods so that existing 2.1 plug-ins can run without modification. Note,
96 :     however, that plug-ins being migrated to 3.0 that reference the moved methods
97 :     will see compile errors that can (only) be resolved by calling the replacement
98 :     methods now located on org.eclipse.ui.ide.IDE.</p>
99 :     <p>The IWorkbenchPage methods in question are: openEditor(IFile),
100 :     openEditor(IFile, String), openEditor(IFile, String, boolean),
101 :     openEditor(IMarker), openEditor(IMarker, boolean), and openSystemEditor(IFile).</p>
102 :    
103 : tod 1.3
104 : johna 1.1
105 :     </body>
106 :    
107 :     </html>