Improve documentation of `classpath.idx` file and its generation by the Maven and Gradle plugins

[davidmichaelkarr]

The "classpath.idx" file allows for the possibility of controlling the artifact load order. In reality, it's completely impractical to do anything with this.

The entries in the file are in the form of "artifactname-version.jar". In a Maven application, it would be extremely awkward to have a local copy of this file in the project and cause that file to be used instead of the generated one, for multiple reasons.

The Spring-boot-maven-plugin really needs an interface for manipulating the content of this file, but not necessarily the entire file.

One reason someone might need to control the order of these artifacts is if two or more artifacts have the same FQCN, with different content. Obviously, that's a bad situation, and artifacts like that likely would be considered to be defective, but that's no consolation if you have no choice but to use them.

At a minimum, to deal with this particular situation, I would want to be able to specify a list of GA pairs, with the implication that the order of those pairs should reflect the ordering of those pairs in the classpath.idx file. There may be other artifacts in between, but for instance, if I had artifact "Foo" first in the list, and artifact "Bar" second in the list, in the resulting "classpath.idx" file, the entry for "Foo-version.jar" needs to be before the entry for "Bar-version.jar".

[wilkinsona]

It isn't intended for the classpath.idx to be user-written. Instead, it's generated at build time with its contents being determined by the classpath that's generated by Maven or Gradle. The index is then used at runtime to ensure that this ordering is honoured, even when a jar's been exploded and the file system may have re-ordered its contents alphabetically.

As a Maven user, if you want to change the ordering of entries in classpath.idx you should update your pom. Dependencies declared earlier (nearer the top) of your pom will appear earlier in the index file. These changes will also be reflected in the classpath that's used for mvn spring-boot:run and when Maven executes your application's tests.

We should update the documentation to clarify this.

[davidmichaelkarr]

I had assumed that the order in the dependencies list in the pom.xml would control this, but it had no effect. I think the behavior of this might differ between "top-level" dependencies, specified directly in the pom.xml, and transient dependencies of those top-level dependencies. When I moved the "top-level" dependency that has a transient dependency on an artifact I needed to be reordered, it didn't matter whether I had that "top-level" dependency at the top of the list or the bottom of the list, it didn't change the ordering of the transient dependencies I needed to control.

[wilkinsona]

If those transitive dependencies share the same top-level dependency, moving the top-level dependency will indeed have no effect on the ordering of the transitive dependencies. To have an effect, you would have to declare those transitive dependencies directly in the pom in the desired order. Note that this isn't specific to Spring Boot, it's Maven's standard behavior, and the Maven pom is the right place to fix it as then it'll fix the ordering of the classpath for tests as well.

[davidmichaelkarr]

Do you think that specifying those transient dependencies in the dependencyManagement section of the parent pom would have an effect? The "top-level" dependencies are specified in the parent pom, but not the particular transient dependencies.

[wilkinsona]

I don't believe it does, but you could experiment to get a definitive answer.