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@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/windup-dev