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

Parent Directory Parent Directory | Revision Log Revision Log

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

1 : jlemieux 1.1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 :     <html>
3 :     <head>
4 :     <title>Support Logical Resources</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 - Plan item</font></b>
12 :     </td>
13 :     </tr>
14 :     </tbody>
15 :     </table>
16 :     <h1>Support Logical Resources</h1>
17 :     This document outlines the state of the Eclipse Platform <strong>Support
18 :     Logical Resources</strong> plan item. Interested parties should review
19 :     this document and verify that their use cases are reflected in the
20 :     requirements then later that the solution provided satisfies their
21 :     needs. Feedback is strongly encouraged and may be provided on the
22 :     platform-team-dev mailing list or in the <a
23 :     href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=37723">bug report</a>
24 :     for this plan item.
25 :     <p class="MsoNormal">This is the plan item:</p>
26 :     <blockquote>
27 :     <p>"<em>The Eclipse Platform supports a strong physical view of
28 :     projects, files, and folders in the workspace. However, there are many
29 :     situations where a physical view is not the most salient or useful for
30 :     many purposes. In some cases, multiple distinct objects happen to be
31 :     stored in a single file, like an archive. Conversely, in other cases,
32 :     something that is logically a single object is stored across multiple
33 :     files. This discrepancy between logical and physical creates problems
34 :     for common operations such as searching, comparing, and versioning,
35 :     which need to work in the physical realm. Eclipse should support some
36 :     way of mapping between a logical view and the physical organization of
37 :     files on disk.</em>"</p>
38 :     <p>Last Modified: July 2nd, 2003<br>
39 :     </p>
40 :     </blockquote>
41 :     <h1>Motivation</h1>
42 :     <p>By definition Eclipse supports logical resources. It's a "an open
43 :     extensible IDE for anything and nothing in particular". The
44 :     applications that are built with it can be tailored to a particular
45 :     problem domain and the workbench extensions can be used to provide
46 :     support for any logical model. What Eclipse really doesn't support is
47 :     integrating tools at the logical model. In order to integrate two
48 :     plugins into Eclipse either the two plugins have to know about each
49 :     other, or both plugins have to depend on some common plugin. While the
50 :     first option is satisfactory for a few cases, the second case is the
51 :     most common and the most problematic. To illustrate, the Eclipse SDK
52 :     contains several plugins that are based on the Resources plugin (e.g.
53 :     Team, Search, Compare, JDT). When an application is packaged based on
54 :     the SDK, because the plugins in the SDK are resource based that is the
55 :     common integration point between plug-ins.<br>
56 :     </p>
57 :     <p>As you will see later, even the users of the SDK (JDT+CVS+Resources)
58 :     can observe some of the problems associated with the lack of support
59 :     for logical resources and the implicit mapping to physical resources.
60 :     The lack of a logical integration point causes the co-existance of
61 :     plugins in Eclipse to be error prone for the user. The next sections
62 :     will examine the relationships between logical and physical resources
63 :     and outline the visible problems with Eclipse 3.0.</p>
64 :     <h2>Existing Bugs</h2>
65 :     <p>Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=32582">32582</a>
66 :     logical to physical mapping problem , 1 model element = 2 Files problem<br>
67 :     Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=3979">3979</a>
68 :     [CVS Decorator] show version info works incorrectly for sub packages
69 : jlemieux 1.2 (1GFDIEB)<br>
70 :     </p>
71 : jlemieux 1.1 <h2>Logical Resources Defined<br>
72 :     </h2>
73 :     <p>Whereas logical resources are elements of the application that model
74 :     the data/processes of a particular problem domain, the physical
75 :     resources are the file system resources (e.g. files and folders) into
76 :     which an application will eventually transform their application model
77 :     for storage. Applications that don't use file system resources are not
78 :     being considered as part of this plan item. For example, an application
79 :     that stores it's application data directly into a database.</p>
80 :     <p>The following table enumerates concrete examples of how logical and
81 :     physical resources are used in current applications integrated into
82 :     Eclipse.</p>
83 :     <p><a name="#table1"></a>Table 1: Example logical to physical uses</p>
84 :     <table width="100%" border="1">
85 :     <tbody>
86 :     <tr>
87 :     <td width="23%">
88 :     <div align="center"><strong>Relationships</strong></div>
89 :     </td>
90 :     <td width="77%">
91 :     <div align="center"><strong>Examples</strong></div>
92 :     </td>
93 :     </tr>
94 :     <tr>
95 :     <td>
96 :     <p>logical (1) &lt;-&gt; (*) physical</p>
97 :     <p>one logical to many physical</p>
98 :     </td>
99 :     <td valign="top">
100 :     <p><a name="#1a"></a>(<strong>1a</strong>) EJB maps to several
101 :     physical files: (WSAD + XDE Tester). This is the most common case we
102 :     have found. </p>
103 :     <blockquote>
104 :     <p>/src/org/app/bean.java<br>
105 :     /src/org/app/beanr.java<br>
106 :     /src/org/app/beanlocal.java</p>
107 :     </blockquote>
108 :     <p><em>Note: If one of the logical resource's files was deleted
109 :     who would remember that the file used to exist and is an outgoing
110 :     deletion or that there is an incoming addition to the logical resource?</em></p>
111 :     <p><a name="#1b"></a>(<strong>1b</strong>) Composite Object
112 :     (logical) maps to several changed physical resources. (Rational XDE)</p>
113 :     <p><em>Note</em>: <em>With 1 to many relationship there is
114 :     always the complication that arises if the logical element maps to
115 :     files in an other project? This would cause many problems in the
116 :     current Team plugin.</em></p>
117 :     </td>
118 :     </tr>
119 :     <tr>
120 :     <td>
121 :     <p>logical (*) &lt;-&gt; (1) physical</p>
122 :     <p>many logical to one physical</p>
123 :     </td>
124 :     <td valign="top">
125 :     <p><a name="#2a"></a>(<strong>2a</strong>) Methods in a class map
126 :     to their containing class file. (JDT)</p>
127 :     <p><a name="#2b"></a>(<strong>2b</strong>) Archive files (zip,
128 :     jar) can be seen as a logical and the contents of the archive all map
129 :     to the same physical.(JTD + all)</p>
130 :     </td>
131 :     </tr>
132 :     <tr>
133 :     <td>
134 :     <p>logical (1) &lt;-&gt; (1) physical</p>
135 :     <p>one logical to one physical</p>
136 :     </td>
137 :     <td valign="top">
138 :     <p><a name="#3a"></a>(<strong>3a</strong>) A Java Package maps to
139 :     a folder but a package does not include sub folders (e.g. they are
140 :     shallow). (JDT)</p>
141 :     <p><a name="#3b"></a>(<strong>3b</strong>) A UML class maps to a
142 :     file. For example, in a UML application a class could be stored in a
143 :     single file called 'x435dsds.umlclass'. The reason it's a logical is
144 :     that the user of the application will never be concerned about the
145 :     actual file name or even the folder it's stored in. (XDE)</p>
146 :     </td>
147 :     </tr>
148 :     </tbody>
149 :     </table>
150 :     <h1>Complaints<br>
151 :     </h1>
152 :     <p>The following complaints are representative of bug reports and
153 :     requirements received from several Eclipse users and developers.<br>
154 :     </p>
155 :     <h2>Complaint 1: Not very adaptable</h2>
156 :     <p>Object contributions and decorators are key mechanisms for providing
157 :     rich integration between tools. Using object contributions and
158 :     adaptable objects, any plugin can provide actions and decorators that
159 :     will show in another plugin's view. </p>
160 :     <p>Since IResource is the lowest common integration class and is
161 :     strongly mapped to its physical storage as files and folders, the
162 :     integration point for actions and decorators cannot be the logical
163 :     types in the view. The actions will consequently use the adaptable type
164 :     from the selection to perform the action or the decorator the resource
165 :     from the getImage request.</p>
166 :     <p>Here is an example to illustrate the problem with the CVS plugin.
167 :     When running a CVS commit action in the packages view the action
168 :     doesn't know that the IFolder is a Java package and is a shallow
169 :     namespace. It will use the selection and traverse the selected
170 :     IContainer using IContainer.members() and commit all child resources.
171 :     This is the same when the CVS outgoing decorator is shown on a package.
172 :     It will reflect the deep outgoing state of the IContainer. This can
173 :     lead to unexpected behavior because the user expected the action to run
174 :     on the model that the action was displayed on.</p>
175 :     <p>Example object contribution for the CVS commit action:</p>
176 :     <pre>&lt;extension point="org.eclipse.ui.popupMenus"&gt;<br> &lt;objectContribution<br> objectClass="org.eclipse.core.resources.IResource"<br> adaptable="true"<br> id="org.eclipse.team.ccvs.ui.IResourceContributions"&gt;<br> &lt;filter<br> name="projectPersistentProperty"<br> value="org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature"&gt;<br> &lt;/filter&gt;<br> &lt;action<br> label="Commit"<br> tooltip="Commit resource to CVS repository"<br> class="org.eclipse.team.internal.ccvs.ui.actions.CommitAction"<br> menubarPath="team.main/group3"<br> id="org.eclipse.team.ccvs.ui.commit"&gt;<br> &lt;/action&gt;<br> &lt;objectContribution&gt;<br>&lt;/extension&gt;<br></pre>
177 :     <p>Example code run in the commit action to calculate the resources to
178 :     commit:</p>
179 :     <pre>public static Object[] getSelectedAdaptables(ISelection selection) {<br> ArrayList result = null;<br> if (!selection.isEmpty()) {<br> result = new ArrayList();<br> Iterator elements = ((IStructuredSelection) selection).iterator();<br> while (elements.hasNext()) {<br> Object adapter = getAdapter(elements.next(), IResource.class);<br> if (c.isInstance(adapter)) {<br> result.add(adapter);<br> }<br> }<br> }<br> if (result != null &amp;&amp; !result.isEmpty()) {<br> return (Object[])result.toArray((Object[])Array.newInstance(IResource.class, result.size()));<br> }<br> return (Object[])Array.newInstance(IResource.class, 0);<br>}</pre>
180 :     <p>Example code for defining an IResource adaptable decorator:</p>
181 :     <pre>&lt;extension<br> point="org.eclipse.ui.decorators"&gt;<br> &lt;decorator objectClass="org.eclipse.core.resources.IResource"<br> adaptable="true"<br> label="%DecoratorStandard.name"<br> state="false"<br> lightweight= "true"<br> quadrant = "BOTTOM_RIGHT"<br> class="org.eclipse.team.internal.ccvs.ui.CVSLightweightDecorator"<br> id="org.eclipse.team.cvs.ui.decorator"&gt;<br> &lt;description&gt;<br> %DecoratorStandard.desc<br> &lt;/description&gt;<br> &lt;/decorator&gt;<br>&lt;/extension&gt;</pre>
182 :     <h2>Complaint 2: Decorators</h2>
183 :     <p>When the CVS decorator decorates a logical container in a view, the
184 :     desire is to decorate parents with the dirty indicator if one or more
185 :     of their logical children are dirty. To do this properly, the decorator
186 :     would need to query the dirty status of each of the logical children of
187 :     the container. This can be a costly operation as each child may itself
188 :     be a logical container. We have optimized the dirty decoration by
189 :     caching folder dirty states. This optimization becomes far more
190 :     complicated with logical models where the caching must be based on this
191 :     alternate model (i.e. the state must be cached for each model).</p>
192 :     <p> In addition, often decorators rely on&nbsp;IResource change events
193 :     to re-calculate some new state. In the case of a logical elements
194 :     representing several physical resources there is no easy way of
195 :     associated a IResource change event to its files and the actual logical
196 :     element.</p>
197 :     <h2>Complaint 3: Presentation of mixed logical models<br>
198 :     </h2>
199 :     <p>It would be nice to see the Java logical view in the Synchronize
200 :     view, in the navigator, or in dialogs contributed by other plug-ins
201 :     besides JDT. However, the entries in these views
202 :     may not be IResources so an IResource independent mapping mechanism
203 :     would be required. A workaround for this problem is demonstrated by the
204 :     Search plug-in which allows for plug-ins to integrate with other tools
205 :     by contributing domain specific pages. JDT contributes a JDT search
206 :     page to the view and shows logical Java elements. This solution however
207 :     doesn't allow showing mixed logical models in the same widget, which is
208 :     required in the Synchronize View and Navigator.<br>
209 :     </p>
210 :     Also, if an action prompts the user, for example to add resources to
211 :     CVS, what icons and labels are used in the dialog? It would be nice to
212 :     show those that are most familiar to the user. <br>
213 :     <br>
214 :     There are two levels of logical model presentation:<br>
215 :     <ul>
216 :     <li>Need for full access to a logical model that would allow building
217 :     a dynamic UI. This would include mapping from an IResource to a logical
218 :     element.<br>
219 :     </li>
220 :     </ul>
221 :     <ul>
222 :     <li>Need name and icon for a logical element to display in simple
223 :     dialogs.<br>
224 :     </li>
225 :     </ul>
226 :     <h2>Complaint 4: Change Sets</h2>
227 :     <p>Consider a user's action as a logical change, for example, the user
228 :     renames a class using the JDT refactoring action. In the user's mind he
229 :     'renamed a class' and as a result there has been many other file
230 :     changes. Currently there is not way of capturing these logical actions
231 :     and associating the set of affected resources. This problem manifests
232 :     itself more in tools where almost every change to the model has side
233 :     effects.</p>
234 :     <h2>Complaint 5: Participating in operations</h2>
235 :     Some logical models may want to participate and even restrict the kinds
236 :     of operations are
237 :     allowed on theirs files. For example, if a logical element is composed
238 :     of three files, the users should not be allowed to move, or delete them
239 :     individually. In essence, a way of vetoing the move/rename, copy, or
240 :     delete would be useful to ensure a coherant logical model.<br>
241 :     <h2>Complaint 6: IResource based views in the IDE</h2>
242 :     There are several views in the workbench IDE that could be used by
243 :     logical models but are currently too tied to resources. For example,
244 :     the problems and tasks views have a resource column and works uniquely
245 :     on IResource markers. This means that if a logical model provides
246 :     problems and tasks the problems and tasks views cannot be used to show
247 :     the logical element instead of the file.<br>
248 :     <h2>Complaint 7: Merging can't consider all files related to a logical
249 :     element</h2>
250 :     When merging a logical element the repository may find a conflict in
251 :     one of the files that is part of the logical element. The repository
252 :     tool will typically fetch the revisions for the conflicting file so
253 :     that a comparison can be shown to the user. But since the repository
254 :     tool doesn't know that other files are part of the logical resource,
255 :     the comparison shown to the user doesn't have access to the correct
256 :     revisions of the other files. This is a problem because it then becomes
257 :     impossible to implement a comparison that has access to all the
258 :     revisions of the logical element's files.<br>
259 :     <h1>Discussion</h1>
260 :     <p>Given the number of different complaints about logical resource
261 :     support indicates that this is indeed a large problem space. If we plan
262 :     on addressing any of the complaints for 3.1, we will have to scope the
263 :     solution to address a subset of the complaints. I propose the following
264 :     grouping of the complaints:<br>
265 :     </p>
266 :     <p><span style="font-weight: bold;">Adaptables: Related to providing a
267 :     richer adaptable interface between plug-ins<br>
268 :     </span>Complaint 1: Not very adaptable<br>
269 :     Complaint 2: Decorators<br>
270 :     Complaint 7: Merging can't consider files related to a logical element<br>
271 :     </p>
272 :     <p><span style="font-weight: bold;">Presentation of logical models:
273 :     Related to exposing a non-resource based data modeling framework</span><br>
274 :     Complaint 6: IResource based views in the IDE<br>
275 :     Complaint 3: Presentation of mixed logical models<br>
276 :     </p>
277 :     <span style="font-weight: bold;">Others</span><br>
278 :     Complaint 4: Change Sets<br>
279 :     Complaint 5: Participating in operations
280 :     <p>A common discussion in the community is the idea
281 :     that the resources plug-in should be generalized to become this generic
282 :     model, but in reality it wasn't designed as such and although it
283 :     contains common model services such as eventing and threading, it was
284 :     explicitly designed to model the file system. Changes to the resources
285 :     plug-in would be a major breaking API change and not acceptable to the
286 :     community. <br>
287 :     </p>
288 :     <p>For 3.1 we will only address the Adaptables group of complaints. See
289 :     <a href="logical-physical-adaptables.html">Solution 1: Support Logical
290 :     Resources - Adaptables</a> for a discussion on a possible solution.<br>
291 :     </p>
292 :     </body>
293 :     </html>