Data Repositories

Spring Data repositories provide a useful abstraction for working with entities, especially when implementing business logic.

Jmix data repositories are built on top of Spring Data and use DataManager under the hood. It allows you to utilize the convenient repository interface while having the full support for advanced Jmix data access features, such as entity events, cross-datastore references, data access checks, etc.

Currently, in version 1.5 the Jmix data repositories API is marked as experimental. It will undergo minor changes in the next feature release and become stable.

Working with Data Repositories

  1. Create an interface extending JmixDataRepository. Use the entity class and the entity identifier class as type parameters for JmixDataRepository. For example:

    public interface CustomerRepository extends JmixDataRepository<Customer, UUID> {
}

  2. Add @EnableJmixDataRepositories annotation to the main application class or the add-on configuration:

    @SpringBootApplication
@EnableJmixDataRepositories
public class SampleDataAccessApplication {

    Jmix will initialize all data repositories located under the base package of the application or the add-on. If you need more customized control over where to search for repositories, use the basePackages, excludeFilters and includeFilters attributes of the annotation.

  3. Inject your repository into Spring beans or UI controllers using the @Autowired annotation:

    @Autowired
private CustomerRepository customerRepository;

JmixDataRepository Features

The JmixDataRepository interface extends the standard Spring Data PagingAndSortingRepository. It provides a few own methods considering Jmix specifics:

  • Load methods, such as findById() or findAll(), can accept a fetch plan.

  • create() method instantiates a new entity.

  • getById() method with the non-optional result loads an entity by id and throws the exception if the entity is not found.

You can use the following annotations on custom query methods:

  • @io.jmix.core.repository.Query defines a JPQL query string, similar to the Spring Data JPA @Query annotation.

  • @io.jmix.core.repository.FetchPlan defines a fetch plan to be used when loading data.

Query Method Examples

Jmix data repositories support the standard Spring Data feature of deriving the query from the method name, for example:

List<Customer> findByEmailContainingIgnoreCase(String emailPart);

Similar to Spring Data JPA, a JPQL query can be defined explicitly using the @io.jmix.core.repository.Query annotation:

@Query("select c from sample_Customer c where c.email like :email")
List<Customer> findCustomersByEmail(@Param("email") String emailPart);

Query methods can accept Pageable for pagination and sorting:

Page<Customer> findByEmailContainingIgnoreCase(String emailPart, Pageable pageable);

Another special parameter that can be passed to query methods is a fetch plan:

List<Customer> findByEmailContainingIgnoreCase(String emailPart, FetchPlan fetchPlan);

A shared fetch plan can be defined in the @io.jmix.core.repository.FetchPlan annotation on the query method:

@FetchPlan("customer-minimal")
List<Customer> findByEmail(String email);