I took a look at your new APIs, and
the direction looks good. It may seem like reinventing the wheel,
but I think this approach will offer you guys the most flexibility and
control over your APIs as WST evolves. I know the current APIs are
still rough, but I took a quick look and have some general comments:
- Having IVirtualResource extend IAdaptable
is always a good thing. If IVirtualResource adapts to IResource,
you will get many UI contributions such as context menus and decorators
for free. It's also generally needed when showing these things in
the UI (adapting to IWorkbenchAdapter, IPropertySource, IPersistableElement,
- Consider avoiding duplication of IResource
methods where it is not necessary. I.e., IVirtualFile.getHistory() may
not be needed if IVirtualFile.getRealFile().getHistory() will always accomplish
the same thing. The same may be true for methods like isReadOnly(), getCharset().
You may have had reasons to duplicate these particular methods, but I wanted
to mention the general guideline that there's no point providing your own
API that always just forwards to the underlying resource. It's always
possible to add methods later, but it will be impossible to take away,
so you should start with a minimal set of API.
- Is there a better term than "virtual"
to describe your model? How about IWebResource, IWebFolder, etc?
- If you don't intend to introduce IVirtualProject
or IVirtualWorkspaceRoot, there is no reason for IVirtualContainer. Its
methods can just be folded into IVirtualFolder. This won't eliminate
the possibility of abstracting out the container methods in the future
should the need arise.
- You may want to consider adding the
IJavaElement method getUnderlyingResource() to IVirtualResource. This
will allow navigation between the two models at an abstract level. This
would also replace the "getRealFile" method currently on IVirtualFile
(somehow "real" isn't the most descriptive term).
- One of the biggest mistakes we made
in the IResource API is the use of boolean parameters. The first
problem is that it doesn't make for very descriptive code at the call site.
If you see code like "folder.create(true,true,null), it doesn't
tell you much about what it's doing. The second problem is that it's
not extensible. Every time you want to add a new flag, you need to
add a new method with an extra parameter. This leads to duplication
bloat that you see in the IResource hierarchy. We finally made the
switch in 2.0 to use SWT-style flag parameters, and we now use those exclusively.
They are much more descriptive and extensible. For this reason I
suggest not copying any of the IResource methods with boolean parameters
that have an equivalent that takes an int flag. Going forward, the
int flag parameter versions are the only ones we recommend. The boolean
argument methods may eventually be deprecated.
- Don't forget progress monitors. I
don't know what IVirtualContainer.commit() does, but if it's potentially
long running it should have a progress monitor parameter.
- I noticed several new methods, but
since they have no javadoc I can't comment on their purpose. In designing
the IResource hierarchy, we always followed the rule of writing the javadoc
before implementing any new method. It's tempting to jump straight into
the code, but thinking about the purpose of a new API from the client's
point of view helps clarify what the implementation of that method should
do. APIs exist solely to serve a client, and without spelling out
the contract and parameters of that service you can't reasonably implement
Michael Elder <mdelder@xxxxxxxxxx> Sent by: wtp-dev-bounces@xxxxxxxxxxx
29/03/2005 09:53 AM
Please respond to
"General discussion of project-wide or architectural issues."
[wtp-dev] Virtual API progress
We have been making progress on the proposal to expose
Path API" to allow clients to browse flexible project structures without
dealing directly with the underlying EMF models. We are beginning to lean
towards making the models wholly internal to allow us the freedom to make
changes in the next release of WTP if necessary. Are there any opinions
there about this?
The initial cut of the API is already available in
CVS under the
We are targeting this weeks Integration Build to have the API tests in
places and most if not all of the javadoc. The one thing that hasn't yet
been addressed is how we intend to expose the Referenced Components
(formerly Dependent Workbench Modules) through the Virtual Path API. We
started by coping the IResource, IContainer, IFolder, and IFile, and then
pruning those down to methods that deal with navigation. The javadoc is
yet ready, so any docs that are there are left over from Eclipse Platform.
We also added methods that were more specific that we thought would be
helpful: getWorkspaceRelativePath(), getProjectRelativePath() [as in
Platform], getRuntimePath(), getRealFile(s)/Folder(s)(), and
We are also considering changing our use of the EMF
URI object to use
the more Eclipse-friendly IPath object to model path structures within
model. By making the models internal, we allow ourselves the opportunity
make this change at a later time (e.g. R1.1), but are considering making
this change as quickly as this Friday. Any thoughts?