9:07 a.m.
All,
Pete asked me to send out some of the ideas I have had about what the Eclipse plugin would
like to see from the Windup core project as far as API goes.
ProgressMonitor
I would suggest basing this off the Eclipse IProgressMonitor API. I do not think it would
make sense to actually use the Eclipse API because then Windup would be dependent on
Eclipse. But if Windup had a similar interface I could use it to convert form a Windup
ProgressMonitor to an Eclipse IProgressMonitor and report status back to the user. For
Windup's long running actions this is very important.
WinupdEngine
I think it is important a single instance of the Windup Engine is reusable and can be run
multiple times on the same project or on different projects. But if for whatever reason it
is only one time use only that needs to be well documented in the API. Currently with
legacy windup I only create one copy of the Engine
WindupEngine#setSettings(WindupEnvironment env) - set the windup options
WindupEngine#process(File parentProject, ProgressMonitor monitor) - runs windup on a
parent folder and generates all the metadata
WindupEngine#generateReport(File parentProject, ProgressMonitor monitor) - generates a
windup report based on all the metadata that is created by the #process(File
parentFolder). This could either error out if the parentFolder has not yet been processed
or could automatically process it
WindupEngine#getRuleMatches(File file) - Should return a list of RuleMatch objects, one
for every rule match on a given file that can then be used to access any needed
information about that rule match determined from all of the generated metadata
RuleMatch
This should be the class that is used to give API users all the information that was
determined about a given resource. I would suggest most of this information if not all of
it be lazily loaded and not pre populated. I do not know what your plan is for the storage
of the windup model you will build on a given project. I hope there is some plan to not
just keep it all in memory all the time and there will be some sort of file backend. An
application like Eclipse is already a memory hog, to have to store the possibly infinite
size of the windup model for all the projects in the workspace in memory all the time
could get way out of proportion quickly. My suggestion would be this model would get saved
to disk and then classes like the RuleMatch could query the model which would in turn
query the disk for information. At the very least if the model is not saved to disk, then
at least text and description from rules should only be loaded from disk when requested.
So when loading a custom rule you have to load the matcher from disk as you process, but
no need to load the description or other information until someone actually requests it,
and even then that information should not be kept in memory by windup when requested, it
should be returned and forgotten. I could go on an on on this subject, and it maybe a
topic for another email or discussion at some point, but wanted to lay down some of my
suggestions as it relates to this API.
I would also assume that the report generator for Winup would be using this same API to
generate the report. I see the Windup Report generator and the Eclipse plugin as siblings,
both using the same API to display the same information in different ways.
RuleMatch#getTitle() - a short description title of the match
RuleMatch#getLongDescription() - a more verbose description of the match. this could
possible contain some level of markup/simple html for basic formatting
RuleMatch#getAdditionalReadingLinks() - returns list of links to externally extensible
information relevant to the match
RuleMatch#getLocation() - returns a location object that will contain the line number and
character start and end locations on that line of the match. If the match if for the
entire file there should be some way of describing that as well.
RuleMatch#getCategory() - I am guessing rules will be provided in sets, JEE, WebSphere,
Wildfly, or something that groups rules together in logical sets, this would be nice for
reporting
RuleMatch#getSeverity() - I would suggest a three level system, info, warning, error.
RuleMatch#getFix() - Should return a block of text that can replace the matched block of
text as a quick fix for the match. If you want to get really fancy these fixes should be
able to match on parts of the match and inject them into the quick fix block. EX: if
replacing one method call with another and there are parameters being passed the fix
should be able to have some way of referencing those parameters so it can use them in its
fix. This would all have to be done on the Windup side and likely all programmaticly by
giving the rule writers access to the source they matched on so they can parse it for use
in their fix code
----------------------
That is all I can think of for now. I hope this helps describe the kind of things Eclipse
will be looking for in terms of API.
Blue Skies,
~Ian