Just few notes, inline.
On 16.6.2014 16:07, Ian Tewksbury wrote:
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.
By nature, the engine
core can't tell what the progress is, other than
number of processed vs. remaining rules.
The rules might provide some metadata about how long they expect to run.
But they don't know until the previous rules are done.
So I guess this will be a bit of guesstimate - perhaps based on some
simple value based on "typical" duration, given by rules as metadata.
*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
Looks like a subset
of input. So this would fill one app dir to input
and run, up to, excluding, the report phase.
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
This might need change in current runner, to resume from
the REPORTING
phase.
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
That would probably be a matter of a
query to the graph, in the ideal case.
*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
This should become part of the graph model. Perhaps not directly in a
FramedVertex. Could need some DTO to be prepared for this purpose.
Ondra
----------------------
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
_______________________________________________
windup-dev mailing list
windup-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev