Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] Virtual API progress

Hi Michael,

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, etc).

- 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 it.


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."

kosta@xxxxxxx, Ted.bashor@xxxxxxx
[wtp-dev] Virtual API progress

Extended Team:

     We have been making progress on the proposal to expose a "Virtual
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 out
there about this?

     The initial cut of the API is already available in CVS under the
modelcore plugin
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 not
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 the
model. By making the models internal, we allow ourselves the opportunity to
make this change at a later time (e.g. R1.1), but are considering making
this change as quickly as this Friday. Any thoughts?

Kind Regards,

Michael D. Elder
Rational Studio / J2EE Tools Development
Ext: (919) 543-8356
T/L:  441-8356

wtp-dev mailing list

Back to the top