| Migration Guide |
Summary
Some changes are being made to the IPath and Path classes in Eclipse 3.1 to allow for creation of paths containing characters that were previously invalid. See the proposal for more details. This document is a draft of a migration guide entry for current IPath users who need to migrate to accomodate these changes.Last modified: October 22, 2004
What is affected: Plug-ins that create, manipulate, or store IPath objects.
Description: In Eclipse 3.0, IPath had a number of restrictions on the segments of paths that were more restrictive than the restrictions of the underlying operating system. These included:
Action required: In order to enable the proper treatment of the expanded range of paths, all usage of Path and IPath 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.
Plug-ins that store string representations of paths in a format that needs to be readable across different platforms should migrate to the new Path.fromPortableString factory method. This method produces an IPath instance from a platform-independent format. This string representation of paths can be created using the IPath.toPortableString 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 (org.eclipse.core.runtime.preferences.IPreferencesService).
Note: fromPortableString will correctly read all path strings that were created using the Eclipse 3.0 IPath.toString method, but not the Eclipse 3.1 toString method. Thus in most cases no change is required to existing metadata file formats except to begin writing paths with toPortableString and reading paths with fromPortableString.
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 Path.toPortableString. 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 new Path("c:/temp") will now create a relative path with two segments on Unix platforms. Similarly, new Path("a\\b") will now create a path with a single segment on Unix platforms, and a path with two segments on Windows.
Plug-ins constructing paths using the IPath.append(String) 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 append("a\\b") on Unix platforms will now append a single segment, whereas on Windows it will continue to append two segments.