Walkthrough

Nicolai Parlog edited this page Dec 2, 2015 · 1 revision
Clone this wiki locally

First Blood :punch:

To get a first impression how you're doing JDK-internal-wise simply run JDeps Mvn:

mvn clean compile org.codefx.mvn:jdeps-maven-plugin:jdkinternals

This will log every dependency jdeps reports to the console (on level WARN).

Killing Streak :+1:

If the result is shocking enough to keep you from immediately fixing all the problems, you might want to integrate JDeps Mvn in your build. Adding this to your pom yields the same result as above but on every run:

<plugin>
	<groupId>org.codefx.mvn</groupId>
	<artifactId>jdeps-maven-plugin</artifactId>
	<version>0.2</version>
	<executions>
		<execution>
			<configuration>
				<!-- define known and acceptable dependencies here (see below) -->
			</configuration>
			<goals>
				<goal>jdkinternals</goal>
			</goals>
		</execution>
	</executions>
</plugin>

To explicitly run this plugin you can do one of these:

mvn clean compile jdeps:jdkinternals # just this plugin
mvn verify # everything up to the phase in which this plugin runs

But we're all too good in ignoring log messages so let's see what's next.

Godlike :clap:

Let's configure JDeps Mvn for a self-paced migration away from the known dependencies. For that we'll want to be informed about the progress of eradicating them while preventing accidental relapses.

The first step is the creation of rules, which tell JDeps Mvn how to react to specific dependencies. We will use rules to get warnings for the currently existing dependencies. The next step is to raise the bar and let the build fail for every other internal dependency that might crop up.

To Rule Them All

With this configuration JDeps Mvn will create a rule for each dependency it finds and write it to the specified file:

<configuration>
	<defaultSeverity>WARN</defaultSeverity>
	<outputRulesForViolations>true</outputRulesForViolations>
	<outputRuleFormat>ARROW</outputRuleFormat>
	<outputFilePath>path/to/dependency_rules.xml</outputFilePath>
</configuration>

There are different severities to choose from. Pick one which you like the most for your current dependencies. For the other parameters see here.

If you're running a multi project build and would like to just specify a single set of rules, make sure to use an absolute file path. All the rules for the different projects will then end up in that same file.

After a successful build you should see a bunch of rules in the file. They might look like this:

<arrowDependencyRules>
	<arrowRules>
		org.food.fruits.Mango -> sun.misc.BASE64Decoder: WARN
		org.food.fruits.Mango -> sun.misc.BASE64Encoder: WARN
		org.food.fruits.Banana -> sun.misc.Unsafe: WARN
	</arrowRules>
</arrowDependencyRules>

This means that you will get warnings for the dependencies of your Mango class on the BASE64 en-/decoder and of Banana on Unsafe.

You might want to edit the rules a little. See here for what they can look like (spoiler: you can also use packages) and how they are interpreted if more than one applies. When you're done, copy the rules into your pom.

As long as outputRulesForViolations is set to true JDeps Mvn will never break the build so make sure to turn it off when it's no longer needed. :boom:

Raising The Bar

This one is easy. Just set the default severity to FAIL:

<configuration>
	<defaultSeverity>FAIL</defaultSeverity>
	<arrowDependencyRules>
		<arrowRules>
			org.food.fruits.Mango -> sun.misc.BASE64Decoder: WARN
			org.food.fruits.Mango -> sun.misc.BASE64Encoder: WARN
			org.food.fruits.Banana -> sun.misc.Unsafe: WARN
		</arrowRules>
	</arrowDependencyRules>
</configuration>

Victory :v:

Done:exclamation:

In the future you will be warned about the configured dependencies but the build will fail loudly if any others are identified. Now you can work your way through them and remove them one by one without fear of accidental relapses.