GH-578 - Support for nested application modules.

The ApplicationModules bootstrap now triggers the module base package detection, followed by a new, additional pass of detecting nested application module packages. Those packages are now added to the ones we create ApplicationModule instances for and also handed into the module instance creation step as exclusions to make sure that parent modules do not include code residing in sub-modules.

Each module now operates on the Classes instance obtained from the JavaPackage instance that constitutes the module's base package but filtered by the given exclusions.

Author: odrotbohm

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

@@ -18,12 +18,14 @@
 import static com.tngtech.archunit.base.DescribedPredicate.*;
 import static com.tngtech.archunit.core.domain.JavaClass.Predicates.*;
 import static java.lang.System.*;
+import static java.util.Comparator.*;
 import static org.springframework.modulith.core.SyntacticSugar.*;
 import static org.springframework.modulith.core.Types.JavaXTypes.*;
 import static org.springframework.modulith.core.Types.SpringDataTypes.*;
 import static org.springframework.modulith.core.Types.SpringTypes.*;
 
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -57,12 +59,15 @@
  *
  * @author Oliver Drotbohm
  */
-public class ApplicationModule {
+public class ApplicationModule implements Comparable<ApplicationModule> {
 
 	/**
 	 * The base package of the {@link ApplicationModule}.
 	 */
 	private final JavaPackage basePackage;
+	private final Classes classes;
+	private final JavaPackages exclusions;
+
 	private final ApplicationModuleInformation information;
 
 	/**
@@ -77,25 +82,31 @@ public class ApplicationModule {
 	private final Supplier<List<JavaClass>> valueTypes;
 	private final Supplier<List<EventType>> publishedEvents;
 
+	ApplicationModule(JavaPackage basePackage, boolean useFullyQualifiedModuleNames) {
+		this(basePackage, JavaPackages.NONE, useFullyQualifiedModuleNames);
+	}
+
 	/**
 	 * Creates a new {@link ApplicationModule} for the given base package and whether to use fully-qualified module names.
 	 *
 	 * @param basePackage must not be {@literal null}.
 	 * @param useFullyQualifiedModuleNames
 	 */
-	ApplicationModule(JavaPackage basePackage, boolean useFullyQualifiedModuleNames) {
+	ApplicationModule(JavaPackage basePackage, JavaPackages exclusions, boolean useFullyQualifiedModuleNames) {
 
 		Assert.notNull(basePackage, "Base package must not be null!");
 
 		this.basePackage = basePackage;
+		this.exclusions = exclusions;
+		this.classes = basePackage.getClasses(exclusions);
 		this.information = ApplicationModuleInformation.of(basePackage);
 		this.namedInterfaces = isOpen()
 				? NamedInterfaces.forOpen(basePackage)
 				: NamedInterfaces.discoverNamedInterfaces(basePackage);
 		this.useFullyQualifiedModuleNames = useFullyQualifiedModuleNames;
 
-		this.springBeans = SingletonSupplier.of(() -> filterSpringBeans(basePackage));
-		this.aggregateRoots = SingletonSupplier.of(() -> findAggregateRoots(basePackage));
+		this.springBeans = SingletonSupplier.of(() -> filterSpringBeans(classes));
+		this.aggregateRoots = SingletonSupplier.of(() -> findAggregateRoots(classes));
 		this.valueTypes = SingletonSupplier
 				.of(() -> findArchitecturallyEvidentType(ArchitecturallyEvidentType::isValueObject));
 		this.publishedEvents = SingletonSupplier.of(() -> findPublishedEvents());
@@ -275,7 +286,7 @@ public ArchitecturallyEvidentType getArchitecturallyEvidentType(Class<?> type) {
 	}
 
 	public boolean contains(JavaClass type) {
-		return basePackage.contains(type);
+		return classes.contains(type);
 	}
 
 	public boolean contains(@Nullable Class<?> type) {
@@ -292,7 +303,7 @@ public Optional<JavaClass> getType(String candidate) {
 
 		Assert.hasText(candidate, "Candidate must not be null or emtpy!");
 
-		return basePackage.stream()
+		return classes.stream()
 				.filter(hasSimpleOrFullyQualifiedName(candidate))
 				.findFirst();
 	}
@@ -366,6 +377,19 @@ public String toString(@Nullable ApplicationModules modules) {
 		builder.append("> Logical name: ").append(getName()).append('\n');
 		builder.append("> Base package: ").append(basePackage.getName()).append('\n');
 
+		builder.append("> Excluded packages: ");
+
+		if (!exclusions.iterator().hasNext()) {
+			builder.append("none").append('\n');
+		} else {
+
+			builder.append('\n');
+
+			exclusions.stream().forEach(it -> {
+				builder.append("  - ").append(it.getName()).append('\n');
+			});
+		}
+
 		if (namedInterfaces.hasExplicitInterfaces()) {
 
 			builder.append("> Named interfaces:\n");
@@ -510,12 +534,21 @@ public int hashCode() {
 				useFullyQualifiedModuleNames, valueTypes);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Comparable#compareTo(java.lang.Object)
+	 */
+	@Override
+	public int compareTo(ApplicationModule o) {
+		return getBasePackage().compareTo(o.getBasePackage());
+	}
+
 	private List<EventType> findPublishedEvents() {
 
 		DescribedPredicate<JavaClass> isEvent = implement(JMoleculesTypes.DOMAIN_EVENT) //
 				.or(isAnnotatedWith(JMoleculesTypes.AT_DOMAIN_EVENT));
 
-		return basePackage.that(isEvent).stream() //
+		return classes.that(isEvent).stream() //
 				.map(EventType::new).toList();
 	}
 
@@ -537,7 +570,7 @@ private Stream<JavaClass> resolveModuleSuperTypes(JavaClass type) {
 
 	private Stream<QualifiedDependency> getAllModuleDependencies(ApplicationModules modules) {
 
-		return basePackage.stream() //
+		return classes.stream() //
 				.flatMap(it -> getModuleDependenciesOf(it, modules));
 	}
 
@@ -590,7 +623,7 @@ private boolean isDependencyToOtherModule(JavaClass dependency, ApplicationModul
 		return modules.contains(dependency) && !contains(dependency);
 	}
 
-	private Classes findAggregateRoots(JavaPackage source) {
+	private Classes findAggregateRoots(Classes source) {
 
 		return source.stream() //
 				.map(it -> ArchitecturallyEvidentType.of(it, getSpringBeansInternal()))
@@ -599,11 +632,71 @@ private Classes findAggregateRoots(JavaPackage source) {
 				.collect(Classes.toClasses());
 	}
 
+	/**
+	 * Returns the current module's immediate parent module, if present.
+	 *
+	 * @param modules must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.3
+	 */
+	Optional<ApplicationModule> getParentModule(ApplicationModules modules) {
+
+		Assert.notNull(modules, "ApplicationModules must not be null!");
+
+		var byPackageDepth = comparing(ApplicationModule::getBasePackage, JavaPackage.reverse());
+
+		return modules.stream()
+				.filter(it -> basePackage.isSubPackageOf(it.getBasePackage()))
+				.sorted(byPackageDepth)
+				.findFirst();
+	}
+
+	/**
+	 * Returns the {@link ApplicationModule}s directly nested inside the current one.
+	 *
+	 * @param modules must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.3
+	 */
+	Collection<ApplicationModule> getDirectlyNestedModules(ApplicationModules modules) {
+
+		Assert.notNull(modules, "ApplicationModules must not be null!");
+
+		return doGetNestedModules(modules, false);
+	}
+
+	/**
+	 * Returns all of the current {@link ApplicationModule}'s nested {@link ApplicationModule}s including ones contained
+	 * in nested modules in turn.
+	 *
+	 * @param modules must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.3
+	 */
+	Collection<ApplicationModule> getNestedModules(ApplicationModules modules) {
+
+		Assert.notNull(modules, "ApplicationModules must not be null!");
+
+		return doGetNestedModules(modules, true);
+	}
+
 	private String getQualifiedName(NamedInterface namedInterface) {
 		return namedInterface.getQualifiedName(getName());
 	}
 
-	private static Classes filterSpringBeans(JavaPackage source) {
+	private Collection<ApplicationModule> doGetNestedModules(ApplicationModules modules, boolean recursive) {
+
+		var result = modules.stream()
+				.filter(it -> it.getParentModule(modules).filter(this::equals).isPresent());
+
+		if (recursive) {
+			result = result.flatMap(it -> Stream.concat(Stream.of(it), it.getNestedModules(modules).stream()));
+		}
+
+		return result.toList();
+	}
+
+	private static Classes filterSpringBeans(Classes source) {
 
 		Map<Boolean, List<JavaClass>> collect = source.that(isConfiguration()).stream() //
 				.flatMap(it -> it.getMethods().stream()) //
@@ -632,7 +725,7 @@ private List<JavaClass> findArchitecturallyEvidentType(Predicate<Architecturally
 
 		var springBeansInternal = getSpringBeansInternal();
 
-		return basePackage.stream()
+		return classes.stream()
 				.map(it -> ArchitecturallyEvidentType.of(it, springBeansInternal))
 				.filter(selector)
 				.map(ArchitecturallyEvidentType::getType)
@@ -907,6 +1000,9 @@ static class QualifiedDependency {
 
 		private static final List<String> INJECTION_TYPES = Arrays.asList(AT_AUTOWIRED, AT_RESOURCE, AT_INJECT);
 
+		private static final String INVALID_SUB_MODULE_REFERENCE = "Invalid sub-module reference from module '%s' to module '%s' (via %s -> %s)!";
+		private static final String INTERNAL_REFERENCE = "Module '%s' depends on non-exposed type %s within module '%s'!";
+
 		private final JavaClass source, target;
 		private final String description;
 		private final DependencyType type;
@@ -1045,13 +1141,41 @@ Violations isValidDependencyWithin(ApplicationModules modules) {
 
 			if (!targetModule.isExposed(target)) {
 
-				var violationText = "Module '%s' depends on non-exposed type %s within module '%s'!"
+				var violationText = INTERNAL_REFERENCE
 						.formatted(originModule.getName(), target.getName(), targetModule.getName());
 
 				return violations.and(new Violation(violationText + lineSeparator() + description));
 			}
 
-			return violations;
+			// Parent child relationships
+
+			var targetParent = targetModule.getParentModule(modules);
+
+			if (targetParent.isEmpty()) {
+				return violations;
+			}
+
+			var originParent = originModule.getParentModule(modules);
+
+			if (targetParent.isPresent()) {
+
+				var resolved = targetParent.get();
+
+				if (resolved.equals(originModule)) {
+					return violations;
+				}
+
+				if (originParent.isPresent() && originParent.get().equals(targetModule)) {
+					return violations;
+				}
+			}
+
+			var violationText = INVALID_SUB_MODULE_REFERENCE
+					.formatted(originModule.getName(), targetModule.getName(),
+							FormatableType.of(source).getAbbreviatedFullName(originModule),
+							FormatableType.of(target).getAbbreviatedFullName(targetModule));
+
+			return violations.and(new Violation(violationText));
 		}
 
 		ApplicationModule getExistingModuleOf(JavaClass javaClass, ApplicationModules modules) {