A Use Case for Local Class Declaration

One of the first things one learns when starting with Java development is how to declare a class into its own file. Potential later stages include:

• Declaring multiple classes into the same file — with at most one of them public
• Declaring static nested classes or inner classes
• Declaring anonymous (inner) classes

But this doesn’t stop there: the JLS is a trove full of surprises. I recently learned classes can be declared inside any block, including methods. This is called local class declaration (§14.3).

A local class is a nested class (§8) that is not a member of any class and that has a name. All local classes are inner classes (§8.1.3). Every local class declaration statement is immediately contained by a block. Local class declaration statements may be intermixed freely with other kinds of statements in the block.

The scope of a local class immediately enclosed by a block (§14.2) is the rest of the immediately enclosing block, including its own class declaration. The scope of a local class immediately enclosed by in a switch block statement group (§14.11)is the rest of the immediately enclosing switch block statement group, including its own class declaration.

Cool, isn’t it? But using it just for the sake of it is not reason enough… until this week: I started to implement something like the Spring Boot Actuator in a non-Boot application, using Jackson to serialize the results.

Jackson offers several ways to customize the serialization process. For objects that require only to hide fields or change their names and which classes stand outside one’s reach, it offers mixins. As an example, let’s tweak serialization of the following class:

public class Person {
    private final String firstName;
    private final String lastName;

    public Person(String firstName, String lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    public String getFirstName() {
        return firstName;
    }

    public String getLastName() {
        return lastName;
    }
}

Suppose the requirement is to have givenName and familyName attributes. In a regular Spring application, the mixin class should be registered during the configuration of message converters:

public class WebConfiguration extends WebMvcConfigurerAdapter {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
        jackson2HttpMessageConverter.getObjectMapper().addMixIn(Person.class, PersonMixin.class);
        converters.add(jackson2HttpMessageConverter);
    }
}

Now, where does it make the most sense to declare this mixin class? The principle to declare something in the smallest possible scope applies: having it in a dedicated file is obviously wrong, but even a private nested class is overkill. Hence, the most restricted scope is the method itself:

public class WebConfiguration extends WebMvcConfigurerAdapter {

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        MappingJackson2HttpMessageConverter jackson2HttpMessageConverter = new MappingJackson2HttpMessageConverter();
        abstract class PersonMixin {
            @JsonProperty("givenName") abstract String getFirstName();
            @JsonProperty("familyName") abstract String getLastName();
        }
        jackson2HttpMessageConverter.getObjectMapper().addMixIn(Person.class, PersonMixin.class);
        converters.add(jackson2HttpMessageConverter);
    }
}

While this way makes sense from a pure software engineering point of view, there is a reason not to design code like this: the principle of least surprise. Unless every member of the team is aware and comfortable with local classes, this feature shouldn’t be used.