platform-vcm-home/docs/online/team3.1/logical-physical-mappings.html

Parent Directory Parent Directory | Revision Log Revision Log

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

1 : mvalenta 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 :     <html>
3 :     <head>
4 :     <title>Support Logical Resources: Resource Mappings</title>
5 :     </head>
6 :     <body>
7 :     <table border="0" cellspacing="5" cellpadding="2" width="100%">
8 :     <tbody>
9 :     <tr>
10 :     <td align="left" valign="top" bgcolor="#0080c0"> <b><font
11 :     color="#ffffff" face="Arial,Helvetica"> Eclipse 3.1 - Support Logical Resources
12 :     - Resource Mappings</font></b></td>
13 :     </tr>
14 :     </tbody>
15 :     </table>
16 :     <h1>Support Logical Resources - Resource Mappings</h1>
17 :     This document outlines the chosen solution to the adaptables problem outlined
18 :     in the <a href="logical-physical-public.html"><strong>Support Logical Resources</strong></a>
19 :     plan item problem description document. Feedback is strongly encouraged and may
20 :     be provided on the platform-team-dev mailing list or in the <a
21 :     href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=37723">bug report</a> for
22 :     this plan item. The API described in this document is not yet final and may undergo
23 :     some revision before the end of the Eclipse 3.1 development cycle.
24 :     <h3>The Basic Resource Mapping API</h3>
25 :     <p>This solution involves adding API to the Resources plugin that maps logical
26 : mvalenta 1.2 models elements to workspace (i.e. file system) resources. The API is purposely
27 :     simple with logical model manipulations omitted. A client can't use this interface
28 :     to display logical models or gain any interesting additional knowledge about
29 :     it. It's purpose is simply to map one or more model elements to workspace resources.
30 :     </p>
31 :     <p>The API consists of the following classes: </p>
32 : mvalenta 1.1 <ul>
33 : mvalenta 1.2 <li><strong>ResourceMapping</strong>: The Class to which logical model elements
34 : mvalenta 1.1 adapt to indicate that the model corresponds to a set of resources in the
35 :     workspace. The complete <code>ResourceMapping</code> class can be viewed <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMapping.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">here</a>.
36 :     The methods of interest are:
37 :     <ul>
38 :     <li><code>Object getModelObject()</code>: The model object from which the
39 :     mapping was derived (or adapted).</li>
40 :     <li><code>ResourceTraversal[] getTraversals(ResourceMappingContext, IProgressMonitor)</code>:
41 :     The resource traversal that cover the resources that constitute the model
42 :     object.</li>
43 :     </ul>
44 :     </li>
45 :     <li><strong>ResourceTraversal</strong>: A <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceTraversal.java?rev=HEAD&content-type=text/vnd.viewcvs-markup"><code>ResourceTraversal</code></a>
46 : mvalenta 1.4 contains a set of resources and a depth flag that indicates the depth to which
47 :     the resources in the traversal are associated with the originating model object.
48 :     Resource traversals are provided to a client by a resource mapping in order
49 : mvalenta 1.9 to describe the contents of a model in such a way that the client (e.g. a
50 :     repository provider) can perform its operations in as efficient a means as
51 :     possible. Methods of interest are:
52 : mvalenta 1.2 <ul>
53 :     <li><code>getResources()</code></li>
54 :     <li><code>getDepth()</code></li>
55 :     </ul>
56 :     </li>
57 : mvalenta 1.1 <li><strong>ResourceMappingContext</strong>: a context that is provided to the
58 : mvalenta 1.2 resource mapping by the client when obtaining traversals. This context allows
59 :     the logical model to determine what the remote state of the model is so that
60 :     the proper resources can be covered by the resource traversals returned by
61 :     the resource mapping. The use of the<code> <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.core.resources/src/org/eclipse/core/resources/mapping/ResourceMappingContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">ResourceMappingContext</a></code>
62 : mvalenta 1.1 is a bit more complicated and is described <a href="#ResourceMappingContext">later</a>.</li>
63 :     </ul>
64 :     <p>There are two types of plugins that should be interested in resource mappings.
65 : mvalenta 1.2 Those who provide a model that consists of, or is persisted in, resources in
66 :     the workspace and those that want to perform operations on resources. The following
67 : mvalenta 1.1 two sections describe how to associate a resource mapping with a model object
68 :     and how to contribute menus to objects that adapt to resource mappings.</p>
69 :     <h4>Adapting a Model to a ResourceMapping</h4>
70 :     <p>Plugins that adapted their model objects to <code>IResource</code> in order
71 : mvalenta 1.2 to get resource specific actions shown in the context menu can now adapt to
72 :     <code>ResourceMapping</code> if a richer description of how the object adapts
73 : mvalenta 1.9 to resources is beneficial. However, they are not required to do so if there
74 : mvalenta 1.4 is no benefit. For instance a Java compilation unit (i.e. *.java file shown
75 :     in a JDT view) that now currently adapts to <code>IFile</code> need not adapt
76 :     to <code>ResourceMapping</code> since nothing is gained. However, a Java package
77 :     should adapt to <code>ResourceMapping</code> in order to indicate that the package
78 :     is only the files in the corresponding folder and not the subfolders.</p>
79 : mvalenta 1.2 <p>The preferred way to adapt model elements to a resource mapping is to use an
80 :     adapter factory. The following is the XML markup for contributing an adapter
81 :     factory in a plugin manifest. </p>
82 : mvalenta 1.1 <pre style="background-color: rgb(204, 204, 255);"> &lt;extension<br> point=&quot;org.eclipse.core.runtime.adapters&quot;&gt;<br> &lt;factory<br> class=&quot;org.eclipse.example.library.logical.AdapterFactory&quot;<br> adaptableType=&quot;org.eclipse.example.library.Book&quot;&gt;<br> &lt;adapter type=&quot;org.eclipse.core.resources.mapping.ResourceMapping&quot;/&gt;<br> &lt;/factory&gt;<br> &lt;factory<br> class=&quot;org.eclipse.example.library.logical.AdapterFactory&quot;<br> adaptableType=&quot;org.eclipse.example.library.Library&quot;&gt;<br> &lt;adapter type=&quot;org.eclipse.core.resources.mapping.ResourceMapping&quot;/&gt;<br> &lt;/factory&gt;<br> ...<br> &lt;/extension&gt;</pre>
83 : mvalenta 1.2 <p>The adapter factory implementation would look something like this:</p>
84 :     <pre style="background-color: rgb(204, 204, 255);">public class AdapterFactory implements IAdapterFactory {
85 :     public Object getAdapter(Object adaptableObject, Class adapterType) {
86 :     if((adaptableObject instanceof EObject) && adapterType == ResourceMapping.class) {
87 :     return new EMFResourceMapping((EObject)adaptableObject);
88 :     }
89 :     return null;
90 :     }
91 :    
92 :     public Class[] getAdapterList() {
93 :     return new Class[] {ResourceMapping.class};
94 :     }
95 :     }</pre>
96 : mvalenta 1.9 <p>For popup menu contributions, it is not required that the model objects implement
97 : mvalenta 1.4 the <code>IAdaptable</code> interface. However, if they do, they must ensure
98 : mvalenta 1.1 that the Platform adapter manager is consulted. This can be done by either subclassing
99 :     <code>PlatformObject</code> or by using the following line of code:</p>
100 :     <blockquote>
101 :     <p><code>Platform.getAdapterManager().getAdapter(Object, Class)</code></p>
102 :     </blockquote>
103 : mvalenta 1.9 <p>The above is the preferable approach. However, the model object can implement
104 : mvalenta 1.1 the IAdaptable interface and provide a <code>getAdapter(Class)</code> implementation
105 :     that creates returns an instance of <code>ResourceMapping</code> explicitly
106 :     when asked for one. This is a more straightforward approach but the least desirable
107 :     as the model must have explicit knowledge of the adaptation to resources.</p>
108 : mvalenta 1.7 <p>In some cases, the provider of a logical model may not want their model to
109 :     adapt to <code>IResource</code> in every context or may want the object to adapt
110 :     differently for object contributions than other contexts, The workbench UI provides
111 :     a special intermediate adapter API, <code>IContributorResourceAdapter</code>,
112 :     for this purpose. When objects are being adapted to <code>IResource</code> in
113 :     the context of object contributions, the workbench first tries to adapt the
114 :     resource to <code>IContributorResourceAdapter</code> before trying to adapt
115 : mvalenta 1.9 to <code>IResource</code> directly. A new sub-interface of this interface, <code>IContributorResourceAdapter2</code>,
116 : mvalenta 1.7 has been added which provides the same capability for <code>ResourceMapping</code>.
117 : mvalenta 1.9 The only difference is that the model provider should register a factory for<code>
118 : mvalenta 1.7 IContributorResourceAdapter</code> since the Workbench does an <em>instanceof</em>
119 :     check to see if the contributed adapter is also an instance of <code>IContributorResourceAdapter2</code>.</p>
120 : mvalenta 1.3 <p>The implementation of the <code>ResourceMapping</code> subclass for a Java
121 :     package would look something like this.</p>
122 :     <pre style="background-color: rgb(204, 204, 255);">public class JavaPackageResourceMapping extends ResourceMapping {
123 :     IPackageFragment package;
124 :     ...
125 :     public getModelObject() {
126 :     return package;
127 :     }
128 :     public ResourceTraversals[] getTraversals(
129 :     ResourceMappingContext context,
130 :     IProgressMonitor monitor) {
131 :     return new ResourceTraversal[] {
132 :     new ResourceTraversal(
133 :     new IResource[] { package.getCorrespondingResource() },
134 :     IResource.DEPTH_ONE, IResource.NONE)
135 :     }
136 :     }
137 :     }</pre>
138 : mvalenta 1.9 <p>This is a fairly straightforward mapping so the implementation is not complex.
139 : mvalenta 1.3 The complexity of the resource mapping implementation will, of course, vary
140 :     from model to model. The <code>EMFResourceMapping</code> example used above
141 :     is implemented in the example and it a much more complicated implementation.</p>
142 : mvalenta 1.1 <h4>Contributing Menus to Resource Mappings</h4>
143 :     <p>Plug-ins that contribute extensions to adaptable extension points will have
144 :     to make two changes to support the new <code>ResourceMapping</code> APIs:</p>
145 :     <ol>
146 : mvalenta 1.4 <li>Update their plugin.xml files to change the objectClass of their adaptable
147 : mvalenta 1.1 contributions to <code>ResourceMapping</code> (for those for which this is
148 :     appropriate).</li>
149 :     <li>Update their actions to work on <code>ResourceMapping</code> instead of
150 : mvalenta 1.4 <code>IResource</code> and respect the depth constraints provided in the traversals.</li>
151 : mvalenta 1.1 <li>(Optional) provide a <code>ResourceMappingContext</code> if they manage
152 :     remote resources (more on this <a href="#ResourceMappingContext">below</a>)</li>
153 :     </ol>
154 :     <p>First of all, plugins that add object contributions to <code>IResource</code>
155 :     (CVS, Search, Compare) can now add them to <code>ResourceMapping</code> instead,
156 : mvalenta 1.9 if the action can apply to multiple resources. Here is an XML snippet that contributes
157 : mvalenta 1.4 a menu action to objects that adapt to resource mappings:</p>
158 : mvalenta 1.1 <pre style="background-color: rgb(204, 204, 255);"> &lt;extension<br> point=&quot;org.eclipse.ui.popupMenus&quot;&gt;<br> &lt;objectContribution<br> adaptable=&quot;true&quot;<br> objectClass=&quot;org.eclipse.core.resources.mapping.ResourceMapping&quot;<br> id=&quot;org.eclipse.example.library.ResourceMappingContributions&quot;&gt;<br> &lt;action<br> label=&quot;Show Resource Mappings&quot;<br> class=&quot;org.eclipse.example.library.contributions.ShowResourceMappingsAction&quot;<br> menubarPath=&quot;additions&quot;<br> id=&quot;org.eclipse.example.library.showMappings&quot;/&gt; <br> &lt;/objectContribution&gt;<br> &lt;/extension&gt;</pre>
159 :     <p>Contributions to <code>ResourceMapping</code> will automatically apply to objects
160 :     that adapt to <code>IResource</code>. This transitive association is handled
161 :     by the Workbench.</p>
162 :     <p>Filtering of the contributions to resource mappings can be done using action
163 : mvalenta 1.9 filters or expressions. An expression for filtering by project persistent property
164 : mvalenta 1.4 has been added to allow repository providers to have their menus appear on projects
165 :     that are mapped to their repositories.</p>
166 : mvalenta 1.1 <pre style="background-color: rgb(204, 204, 255);"> &lt;extension<br> point=&quot;org.eclipse.ui.popupMenus&quot;&gt;<br> &lt;objectContribution<br> objectClass=&quot;org.eclipse.core.resources.mapping.ResourceMapping&quot;<br> adaptable=&quot;true&quot;<br> id=&quot;org.eclipse.team.ccvs.ui.ResourceMapperContributions&quot;&gt;<br> &lt;enablement&gt;<br> &lt;adapt type=&quot;org.eclipse.core.resources.mapping.ResourceMapping&quot;&gt;<br> &lt;test
167 :     property=&quot;org.eclipse.ui.ide.projectPersistentProperty&quot;
168 :     args=&quot;org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature&quot; /&gt;<br> &lt;/adapt&gt;<br> &lt;/enablement&gt;<br> &lt;action<br> label=&quot;%UpdateAction.label&quot;<br> definitionId=&quot;org.eclipse.team.cvs.ui.update&quot;<br> class=&quot;org.eclipse.team.internal.ccvs.ui.actions.UpdateAction&quot;<br> tooltip=&quot;%UpdateAction.tooltip&quot;<br> menubarPath=&quot;team.main/group2&quot;<br> id=&quot;org.eclipse.team.cvs.ui.update&quot;&gt;<br> &lt;/action&gt;
169 :     ...<br> &lt;/objectContribution&gt;<br> &lt;/extension&gt;</pre>
170 :     <p>Actions that have been contributed to the <code>ResourceMapping</code> class
171 :     will be given a selection that contains one or more <code>ResourceMappings</code>.
172 :     It is the actions responsibility to translate the resource mapping into a set
173 :     of resources to be operated on. This can be done by calling <code>getTraversals</code>
174 :     to get the traversals of the mapping. Traversals are used to allow the clients
175 :     of the traversal to optimize their operations based on the depth of the resources
176 :     being traversed. A client may traverse the resource manually or may use the
177 :     resource and the depth as input into an operation that the action delegates
178 :     to do the work. As an example, if the user performs a CVS update on a java package
179 :     and the java package resource mapping maps to a folder of depth one, CVS would
180 : mvalenta 1.9 issue an appropriate command (&quot;cvs update -l&quot; for those who are curious)
181 :     which would perform a shallow update on the folder the package represents.</p>
182 : mvalenta 1.1 <h3><a name="ResourceMappingContext"></a>Resource Mapping Context</h3>
183 : mvalenta 1.9 <p>One of the advantages of a Resource Mapping API is that it allows plug-ins
184 :     to implement any operations they desire in terms of resource mappings (e.g.
185 :     CVS update, CVS commit, CVS tag, dirty decoration, etc.). However, the API that
186 : mvalenta 1.1 has been introduced so far deals only with the local state of the model. When
187 :     working with a model that may be shared between developers, you end up in a
188 :     situation where the remote state of the model (i.e. the state of the model that
189 :     another user has checked-in to the repository) may differ from the state in
190 :     the workspace. If you performed a CVS update, you would want the local state
191 :     of the model to match the remote state even if it meant that additional files
192 :     needed to be included or some files needed to be removed.</p>
193 :     <p>This is not an issue for some logical models. For instance, a java package
194 :     is a container visited to a depth of one, regardless of the remote state of
195 :     the model. Given this, a repository provider can easily determine that outgoing
196 :     deletions should be included when committing or that incoming additions should
197 :     be included when updating. However, the resources that constitute some logical
198 :     models may change over time. For instance, the resources that constitute a model
199 :     element may depend of the contents of a manifest file (or some other similar
200 : mvalenta 1.4 mechanism). In order for the resource mapping to return the proper traversal,
201 : mvalenta 1.9 it must access the remote contents of the manifest file (if it differs from
202 : mvalenta 1.1 the local contents) in order to see if there are additional resources that need
203 :     to be included. These additional resources may not exist in the workspace but
204 :     the repository provider would know how to make sure they did when the selected
205 :     action was performed.</p>
206 :     <p>In order to support these more complex models, a <code>ResourceMappingContext</code>
207 :     can be passed to the <code>ResourceMapping#getTraversals</code> method. When
208 :     a context is provided, the mapping can use it to ensure that all the necessary
209 :     resources are included in the traversal. If a context is not provided, the mapping
210 :     can assume that only the local state is of interest. </p>
211 :     <h4>When does a ResourceMapping need to worry about the ResourceMappingContext?</h4>
212 :     <p>A <code>ResourceMapping</code> need only worry about a context supplied to
213 :     the <code>getTraversals</code> method in cases were the resources that make
214 :     up a model change over time and the relationship between the model and resources
215 : mvalenta 1.9 cannot be described by a simple traversal that is guaranteed to encompass those
216 :     resources (and only those resources) that constitute the model. For example,
217 : mvalenta 1.1 although the resources of a Java package may change over time, the package can
218 : mvalenta 1.3 be described as a folder of depth of one so a resource mapping for java packages
219 : mvalenta 1.1 would not ned to make use of the resource mapping context. </p>
220 :     <p>As a more complicated example, consider an HTML file that contains several
221 : mvalenta 1.4 images. Let's make the assumption that any images references from an HTML file
222 :     are part of the model of that file. When updating the local contents of the
223 :     HTML file from a repository, the user would expect that any new images would
224 :     be included. The <code>getTraversals</code> method for a <code>ResourceMapping</code>
225 :     for the HTML file model would look something like this:</p>
226 : mvalenta 1.2 <pre style="background-color: rgb(204, 204, 255);">public class HTMLResourceMapping extends ResourceMapping {
227 : mvalenta 1.1 private HTMLFile htmlFile;
228 :     getTraversals(ResourceMappingContext context, IPorgressMonitor monitor) {
229 : mvalenta 1.4 IResource[] resources = htmlFile.getResources();
230 : mvalenta 1.1 if (context != null) {
231 :     // Look for any additional resources on the server
232 :     IFile file = htmlFile.getFile();
233 :     if (context.contentDiffers(file, monitor) {
234 :     IStorage storage = context.fetchContents(file, monitor);
235 :     IResource[] additionalResources = getReferences(storage.getContents());
236 :     resources = combine(resources, additionalResources);
237 :    
238 :     }
239 :     }
240 :     return new ResourceTraversal(resources, IResource.DEPTH_ZERO);
241 :    
242 :     }<br>}</pre>
243 : mvalenta 1.6 <p>Notice that there are two sets of resources included in the model: those derived
244 : mvalenta 1.9 from the local contents of the HTML file in the workspace and the contents of
245 : mvalenta 1.6 the file remotely. In either of these two sets, there may be resources that
246 :     do not exist in the workspace. For instance, the local HTML file may contain
247 :     a relative link to an image that does not exist in the workspace. This resource
248 :     should be included so that it will be fetched if it exists remotely. As for
249 :     the remote file, it may contain a new copy that references additional images
250 :     that should be fetched when the new remote contents are downloaded.</p>
251 : mvalenta 1.1 <h4>When does a client need to provide a ResourceMappingContext?</h4>
252 :     <p>Any client that is providing the ability of sharing workspace resources through
253 :     a repository and is supporting ResourceMappings should provide an appropriate
254 : mvalenta 1.4 context for determining the relevant remote state of the model resources. The
255 : mvalenta 1.9 context provides three basic queries:</p>
256 : mvalenta 1.1 <ul>
257 :     <li>Does the local contents differ from the remote contents</li>
258 :     <li>What are the remote contents of a file</li>
259 : mvalenta 1.9 <li>What are the remote members of a folder</li>
260 : mvalenta 1.1 </ul>
261 :     <p>The answer to the first question above depends on the type of operation that
262 :     is being performed:</p>
263 :     <ul>
264 :     <li>When checking in a resource, the context would consider that a file's contents
265 :     differ if the local contents have been modified since the last check-in.</li>
266 :     <li>When updating a resource, the context would consider that a file's contents
267 :     differ if the remote contents have been modified since the users last update.</li>
268 :     <li>When replacing a resource, the context would consider that a file's contents
269 :     differ if either the the local or remote contents have changed since the last
270 :     synchronization.</li>
271 :     </ul>
272 :     <p>The Eclipse Team API includes a <code>Subcriber</code> class that defines an
273 :     API for providing the synchronization state between the local workspace and
274 : mvalenta 1.6 a remote server. A <code><a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberResourceMappingContext.java?rev=HEAD&content-type=text/vnd.viewcvs-markup">SubscriberResourceMappingContext</a></code>
275 :     has been created that uses a <code>Subscriber</code> to access the necessary
276 :     remote state. Clients that have a <code>Subscriber</code> do not need to do
277 :     any additional work to get a resource mapping context.</p>
278 : mvalenta 1.5 <h2>EMF Library Example</h2>
279 :     <p>This example, available <a href="../../../plugins/library.zip">here</a>, is
280 :     built on a model that consists of libraries, books and writers. The code is
281 :     generated by EMF. It requires Eclipse 3.1 M5 and EMF SDK 2.0.1.</p>
282 :     <p> The model is persisted in several types of files:</p>
283 :     <ul>
284 : mvalenta 1.9 <li>*.library files which contain the name of a library and one or more book
285 :     copy records which reference a book and indicate the number of copies of the
286 : mvalenta 1.5 book the libraries contain.</li>
287 : mvalenta 1.9 <li>*.books files which contain one or more books. Each book has several properties
288 : mvalenta 1.5 (name, number of pages, etc.) as well as a reference to the book's author.</li>
289 :     <li>*.writers files which contain one or more writers. Each writer has properties
290 : mvalenta 1.9 (e.g. name) as well as references to one or more books that have been authored
291 : mvalenta 1.5 by the writer.</li>
292 :     </ul>
293 : mvalenta 1.9 <p>The following screen shot shows an example Library.</p>
294 : mvalenta 1.5 <p><img src="libraryView.png" width="306" height="229"></p>
295 :     <p>Here is the containment relationship of these model elements</p>
296 :     <ul>
297 :     <li>My.writers: contains &quot;Bob&quot;</li>
298 :     <li>My.books: contains &quot;The Life of Bob&quot;</li>
299 : mvalenta 1.9 <li>mylib.library: contains copies of the &quot;Life of Bob&quot;</li>
300 : mvalenta 1.5 </ul>
301 :     <p>For the purposes of this example, model containment is determined by following
302 :     all the references from the file containing the selected model element to all
303 :     other files. For instance, the resources associated with the writer &quot;Bob&quot;
304 :     would be My.writers, since Bob is contained in that file, and My.books since
305 :     Bob wrote a book in that book catalog. The resources associated with the Main
306 :     Library would be mylib.library, My.books, since the library contains a book
307 : mvalenta 1.9 from that catalog, and My.writers, since the it contains Bob, the author of
308 : mvalenta 1.5 that book.</p>
309 :     <p>There are three files of interest in the example code, all of them in the org.eclipse.team.examples.library.adapt
310 :     plugin.</p>
311 :     <ul>
312 : mvalenta 1.9 <li><em>org.eclipse.team.examples.library.adapt/plugin.xml</em>: contains the
313 : mvalenta 1.5 adapter factory registration and an object contribution to <code>ResourceMapping</code>.</li>
314 :     <li><em>org.eclipse.team.examples.library.adapt/src/org/eclipse/team/examples/library/adapt/EMFResourceMapping</em>:
315 :     The resource mapping from the Library model to resources. This is basically
316 : mvalenta 1.9 a worst-case mapping that uses EMF to traverse the model for file references.
317 : mvalenta 1.5 Read the class javadoc for more information.</li>
318 :     <li><em>org.eclipse.team.examples.library.adapt/src/org/eclipse/team/examples/library/adapt/ShowResourceMappingsAction</em>:
319 : mvalenta 1.9 The action that shows the resource mapping. At the time of writing it uses
320 : mvalenta 1.5 internal Team UI classes but the intention is to make these classes (or at
321 : mvalenta 1.9 least the functionality they provide) API in 3.1.</li>
322 : mvalenta 1.5 </ul>
323 :     <p>There is also a read-me file (<em>org.eclipse.team.examples.library.adapt/readme.html</em>)
324 :     that contains instructions on how to use the example. </p>
325 :     <h2>Conclusion</h2>
326 :     <h3>How this will affect existing plug-ins</h3>
327 : mvalenta 1.1 <p>Existing plugins do not need to change at all unless they want to take advantage
328 : mvalenta 1.5 of the new API. For plugins that provide logical models, it may be worthwhile
329 : mvalenta 1.1 for them to adapt their model objects to <code>ResourceMappings</code>. Of course,
330 :     this is only a benefit when combined with a repository provider implementation
331 :     that contributes at last some of it's actions to resource mappings.</p>
332 :     <span style="font-weight: bold;"></span>
333 : mvalenta 1.5 <h3>Open Issues</h3>
334 : mvalenta 1.1 <p>The following issues would need to be addressed for this solutions.</p>
335 : mvalenta 1.8 <h4>UI Support</h4>
336 :     <p>Plugins that add object contributions will have to modify their actions to
337 :     handle logical resources. There should be some standard UI components for showing
338 :     the mappings. For instance you could show the logical model at the top and in
339 :     a details part the physical files/folders that will be affected by the operation.
340 :     There is currently a <code>MappingSelectionDialog</code> in the Team UI plugin
341 :     but it is not yet API. The goal is to evolve this class to the point where it
342 :     can be made API.</p>
343 :     <h4><strong>Incomplete Implementations</strong></h4>
344 :     <p>Full support for resource mappings depends on these factors:</p>
345 :     <ol>
346 :     <li>The model provides a resource mapping for its model elements</li>
347 :     <li>Repository providers (or other tools) become resource mapping aware.</li>
348 :     <li>Repository providers (or other tools) provide a resource mapping context
349 :     for those operations that warrant it.</li>
350 :     <li>Model that may have resources added or removed at the root level (i.e. the
351 :     resources returned by the <code>ResourceTraversal#getResources()</code> method)
352 :     make use of the context to determine any additional resources that should
353 :     be included in the mapping.</li>
354 :     </ol>
355 :     <p>Without the first point, nothing can be done so this is really the main requirement.
356 :     Assuming we have a model that provides a resource mapping, we end up with the
357 :     following possible scenarios:</p>
358 :     <p><strong>A repository provider is not mapping aware</strong>: In this case,
359 :     the best that can be done is for the model (i.e. the model's view) to provide
360 :     a Show In&gt;Navigator command which will allow the user to perform Team operations
361 :     from there. Of course, this is only an issue for model elements that do not
362 :     map to a single resource. Although this is a bit cumbersome, it will work in
363 :     many situations. It will not work well for those models that may have added
364 :     or removed resources at the root level.</p>
365 :     <p><strong>A repository provider does not provide a resource mapping context or
366 :     a model does not make use of the context</strong>: For some repository providers,
367 :     it may be difficult to provide a resource mapping context. It is also possible
368 :     that a model may not make use of the context to determine which resource should
369 :     be included in the mapping. In either case, this is only an issue for models
370 :     that may add or remove resources at the root level. In reality, the number of
371 : mvalenta 1.9 these cases may be small but the effects will be noticeable since operations
372 :     may exclude resources. These cases can be handled by falling back to operations
373 : mvalenta 1.8 on the resources themselves.<br>
374 :     </p>
375 : mvalenta 1.1 </body>
376 :     </html>