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

Parent Directory Parent Directory | Revision Log Revision Log

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