Offer a way to access enclosing `AnnotatedClass` from `AnnotatedMember`

[SimonCockx]

Is your feature request related to a problem? Please describe.

The AnnotatedMember interface does not expose a method to access its enclosing AnnotatedClass.

Example use case: a custom annotation introspector

@Pojo(prefix="Prefix_")
public class Foo {
    @Field("Name")
    public int getField() {
        return 42;
    }
}

Suppose I would like to implement the AnnotationIntrospector#findNameForSerialization method to return "Prefix_Name" for the annotated method getField.

Solution 1: access annotation directly on the declaring Class<?> object

    @Override
    public PropertyName findNameForSerialization(Annotated a) {
        if (a.hasAnnotation(Field.class)) {
            String name = a.getAnnotation(Field.class).value();
            String prefix = "";
            // Try to access the prefix from the enclosing class.
            if (a instanceof AnnotatedMember) {
                AnnotatedMember m = (AnnotatedMember) a;
                Class<?> declaringClass = m.getDeclaringClass();
                if (declaringClass.isAnnotationPresent(Pojo.class)) {
                    prefix = declaringClass.getAnnotation(Pojo.class).prefix();
                }
            }
            return new PropertyName(prefix + name);
        }
        return null;
    }

Notice that, whereas I can access annotations of the Annotated input using the conventional Jackson API, I have to go through the basic Java Class API to access the annotation of the enclosing class.

This works for this particular use case. However, it does not work when inheritance is involved, e.g., for the following pojo:

@Pojo(prefix="Prefix_")
public interface Foo {
    int getField();
    
    public class FooImpl implements Foo {
        @Field("Name")
        @Override
        public int getField() {
            return 42;
        }
    }
}

It would be better if I would be able to somehow access the declaring AnnotatedClass object instead. This is what I try to do in the following solution.

Solution 2: access annotation on the declaring AnnotatedClass object.

    @Override
    public PropertyName findNameForSerialization(Annotated a) {
        if (a.hasAnnotation(Field.class)) {
            String name = a.getAnnotation(Field.class).value();
            String prefix = "";
            // Try to access the prefix from the enclosing class.
            if (a instanceof AnnotatedMember) {
                AnnotatedMember m = (AnnotatedMember) a;
                AnnotatedClass declaringClass = (AnnotatedClass) m.getTypeContext(); // Note: `getTypeContext` is deprecated.
                if (declaringClass.hasAnnotation(Pojo.class)) {
                    prefix = declaringClass.getAnnotation(Pojo.class).prefix();
                }
            }
            return new PropertyName(prefix + name);
        }
        return null;
    }

While this seems to work perfectly (even for the inheritance use case), I have to use a deprecated method getTypeContext, and I have to cast that result into an AnnotatedClass. I don't see a way around this though. For now, I am using this as a workaround, but ideally it would be possible to do this in a non-deprecated direct way.

Describe the solution you'd like

AnnotatedMember should expose a method called getAnnotatedDeclaringClass() that returns the enclosing AnnotatedClass.

Usage example

Taking my use case from above, it could be implemented as follows:

    @Override
    public PropertyName findNameForSerialization(Annotated a) {
        if (a.hasAnnotation(Field.class)) {
            String name = a.getAnnotation(Field.class).value();
            String prefix = "";
            // Try to access the prefix from the enclosing class.
            if (a instanceof AnnotatedMember) {
                AnnotatedMember m = (AnnotatedMember) a;
                AnnotatedClass declaringClass = m.getAnnotatedDeclaringClass(); // Example usage
                if (declaringClass.hasAnnotation(Pojo.class)) {
                    prefix = declaringClass.getAnnotation(Pojo.class).prefix();
                }
            }
            return new PropertyName(prefix + name);
        }
        return null;
    }

[JooHyukKim]

AnnotatedXxxx classes are deeply integrated and aren't easily customized. To assist better:

• Can you clarify the actual use case, beyond the implementation details provided?
• Have custom de/serializers been considered?
• Is there an similar feature out there? like @JsonSerialize or @JsonDeserialize

[cowtowncoder]

Quick note: my first thinking is -- no, I don't think adding back-link is a good idea. Further, defaulting should NOT be implemented by methods of AnnotationIntrospector but entities calling it.

I will need to think about a bit more as I do see potential benefits, but as @JooHyukKim pointed out, classes are quite tightly coupled and adding linkage may be problematic in other ways.

EDIT: thought I should clarify part of "defaulting should not be implemented" -- this refers to the idea that AnnotationIntrospector should provide information only about specific level: for example, @JsonIgnoredProperties for Class, separate from @JsonIgnoredProperties for fields/getters, or @JsonIgnore for fields/getters. And then it is BasicSerializerFactory (etc) that combines this information. That allows AnnotationIntrospector to be simple, including ones that "translate" annotations from other package like JAXB.
But that obviously then requires that jackson-databind handles such aggregation.
I understand that this is not the case for use case given here, for example.

[SimonCockx]

@JooHyukKim, @cowtowncoder Thanks for the quick reply. Details below.

Can you clarify the actual use case, beyond the implementation details provided?

Actual use case:

There is a modelling language called Rosetta, which generates Java code of the form

@RosettaDataType("MyType")
public interface MyTypeInJava {
    int getAttr();
    
    public class MyTypeInJavaImpl implements MyTypeInJava {
        private int attr;
        public MyTypeInJavaImpl(int attr) {
            this.attr = attr;
        }
        
        @Override
        @RosettaAttribute("attr")
        public int getAttr() {
            return attr;
        }
    }
}

based on a .rosetta input file of the form

type MyType:
    attr number (1..1)

We have a use case where clients need to be able to customize the serialised attribute names. Our current approach is to use a configuration file, e.g.,

{
    "MyType": {
        "attr": "MyCustomAttrName"
    },
    ... // custom names for other types
}

I would like to define a mapper that uses this configuration in such a way that mapper.writeValueAsString(new MyTypeInJavaImpl(42)) yields the following JSON:

{
    "MyCustomAttrName": 42
}

My current approach was to create an annotation processor that does the following:

1. Given an annotated method with the RosettaAttribute annotation, lookup the RosettaDataType annotation on the enclosing class.
2. From this RosettaDataType annotation, infer the data type name from the Rosetta model (e.g., "MyType").
3. Lookup this name in the configuration to get a map from attribute names to custom JSON field names.
4. From this map, lookup the custom JSON field name associated with the attribute name as indicated by the RosettaAttribute annotation (e.g., "attr"). This yields "MyCustomAttrName".

It's step 1 that I'm having trouble with. (finding the RosettaDataType annotation on the enclosing class)

Have custom de/serializers been considered?

I'm looking for a general purpose solution that will work for any generated Java class based on a Rosetta model, so this is not really possible.

Is there an similar feature out there? like @JsonSerialize or @JsonDeserialize

Since the Java code generator for Rosetta is currently independent of any serialisation framework, I don't see this happening soon.

Further, defaulting should NOT be implemented by methods of AnnotationIntrospector but entities calling it.

Could you elaborate this please? I'm not sure I get what you mean.

I will need to think about a bit more as I do see potential benefits

Keen to hear your ideas. :)

If you can think of another approach that allows me to do something similar, I'm all ears of course.

[yihtserns]

Why is your custom code not traversing through the class/interface hierarchy to look for the annotation? E.g.:

    @Override
    public PropertyName findNameForSerialization(Annotated a) {
        if (a.hasAnnotation(Field.class)) {
            String name = a.getAnnotation(Field.class).value();
            String prefix = "";
            if (a instanceof AnnotatedMember) {
                AnnotatedMember m = (AnnotatedMember) a;
                Class<?> declaringClass = m.getDeclaringClass();

                // TODO: Cache for performance
                List<? extends Class<?>> classes = Stream.iterate(
                                declaringClass,
                                clazz -> clazz.getSuperclass() != null,
                                clazz -> (Class) clazz.getSuperclass())
                        .toList();

                // Try find in class & superclasses
                Pojo pojoAnnotation = classes.stream()
                        .map(clazz -> clazz.getAnnotation(Pojo.class))
                        .filter(Objects::nonNull)
                        .findFirst()
                        .orElse(null);

                if (pojoAnnotation == null) {
                    // Try find in any interface
                    pojoAnnotation = classes.stream()
                            .flatMap(clazz -> Stream.of(clazz.getInterfaces()))
                            .map(interfaceClass -> interfaceClass.getAnnotation(Pojo.class))
                            .filter(Objects::nonNull)
                            .findFirst()
                            .orElse(null);
                }

                if (pojoAnnotation != null) {
                    prefix = pojoAnnotation.prefix();
                }
            }
            return new PropertyName(prefix + name);
        }
        return null;
    }

[cowtowncoder]

@yihtserns If using AnnotatedXxx, inheritance would be handled by Jackson so there'd be no need to traverse. So maybe it's to just show simplified example.

[yihtserns]

If using AnnotatedXxx, inheritance would be handled by Jackson so there'd be no need to traverse.

In the case where the same annotation is on multiple interfaces, which one wins?

[cowtowncoder]

@yihtserns Probably somewhat arbitrary, I'd have to check the logic. In general. "closer" one (as per class inheritance hierarchy). For classes it follows expected hierarchy.

[yihtserns]

My thought is that if the user has special needs/purpose, it would be better/safer for them to have control over the logic/rule for whatever they are doing, rather than relying on a 3rd party lib's behaviour. 🤔

[SimonCockx]

I'm fine with reusing the same inheritance mechanism that Jackson uses under the hood. I think diverging from that behaviour would only cause confusion, where users expect the same logic to apply as regular Jackson annotations.

That being said, I of course agree with @yihtserns that a manual implementation would also work. The point of this feature request is however convenience: I don't want to bother implementing some highly optimised code to traverse classes and interfaces if Jackson already implements it. :)

[yihtserns]

I'm fine with reusing the same inheritance mechanism that Jackson uses under the hood. I think diverging from that behaviour would only cause confusion, where users expect the same logic to apply as regular Jackson annotations.

The problem with relying on that kind of undocumented (thus unguaranteed) behaviour is, users of your code may be in trouble if Jackson decides to change the behaviour/rule. 🤷

Anyway, @cowtowncoder why was AnnotatedMember.getTypeContext() deprecated? The commit didn't explain the reason.

[JooHyukKim]

Anyway, @cowtowncoder why was AnnotatedMember.getTypeContext() deprecated? The commit didn't explain the reason.

Try checking out the commit git checkout 01a37b9b2b3bff82c5aa0cd8dd399918d95eaffb and see the trailing commits that lead up to the mentioned commit. Seems like part of #1381, though I am not sure if answers the question.

[SimonCockx]

The problem with relying on that kind of undocumented (thus unguaranteed) behaviour is, users of your code may be in trouble if Jackson decides to change the behaviour/rule.

I think you could say this about users of Jackson as well. If anybody relies on Jackson annotations combined with inheritance (which I would guess is common practice - correct me if I'm wrong), their code might be in trouble if Jackson decides to change the behaviour. If this is a concern, then IMO this is more of a Jackson docs issue, and the solution would be to add documentation about it.

Anyway, my main point is that this is a feature request for convenience. If the consensus is that Jackson's inheritance mechanism is for internal use only, then so be it; otherwise I would like to reuse it. :)