org.eclipse.platform.doc.isv/porting/3.2/incompatibilities.html

Parent Directory Parent Directory | Revision Log Revision Log

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

1 : jeem 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 :     <html>
3 :    
4 :     <head>
5 :    
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 :    
8 :     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
9 :     <meta http-equiv="Content-Style-Type" content="text/css">
10 :     <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css">
11 :     <title>Incompatibilities between Eclipse 3.1 and 3.2</title>
12 :     </head>
13 :    
14 :     <body>
15 :    
16 :     <h1>Incompatibilities between Eclipse 3.1 and 3.2</h1>
17 :    
18 :     <p> Eclipse changed in incompatible ways between 3.1 and 3.2 in ways that affect
19 :     plug-ins. The following entries describe the areas that changed and provide
20 :     instructions for migrating 3.1 plug-ins to 3.2. Note that you only need to look
21 :     here if you are experiencing problems running your 3.1 plug-in on 3.2.</p>
22 : darin 1.2 <ol>
23 : johna 1.4 <li><a href="#nonLocalResources">Resources are no longer necessarily in the local file system</a></li>
24 : dpollock 1.7 <li><a href="#MultiPageEditorSiteProgress">API changes to MultiPageEditorSite</a></li>
25 : prapicau 1.9 <li><a href="#configIni">Content changes in config.ini</a></li>
26 :     <li><a href="#jwsConfigIni">Content changes in jnlp deployed applications</a></li>
27 : dj 1.13 <li><a href="#bundleStart">Explicit calls to Bundle.start() force the bundle to be activated on next restart</a></li>
28 : dmegert 1.18 <li><a href="#pluginVersion">Underscore no longer replaced by hyphen in plug-ins version numbers</a></li>
29 : darin 1.2 </ol>
30 :     <hr>
31 : johna 1.4
32 : johna 1.5 <!-- ############################################## -->
33 : darin 1.14 <h2>1. <a name="nonLocalResources"></a>Resources are no longer necessarily in
34 :     the local file system</h2>
35 : johna 1.4 <p><strong>What is affected:</strong>Clients of the <code>IWorkspace</code> API
36 : johna 1.6 that assume resources are stored in the local file system.</p>
37 :     <p><strong>Description:</strong>
38 : johna 1.4 Prior to Eclipse 3.2, each existing <code>IResource</code> had a corresponding
39 : johna 1.6 file or directory in a file system accessible by <code>java.io.File</code>. In
40 :     Eclipse 3.2, support was added for creating resources whose contents are stored
41 :     in an arbitrary backing file system. Resources using this support can no longer
42 :     be represented directly as a <tt>java.io.File</tt>.
43 :     </p>
44 :     <p><strong>Action required:</strong>
45 : johna 1.4 The old method <tt>IResource.getLocation()</tt> returns the local file
46 :     system path of a resource. This method returns null for resources
47 :     that are not stored in the local file system. Most callers of <tt>getLocation()</tt>
48 :     did so in order to obtain an instance of <tt>java.io.File</tt>, which can
49 :     no longer be used for resources that are not stored in the local file system.
50 :     </p>
51 :     <p>
52 : johna 1.16 The new <tt>org.eclipse.core.filesystem</tt> plug-in provides a generic file
53 : johna 1.4 system API that can be used in place of <tt>java.io.File</tt>. In particular,
54 :     an instance of <tt>org.eclipse.core.filesystem.IFileStore</tt> provides most
55 :     of the same methods that are available on <tt>java.io.File</tt>. The following
56 : johna 1.11 snippet of code obtains an instance of <tt>IFileStore</tt> for a given resource:</p>
57 : johna 1.4 <pre>
58 :     IResource resource = ...;//some resource
59 :     IFileStore store = EFS.getStore(resource.getLocationURI());
60 :     </pre>
61 :     <p>
62 :     The following table provides equivalent methods on <tt>IFileStore</tt>
63 :     for operations usually done with <tt>java.io.File</tt>:
64 :     </p>
65 :     <table border=1>
66 : johna 1.11 <tr>
67 : johna 1.4 <th align=left>java.io.File</th><th align=left>IFileStore</th>
68 : johna 1.11 </tr>
69 : johna 1.4 <tr><td>delete</td><td>delete</td></tr>
70 :     <tr><td>getName</td><td>getName</td></tr>
71 :     <tr><td>getParent</td><td>getParent</td></tr>
72 :     <tr><td>list</td><td>childNames</td></tr>
73 :     <tr><td>mkdir</td><td>mkdir(EFS.SHALLOW, null)</td></tr>
74 :     <tr><td>mkdirs</td><td>mkdir(EFS.NONE, null)</td></tr>
75 :     <tr><td>renameTo</td><td>move</td></tr>
76 :     <tr><td>new FileInputStream(file)</td><td>openInputStream</td></tr>
77 :     <tr><td>new FileOutputStream(file)</td><td>openOutputStream</td></tr>
78 :     </table>
79 :     <p>
80 :     In the <tt>IFileStore</tt> API, most information about a file is stored in a
81 :     structure called <tt>IFileInfo</tt>, obtained by calling <tt>IFileStore.fetchInfo()</tt>.
82 :     This design allows for greater optimization over code using <tt>java.io.File</tt>,
83 :     because many attributes about a file can often be obtained with a single file system
84 :     call. Note that the information in an <tt>IFileInfo</tt> will become stale
85 :     if the underlying file is changed, so instances should only be held onto
86 :     as long as they are needed. Here are some methods on <tt>java.io.File</tt>
87 :     that have equivalent methods on <tt>IFileInfo</tt>:
88 :     </p>
89 :     <table border=1>
90 : johna 1.11 <tr><th align=left>java.io.File</th><th align=left>IFileInfo</th></tr>
91 : johna 1.20 <tr><td>canWrite</td><td>getAttribute(EFS.ATTRIBUTE_READ_ONLY)</td></tr>
92 :     <tr><td>exists</td><td>exists()</td></tr>
93 :     <tr><td>getName</td><td>getName()</td></tr>
94 :     <tr><td>isDirectory</td><td>isDirectory()</td></tr>
95 : johna 1.4 <tr><td>isFile</td><td>!isDirectory()</td></tr>
96 : johna 1.20 <tr><td>isHidden</td><td>getAttribute(EFS.ATTRIBUTE_HIDDEN)</td></tr>
97 :     <tr><td>lastModified</td><td>getLastModified()</td></tr>
98 :     <tr><td>length</td><td>getLength()</td></tr>
99 :     <tr><td>setLastModified</td><td>setLastModified(long)</td></tr>
100 : johna 1.4 <tr><td>setReadOnly</td><td>setAttribute(EFS.ATTRIBUTE_READ_ONLY, true)</td></tr>
101 :     </table>
102 :     <p>
103 :     As a concrete example, code that was previously calling <tt>java.io.File.exists()</tt>
104 :     can now call <tt>IFileStore.fetchInfo().exists()</tt>. When a <tt>IFileInfo</tt>
105 :     is modified, the result needs to be stored back using the <tt>IFileStore.putInfo</tt>
106 :     method. For example, this snippet flips the read only attribute on a file
107 : curtispd 1.12 </p>
108 : johna 1.4 <pre>
109 :     IFileStore store = ...;//some file store
110 :     IFileInfo info = store.fetchInfo();
111 :     boolean readOnly = info.getAttribute(EFS.ATTRIBUTE_READ_ONLY);
112 :     info.setAttribute(EFS.ATTRIBUTE_READ_ONLY, !readOnly);
113 :     store.putInfo(info, EFS.SET_ATTRIBUTES, null);
114 :     </pre>
115 :     <h4>IProjectDescription.getLocation()</h4>
116 :     <p>
117 :     As with the <tt>getLocation()</tt> method, the project description's location
118 :     may no longer be in the local file system. The method
119 :     <tt>IProjectDescription.getLocationURI()</tt> can be used to obtain the location
120 :     of a resource in an arbitrary file system.
121 :     </p>
122 : johna 1.6 <h4>Local caching</h4>
123 :     <p>
124 :     Some clients absolutely must have a local representation of a file. For example,
125 :     they may be launching a native tool against that file, or using non Eclipse-aware
126 :     libraries that can only handle file system resources (such as <tt>java.util.zip.ZipFile</tt>).
127 :     In these cases, you can ask an IFileStore to return a cached local copy of its contents:
128 : curtispd 1.12 </p>
129 : johna 1.6 <pre>
130 :     IFileStore store = ...;//some file store
131 :     //see if it can directly be represented as a local file
132 :     java.io.File local = store.toLocalFile(EFS.NONE, null);
133 :     //if not, ask for a cached local copy of the file
134 :     if (local == null)
135 :     local = store.toLocalFile(EFS.CACHE, null);
136 :     </pre>
137 : curtispd 1.12 <p>
138 : johna 1.6 Note that once a cached copy of a file is obtained, it does not remain in sync with
139 :     the actual file system it came from. Modifying the cached copy will not cause the
140 :     underlying file to be modified.
141 :     </p>
142 : johna 1.4 <h4>Graceful failure</h4>
143 :     <p>
144 :     Clients that cannot handle resources outside the local file system may still
145 :     want to adapt their code to fail more gracefully. Clients can check if a resource
146 :     is in the local file system, and either ignore the resource or alert the user when
147 :     they encouter a resource they cannot handle. To determine if a resource is
148 :     in the local file system, you need to find out its file system <i>scheme</i>.
149 :     This can be obtained from a resource as follows:
150 : curtispd 1.12 </p>
151 : johna 1.4 <pre>
152 :     IResource resource = ...;//some resource
153 :     URI uri = resource.getLocationURI();
154 : johna 1.5 if (uri != null &amp;&amp; EFS.SCHEME_LOCAL.equals(uri.getScheme())) {
155 : johna 1.4 //file is in local file system
156 :     } else {
157 :     //file is not in the local file system
158 :     }
159 :     </pre>
160 : curtispd 1.12 <p>
161 : johna 1.4 If you have an <tt>IFileStore</tt> instance in hand, you can obtain the scheme
162 :     as follows:
163 : curtispd 1.12 </p>
164 : johna 1.4 <pre>
165 :     IFileStore store = ...;//a file store
166 :     store.getFileSystem().getScheme();
167 :     </pre>
168 : johna 1.6
169 : johna 1.5 <!-- ############################################## -->
170 : darin 1.14 <h2>2. <a name="MultiPageEditorSiteProgress"></a>API changes to MultiPageEditorSite</h2>
171 : dpollock 1.7 <p><strong>What is affected:</strong> Clients that call <code>MultiPageEditorSite.progressStart()</code> or <code>MultiPageEditorSite.progressEnd()</code>.</p>
172 :     <p><strong>Description:</strong> During Eclipse 3.0 development, these
173 :     methods were added as part of the progress support work. Before the 3.0
174 :     release, the way in which progress was handled was changed, and this method
175 :     was no longer necessary. Through programmer error, these public methods were
176 :     left in for the 3.0 release. These two methods have never served any function
177 : johna 1.11 in an Eclipse release, and so have been deleted.</p>
178 : dpollock 1.7 <p><strong>Action required:</strong> Clients calling
179 :     <code>MultiPageEditorSite.progressStart()</code> or
180 :     <code>MultiPageEditorSite.progressEnd()</code> should switch to using
181 :     <code>IWorkbenchSiteProgressService</code> instead.</p>
182 :    
183 :     <!-- ############################################## -->
184 : johna 1.4
185 : prapicau 1.8 <!-- ############################################## -->
186 : darin 1.14 <h2>3. <a name="configIni"></a>Content changes in config.ini</h2>
187 : prapicau 1.8 <p><strong>What is affected:</strong> Clients who have a custom a config.ini and are moving their application to 3.2.
188 :     </p>
189 :     <p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the config.ini was <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
190 : prapicau 1.10 Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated for the application to successfully start.
191 : prapicau 1.8 </p>
192 :     <p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
193 :     org.eclipse.core.runtime@start.</code>
194 :     </p>
195 :     <!-- ############################################## -->
196 :    
197 :    
198 : prapicau 1.9 <!-- ############################################## -->
199 : darin 1.14 <h2>4. <a name="jwsConfigIni"></a>Content changes in jnlp deployed applications</h2>
200 : prapicau 1.9 <p><strong>What is affected:</strong> Clients deploying RCP applications and specified a value to osgi.bundles.
201 :     </p>
202 :     <p><strong>Description:</strong> Prior to 3.2, the typical value for osgi.bundles contained in the main jnlp file was <code>org.eclipse.core.runtime@2:start, org.eclipse.update.configurator@3:start</code>.
203 : prapicau 1.10 Because of the <a href="recommended.html#runtimeSplit">runtime refactoring</a>, this value needs to be updated otherwise <code>NullPointerException</code>s could be thrown preventing the application to start.
204 : prapicau 1.9 </p>
205 :     <p><strong>Action required:</strong>Change the value of osgi.bundles to includes <code>org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start,
206 :     org.eclipse.core.runtime@start.</code>
207 :     </p>
208 :     <!-- ############################################## -->
209 : johna 1.4
210 : dj 1.13 <!-- ############################################## -->
211 : darin 1.14 <h2>5. <a name="bundleStart"></a>Explicit calls to Bundle.start() force the bundle
212 :     to be activated on next restart</h2>
213 : dj 1.13 <p><strong>What is affected:</strong> Clients that call <code>Bundle.start()</code>.
214 :     </p>
215 :     <p><strong>Description:</strong>
216 :     In Eclipse a bundle is specified to be a lazy start bundle
217 :     by using the <code>Eclipse-LazyStart</code> header (or the deprecated
218 :     <code>Eclipse-AutoStart</code> header). In Eclipse 3.1, the method
219 :     <code>org.osgi.framework.Bundle.start()</code> did not mark lazy start bundles as
220 :     persistently started. Since lazy start bundles never got marked as persistently
221 :     started they would not be automatically started when eclipse was restarted. The
222 :     javadoc for <code>Bundle.start()</code> states that the following must occur when the method is called:
223 :     </p>
224 :     <p>
225 :     &quot;Persistently record that this bundle has been started. When the Framework is restarted, this bundle must be automatically started.&quot;
226 :     </p>
227 :     <p>
228 :     In Eclipse 3.2 the <code>Bundle.start()</code> method has been fixed to properly mark
229 :     the bundle as persistently started even if the bundle is a lazy start bundle. This fix
230 :     was required to comply with the OSGi Framework specification. As a result callers of
231 :     <code>Bundle.start()</code> will force the bundle to be started when Eclipse is restarted.
232 :     In general this is considered a bad practice because it will cause unnecessary bundles to
233 :     be activated each time Eclipse is started. In some cases it can cause unexpected results
234 :     such as <a href=https://bugs.eclipse.org/bugs/show_bug.cgi?id=134412>bug 134412</a>.
235 :     </p>
236 :     <p><strong>Action required:</strong> Clients of <code>Bundle.start()</code> need to evaluate
237 :     if their intention is to persistently activate the bundle for every restart. If that is
238 :     not the intention then clients should find another way to activate the bundle. In most
239 :     cases calls <code>Bundle.start()</code> can be avoided by simply allowing the target bundle
240 :     to be lazily activated when classes are loaded from them. There are rare scenarios that
241 :     require a lazy start bundle to be agressively activated, but not persistenly marked for
242 :     activation on a restart. These types of scenarios should use <code>Bundle.loadClass()</code>
243 :     to load a class from the bundle which needs to be activated instead of calling
244 :     <code>Bundle.start()</code>.
245 :     </p>
246 :     <!-- ############################################## -->
247 : prapicau 1.17 <h2>5. <a name="pluginVersion"></a>Underscore no longer replaced by hyphen in plug-in version numbers</h2>
248 :     <p>
249 :     In Eclipse 3.0, the use of an underscore ('_') character in the qualifier segment of a version identifier
250 :     was not supported, but also was not enforced. If a plug-in version identifier contained an underscore in the qualifier,
251 :     then this character was transformed to a hyphen ('-') when exporting the plug-in to the file-system and also when installing the plug-in from an update site.
252 : johna 1.19 <br>
253 : prapicau 1.17 In Eclipse 3.1 the rules for characters allowed in qualifiers was relaxed to include the underscore character, so
254 :     when an offending plug-in was exported or installed the qualifier was not modified from its original state.
255 :     This subtle change was accidently left out from the migration guide for 3.0 to 3.1.
256 :    
257 :     The story going forward (and for Eclipse 3.2) is that we are maintaining compatibility with Eclipse 3.1
258 :     and plug-ins who use underscore characters in their version qualifiers, should be aware of the aforementioned changes when
259 :     dealing with old plug-in versions (both when exporting and when they exist on update sites). This means, for instance,
260 :     that plug-in providers who have old versions of their plug-in on an update site should ensure that the name in the file-system matches the name of the plug-in.
261 :     </p>
262 :     <!-- ############################################## -->
263 : jeem 1.1 </body>
264 :     </html>