Comparison REST API to trigger Comparisons from Automated CI Test Pipelines

[bruderol]

Currently there is a new service for triggering an import of a buidl together with a diff calculation.
This service is waiting synchronously for the diff until it has been calculated and then returns the diff value. We want to simplify that and document the new services accordingly.

Acceptance criterias:

• The newly added REST-call in BuildsImporterResource.java is moved to new service ComparisonsResource.java and has to be changed as following:
  • A build can be triggered for explicit reimport over BuildsImporterResource.java (with removing any pre-existing data, if any, maybe that servcie already exists?)
  • The URL of the service to calculate comparisons is changed and all comparisons rest services are placed somewhere in the DiffViewer resources, to avoid mixing it up, with the already existing importBuilds service , that triggers all unimported/new builds to be imported.
  • The build import services do not anymore calculate any comparison and also not wait anymore for the import and the calculation to be finished. It only returns a failure if the build to be imported could not be filed somehow for import (e.g. existing data could not be removed?).
  • There is another additional new service (separate one) to also queue a comparison calculation to calculate a diff (asynchronously), that asynchronous task might have to wait somehow for the build to be imported first before starting to run.
  • Third (existing) service can be used then to check for the comparison result (as soon as it is available):
  • A similar service to the one that has been added that synchronously does alltogether as convenince in one call ist still kept for convenince: import a build and then immediately start to compare another build and wait for its comparison to be calculated but put a comment that this servcie should be used with care, as it might block for a long time. But the code is refactored to be simplified and to not use multiple futures anymore (waiting for more than one build / comparison at once is not possible).
• Open follow up story for frontend to use the new service for creating a comparison on request through the UI - see Diff Viewer Plus: Create Comparisons Manually through Viewer Web Frontend in Dialog #692 (allready implemented)
• the important new services are documented and how they can be used to get a diff viewer comparison result, when needed in another application (e.g. for triggering calculations of comparisons from CI Server).
  * currently I would just mention it in the diff viewer user guide
• the new services and breaking changes to existing services are briefly mentioned in the changelog and link to the documentation for info about new services.
• the new added and refactored services have been tested appropriately
  * manually
  * maybe automatically? e2e tests with jasmine (could be easy)?

TODO (@adiherzog duplication to Acceptance Criteria - can we remove it ?)

• Review Changes by @adiherzog
• Review the things mentioned in email by @adiherzog
• finalize the changes
• open follow up story for UI to trigger a comparison on request --> already implemented and working, see Diff Viewer Plus: Create Comparisons Manually through Viewer Web Frontend in Dialog #692
• Document REST services (only most important ones!)
• Document breaking changes in changelog
• Test the services

[adiherzog]

Currently the endpoint does not return an error if the requested build does not exist. We should change this. If the requested build or comparison build does not exist we should return a 404.

Example result for a build comparison that did not exist (current state that we should change):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<comparisonResult>
    <baseBuild>
        <branchName>BranchDoesNotExist</branchName>
        <buildName>2014-01-20</buildName>
    </baseBuild>
    <comparisonBuild>
        <branchName>wikipedia-docu-example</branchName>
        <buildName>2014-02-21</buildName>
    </comparisonBuild>
    <comparisonConfiguration>
        <name>Manually Triggered Comparison</name>
        <baseBranchName>BranchDoesNotExist</baseBranchName>
        <comparisonBranchName>wikipedia-docu-example</comparisonBranchName>
        <comparisonBuildName>2014-02-21</comparisonBuildName>
    </comparisonConfiguration>
    <rmaePercentage>100.0</rmaePercentage>
</comparisonResult>

[adiherzog]

@bruderol Opened a feature branch for this one: feature/605-comparison-rest-endpoint

[adiherzog]

@bruderol I added the remaining endpoints. Would be good if we could review this together some time soon, maybe next week. I have some open questions we should discuss.

[bruderol]

@adiherzog Somehow the build still seems to fail ??

[bruderol]

@adiherzog for the remaining documentation work I recommend you to continue work on one of my branches (the one for issue #692 - unless my PR is merged) - because there I already removed the old rest service documentation file on my branch and merged all still relevant diff viewer documentation into one feature documentation file in slightly different location (in folder docs/features).

Please document only the most important rest services that might be helpful for CI to trigger comparisons from CI - and I think this should simply go into that same diff viewer docu file, nd only mention the most improtant endpoints.

Thanks a lot!

[bruderol]

@adiherzog I adjusted the accpetance criteria and what remains to be done. Please merge with my latest branch (see PR #696 ) before you continue your work, because I did some changes to docu as well!

[bruderol]

@adiherzog what about this issue? can you finish it? What about testing this REST endpoints?

[bruderol]

@adiherzog I propose we close this now, and open a follow up story to add automated tests for that.

What would be great if you could add the breaking changes for the REST services at least quickly to the CHANGELOG.md on the release branch! and maybe to the Diff Viewer docu as well a short overview of the important services?

[adiherzog]

@bruderol Let's keep this open. I'll do it today.

[adiherzog]

I created a follow-up task to automatically check the REST endpoints: #742

[bruderol]

@adiherzog Thanks a lot! Great we have that done :-)