GH-284 - Support for open application modules.

Application modules can now be declared as open, which causes internal components being exposed for access by other modules.

Author: odrotbohm

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

@@ -52,4 +52,37 @@
 	 * @see NamedInterface
 	 */
 	String[] allowedDependencies() default { OPEN_TOKEN };
+
+	/**
+	 * Declares the {@link Type} of the {@link ApplicationModule}
+	 *
+	 * @return will never be {@literal null}.
+	 * @since 1.2
+	 */
+	Type type() default Type.CLOSED;
+
+	/**
+	 * The type of an application module
+	 *
+	 * @author Oliver Drotbohm
+	 * @since 1.2
+	 */
+	enum Type {
+
+		/**
+		 * A closed application module exposes an API to other modules, but also allows to hide internals. Access to those
+		 * internals from other modules is sanctioned. Also, closed application modules must not be part of dependency
+		 * cycles.
+		 *
+		 * @see NamedInterface
+		 */
+		CLOSED,
+
+		/**
+		 * An open application module does not hide its internals, which means that access to those from other modules is
+		 * not sanctioned. They are also excluded from the cycle detection algorithm. All types contained in an open module
+		 * are part of the unnamed named interface.
+		 */
+		OPEN;
+	}
 }

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

@@ -86,7 +86,9 @@ public class ApplicationModule {
 
 		this.basePackage = basePackage;
 		this.information = ApplicationModuleInformation.of(basePackage);
-		this.namedInterfaces = NamedInterfaces.discoverNamedInterfaces(basePackage);
+		this.namedInterfaces = isOpen()
+				? NamedInterfaces.forOpen(basePackage)
+				: NamedInterfaces.discoverNamedInterfaces(basePackage);
 		this.useFullyQualifiedModuleNames = useFullyQualifiedModuleNames;
 
 		this.springBeans = SingletonSupplier.of(() -> filterSpringBeans(basePackage));
@@ -320,7 +322,7 @@ public Violations detectDependencies(ApplicationModules modules) {
 	/**
 	 * Returns whether the module is considered a root one, i.e., it is an artificial one created for each base package
 	 * configured.
-	 * 
+	 *
 	 * @return whether the module is considered a root one.
 	 * @since 1.1
 	 */
@@ -350,7 +352,13 @@ public String toString() {
 
 	public String toString(@Nullable ApplicationModules modules) {
 
-		var builder = new StringBuilder("# ").append(getDisplayName()).append("\n");
+		var builder = new StringBuilder("# ").append(getDisplayName());
+
+		if (isOpen()) {
+			builder.append(" (open)");
+		}
+
+		builder.append("\n");
 
 		builder.append("> Logical name: ").append(getName()).append('\n');
 		builder.append("> Base package: ").append(basePackage.getName()).append('\n');
@@ -454,6 +462,16 @@ boolean containsPackage(String packageName) {
 				|| packageName.startsWith(basePackageName + ".");
 	}
 
+	/**
+	 * Returns whether the module is considered open.
+	 *
+	 * @see org.springframework.modulith.ApplicationModule.Type
+	 * @since 1.2
+	 */
+	boolean isOpen() {
+		return information.isOpen();
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see java.lang.Object#equals(java.lang.Object)
@@ -964,8 +982,8 @@ Violations isValidDependencyWithin(ApplicationModules modules) {
 			var originModule = getExistingModuleOf(source, modules);
 			var targetModule = getExistingModuleOf(target, modules);
 
-			DeclaredDependencies declaredDependencies = originModule.getDeclaredDependencies(modules);
-			Violations violations = Violations.NONE;
+			var declaredDependencies = originModule.getDeclaredDependencies(modules);
+			var violations = Violations.NONE;
 
 			// Check explicitly defined allowed targets
 			if (!declaredDependencies.isAllowedDependency(target)) {
@@ -979,6 +997,10 @@ Violations isValidDependencyWithin(ApplicationModules modules) {
 
 			// No explicitly allowed dependencies - check for general access
 
+			if (targetModule.isOpen()) {
+				return violations;
+			}
+
 			if (!targetModule.isExposed(target)) {
 
 				var violationText = "Module '%s' depends on non-exposed type %s within module '%s'!"

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

@@ -21,8 +21,8 @@
 import java.util.function.Supplier;
 import java.util.stream.Stream;
 
-import org.jmolecules.ddd.annotation.Module;
 import org.springframework.modulith.ApplicationModule;
+import org.springframework.modulith.ApplicationModule.Type;
 import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.StringUtils;
@@ -68,6 +68,14 @@ default Optional<String> getDisplayName() {
 	 */
 	List<String> getDeclaredDependencies();
 
+	/**
+	 * Returns whether the module is considered open.
+	 *
+	 * @see org.springframework.modulith.ApplicationModule.Type
+	 * @since 1.2
+	 */
+	boolean isOpen();
+
 	/**
 	 * An {@link ApplicationModuleInformation} for the jMolecules {@link Module} annotation.
 	 *
@@ -111,6 +119,15 @@ public Optional<String> getDisplayName() {
 		public List<String> getDeclaredDependencies() {
 			return List.of(ApplicationModule.OPEN_TOKEN);
 		}
+
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.modulith.core.ApplicationModuleInformation#isOpenModule()
+		 */
+		@Override
+		public boolean isOpen() {
+			return false;
+		}
 	}
 
 	/**
@@ -167,5 +184,14 @@ public List<String> getDeclaredDependencies() {
 					.orElse(Stream.of(ApplicationModule.OPEN_TOKEN)) //
 					.toList();
 		}
+
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.modulith.core.ApplicationModuleInformation#isOpenModule()
+		 */
+		@Override
+		public boolean isOpen() {
+			return annotation.map(it -> it.type().equals(Type.OPEN)).orElse(false);
+		}
 	}
 }

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

@@ -24,6 +24,7 @@
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
@@ -810,6 +811,7 @@ private class ApplicationModulesSliceAssignment implements SliceAssignment {
 		public SliceIdentifier getIdentifierOf(JavaClass javaClass) {
 
 			return getModuleByType(javaClass)
+					.filter(Predicate.not(ApplicationModule::isOpen))
 					.map(ApplicationModule::getName)
 					.map(SliceIdentifier::of)
 					.orElse(SliceIdentifier.ignore());

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

@@ -44,6 +44,8 @@ public class NamedInterface implements Iterable<JavaClass> {
 	static final String UNNAMED_NAME = "<<UNNAMED>>";
 	private static final DescribedPredicate<CanBeAnnotated> ANNOTATED_NAMED_INTERFACE = //
 			isAnnotatedWith(org.springframework.modulith.NamedInterface.class);
+	private static final DescribedPredicate<JavaClass> ANNOTATED_NAMED_INTERFACE_PACKAGE = //
+			residesInPackageAnnotatedWith(org.springframework.modulith.NamedInterface.class);
 
 	private final String name;
 	private final Classes classes;
@@ -98,22 +100,26 @@ static NamedInterface of(String name, Classes classes) {
 	 * @param javaPackage must not be {@literal null}.
 	 * @return will never be {@literal null}.
 	 */
-	static NamedInterface unnamed(JavaPackage javaPackage) {
+	static NamedInterface unnamed(JavaPackage javaPackage, boolean flatten) {
 
-		var basePackageClasses = javaPackage.toSingle().getExposedClasses();
+		var basePackageClasses = (flatten ? javaPackage.toSingle() : javaPackage).getExposedClasses();
 
-		// Types that declare the annotation but no explicit name
-		var withDefaultedNamedInterface = basePackageClasses.stream()
-				.filter(ANNOTATED_NAMED_INTERFACE)
-				.filter(NamedInterface::withDefaultedNamedInterface)
-				.toList();
+		if (flatten) {
+
+			// Types that declare the annotation but no explicit name
+			var withDefaultedNamedInterface = basePackageClasses.stream()
+					.filter(ANNOTATED_NAMED_INTERFACE)
+					.filter(NamedInterface::withDefaultedNamedInterface)
+					.toList();
 
-		// Illegal in the base package
-		Assert.state(withDefaultedNamedInterface.isEmpty(),
-				() -> "Cannot use named interface defaulting for type(s) %s located in base package!"
-						.formatted(FormatableType.format(withDefaultedNamedInterface)));
+			// Illegal in the base package
+			Assert.state(withDefaultedNamedInterface.isEmpty(),
+					() -> "Cannot use named interface defaulting for type(s) %s located in base package!"
+							.formatted(FormatableType.format(withDefaultedNamedInterface)));
+		}
 
-		return new NamedInterface(UNNAMED_NAME, basePackageClasses.that(not(ANNOTATED_NAMED_INTERFACE)));
+		return new NamedInterface(UNNAMED_NAME, basePackageClasses
+				.that(not(ANNOTATED_NAMED_INTERFACE_PACKAGE).and(not(ANNOTATED_NAMED_INTERFACE))));
 	}
 
 	/**

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

@@ -63,7 +63,7 @@ private NamedInterfaces(List<NamedInterface> namedInterfaces) {
 	 */
 	static NamedInterfaces discoverNamedInterfaces(JavaPackage basePackage) {
 
-		return NamedInterfaces.of(NamedInterface.unnamed(basePackage))
+		return NamedInterfaces.of(NamedInterface.unnamed(basePackage, true))
 				.and(ofAnnotatedPackages(basePackage))
 				.and(ofAnnotatedTypes(basePackage));
 	}
@@ -94,6 +94,21 @@ static NamedInterfaces ofAnnotatedPackages(JavaPackage basePackage) {
 				.collect(Collectors.collectingAndThen(Collectors.toList(), NamedInterfaces::of));
 	}
 
+	/**
+	 * Creates a new {@link NamedInterface} consisting of the unnamed one containing all classes in the given
+	 * {@link JavaPackage}.
+	 *
+	 * @param basePackage must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.2
+	 */
+	static NamedInterfaces forOpen(JavaPackage basePackage) {
+
+		return NamedInterfaces.of(NamedInterface.unnamed(basePackage, false))
+				.and(ofAnnotatedPackages(basePackage))
+				.and(ofAnnotatedTypes(basePackage));
+	}
+
 	/**
 	 * Returns whether at least one explicit {@link NamedInterface} is declared.
 	 *

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

@@ -20,6 +20,7 @@
 import java.lang.annotation.Annotation;
 
 import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
 import com.tngtech.archunit.base.DescribedPredicate;
@@ -145,12 +146,32 @@ static DescribedPredicate<JavaClass> isSpringDataRepository() {
 		}
 	}
 
-	static DescribedPredicate<CanBeAnnotated> isAnnotatedWith(Class<?> type) {
+	static DescribedPredicate<CanBeAnnotated> isAnnotatedWith(Class<? extends Annotation> type) {
 		return isAnnotatedWith(type.getName());
 	}
 
 	static DescribedPredicate<CanBeAnnotated> isAnnotatedWith(String type) {
 		return Predicates.annotatedWith(type) //
 				.or(Predicates.metaAnnotatedWith(type));
 	}
+
+	/**
+	 * Creates a new {@link DescribedPredicate} to match classes
+	 *
+	 * @param type must not be {@literal null}.
+	 * @return will never be {@literal null}.
+	 * @since 1.2
+	 */
+	static DescribedPredicate<JavaClass> residesInPackageAnnotatedWith(Class<? extends Annotation> type) {
+
+		Assert.notNull(type, "Annotation type must not be null!");
+
+		return new DescribedPredicate<JavaClass>("resides in a package annotated with", type) {
+
+			@Override
+			public boolean test(JavaClass t) {
+				return t.getPackage().isMetaAnnotatedWith(type);
+			}
+		};
+	}
 }

spring-modulith-core/src/test/java/example/ni/internal/Internal.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.ni.internal;
+
+/**
+ * @author Oliver Drotbohm
+ */
+public interface Internal {}

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

@@ -22,6 +22,7 @@
 import example.ni.api.ApiType;
 import example.ni.internal.AdditionalSpiType;
 import example.ni.internal.DefaultedNamedInterfaceType;
+import example.ni.internal.Internal;
 import example.ni.spi.SpiType;
 import example.ninvalid.InvalidDefaultNamedInterface;
 
@@ -64,6 +65,18 @@ void rejectsDefaultingNamedInterfaceTypeInBasePackage() {
 				.withMessageContaining(InvalidDefaultNamedInterface.class.getSimpleName());
 	}
 
+	@Test // GH-284
+	void detectsOpenNamedInterface() {
+
+		var javaPackage = TestUtils.getPackage(RootType.class);
+		var interfaces = NamedInterfaces.forOpen(javaPackage);
+
+		assertThat(interfaces).map(NamedInterface::getName)
+				.containsExactlyInAnyOrder(NamedInterface.UNNAMED_NAME, "api", "spi", "kpi", "internal");
+
+		assertInterfaceContains(interfaces, NamedInterface.UNNAMED_NAME, RootType.class, Internal.class);
+	}
+
 	private static void assertInterfaceContains(NamedInterfaces interfaces, String name, Class<?>... types) {
 
 		var classNames = Arrays.stream(types).map(Class::getName).toArray(String[]::new);

spring-modulith-integration-test/src/main/java/com/acme/myproject/open/internal/Internal.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.acme.myproject.open.internal;
+
+import org.springframework.stereotype.Component;
+
+import com.acme.myproject.openclient.ClientToInternal;
+
+/**
+ * @author Oliver Drotbohm
+ */
+@Component
+public class Internal {
+
+	ClientToInternal clientToInternal;
+}