platform-core/documents/path_migration.html - www.eclipse.org/eclipse - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2">
 <html>
 <head>
 <title>Migration guide for <tt>Path</tt> changes</title>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     <meta http-equiv="Content-Style-Type" content="text/css">
     <link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css">
 </head>
 <body bgcolor="#ffffff">

 <table width="100%">
 <tr><td style="background:#0080C0"><b><span style="color:white">Migration Guide</span></b></td></tr>
 </table>

 <h1>Migration guide for <tt>Path</tt> changes</h1>

 <blockquote> <b>Summary</b>  <br>
 Some changes are being made to the <tt>IPath</tt> and <tt>Path</tt>
 classes in Eclipse 3.1 to allow for creation of paths containing characters
 that were previously invalid.  See the <a href="path_changes_html">proposal</a>
 for more details. This document is a draft of a migration guide entry for current
 <tt>IPath</tt> users who need to migrate to accomodate these changes.
 <p>
 <font size="-1">Last modified: October 22, 2004</font>
 </blockquote>
 <p>
 <h3>Incompatibilities</h3>
 <p>
 <b>What is affected:</b> Plug-ins that create, manipulate, or store <tt>IPath</tt> objects.
 <p>
 <b>Description:</b> In Eclipse 3.0, <tt>IPath</tt> had a number of restrictions
 on the segments of paths that were more restrictive than the restrictions of the
 underlying operating system. These included:
 <ul>
 <li>Leading and trailing whitespace in path segments were not allowed</li>
 <li>The colon character (':') was reserved as a device separator character</li>
 <li>The backslash character ('\') was reserved as a segment separator character</li>
 </ul>
 These restrictions have been removed in Eclipse 3.1 when the platform's data
 location (workspace) is located on a file system that does not have these restrictions.
 <p>
 <b>Action required:</b> In order to enable the proper treatment of the expanded
 range of paths, all usage of <tt>Path</tt> and <tt>IPath</tt> within plug-ins
 should be reviewed and updated as described below. Most unmodified plug-ins
 will continue to behave exactly as in 3.0 on all paths considered legal in 3.0.
 However, unless these prescribed changes are made, they are likely to fail in
 cases involving paths considered legal in 3.1 that were illegal in 3.0.
 <p>
 Plug-ins that store string representations of paths in a format that needs to be
 readable across different platforms should migrate to the new
 <tt>Path.fromPortableString</tt> factory method. This method produces
 an <tt>IPath</tt> instance from a platform-independent format. This string
 representation of paths can be created using the <tt>IPath.toPortableString</tt> method.
 Examples of metadata files that are affected include files that are stored inside Eclipse
 workspace projects (.project, .classpath, etc), and all paths stored in the preference
 store (<tt>org.eclipse.core.runtime.preferences.IPreferencesService</tt>).
 <p>
 Note: <tt>fromPortableString</tt> will correctly read all path strings that were
 created using the Eclipse 3.0 <tt>IPath.toString</tt> method, but not the
 Eclipse 3.1 <tt>toString</tt> method. Thus in most cases no change is required
 to existing metadata file formats except to begin writing paths with <tt>toPortableString</tt>
 and reading paths with <tt>fromPortableString</tt>.
 <p>
 Plug-ins that were creating paths from hard-coded string literals that assumed
 ':' and '\' had special meaning on all platforms will need to migrate. The easiest
 solution is to restrict string path literals to the subset that is supported
 on all platforms (avoid colon and backslash characters).  Path literals can support
 the complete set of valid Unix paths by using the portable path string format produced
 by <tt>Path.toPortableString</tt>. This format interprets the first single colon (':')
 as the device separator, slash ('/') as the segment separator, and double colon ("::")
 as a literal colon character. For example, the code <tt>new Path("c:/temp")</tt>
 will now create a relative path with two segments on Unix platforms.  Similarly,
 <tt>new Path("a\\b")</tt> will now create a path with a single segment
 on Unix platforms, and a path with two segments on Windows.
 <p>
 Plug-ins constructing paths using the <tt>IPath.append(String)</tt> method
 that assumed ':' and '\' had special meaning on all platforms may need to update their code.
 In Eclipse 3.1, this method uses operating-system specific device and segment
 delimiters to interpret the provided path string.  For example, calling <tt>append("a\\b")</tt>
 on Unix platforms will now append a single segment, whereas on Windows it will
 continue to append two segments.

 <h3>References</h3>
 <p>
 <ul>
 <li><a href="path_changes.html">Path changes proposal</a></li>
 <li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=24152">bug 24152</a></li>
 </ul>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN2">
	<html>
	<head>
	<title>Migration guide for <tt>Path</tt> changes</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link href="http://dev.eclipse.org/default_style.css" rel="stylesheet" type="text/css">
	</head>
	<body bgcolor="#ffffff">

	<table width="100%">
	<tr><td style="background:#0080C0"><b><span style="color:white">Migration Guide</span></b></td></tr>
	</table>

	<h1>Migration guide for <tt>Path</tt> changes</h1>

	<blockquote> <b>Summary</b> <br>
	Some changes are being made to the <tt>IPath</tt> and <tt>Path</tt>
	classes in Eclipse 3.1 to allow for creation of paths containing characters
	that were previously invalid. See the <a href="path_changes_html">proposal</a>
	for more details. This document is a draft of a migration guide entry for current
	<tt>IPath</tt> users who need to migrate to accomodate these changes.
	<p>
	<font size="-1">Last modified: October 22, 2004</font>
	</blockquote>
	<p>
	<h3>Incompatibilities</h3>
	<p>
	<b>What is affected:</b> Plug-ins that create, manipulate, or store <tt>IPath</tt> objects.
	<p>
	<b>Description:</b> In Eclipse 3.0, <tt>IPath</tt> had a number of restrictions
	on the segments of paths that were more restrictive than the restrictions of the
	underlying operating system. These included:
	<ul>
	<li>Leading and trailing whitespace in path segments were not allowed</li>
	<li>The colon character (':') was reserved as a device separator character</li>
	<li>The backslash character ('\') was reserved as a segment separator character</li>
	</ul>
	These restrictions have been removed in Eclipse 3.1 when the platform's data
	location (workspace) is located on a file system that does not have these restrictions.
	<p>
	<b>Action required:</b> In order to enable the proper treatment of the expanded
	range of paths, all usage of <tt>Path</tt> and <tt>IPath</tt> within plug-ins
	should be reviewed and updated as described below. Most unmodified plug-ins
	will continue to behave exactly as in 3.0 on all paths considered legal in 3.0.
	However, unless these prescribed changes are made, they are likely to fail in
	cases involving paths considered legal in 3.1 that were illegal in 3.0.
	<p>
	Plug-ins that store string representations of paths in a format that needs to be
	readable across different platforms should migrate to the new
	<tt>Path.fromPortableString</tt> factory method. This method produces
	an <tt>IPath</tt> instance from a platform-independent format. This string
	representation of paths can be created using the <tt>IPath.toPortableString</tt> method.
	Examples of metadata files that are affected include files that are stored inside Eclipse
	workspace projects (.project, .classpath, etc), and all paths stored in the preference
	store (<tt>org.eclipse.core.runtime.preferences.IPreferencesService</tt>).
	<p>
	Note: <tt>fromPortableString</tt> will correctly read all path strings that were
	created using the Eclipse 3.0 <tt>IPath.toString</tt> method, but not the
	Eclipse 3.1 <tt>toString</tt> method. Thus in most cases no change is required
	to existing metadata file formats except to begin writing paths with <tt>toPortableString</tt>
	and reading paths with <tt>fromPortableString</tt>.
	<p>
	Plug-ins that were creating paths from hard-coded string literals that assumed
	':' and '\' had special meaning on all platforms will need to migrate. The easiest
	solution is to restrict string path literals to the subset that is supported
	on all platforms (avoid colon and backslash characters). Path literals can support
	the complete set of valid Unix paths by using the portable path string format produced
	by <tt>Path.toPortableString</tt>. This format interprets the first single colon (':')
	as the device separator, slash ('/') as the segment separator, and double colon ("::")
	as a literal colon character. For example, the code <tt>new Path("c:/temp")</tt>
	will now create a relative path with two segments on Unix platforms. Similarly,
	<tt>new Path("a\\b")</tt> will now create a path with a single segment
	on Unix platforms, and a path with two segments on Windows.
	<p>
	Plug-ins constructing paths using the <tt>IPath.append(String)</tt> method
	that assumed ':' and '\' had special meaning on all platforms may need to update their code.
	In Eclipse 3.1, this method uses operating-system specific device and segment
	delimiters to interpret the provided path string. For example, calling <tt>append("a\\b")</tt>
	on Unix platforms will now append a single segment, whereas on Windows it will
	continue to append two segments.

	<h3>References</h3>
	<p>
	<ul>
	<li><a href="path_changes.html">Path changes proposal</a></li>
	<li><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=24152">bug 24152</a></li>
	</ul>
	</body>
	</html>