Difference between revisions of "FAQ What is the difference between a path and a location?"

From Eclipsepedia

Jump to: navigation, search
 
m (Formatting)
Line 1: Line 1:
In general, the term <i>location</i> represents physical
+
In general, the term ''location'' represents physical file system paths, and ''path'' represents a resource's logical position within the workspace. Many people are confused by this distinction, as both terms are represented by using the <tt>IPath</tt> data type.
file system paths, and <i>path</i> represents a resource&#146;s logical position within
+
the workspace. Many people are confused by this distinction, as both terms are
+
represented by using the <tt>IPath</tt> data type.
+
  
<tt>IPath</tt> is in fact an abstract data structure that  
+
<tt>IPath</tt> is in fact an abstract data structure that represents a series of slash-separated strings. Many people assume that paths always correspond to a file-system location, but this is not always the case.
represents a series of slash-separated strings. Many people assume that paths
+
  In fact, <tt>IPath</tt> objects are used in a variety of contexts for locating an  
always correspond to a file-system location, but this is not always
+
object within a tree-like hierarchy. For example, a resource pathreturned by
the case.  In fact, <tt>IPath</tt> objects are used in a variety of
+
<tt>IResource.getFullPath</tt>, represents the position of a resource within the
contexts for locating an object within a tree-like hierarchy. For example,
+
workspace tree.  The first segment is the name of the project, the last segment
a resource path, returned by <tt>IResource.getFullPath</tt>, represents
+
is the name of the file or folder, and the middle segments are the names of the
the position of a resource within the workspace tree.  The first segment
+
  parent folders in order between the project and the file or folder in question.
is the name of the project, the last segment is the name of the file or
+
  This doesn't always match the path of the resource in the file system!  
folder, and the middle segments are the names of the parent folders
+
 
  in order between the project and the file or folder in question. This
+
The file-system location of a resource, on the other hand, is returned by the method <tt>IResource.getLocation</tt>. Methods on <tt>IContainer</tt> and <tt>IWorkspaceRoot</tt> can help you convert from one to the other. The following code converts from a path to a location:
  doesn&#146;t always match the path of the resource in the file system!
+
+
   
+
  
The file-system location of a resource, on the other hand, is returned
 
by the method <tt>IResource.getLocation</tt>.  Methods
 
on <tt>IContainer</tt> and <tt>IWorkspaceRoot</tt> can help
 
you convert from one to the other.  The following code converts from
 
a path to a location:
 
 
<pre>
 
<pre>
 
   IPath path = ...;
 
   IPath path = ...;
Line 32: Line 21:
 
   }
 
   }
 
</pre>
 
</pre>
Note that in some situations, a resource can have
 
a <tt>null</tt> location.  In particular, resources whose project
 
doesn&#146;t exist and linked resources that are relative to a nonexistent
 
path variable will have a <tt>null</tt> location.
 
  
 +
Note that in some situations, a resource can have a <tt>null</tt> location.  In particular, resources whose project doesn't exist and linked resources that are relative to a nonexistent path variable will have a <tt>null</tt> location.
  
Here is the converse code to convert from a location to the workspace
+
Here is the converse code to convert from a location to the workspace paths that correspond to it:
paths that correspond to it:
+
 
<pre>
 
<pre>
 
   IPath location = ...;
 
   IPath location = ...;
Line 52: Line 37:
 
   }
 
   }
 
</pre>
 
</pre>
As this snippet shows, a single file-system location
+
As this snippet shows, a single file-system location can correspond to multiple resources.  This is true because linked resources can point to locations inside other projects.  Of course, the same file-system location can't correspond to both files and folders at the same time.
can correspond to multiple resources.  This is true because linked
+
resources can point to locations inside other projects.  Of course,
+
the same file-system location can&#146;t correspond to both files
+
and folders at the same time.
+
 
+
  
When using API from the resources plug-in that involve <tt>IPath</tt>
+
When using API from the resources plug-in that involve <tt>IPath</tt> objects, always read the API javadoc carefully to see whether it deals with paths or
objects, always read the API javadoc carefully to see whether it deals with paths or
+
locations. These different types of paths must never be mixed or used interchangeably, as they represent completely different things.
locations. These different types of paths must never be mixed or used
+
interchangeably, as they represent completely different things.
+
  
 
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
 
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>

Revision as of 19:49, 19 June 2006

In general, the term location represents physical file system paths, and path represents a resource's logical position within the workspace. Many people are confused by this distinction, as both terms are represented by using the IPath data type.

IPath is in fact an abstract data structure that represents a series of slash-separated strings. Many people assume that paths always correspond to a file-system location, but this is not always the case.

In fact, IPath objects are used in a variety of contexts for locating an 
object within a tree-like hierarchy. For example, a resource pathreturned by
IResource.getFullPath, represents the position of a resource within the
workspace tree.  The first segment is the name of the project, the last segment
is the name of the file or folder, and the middle segments are the names of the
parent folders in order between the project and the file or folder in question.
This doesn't always match the path of the resource in the file system! 

The file-system location of a resource, on the other hand, is returned by the method IResource.getLocation. Methods on IContainer and IWorkspaceRoot can help you convert from one to the other. The following code converts from a path to a location:

   IPath path = ...;
   IWorkspace workspace = ResourcesPlugin.getWorkspace();
   IWorkspaceRoot root = workspace.getRoot();
   IResource resource = root.findMember(path);
   if (resource != null) {
      location = resource.getLocation();
   }

Note that in some situations, a resource can have a null location. In particular, resources whose project doesn't exist and linked resources that are relative to a nonexistent path variable will have a null location.

Here is the converse code to convert from a location to the workspace paths that correspond to it:

   IPath location = ...;
   IFile[] files = root.findFilesForLocation(location);
   IFolder[] folders = root.findContainersForLocation(location);
   if (files.length > 0) {
      for (int i = 0; i < files.length; i++)
         path = files[i].getLocation();
   } else {
      for (int i = 0; i < folders.length; i++)
         path = folders[i].getLocation();
   }

As this snippet shows, a single file-system location can correspond to multiple resources. This is true because linked resources can point to locations inside other projects. Of course, the same file-system location can't correspond to both files and folders at the same time.

When using API from the resources plug-in that involve IPath objects, always read the API javadoc carefully to see whether it deals with paths or locations. These different types of paths must never be mixed or used interchangeably, as they represent completely different things.


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.