add support to traverse JavaType signature

At the moment, handling `JavaType`s is not convenient,
because there are many different subtypes.
And effectively the only way to handle those is a chain of `instanceof`
checks with individual handling for each type.
We can make this more convenient by adding a visitor pattern API
that allows to simply define what to do on every partial type encountered
in the signature (i.e. what to do when a parameterized type is encountered,
what to do when each actual type argument of the parameterized type is encountered,
and so on).
As a benefit, we can use this API in the next step to fix the infinite
recursion problem we have for the `getAllRawTypes()` method at the moment.
Because, there we haven't handled the case where type variables are defined
recursively. Adding this visitor pattern API we can solve this problem
in a generic way once at the infrastructure level, i.e. implement the
traversal correctly once and utilize it in more specific use cases.

Signed-off-by: Peter Gafert <[email protected]>

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaClass.java

@@ -662,6 +662,11 @@ public Set<JavaClass> getAllInvolvedRawTypes() {
  return ImmutableSet.of(getBaseComponentType());
  }
 
+ @Override
+ public void traverseSignature(SignatureVisitor visitor) {
+ SignatureTraversal.from(visitor).visitClass(this);
+ }
+
  @PublicAPI(usage = ACCESS)
  public Optional<JavaClass> getRawSuperclass() {
  return superclass.getRaw();

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaGenericArrayType.java

@@ -74,6 +74,11 @@ public Set<JavaClass> getAllInvolvedRawTypes() {
  return this.componentType.getAllInvolvedRawTypes();
  }
 
+ @Override
+ public void traverseSignature(SignatureVisitor visitor) {
+ SignatureTraversal.from(visitor).visitGenericArrayType(this);
+ }
+
  @Override
  public String toString() {
  return getClass().getSimpleName() + '{' + getName() + '}';

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaParameterizedType.java

@@ -35,4 +35,9 @@ public interface JavaParameterizedType extends JavaType {
  */
  @PublicAPI(usage = ACCESS)
  List<JavaType> getActualTypeArguments();
+
+ @Override
+ default void traverseSignature(SignatureVisitor visitor) {
+ SignatureTraversal.from(visitor).visitParameterizedType(this);
+ }
 }

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java

@@ -16,13 +16,22 @@
 package com.tngtech.archunit.core.domain;
 
 import java.lang.reflect.Type;
+import java.util.Collections;
+import java.util.HashSet;
 import java.util.Set;
+import java.util.function.Function;
+import java.util.function.Supplier;
 
+import com.google.common.collect.Iterables;
 import com.tngtech.archunit.PublicAPI;
 import com.tngtech.archunit.base.ChainableFunction;
 import com.tngtech.archunit.core.domain.properties.HasName;
 
 import static com.tngtech.archunit.PublicAPI.Usage.ACCESS;
+import static com.tngtech.archunit.PublicAPI.Usage.INHERITANCE;
+import static com.tngtech.archunit.core.domain.JavaType.SignatureVisitor.Result.CONTINUE;
+import static com.tngtech.archunit.core.domain.JavaType.SignatureVisitor.Result.STOP;
+import static java.util.Collections.singleton;
 
 /**
  * Represents a general Java type. This can e.g. be a class like {@code java.lang.String}, a parameterized type
@@ -84,6 +93,94 @@ public interface JavaType extends HasName {
  @PublicAPI(usage = ACCESS)
  Set<JavaClass> getAllInvolvedRawTypes();
 
+ /**
+ * Traverses through the signature of this {@link JavaType}.<br>
+ * This method considers the type signature as a tree,
+ * where e.g. a {@link JavaClass} is a simple leaf,
+ * but a {@link JavaParameterizedType} has the type as root and then
+ * branches out into its actual type arguments, which in turn can have type arguments
+ * or upper/lower bounds in case of {@link JavaTypeVariable} or {@link JavaWildcardType}.<br>
+ * The following is a simple visualization of such a signature tree:
+ * <pre><code>
+ * List&lt;Map&lt;? extends Serializable, String[]&gt;&gt;
+ * |
+ * Map&lt;? extends Serializable, String[]&gt;
+ * / \
+ * ? extends Serializable String[]
+ * |
+ * Serializable
+ * </code></pre>
+ * For every node visited the respective method of the provided {@code visitor}
+ * will be invoked. The traversal happens depth first, i.e. in this case the {@code visitor}
+ * would be invoked for all types down to {@code Serializable} before visiting the {@code String[]}
+ * array type of the second branch. At every step it is possible to continue the traversal
+ * by returning {@link SignatureVisitor.Result#CONTINUE CONTINUE} or stop at that point by
+ * returning {@link SignatureVisitor.Result#STOP STOP}.<br><br>
+ * Note that the traversal will continue to traverse bounds of type variables,
+ * even if that type variable isn't declared in this signature itself.<br>
+ * E.g. take the following scenario
+ * <pre><code>
+ * class Example&lt;T extends String&gt; {
+ * T field;
+ * }</code></pre>
+ * Traversing the {@link JavaField#getType() field type} of {@code field} will continue
+ * down to the upper bounds of the type variable {@code T} and thus end at the type {@code String}.<br><br>
+ * Also, note that the traversal will not continue down the type parameters of a raw type
+ * declared in a signature.<br>
+ * E.g. given the signature {@code class Example<T extends Map>} the traversal would stop at
+ * {@code Map} and not traverse down the type parameters {@code K} and {@code V} of {@code Map}.
+ *
+ * @param visitor A {@link SignatureVisitor} to invoke for every encountered {@link JavaType}
+ * while traversing this signature.
+ */
+ @PublicAPI(usage = ACCESS)
+ void traverseSignature(SignatureVisitor visitor);
+
+ /**
+ * @see #traverseSignature(SignatureVisitor)
+ */
+ @PublicAPI(usage = INHERITANCE)
+ interface SignatureVisitor {
+ default Result visitClass(JavaClass type) {
+ return CONTINUE;
+ }
+
+ default Result visitParameterizedType(JavaParameterizedType type) {
+ return CONTINUE;
+ }
+
+ default Result visitTypeVariable(JavaTypeVariable<?> type) {
+ return CONTINUE;
+ }
+
+ default Result visitGenericArrayType(JavaGenericArrayType type) {
+ return CONTINUE;
+ }
+
+ default Result visitWildcardType(JavaWildcardType type) {
+ return CONTINUE;
+ }
+
+ /**
+ * Result of a single step {@link #traverseSignature(SignatureVisitor) traversing a signature}.
+ * After each step it's possible to either {@link #STOP stop} or {@link #CONTINUE continue}
+ * the traversal.
+ */
+ @PublicAPI(usage = ACCESS)
+ enum Result {
+ /**
+ * Causes the traversal to continue
+ */
+ @PublicAPI(usage = ACCESS)
+ CONTINUE,
+ /**
+ * Causes the traversal to stop
+ */
+ @PublicAPI(usage = ACCESS)
+ STOP
+ }
+ }
+
  /**
  * Predefined {@link ChainableFunction functions} to transform {@link JavaType}.
  */
@@ -101,3 +198,81 @@ public JavaClass apply(JavaType input) {
  };
  }
 }
+
+class SignatureTraversal implements JavaType.SignatureVisitor {
+ private final Set<JavaType> visited = new HashSet<>();
+ private final JavaType.SignatureVisitor delegate;
+ private Result lastResult;
+
+ private SignatureTraversal(JavaType.SignatureVisitor delegate) {
+ this.delegate = delegate;
+ }
+
+ @Override
+ public Result visitClass(JavaClass type) {
+ // We only traverse type parameters of a JavaClass if the traversal was started *at the JavaClass* itself.
+ // Otherwise, we can only encounter a regular class as a raw type in a type signature.
+ // In these cases we don't want to traverse further down, as that would be surprising behavior
+ // (consider `class MyClass<T extends Map>`, traversing into the type variables `K` and `V` of `Map` would be surprising).
+ Supplier<Iterable<JavaTypeVariable<JavaClass>>> getFurtherTypesToTraverse = visited.isEmpty() ? type::getTypeParameters : Collections::emptyList;
+ return visit(type, delegate::visitClass, getFurtherTypesToTraverse);
+ }
+
+ @Override
+ public Result visitParameterizedType(JavaParameterizedType type) {
+ return visit(type, delegate::visitParameterizedType, type::getActualTypeArguments);
+ }
+
+ @Override
+ public Result visitTypeVariable(JavaTypeVariable<?> type) {
+ return visit(type, delegate::visitTypeVariable, type::getUpperBounds);
+ }
+
+ @Override
+ public Result visitGenericArrayType(JavaGenericArrayType type) {
+ return visit(type, delegate::visitGenericArrayType, () -> singleton(type.getComponentType()));
+ }
+
+ @Override
+ public Result visitWildcardType(JavaWildcardType type) {
+ return visit(type, delegate::visitWildcardType, () -> Iterables.concat(type.getUpperBounds(), type.getLowerBounds()));
+ }
+
+ private <CURRENT extends JavaType, NEXT extends JavaType> Result visit(
+ CURRENT type,
+ Function<CURRENT, Result> visitCurrent,
+ Supplier<Iterable<NEXT>> nextTypes
+ ) {
+ if (visited.contains(type)) {
+ // if we've encountered this type already we continue traversing the siblings,
+ // but we won't descend further into this type signature
+ return setLast(CONTINUE);
+ }
+ visited.add(type);
+ if (visitCurrent.apply(type) == CONTINUE) {
+ Result result = visit(nextTypes.get());
+ return setLast(result);
+ } else {
+ return setLast(STOP);
+ }
+ }
+
+ private Result visit(Iterable<? extends JavaType> types) {
+ for (JavaType nextType : types) {
+ nextType.traverseSignature(this);
+ if (lastResult == STOP) {
+ return STOP;
+ }
+ }
+ return CONTINUE;
+ }
+
+ private Result setLast(Result result) {
+ lastResult = result;
+ return result;
+ }
+
+ static SignatureTraversal from(JavaType.SignatureVisitor visitor) {
+ return visitor instanceof SignatureTraversal ? (SignatureTraversal) visitor : new SignatureTraversal(visitor);
+ }
+}

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaTypeVariable.java

@@ -129,6 +129,11 @@ public Set<JavaClass> getAllInvolvedRawTypes() {
  .collect(toSet());
  }
 
+ @Override
+ public void traverseSignature(SignatureVisitor visitor) {
+ SignatureTraversal.from(visitor).visitTypeVariable(this);
+ }
+
  @Override
  public String toString() {
  String bounds = printExtendsClause() ? " extends " + joinTypeNames(upperBounds) : "";

archunit/src/main/java/com/tngtech/archunit/core/domain/JavaWildcardType.java

@@ -106,6 +106,11 @@ public Set<JavaClass> getAllInvolvedRawTypes() {
  .collect(toSet());
  }
 
+ @Override
+ public void traverseSignature(SignatureVisitor visitor) {
+ SignatureTraversal.from(visitor).visitWildcardType(this);
+ }
+
  @Override
  public String toString() {
  return getClass().getSimpleName() + '{' + getName() + '}';