extend Onion Architecture to allow defining components by predicate

Some users use different conventions, like class naming or annotations, to define the components of their Onion Architecture. To support such use cases we extend `OnionArchitecture` similar to `LayeredArchitecture` to also allow defining components via any arbitrary `DescribedPredicate`.

While extending the example I noticed that it might be a good addition to have a more generic `JavaClass.Predicates.belongTo(DescribedPredicate)` method additionally to `belongToAnyOf(Class<?>...)`. At least writing the example would otherwise have been tedious, since assigning nested and anonymous classes to the annotation of the outer class would always be necessary for this use case.

Signed-off-by: Peter Gafert <peter.gafert@tngtech.com>

archunit-example/example-junit4/src/test/java/com/tngtech/archunit/exampletest/junit4/OnionArchitectureTest.java

@@ -1,19 +1,35 @@
 package com.tngtech.archunit.exampletest.junit4;
 
+import java.lang.annotation.Annotation;
+
+import com.tngtech.archunit.base.DescribedPredicate;
+import com.tngtech.archunit.core.domain.JavaAnnotation;
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.properties.CanBeAnnotated;
 import com.tngtech.archunit.example.onionarchitecture.domain.model.OrderItem;
 import com.tngtech.archunit.example.onionarchitecture.domain.service.OrderQuantity;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Application;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainService;
 import com.tngtech.archunit.junit.AnalyzeClasses;
 import com.tngtech.archunit.junit.ArchTest;
 import com.tngtech.archunit.junit.ArchUnitRunner;
 import com.tngtech.archunit.lang.ArchRule;
 import org.junit.experimental.categories.Category;
 import org.junit.runner.RunWith;
 
+import static com.tngtech.archunit.base.DescribedPredicate.describe;
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.belongTo;
+import static com.tngtech.archunit.core.domain.properties.CanBeAnnotated.Predicates.annotatedWith;
 import static com.tngtech.archunit.library.Architectures.onionArchitecture;
 
 @Category(Example.class)
 @RunWith(ArchUnitRunner.class)
-@AnalyzeClasses(packages = "com.tngtech.archunit.example.onionarchitecture")
+@AnalyzeClasses(packages = {
+        "com.tngtech.archunit.example.onionarchitecture",
+        "com.tngtech.archunit.example.onionarchitecture_by_annotations"
+})
 public class OnionArchitectureTest {
 
     @ArchTest
@@ -35,4 +51,30 @@ public class OnionArchitectureTest {
             .adapter("rest", "..adapter.rest..")
 
             .ignoreDependency(OrderItem.class, OrderQuantity.class);
+
+    @ArchTest
+    static final ArchRule onion_architecture_defined_by_annotations = onionArchitecture()
+            .domainModels(byAnnotation(DomainModel.class))
+            .domainServices(byAnnotation(DomainService.class))
+            .applicationServices(byAnnotation(Application.class))
+            .adapter("cli", byAnnotation(adapter("cli")))
+            .adapter("persistence", byAnnotation(adapter("persistence")))
+            .adapter("rest", byAnnotation(adapter("rest")));
+
+    private static DescribedPredicate<JavaClass> byAnnotation(Class<? extends Annotation> annotationType) {
+        DescribedPredicate<CanBeAnnotated> annotatedWith = annotatedWith(annotationType);
+        return belongTo(annotatedWith).as(annotatedWith.getDescription());
+    }
+
+    private static DescribedPredicate<JavaClass> byAnnotation(DescribedPredicate<? super JavaAnnotation<?>> annotationType) {
+        DescribedPredicate<CanBeAnnotated> annotatedWith = annotatedWith(annotationType);
+        return belongTo(annotatedWith).as(annotatedWith.getDescription());
+    }
+
+    private static DescribedPredicate<JavaAnnotation<?>> adapter(String adapterName) {
+        return describe(
+                String.format("@%s(\"%s\")", Adapter.class.getSimpleName(), adapterName),
+                a -> a.getRawType().isEquivalentTo(Adapter.class) && a.as(Adapter.class).value().equals(adapterName)
+        );
+    }
 }

archunit-example/example-junit5/src/test/java/com/tngtech/archunit/exampletest/junit5/OnionArchitectureTest.java

@@ -1,16 +1,32 @@
 package com.tngtech.archunit.exampletest.junit5;
 
+import java.lang.annotation.Annotation;
+
+import com.tngtech.archunit.base.DescribedPredicate;
+import com.tngtech.archunit.core.domain.JavaAnnotation;
+import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.properties.CanBeAnnotated;
 import com.tngtech.archunit.example.onionarchitecture.domain.model.OrderItem;
 import com.tngtech.archunit.example.onionarchitecture.domain.service.OrderQuantity;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Application;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainService;
 import com.tngtech.archunit.junit.AnalyzeClasses;
 import com.tngtech.archunit.junit.ArchTag;
 import com.tngtech.archunit.junit.ArchTest;
 import com.tngtech.archunit.lang.ArchRule;
 
+import static com.tngtech.archunit.base.DescribedPredicate.describe;
+import static com.tngtech.archunit.core.domain.JavaClass.Predicates.belongTo;
+import static com.tngtech.archunit.core.domain.properties.CanBeAnnotated.Predicates.annotatedWith;
 import static com.tngtech.archunit.library.Architectures.onionArchitecture;
 
 @ArchTag("example")
-@AnalyzeClasses(packages = "com.tngtech.archunit.example.onionarchitecture")
+@AnalyzeClasses(packages = {
+        "com.tngtech.archunit.example.onionarchitecture",
+        "com.tngtech.archunit.example.onionarchitecture_by_annotations"
+})
 public class OnionArchitectureTest {
 
     @ArchTest
@@ -32,4 +48,30 @@ public class OnionArchitectureTest {
             .adapter("rest", "..adapter.rest..")
 
             .ignoreDependency(OrderItem.class, OrderQuantity.class);
+
+    @ArchTest
+    static final ArchRule onion_architecture_defined_by_annotations = onionArchitecture()
+            .domainModels(byAnnotation(DomainModel.class))
+            .domainServices(byAnnotation(DomainService.class))
+            .applicationServices(byAnnotation(Application.class))
+            .adapter("cli", byAnnotation(adapter("cli")))
+            .adapter("persistence", byAnnotation(adapter("persistence")))
+            .adapter("rest", byAnnotation(adapter("rest")));
+
+    private static DescribedPredicate<JavaClass> byAnnotation(Class<? extends Annotation> annotationType) {
+        DescribedPredicate<CanBeAnnotated> annotatedWith = annotatedWith(annotationType);
+        return belongTo(annotatedWith).as(annotatedWith.getDescription());
+    }
+
+    private static DescribedPredicate<JavaClass> byAnnotation(DescribedPredicate<? super JavaAnnotation<?>> annotationType) {
+        DescribedPredicate<CanBeAnnotated> annotatedWith = annotatedWith(annotationType);
+        return belongTo(annotatedWith).as(annotatedWith.getDescription());
+    }
+
+    private static DescribedPredicate<JavaAnnotation<?>> adapter(String adapterName) {
+        return describe(
+                String.format("@%s(\"%s\")", Adapter.class.getSimpleName(), adapterName),
+                a -> a.getRawType().isEquivalentTo(Adapter.class) && a.as(Adapter.class).value().equals(adapterName)
+        );
+    }
 }

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/annotations/Adapter.java

@@ -0,0 +1,5 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations;
+
+public @interface Adapter {
+    String value();
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/annotations/Application.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations;
+
+public @interface Application {
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/annotations/DomainModel.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations;
+
+public @interface DomainModel {
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/annotations/DomainService.java

@@ -0,0 +1,4 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations;
+
+public @interface DomainService {
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/AdministrationPort.java

@@ -0,0 +1,8 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Application;
+
+@Application
+public interface AdministrationPort {
+    <T> T getInstanceOf(Class<T> type);
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/ShoppingApplication.java

@@ -0,0 +1,19 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Application;
+
+@Application
+public class ShoppingApplication {
+    public static void main(String[] args) {
+        // start the whole application / provide IOC features
+    }
+
+    public static AdministrationPort openAdministrationPort() {
+        return new AdministrationPort() {
+            @Override
+            public <T> T getInstanceOf(Class<T> type) {
+                throw new UnsupportedOperationException("Not yet implemented");
+            }
+        };
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/administration/AdministrationCLI.java

@@ -0,0 +1,22 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.administration;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.AdministrationPort;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.ShoppingApplication;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product.ProductRepository;
+
+@Adapter("cli")
+@SuppressWarnings("unused")
+public class AdministrationCLI {
+    public static void main(String[] args) {
+        AdministrationPort port = ShoppingApplication.openAdministrationPort();
+        handle(args, port);
+    }
+
+    private static void handle(String[] args, AdministrationPort port) {
+        // violates the pairwise independence of adapters
+        ProductRepository repository = port.getInstanceOf(ProductRepository.class);
+        long count = repository.getTotalCount();
+        // parse arguments and re-configure application according to count through port
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/order/OrderItem.java

@@ -0,0 +1,26 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.order;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product.Product;
+
+@DomainModel
+public class OrderItem {
+    private final Product product;
+    private final OrderQuantity quantity;
+
+    public OrderItem(Product product, OrderQuantity quantity) {
+        if (product == null) {
+            throw new IllegalArgumentException("Product must not be null");
+        }
+        if (quantity == null) {
+            throw new IllegalArgumentException("Quantity not be null");
+        }
+        this.product = product;
+        this.quantity = quantity;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{product=" + product + ", quantity=" + quantity + '}';
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/order/OrderQuantity.java

@@ -0,0 +1,21 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.order;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainService;
+
+@DomainService
+@SuppressWarnings("unused")
+public class OrderQuantity {
+    private final int quantity;
+
+    public OrderQuantity(int quantity) {
+        if (quantity <= 0) {
+            throw new IllegalArgumentException("Quantity must be positive");
+        }
+        this.quantity = quantity;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{quantity=" + quantity + '}';
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/order/PaymentMethod.java

@@ -0,0 +1,7 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.order;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+
+@DomainModel
+public class PaymentMethod {
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/product/Product.java

@@ -0,0 +1,27 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+
+@DomainModel
+public class Product {
+    // Dependency on ProductId violates the architecture, since ProductId resides with persistence adapter
+    private final ProductId id;
+    // Dependency on ProductName violates the architecture, since ProductName is located in the DomainService layer
+    private final ProductName name;
+
+    public Product(ProductId id, ProductName name) {
+        if (id == null) {
+            throw new IllegalArgumentException("Product id must not be null");
+        }
+        if (name == null) {
+            throw new IllegalArgumentException("Product name must not be null");
+        }
+        this.id = id;
+        this.name = name;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{id=" + id + ", name=" + name + '}';
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/product/ProductId.java

@@ -0,0 +1,23 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product;
+
+import java.util.UUID;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+
+@Adapter("persistence")
+@SuppressWarnings("unused")
+public class ProductId {
+    private final UUID id;
+
+    public ProductId(UUID id) {
+        if (id == null) {
+            throw new IllegalArgumentException("ID must not be null");
+        }
+        this.id = id;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{id=" + id + '}';
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/product/ProductJpaRepository.java

@@ -0,0 +1,17 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+
+@Adapter("persistence")
+@SuppressWarnings("unused")
+public class ProductJpaRepository implements ProductRepository {
+    @Override
+    public Product read(ProductId id) {
+        return new Product(id, new ProductName("would normally be read"));
+    }
+
+    @Override
+    public long getTotalCount() {
+        return 0;
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/product/ProductName.java

@@ -0,0 +1,21 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainService;
+
+@DomainService
+@SuppressWarnings("unused")
+public class ProductName {
+    private final String name;
+
+    public ProductName(String name) {
+        if (name == null || name.isEmpty()) {
+            throw new IllegalArgumentException("Name must not be empty");
+        }
+        this.name = name;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{name='" + name + '\'' + '}';
+    }
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/product/ProductRepository.java

@@ -0,0 +1,11 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.product;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.Adapter;
+
+// Violates the architecture because Domain must be the owner of the interfaces, not the persistence adapter
+@Adapter("persistence")
+public interface ProductRepository {
+    Product read(ProductId id);
+
+    long getTotalCount();
+}

archunit-example/example-plain/src/main/java/com/tngtech/archunit/example/onionarchitecture_by_annotations/onion/shopping/ShoppingCart.java

@@ -0,0 +1,32 @@
+package com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.shopping;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.annotations.DomainModel;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.order.OrderItem;
+import com.tngtech.archunit.example.onionarchitecture_by_annotations.onion.order.PaymentMethod;
+
+@DomainModel
+@SuppressWarnings("unused")
+public class ShoppingCart {
+    private final ShoppingCartId id;
+    private final Set<OrderItem> orderItems = new HashSet<>();
+
+    public ShoppingCart(ShoppingCartId id) {
+        this.id = id;
+    }
+
+    public void add(OrderItem orderItem) {
+        orderItems.add(orderItem);
+    }
+
+    public void executeOrder(PaymentMethod method) {
+        // complete financial transaction and initiate shipping process
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName() + "{id=" + id + ", orderItems=" + orderItems + '}';
+    }
+}