methods().that().areAnnotatedWith() does not match methods which have multiple instances of the same annotation type

[m-ismar]

Hello,

I don't know if this is due to me misconfiguring something, or due to ArchUnit, but I have a case where areAnnotatedWith() is not finding all the instances in a class.

In the following arch test:

    ArchCondition<JavaMethod> haveDescriptionInResponseDefinition =
            new ArchCondition<JavaMethod>(
                    "not have description in @ApiResponse definition") {
                @Override
                public void check(JavaMethod javaMethod, ConditionEvents conditionEvents) {

                    if (Util.readApiResponseDescription(javaMethod).isEmpty()) {
                        String message = String.format(
                                "@ApiResponse %s in method %s must have a description",
                                javaMethod.getAnnotationOfType(ApiResponse.class).responseCode(),
                                javaMethod.getFullName()
                        );
                        conditionEvents.add(SimpleConditionEvent.violated(javaMethod, message));
                    }
                }
            };
   
    @ArchTest
    private final ArchRule no_description_in_api_response = methods().that().
            areAnnotatedWith(ApiResponse.class)
            .should(haveDescriptionInResponseDefinition);

Not all methods get matched:

    //Recognized
    @GET
    @RolesAllowed(ROLE_RESTCLIENT)
    @Path("/{id}")
    @Produces({IMAGE_JPEG, IMAGE_JPG})
    @Operation(description = "Provides downloading images.")
    @ApiResponse(responseCode = "200", description = "The image binary.")
    public File getImage(
            @PathParam("id")
            String imageId, 
           @Context MessageContext context
     ) {...}

    //Not recognized
    @PUT
    @RolesAllowed(ROLE_RESTCLIENT)
    @Path("/{id}")
    @Consumes(MULTIPART_FORM_DATA)
    @Produces(APPLICATION_JSON)
    @Operation(description = "Handles upload of images.")
    @ApiResponse(responseCode = "204", description = "Successfully uploaded image")
    @ApiResponse(responseCode = "401", description = "Missing authorization for putting image")
    @ApiResponse(responseCode = "400", description = "A bad request, e.g., an invalid image ID")
    public Response putImage(
            @PathParam("id")
            @Parameter(description = "The ID (client-generated UUID) of the image to upload.") String imageId,
            MultipartBody body
    ) {...}

I figured that that was because putImage() has multiple @ApiResponse annotations, but I'm not sure why that happens and what can I do to avoid it.

Is this intended ArchUnit behaviour or am I missing something?

Sorry if this question was asked before, but I found nothing on the topic.

[rweisleder]

This behavior is due to the fact of how Java handles repeatable annotations.

In your example, @ApiResponse is a repeatable annotation. Let me abbreviate that to

@Retention(RetentionPolicy.RUNTIME)
@Repeatable(ApiResponses.class)
public @interface ApiResponse {
    int status();
}

@Retention(RetentionPolicy.RUNTIME)
public @interface ApiResponses {
    ApiResponse[] value();
}

Also, consider these two example usages:

@ApiResponse(status = 200)
public class FirstAnnotatedClass {
}

@ApiResponse(status = 200)
@ApiResponse(status = 404)
public class SecondAnnotatedClass {
}

If we use Java's Reflection API to get the annotations, we get the following result:

System.out.println(FirstAnnotatedClass.class.getAnnotation(ApiResponse.class)); // prints @org.example.ApiResponse(status=200)
System.out.println(SecondAnnotatedClass.class.getAnnotation(ApiResponse.class)); // prints null

What happened? Somewhere between your code and the reflective call, the repeatable annotation is wrapped into the containing annotation type, but only if the annotation is repeated. (I'm not sure if this happens during compile time or during runtime, but it doesn't matter.)

If we try to read the containing annotation type with Java's Reflection API, we get:

System.out.println(FirstAnnotatedClass.class.getAnnotation(ApiResponses.class)); // prints null
System.out.println(SecondAnnotatedClass.class.getAnnotation(ApiResponses.class)); // @org.example.ApiResponses(value=[@org.example.ApiResponse(status=200), @org.example.ApiResponse(status=404)])

And now compared to the behavior of ArchUnit:

JavaClasses classes = new ClassFileImporter().importClasses(FirstAnnotatedClass.class, SecondAnnotatedClass.class);

System.out.println(classes.get(FirstAnnotatedClass.class).tryGetAnnotationOfType(ApiResponse.class).orNull()); // prints @org.example.ApiResponse(status=200)
System.out.println(classes.get(SecondAnnotatedClass.class).tryGetAnnotationOfType(ApiResponse.class).orNull()); // prints null

System.out.println(classes.get(FirstAnnotatedClass.class).tryGetAnnotationOfType(ApiResponses.class).orNull()); // prints null
System.out.println(classes.get(SecondAnnotatedClass.class).tryGetAnnotationOfType(ApiResponses.class).orNull()); // @org.example.ApiResponses(value=[@org.example.ApiResponse(status=200), @org.example.ApiResponse(status=404)])

Compared to Java's Reflection API, ArchUnit produces the same results. So I would say this is the intended behavior.

My summary is, if you have to deal with repeatable annotations, you have to check both the annotation type and the containing annotation type.

[codecholeric]

What happened? Somewhere between your code and the reflective call, the repeatable annotation is wrapped into the containing annotation type, but only if the annotation is repeated. (I'm not sure if this happens during compile time or during runtime, but it doesn't matter.)

ArchUnit mirrors the bytecode, so that should answer the question 😉

Other than that, yes, ArchUnit tries to mirror the Reflection API to avoid confusion (and duplicate confusion if the Reflection API is confusing 😂 )

[m-ismar]

Thank you for the quick answer, helps a lot 🙂

[KalCramer]

I wanted to write up a little workaround that seemed to work for me if anyone else finds themselves in this situation.

Instead of using methods().that().areAnnotatedWith().should(), use methods().should().

And pass in a custom ArchCondition which does something like the following in this case checking OP's ApiResponse.class:

        @Override
        public void check(JavaMethod method, ConditionEvents conditionEvents) {
          Arrays.stream(method.reflect().getAnnotationsByType(ApiResponse.class))
              .forEach(annotation -> doCheckHere(annotation));
        }