Dynamic Projections with Spring Data JPA

Methods returning projections are typically defined on the repository level, making the repository interface aware of all possible types of projections used in the application.

package com.app.account.domain;

public interface AccountRepository extends Repository<Account, String> {
    AccountBasic findAccountBasicById(String id);
    AccountComplete findAccountCompleteById(String id);
}

public record AccountBasic(String id, 
                           String iban,
                           String bic) {}

public record AccountComplete(String id,
                       String iban,
                       String bic,
                       State state,
                       Type type,
                       LocalDateTime createdAt) {}

This approach has some drawbacks:

• if there is a projection that almost fits our use case, it is tempting to modify it and add needed field - at the same time defeating a bit the main purpose of projections - fetching only what's needed.
• naming projections becomes a challenge - how to name them? AccountBasic? AccountLight? AccountData? All these names are quite meaningless.
• repository becomes difficult to use as it contains a long list of method, and to find out which one should be used you need to visit every projection.
• because projections are shared between use cases, they become a coupling point, making future refactoring more difficult.
• projections must have the same visibility level as the repository, for example if repository is public, projections must be public too.

Instead of making the repository aware of all types projections used by all the use cases, we can use dynamic projections.

Dynamic Projections ​

Dynamic Projections is one of the lesser known and used feature of Spring Data JPA.

Dynamic projections let you define a generic method on the repository level that takes any kind of projection, and remain unaware of the shape of projections.

package com.app.account.domain;

public interface AccountRepository extends Repository<Account, String> {
    <T> T findById(String id, Class<T> projection);
}

Now, in any package we can define a projection interface or a record, which as long as it matches the structure of an Account entity, can be used with this dynamic repository method:

package com.app.account;

record AccountBasic(String id, 
                    String iban, 
                    String bic) {}

// ...
AccountBasic account = accountRepository.findById(id, AccountBasic.class);

In this particular example AccountBasic is a package private class located in com.app.account. Only classes from this package can access it and as a result, the risk of abusing this projection in other parts of the application does not exist.

Local Records Projections ​

We can take hiding the projections visibility to the next level by using local records.

Records that are records defined inside a method are called local records and become a perfect solution for use cases, where the projection is used only inside of this method and are not returned:

class BankTransferService {
    private final AccountRepository accountRepository;
    
    // ...
    
    void transferMoney(String sourceAccountId, String targetAccountId) {
        record AccountBasic(String id,
                            String iban,
                            String bic) {}
        
        var source = accountRepository.findById(sourceAccountId, AccountBasic.class);
        var target = accountRepository.findById(targetAccountId, AccountBasic.class);
        // ...
    }
}

Just in case you are thinking now about using classes the same way, perhaps don't because local records and local classes are different:

Like nested record classes, local record classes are implicitly static, which means that their own methods can't access any variables of the enclosing method, unlike local classes, which are never static.

https://docs.oracle.com/en/java/javase/17/language/records.html

Downsides of Dynamic Projections ​

As usual, there are some downsides of this approach worth taking into consideration:

• repository is not anymore a single place to look at all possible queries executed from the application code
• tested repository does not mean tested all interactions with the database - any place that uses dynamic projection must have a corresponding integration test that uses real database
• the where part of repository method returning a dynamic projection is resolved only from the method name - it is not possible to write a custom JPQL or SQL query

Summary ​

Hope you found it useful or at least slightly interesting 😉 Feel free to drop a comment if you found any mistake or have a question. Also, feel free to reach out to me on twitter.com/maciejwalkowiak.