Allow detecting `NamedInterfaces` programmatically

[PinkMoustacheMan]

Proposal

Sprign Modulith already allows for customizing the ruleset to detect modules in your application (ApplicationModuleDetectionStrategy).
I think it would be a good idea to also allow adding custom rules to detect (and name) NamedInterfaces.

Why would this be a good feature?

Many REST APIs (and also other types of Spring applications) seem to use a slightly different package structure than the one being proposed by Spring Modulith currently.
Spring Modulith assumes all publicly exposed classes should be at the root level of the module and all internal classes should be in an internal package. However, a common way of structuring Web applications is to add subpackages to the root module's package which contain mappers, services, models, repositories and controllers respectively. These packages in many cases would be considered part of the public API, but because they are nested inside of another package, Spring Modulith does not recognize them as such.

Why the current way of declaring NamedInterfaces this is sub-optimal

The current way to "fix" this issue is to add a class (usually a package-info.java) that is annotated with @NamedInterface. This however puts a lot more visual clutter into a codebase if included in every package that needs it (~5 per domain).
A more centralized way of declaring rules as to when a package should be considered a named interface would be one way of reducing this clutter, very similar to the ApplicationModuleDetectionStrategy for module detection.

[PinkMoustacheMan]

This issue probably relates to #167 as they would benefit from a simpler way of declaring the structure of modules.

[odrotbohm]

I have a prototype here locally that adds a

NamedInterfaces detectNamedInterfaces(JavaPackage basePackage, ApplicationModuleInformation information)

to ApplicationModuleDetectionStrategy defaulting to the current algorithm. That said, for users to be able to properly implement the method, we now also need to expose the factory methods on NamedInterface(s) that have been package protected so far. To not throw out the baby with the bath water, what detection patterns do you assume you'd be using to create the set of NamedInterfaces from a package? Is it detecting sub-packages by naming convention? NamedInterface.of(JavaPackage) currently rejects packages not annotated, so I guess we'll have to relax our assumptions a little bit here.

Also, a NamedInterface can be established from annotating types. Would you think, manually selecting those should be possible, too? To allow picking up the defaults anyway (particularly the unnamed named interface) I think we'll have to expose a few of the default lookup mechanisms, too. So I wonder which of autodetection you'd expect to be active or at least easily accessible when implementing custom strategies.

[PinkMoustacheMan]

To not throw out the baby with the bath water, what detection patterns do you assume you'd be using to create the set of NamedInterfaces from a package? Is it detecting sub-packages by naming convention?

I would like to detect both modules as well as named interfaces using the local names of packages as this method does give you a great deal of customizability (although one shouldn't create needlessly complex structures).
Code example:

class CustomApplicationModuleDetectionStrategy implements ApplicationModuleDetectionStrategy {

    private static final List<String> NAMED_INTERFACE_PACKAGE_NAMES =
        List.of("mapper", "model", "repository", "service", "web");

    private static final List<String> INTERNAL_PACKAGE_NAME =
        List.of("internal");

    @Override
    public Stream<JavaPackage> getModuleBasePackages(JavaPackage basePackage) {
        return getAllNestedSubPackages(basePackage)
            .filter(subPackage -> !isInternalPackage(basePackage, subPackage) && !isNamedInterfacePackage(basePackage, subPackage));
    }

    // Hypothetical method
    @Override
    public Stream<JavaPackage> getNamedInterfaceBasePackages(JavaPackage basePackage) {
        return getAllNestedSubPackages(basePackage)
            .filter(subPackage -> isNamedInterfacePackage(basePackage, subPackage));
    }

    private static Stream<JavaPackage> getAllNestedSubPackages(JavaPackage basePackage) {
        Stream<JavaPackage> directSubPackages = basePackage.getDirectSubPackages().stream();
        Stream<JavaPackage> nestedSubPackages =
            basePackage.getDirectSubPackages().stream().flatMap(CustomApplicationModuleDetectionStrategy::getAllNestedSubPackages);
        return Stream.concat(directSubPackages, nestedSubPackages);
    }

    private static boolean isNamedInterfacePackage(JavaPackage basePackage, JavaPackage subPackage) {
        final String subPackageName = basePackage.getTrailingName(subPackage);
        return NAMED_INTERFACE_PACKAGE_NAMES.stream().anyMatch(subPackageName::contains);
    }

    private static boolean isInternalPackage(JavaPackage basePackage, JavaPackage subPackage) {
        final String subPackageName = basePackage.getTrailingName(subPackage);
        return INTERNAL_PACKAGE_NAME.stream().anyMatch(subPackageName::contains);
    }
}

Using this idea I can create my packages as I would do normally as well as customize all named interfaces contained within the modules.
I am not suggesting that this is the best way of detecting modules and named interfaces, but it would work very well for the project structure I described, including sub-modules as well as internal packages.

Also, a named interface can be established from annotating types. Would you think, manually selecting those should be possible, too?

That can of course be used (and I did forget about that), but that would just mean adding one more annotation to a class that already contains 1-5 of them (depending on if Lombok is used).
It also puts additional architectural burden on classes that aren't related to the architecture definition (especially because the automatic name detection only works when using the annotation on packages, so you have to declare a name).

So I wonder which of autodetection you'd expect to be active or at least easily accessible when implementing custom strategies.

My idea of this API expects explicit declarations of modules and named interfaces to override this custom strategy whilst ignoring any other automatic detection that may be present.

[odrotbohm]

What if you could write your detection algorithm as follows:

class MyCustomStrategy implements AppplicationModuleDetectionStrategy {

  @Override
  NamedInterfaces detectNamedInterfaces(JavaPackage basePackage, ApplicationModuleInformation information) {

    return NamedInterfaces.builder(basePackage)
      .excluding("internal")
      .matching("mapper", "model", "repository", "services", "web")
   // .matching(Predicate<JavaPackage>) // more flexible variant, would see all candidate packages, except excluded ones
      .recursive() // also considers packages below nested packages
      .build();
  }
}

[odrotbohm]

I just realized that you only need the exclusions during the module base package detection phase. With a couple more API tweaks, we still could reduce the code you need to this:

class CustomApplicationModuleDetectionStrategy implements ApplicationModuleDetectionStrategy {

    private static final List<String> NAMED_INTERFACE_PACKAGE_NAMES = List.of("mapper", "model", "repository", "service", "web");
    private static final List<String> INTERNAL_PACKAGE_NAME = List.of("internal");

    @Override
    public Stream<JavaPackage> getModuleBasePackages(JavaPackage basePackage) {

        var allExclusions = Stream.concat(NAMED_INTERFACE_PACKAGE_NAMES.stream(), INTERNAL_PACKAGE_NAME.stream());

        //                 New method to be introduced on JavaPackage
        return basePackage.getSubPackagesMatching((pkg, trailingName) -> allExclusions.noneMatch(trailingName::contains));
    }

    @Override
    public NamedInterfaces detectNamedInterfaces(JavaPackage basePackage, ApplicationModuleInformation information) {

        return NamedInterfaces.builder(basePackage)
            .matching(NAMED_INTERFACE_PACKAGE_NAMES)
            .recursive()
            .build();
    }
}

[PinkMoustacheMan]

I like the API design.

To make sure, however, that no weird behaviour is experienced and that the exact specifications of named interface (and module) detection are defined, I would like to clearly outline some constraints to these APIs.
Feel free to add/change/remove rules as makes sense.

• An ApplicationModule-package can only be placed either alongside the Spring Application class or be directly contained within another module-package.
• A NamedInterface-package can only be placed either directly within an ApplicationModule-package or another NamedInterface-package
• A module-internal package can only be placed directly within an ApplicationModule-package, a NamedInterface-package, or another module-internal package.

These constraints (hopefully) ensure correct usage of nested packages of any kind.

I do also hope that the .matching(Predicate<JavaPackage>) will be included, as it would allow for projects to define their packages with more freedom.

[odrotbohm]

• An ApplicationModule-package can only be placed either alongside the Spring Application class or be directly contained within another module-package.

The Javadoc of ApplicationModuleDetectionStrategy is already clear about the selection process. The responsibility of the method is to select packages to become base packages of application modules. That said, this doesn't mean that application modules have to reside in that package space. Spring Modulith 1.3 introduced ApplicationModuleSourceFactory, which allows contributing additional root packages (to get a AMDS applied) or even application module base packages directly, all of which can exist anywhere in the package space.

• A NamedInterface-package can only be placed either directly within an ApplicationModule-package or another NamedInterface-package

I think that is obvious from the method signature, as you only have access to the package tree starting at the application module's base package. I'll refine the Javadoc of the method to be introduced to mention the builder API and hint at the selection process.

• A module-internal package can only be placed directly within an ApplicationModule-package, a NamedInterface-package, or another module-internal package.

That's kind of obvious, too, as modules (currently) have a single base package and all code included in that and nested packages is considered part of that module, unless a nested module is detected.

There's a tension here between being very explicit about the general rules, trying to create an all-encompassing definition covering all aspects. That said, trying to do so and cover all edge cases is likely to result in a lot of prose that might actually cause more confusion than clarity. Especially for folks that follow the defaults and might not even care about named interfaces in the first place.

[odrotbohm]

This change is available in 1.4.0-SNAPSHOTs. Please give them a spin if you have the chance.