[windup-dev] Windup API for Eclipse Plugin Suggesitons

Wed Jun 18 09:30:36 EDT 2014

Copied to WINDUP-91


On 18.6.2014 01:16, Ondrej Zizka wrote:
> 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 at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/windup-dev
>
>
>
> _______________________________________________
> windup-dev mailing list
> windup-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/windup-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/windup-dev/attachments/20140618/29e87d09/attachment.html