Introduce fluent API to build named interfaces.

Primary selection criterion is the trailing package name and a flag to switch between

Author: odrotbohm

spring-modulith-core/src/main/java/org/springframework/modulith/core/JavaPackage.java

@@ -28,6 +28,7 @@
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
+import java.util.function.BiPredicate;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
@@ -197,6 +198,23 @@ public Stream<JavaPackage> getSubPackagesAnnotatedWith(Class<? extends Annotatio
 				.map(it -> of(classes, it));
 	}
 
+	/**
+	 * Returns all sub-packages that match the given {@link BiPredicate} for the canidate package and its trailing name
+	 * relative to the current one.
+	 *
+	 * @param filter must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @see #getTrailingName(JavaPackage)
+	 * @since 1.4
+	 */
+	public Stream<JavaPackage> getSubPackagesMatching(BiPredicate<JavaPackage, String> filter) {
+
+		Assert.notNull(filter, "Filter must not be null!");
+
+		return getSubPackages().stream()
+				.filter(it -> filter.test(it, this.getTrailingName(it)));
+	}
+
 	/**
 	 * Returns all {@link Classes} that match the given {@link DescribedPredicate}.
 	 *

spring-modulith-core/src/main/java/org/springframework/modulith/core/NamedInterfaces.java

@@ -16,11 +16,13 @@
 package org.springframework.modulith.core;
 
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.Iterator;
 import java.util.List;
 import java.util.Optional;
+import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -82,6 +84,10 @@ public static NamedInterfaces discoverNamedInterfaces(JavaPackage basePackage) {
 				.and(ofAnnotatedTypes(basePackage.getClasses()));
 	}
 
+	public static Builder builder(JavaPackage basePackage) {
+		return new Builder(basePackage, false, __ -> false, __ -> false);
+	}
+
 	/**
 	 * Creates a new {@link NamedInterfaces} for the given {@link NamedInterface}s.
 	 *
@@ -280,4 +286,64 @@ private static List<NamedInterface> ofAnnotatedTypes(Classes classes) {
 				.map(entry -> NamedInterface.of(entry.getKey(), Classes.of(entry.getValue()))) //
 				.toList();
 	}
+
+	public static class Builder {
+
+		private final JavaPackage basePackage;
+		private final boolean recursive;
+		private final Predicate<JavaPackage> inclusions, exclusions;
+
+		private Builder(JavaPackage basePackage, boolean recursive, Predicate<JavaPackage> predicate,
+				Predicate<JavaPackage> exclusions) {
+
+			this.basePackage = basePackage;
+			this.recursive = recursive;
+			this.inclusions = predicate;
+			this.exclusions = exclusions;
+		}
+
+		public Builder recursive() {
+			return new Builder(basePackage, true, inclusions, exclusions);
+		}
+
+		public Builder matching(String... names) {
+			return matching(List.of(names));
+		}
+
+		public Builder matching(Collection<String> names) {
+			return matching(matchesTrailingName(names));
+		}
+
+		public Builder matching(Predicate<JavaPackage> predicate) {
+			return new Builder(basePackage, recursive, predicate, exclusions);
+		}
+
+		public Builder excluding(String... names) {
+
+			var exclusions = Predicate.not(matchesTrailingName(List.of(names)));
+
+			return new Builder(basePackage, recursive, inclusions, exclusions);
+		}
+
+		private Predicate<JavaPackage> matchesTrailingName(Collection<String> names) {
+
+			return it -> {
+
+				var trailingName = new PackageName(basePackage.getTrailingName(it));
+
+				return names.stream().anyMatch(trailingName::nameContainsOrMatches);
+			};
+		}
+
+		public NamedInterfaces build() {
+
+			var packages = recursive
+					? basePackage.getSubPackages().stream()
+					: basePackage.getDirectSubPackages().stream();
+
+			return packages.filter(inclusions)
+					.map(it -> NamedInterface.of(basePackage.getTrailingName(it), it.getClasses()))
+					.collect(Collectors.collectingAndThen(Collectors.toUnmodifiableList(), NamedInterfaces::new));
+		}
+	}
 }

spring-modulith-core/src/main/java/org/springframework/modulith/core/PackageName.java

@@ -15,6 +15,8 @@
  */
 package org.springframework.modulith.core;
 
+import java.util.stream.Stream;
+
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
@@ -162,6 +164,27 @@ boolean isEmpty() {
 		return length() == 0;
 	}
 
+	/**
+	 * Returns whether the package name contains a segment with the given candidate or matches the given expression
+	 * entirely. The latter is tested for if the expression contains a dot, indicating a multi-package match is requested.
+	 * Expressions generally support single character ({@literal ?}) and multi-character ({@literal *}) wildcards.
+	 *
+	 * @param candidate must not be {@literal null} or empty.
+	 * @since 1.4
+	 */
+	boolean nameContainsOrMatches(String candidate) {
+
+		Assert.hasText(candidate, "Expression must not be null or empty!");
+
+		var regex = candidate.replace(".", "\\.")
+				.replace("*", ".*")
+				.replace("?", ".");
+
+		return candidate.contains(".")
+				? name.matches(regex)
+				: Stream.of(segments).anyMatch(it -> it.matches(regex));
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Comparable#compareTo(java.lang.Object)

spring-modulith-core/src/test/java/org/springframework/modulith/core/CustomApplicationModuleDetectionStrategy.java

@@ -0,0 +1,30 @@
+package org.springframework.modulith.core;
+
+import java.util.List;
+import java.util.stream.Stream;
+
+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();
+	}
+}

spring-modulith-core/src/test/java/org/springframework/modulith/core/NamedInterfacesUnitTests.java

@@ -98,6 +98,37 @@ void detectsNamedInterfacesATypeIsContainedIn() {
 				.containsExactlyInAnyOrder("spi", "kpi");
 	}
 
+	@Test
+	void createsNamedInterfacesFromBuilder() {
+
+		JavaPackage pkg = TestUtils.getPackage(RootType.class);
+
+		var result = NamedInterfaces.builder(pkg)
+				.excluding("internal")
+				.matching("nested")
+				.build();
+
+		assertThat(result).hasSize(1)
+				.extracting(NamedInterface::getName)
+				.containsExactlyInAnyOrder("nested");
+	}
+
+	@Test
+	void createsNamedInterfacesFromRecursiveBuilder() {
+
+		JavaPackage pkg = TestUtils.getPackage(RootType.class);
+
+		var result = NamedInterfaces.builder(pkg)
+				.excluding("internal")
+				.matching("nested")
+				.recursive()
+				.build();
+
+		assertThat(result).hasSize(5)
+				.extracting(NamedInterface::getName)
+				.containsExactlyInAnyOrder("nested", "nested.a", "nested.b", "nested.b.first", "nested.b.second");
+	}
+
 	private static void assertInterfaceContains(NamedInterfaces interfaces, String name, Class<?>... types) {
 
 		var classNames = Arrays.stream(types).map(Class::getName).toArray(String[]::new);

spring-modulith-core/src/test/java/org/springframework/modulith/core/PackageNameUnitTests.java

@@ -55,4 +55,21 @@ void caculatesNestingCorrectly() {
 		assertThat(comAcme.contains(comAcmeA)).isTrue();
 		assertThat(comAcmeA.contains(comAcme)).isFalse();
 	}
+
+	@Test
+	void findsMatchingSegments() {
+
+		var source = new PackageName("com.acme.foo");
+
+		assertThat(source.nameContainsOrMatches("acme")).isTrue();
+		assertThat(source.nameContainsOrMatches("*me")).isTrue();
+		assertThat(source.nameContainsOrMatches("ac*")).isTrue();
+		assertThat(source.nameContainsOrMatches("*m.acme.foo")).isTrue();
+		assertThat(source.nameContainsOrMatches("*m.acme.?oo")).isTrue();
+		assertThat(source.nameContainsOrMatches("*m.ac*")).isTrue();
+		assertThat(source.nameContainsOrMatches("*m.*.fo*")).isTrue();
+
+		assertThat(source.nameContainsOrMatches("cm")).isFalse();
+
+	}
 }