[MSHARED-632] Expose which dependency classes are used and where

[jhaber]

We use the maven-dependency-plugin to analyze dependencies and fail our build if there are any used undeclared or unused declared dependencies. In the case of used undeclared dependencies, it is often helpful to know which classes are being used and where they are being used. We've found a few workarounds to make this a little easier, but the plugin has access to this information so what we really want is for the plugin to just print this info along with each used undeclared dependency. We've made this change in our fork and our developers are very happy with it, so I'd like to contribute it back (here is an example of the output before and after the change).

If you agree this is a useful feature, this PR implements the first step which is to update the maven-dependency-analyzer to return this information so that the maven-dependency-plugin can use it.

I introduced a new interface, DependencyAnalyzerWithUsages, to avoid breaking changes to the DependencyAnalyzer interface. I confirmed with the japi-compliance-checker that source and binary compatibility has been maintained:

➜  ~ perl japi-compliance-checker.pl -lib maven-dependency-analyzer -jdk-path $JAVA7_HOME -old ~/Downloads/maven-dependency-analyzer-1.6.jar -new ~/src/maven-shared-pr/maven-dependency-analyzer/target/maven-dependency-analyzer-1.7-SNAPSHOT.jar
using Java 1.7.0_75
WARNING: set 1st version number to 1.6 (use -v1 option to change it)
WARNING: set 2nd version number to 1.7-SNAPSHOT (use -v2 option to change it)
reading classes 1.6 ...
reading classes 1.7-SNAPSHOT ...
comparing classes ...
creating compatibility report ...
result: COMPATIBLE
total "Binary" compatibility problems: 0, warnings: 0
total "Source" compatibility problems: 0, warnings: 0
see detailed report:
  compat_reports/maven-dependency-analyzer/1.6_to_1.7-SNAPSHOT/compat_report.html

I'd love to hear any thoughts or feedback you have, thanks!

[michael-o]

@rfscholte Is this something you can review?

[rfscholte]

New features like this deserve at least one or more tests.
Regarding the code, I don't think it deserves a new interface, since it is very very likely this library contains the only implementations of the DependencyAnalyzer, so let's just add the new method here.
Also, don't use @version $Id$ in javadoc anymore, nor ROLE: these are leftovers from ancient times and not used anymore.

[jhaber]

Thanks for reviewing the PR, I have updated it based on your suggestions. With regard to testing, DefaultProjectDependencyAnalyzer was updated to use the new functionality internally. So I'm largely relying on its existing test suite (DefaultProjectDependencyAnalyzerTest) to validate the correctness of the refactoring. I have also added assertions to these tests to flex the new methods and verify that the returned DependencyUsages have the expect values