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.

The bootstrap of ApplicationModules now uses a dedicated ApplicationModuleSource to allow calculating a default module name relative to the application base package.

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

pom.xml

@@ -299,11 +299,11 @@ limitations under the License.
 							<extensions>true</extensions>
 							<configuration>
 								<packages>
-									<package>@antora/atlas-extension@1.0.0-alpha.1</package>
-									<package>@antora/collector-extension@1.0.0-alpha.3</package>
-									<package>@asciidoctor/tabs@1.0.0-beta.3</package>
-									<package>@springio/antora-extensions@1.5.0</package>
-									<package>@springio/asciidoctor-extensions@1.0.0-alpha.9</package>
+									<package>@antora/atlas-extension@1.0.0-alpha.2</package>
+									<package>@antora/collector-extension@1.0.0-beta.2</package>
+									<package>@asciidoctor/tabs@1.0.0-beta.6</package>
+									<package>@springio/antora-extensions@1.13.1</package>
+									<package>@springio/asciidoctor-extensions@1.0.0-alpha.12</package>
 									<package>asciidoctor-kroki</package>
 								</packages>
 								<playbook>../src/docs/antora/antora-playbook.yml</playbook>

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,45 +59,62 @@
  *
  * @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;
 
 	/**
 	 * All {@link NamedInterfaces} of the {@link ApplicationModule} either declared explicitly via {@link NamedInterface}
 	 * or implicitly.
 	 */
 	private final NamedInterfaces namedInterfaces;
-	private final boolean useFullyQualifiedModuleNames;
+	private final ApplicationModuleSource source;
 
 	private final Supplier<Classes> springBeans;
 	private final Supplier<Classes> aggregateRoots;
 	private final Supplier<List<JavaClass>> valueTypes;
 	private final Supplier<List<EventType>> publishedEvents;
 
+	/**
+	 * Creates a new {@link ApplicationModule} from the given {@link ApplicationModuleSource}.
+	 *
+	 * @param source must not be {@literal null}.
+	 */
+	ApplicationModule(ApplicationModuleSource source) {
+		this(source, JavaPackages.NONE);
+	}
+
 	/**
 	 * 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
+	 * @param source must not be {@literal null}.
+	 * @param exclusions must not be {@literal null}.
 	 */
-	ApplicationModule(JavaPackage basePackage, boolean useFullyQualifiedModuleNames) {
+	ApplicationModule(ApplicationModuleSource source, JavaPackages exclusions) {
 
-		Assert.notNull(basePackage, "Base package must not be null!");
+		Assert.notNull(source, "Base package must not be null!");
+		Assert.notNull(exclusions, "Exclusions must not be null!");
 
+		JavaPackage basePackage = source.moduleBasePackage();
+
+		this.source = source;
 		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());
@@ -125,7 +144,7 @@ public NamedInterfaces getNamedInterfaces() {
 	 * @return will never be {@literal null} or empty.
 	 */
 	public String getName() {
-		return useFullyQualifiedModuleNames ? basePackage.getName() : basePackage.getLocalName();
+		return source.moduleName();
 	}
 
 	/**
@@ -274,10 +293,20 @@ public ArchitecturallyEvidentType getArchitecturallyEvidentType(Class<?> type) {
 						FormatableType.of(type).getAbbreviatedFullName(this), getName())));
 	}
 
+	/**
+	 * Returns whether the current module contains the given type.
+	 *
+	 * @param type must not be {@literal null}.
+	 */
 	public boolean contains(JavaClass type) {
-		return basePackage.contains(type);
+		return classes.contains(type);
 	}
 
+	/**
+	 * Returns whether the current module contains the given type.
+	 *
+	 * @param type can be {@literal null}.
+	 */
 	public boolean contains(@Nullable Class<?> type) {
 		return type != null && getType(type.getName()).isPresent();
 	}
@@ -292,7 +321,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();
 	}
@@ -363,9 +392,28 @@ public String toString(@Nullable ApplicationModules modules) {
 
 		builder.append("\n");
 
+		if (modules != null) {
+			modules.getParentOf(this).ifPresent(it -> {
+				builder.append("> Parent module: ").append(it.getName()).append("\n");
+			});
+		}
+
 		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");
@@ -475,6 +523,23 @@ boolean isOpen() {
 		return information.isOpen();
 	}
 
+	/**
+	 * Returns whether the given type is contained in any of the parent modules of the current one.
+	 *
+	 * @param type must not be {@literal null}.
+	 * @param modules must not be {@literal null}.
+	 * @since 1.3
+	 */
+	boolean containsTypeInAnyParent(JavaClass type, ApplicationModules modules) {
+
+		Assert.notNull(type, "Type must not be null!");
+		Assert.notNull(modules, "ApplicationModules must not be null!");
+
+		return modules.getParentOf(this)
+				.filter(it -> it.contains(type) || it.containsTypeInAnyParent(type, modules))
+				.isPresent();
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Object#equals(java.lang.Object)
@@ -490,13 +555,13 @@ public boolean equals(Object obj) {
 			return false;
 		}
 
-		return Objects.equals(this.basePackage, that.basePackage) //
+		return Objects.equals(this.source, that.source)
+				&& Objects.equals(this.basePackage, that.basePackage) //
 				&& Objects.equals(this.aggregateRoots, that.aggregateRoots) //
 				&& Objects.equals(this.information, that.information) //
 				&& Objects.equals(this.namedInterfaces, that.namedInterfaces) //
 				&& Objects.equals(this.publishedEvents, that.publishedEvents) //
 				&& Objects.equals(this.springBeans, that.springBeans) //
-				&& Objects.equals(this.useFullyQualifiedModuleNames, that.useFullyQualifiedModuleNames) //
 				&& Objects.equals(this.valueTypes, that.valueTypes);
 	}
 
@@ -506,16 +571,25 @@ public boolean equals(Object obj) {
 	 */
 	@Override
 	public int hashCode() {
-		return Objects.hash(basePackage, aggregateRoots, information, namedInterfaces, publishedEvents, springBeans,
-				useFullyQualifiedModuleNames, valueTypes);
+		return Objects.hash(source, basePackage, aggregateRoots, information, namedInterfaces, publishedEvents, springBeans,
+				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 +611,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 +664,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 +673,78 @@ 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);
+	}
+
+	/**
+	 * @return the classes
+	 */
+	Classes getClasses() {
+		return classes;
+	}
+
 	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 +773,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 +1048,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;
@@ -1043,15 +1187,32 @@ Violations isValidDependencyWithin(ApplicationModules modules) {
 				return violations;
 			}
 
+			if (originModule.containsTypeInAnyParent(target, modules)) {
+				return violations;
+			}
+
 			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
+
+			return targetModule.getParentModule(modules)
+					.filter(it -> !it.equals(originModule))
+					.map(__ -> {
+
+						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));
+					})
+					.orElse(violations);
 		}
 
 		ApplicationModule getExistingModuleOf(JavaClass javaClass, ApplicationModules modules) {