What is the difference between withEnclosingType() and withDeclaringType() in InstrumentedType?

I'm an experienced Byte Buddy user.

What practical effect does InstrumentedType#withDeclaringType(TypeDescription) have over InstrumentedType#withEnclosingType(TypeDescription)? When do I use one versus the other?

Let's explore each method's practical effects and when to use them.

1. InstrumentedType#withDeclaringType(TypeDescription):

• Practical Effect: This method sets the declaring type for the instrumented type. The declaring type is the type that directly contains the instrumented type, as in the case of nested classes.

• Usage: You would use this method when you want to specify the exact declaring type of the instrumented type explicitly. It is typically used when creating or modifying nested classes, where the declaring type determines the scope of the nested class within the containing class.

2. InstrumentedType#withEnclosingType(TypeDescription):

• Practical Effect: This method sets the enclosing type for the instrumented type. The enclosing type is the type that conceptually encloses the instrumented type, but it may not be its direct container. It represents the lexical nesting relationship between types, such as when dealing with inner classes.

• Usage: You would use this method when you want to establish the lexical nesting relationship between types, especially in the context of inner classes. The enclosing type represents the scope in which the instrumented type is defined, allowing access to the enclosing type's members.

In summary, withDeclaringType() is used to explicitly set the direct container or declaring type of the instrumented type, while withEnclosingType() establishes the lexical nesting relationship between types, particularly in the case of inner classes.

When choosing between the two methods, consider the specific context and requirements of your instrumentation. If you are dealing with nested classes and need to specify the immediate container, use withDeclaringType(). If you are working with inner classes and want to establish the lexical nesting relationship, use withEnclosingType().

You can read more about nested vs inner classes to get a wider context on when to use both methods:

Inner Class:

• A static inner class is a nested class that is marked as static.
• It is not associated with an instance of the enclosing class.
• The static inner class does not have a reference to an instance of the enclosing class.
• The enclosing type and the declaring type are the same for a static inner class.

Nested Class:

• A non-static nested class, is a class declared within another class without the static keyword.

• An inner class is associated with an instance of the enclosing class and has access to the instance members of the enclosing class (using qualified this).

• The enclosing type and the declaring type are different for an inner class.

Anonymous types will have an enclosing type but not a declaring type. Member types on the other hand will have both a declaring type and an enclosing type.

You can check the DynamicType class which maps these attributes to the Java representations within its builder API. If you create an InstrumentedType manually, you can combine attributes like you want, but they might not make sense to the Java reflection API.