Data: entities, repositories, queries

For an application on spring_boot_starter_data, the generator does the work Spring Data does when the application starts: it reads the entities, implements the repository interfaces, parses the names of derived query methods and checks @Query texts. All of it happens at build time, so nothing is parsed or described when the app starts, and a misspelled property is a build error with a suggestion, not a failure at startup.

The data starter's annotations are matched by URL, so the generator does not depend on the starter.

Why

Spring Data creates repository implementations at run time with dynamic proxies and parses method names such as findByTitleAndYear on every start. Dart cannot create classes at run time, and parsing at startup costs time on every launch of a mobile app. The build already sees the entities, the interfaces and the SQL files of lib/resources/, so it can write the implementation, check everything against the entities, and report every problem of an interface at once.

Entities: EntityIntrospection

For each @Table class, and each class a @Query method returns (a DTO), the generator writes an EntityIntrospection: the properties as constants, and closures that read one property, call the constructor, and set one property. Nothing more.

Input:

@Table('authors')
class Author {
  Author({required this.name, this.id, this.isni});

  @Id()
  int? id;

  String name;

  @Unique()
  String? isni;
}

Output (from the generator's test, prefixes dropped):

EntityIntrospection<Author>(
  r'Author',
  const [
    EntityProperty(r'id', ClassType<int>(nullable: true),
        annotations: [Id()], parameter: true, writable: true),
    EntityProperty(r'name', ClassType<String>(),
        parameter: true, writable: true),
    EntityProperty(r'isni', ClassType<String>(nullable: true),
        annotations: [Unique()], parameter: true, writable: true),
  ],
  annotations: const [Table(r'authors')],
  get: (e, i) => switch (i) {
    0 => e.id,
    1 => e.name,
    _ => e.isni,
  },
  create: (v) => Author(
      name: v[1] as String, id: v[0] as int?, isni: v[2] as String?),
  write: (e, i, v) => switch (i) {
    0 => e.id = v as int?,
    1 => e.name = v as String,
    2 => e.isni = v as String?,
    _ => null,
  },
)

All the descriptions of a module go into one bean, entityIntrospections#<module> (an EntityIntrospections), which the data layer reads. A module without entities has none.

A @Table class gets no Introspection (the general description used by JSON and SpEL) unless it is also @Introspected: the data layer needs only the EntityIntrospection.

Entity errors

The build fails when the data layer could not create or fill the class:

Problem Message (part)
A required constructor parameter that names no field (Book(String isbn)) names Book(isbn), says it names no field, and suggests this.isbn
No public unnamed constructor @Table class Book has no public unnamed constructor ... with Add one
A private class @Table class _Book must be public ...
An abstract class @Table class Book is abstract ..., asking for a concrete class

An optional parameter that names no field is left out of create.

Repositories: a class extending SimpleRepository

For each interface that extends DataRepository (directly, or through CrudRepository, ListCrudRepository, ...), the generator writes a class. It extends the starter's SimpleRepository, which has the CRUD methods, and adds one line for each other method of the interface. Nothing describes the methods for the starter to read at startup.

Input:

abstract interface class BookRepository
    implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitleAndYear(String title, int year);

  @Query('select title from books where year = :year')
  Future<List<BookCard>> cards(int year);
}

Output (prefixes dropped):

class _$BookRepositoryImpl extends SimpleRepository<Book, int>
    implements BookRepository {
  _$BookRepositoryImpl(super.operations);

  static _$BookRepositoryImpl $create(DependencyResolver r) =>
      _$BookRepositoryImpl(r
          .dependency<RepositoryFactory>()
          .operations<Book, int>(r'BookRepository', queries: [_cards]));

  static const _findByTitleAndYear = PartTree(r'findByTitleAndYear', [
    OrPart([Part(r'title'), Part(r'year')]),
  ]);

  static const _cards = QueryMethod(
    r'cards',
    Query(r'select title from books where year = :year'),
    parameters: [r'year'],
    element: ClassType<BookCard>(),
  );

  @override
  Future<List<Book>> findByTitleAndYear(String title, int year) =>
      this.operations.list(_findByTitleAndYear, [title, year]);

  @override
  Future<List<BookCard>> cards(int year) =>
      this.operations.query<List<BookCard>>(_cards, [year]);
}

The bean definition registers the interface and its supertypes, with create: (r) => _$BookRepositoryImpl.$create(r). The bean name is the decapitalized interface name (bookRepository), or the name given in @Repository('library'). The annotations of the interface (@Repository, @UseStore) are passed to operations.

A repository with only CRUD methods gets an empty class. A CRUD method the interface declares again is left to SimpleRepository. A generic base interface (interface Crud<E> extends DataRepository<E, int>) is never a bean, and a concrete @Repository class stays an ordinary component.

Derived queries: a constant PartTree

A method whose name starts with find, read, get, query, search, stream, count, exists, delete or remove, optionally followed by words, then By, is a derived query. The build reads the name as Spring Data's PartTree does (Distinct, First/Top<n>, And, Or, the operators, IgnoreCase, AllIgnoreCase, OrderBy...Asc/Desc) and writes the result as a constant:

static const _findByTitleContaining = PartTree(r'findByTitleContaining', [
  OrPart([Part(r'title', PartType.containing)]),
]);

The operation follows the return type of the method:

Return type Call
Future<List<Book>>, Future<Iterable<Book>> list
Future<Set<Book>> set
Future<Book?> one
Future<Book> single
Stream<Book> stream
Future<Page<Book>> (with a Pageable parameter) page
Future<Slice<Book>> (with a Pageable parameter) slice
Future<int> from countBy... countBy
Future<bool> from existsBy... existsBy
Future<int> or Future<void> from deleteBy... / removeBy... deleteBy
Future<List<Book>> from deleteBy... deleteByReturning

Sort and Pageable parameters are passed by name (sort: order); @Lock is passed with the call.

Derived query errors

The build checks each name against the entity, the parameters and the return type. A wrong name, an unknown property, a property that is a collection or a nested path, or a parameter that does not fit fails the build. All problems of one interface come in one error, a line per method, in the order of the methods:

Invalid repository BookRepository:
  - BookRepository.findByTitel: No property 'titel' found for type 'Book'; did you mean 'title'? Available properties: id, title, year.
  - BookRepository.findAll: not a CRUD method of the repository interfaces and not a derived query
  - BookRepository.twice has a body: every method of the interface is implemented by the generated class.

@Query methods

A method with @Query is written as a small QueryMethod constant. The build checks the method and its text before it writes it.

The method against its annotation. Some of the messages:

Method Message (after BookRepository.<method>: )
@Query('select * from books') Future<void> voidRead(); the method returns nothing: a change needs @Modifying, a read a result type
@Modifying() ... Future<String> modifyingText(); @Modifying returns the rows changed (Future<int>), whether any changed (Future<bool>) or nothing (Future<void>), not String
... Future<Page<Book>> pageAlone(); a page needs a Pageable parameter (the window to read)
countQuery: on a method that returns no Page countQuery is for a method that returns a Page
... Future<Map<String, int>> intMap(); a row as a map is a Map<String, Object?>, not Map<String, int>
a private rowMapper the rowMapper of @Query must be public: the generated code refers to it

The text's parameters and placeholders.

Text Message (after BookRepository.<method>: )
... where year = :yeer (parameter year) :yeer matches no parameter of the method (it has year)
... where year = :book.year :book.year matches no parameter of the method (it has book) (to read a property write :#{#book.year})
... where year = ? the query has a plain ? marker: write :name and bind it by the name of a parameter of the method
select * from #{#tableName} ... #{#tableName} is not allowed in the SQL text: only #{#entityName} is; to bind a value write :#{#tableName}
select * from {Bok} {Bok}: no @Table class Bok in the application, did you mean 'Book'?
select {Book.titel} from {Book} {Book.titel}: Book has no property titel, did you mean 'title'? (stored properties: id, title, year, authorId)
select {Book.cache} from {Book} {Book.cache}: Book.cache is @Transient: it has no column

The countQuery is checked the same way and named: BookRepository.counted (countQuery): .... An entity placeholder becomes part of the constant: entities: {r'Book': Book}.

Tables and columns. The build knows the schema from the migrations and init scripts of lib/resources/, found as the starter finds them (spring.sql.migration.locations, default resources:db/migration; spring.sql.init.schema-locations). Without SQL files, the entities are the schema. A misspelled table or column fails the build when a known name is close:

  - BookRepository.column: b.titel: no column titel in books, did you mean 'title'?
  - BookRepository.table: bokks: no table bokks, did you mean 'books'?

This check turns itself off when the build cannot be sure of the schema: a location outside lib/resources/ or with a placeholder, a profile file or an import that may change a location, a file that does not parse, or a NamingStrategy bean of the application that may name the columns differently.

SpEL in @Query: compiled to Dart

A :#{...} value in a @Query text is a SpEL expression. When the build can, it compiles the expression to Dart, checked against the types of the parameters:

@Query('select * from books where title = :#{#book.title}')
Future<List<Book>> sameTitle(Book book);
static final _sameTitle = QueryMethod(
  r'sameTitle',
  const Query(r'select * from books where title = :#{#book.title}'),
  parameters: const [r'book'],
  element: const ClassType<Book>(),
  expressions: [(arguments, context) => (arguments[0] as Book).title],
);

A compiled expression is a function, so the QueryMethod is a static final instead of a static const. The compiler handles the arguments by name (#book), by position (#p1, #a0, [0]), the context's #entityName and #methodName, beans of the application (@cutoffs.year becomes a typed call on context.bean(r'cutoffs')) and the environment (@environment.getProperty('c', '0')).

A mistake in an expression is a build error:

Expression Message (after BookRepository.<method>: the expression :#{...} is invalid: )
#book.titel No property 'titel' on type 'Book'; did you mean 'title'?
#yeer Unknown variable '#yeer'; did you mean '#year'?
1 + Invalid expression: EL1042E...
#book.title.substring() Method 'String.substring' takes between 1 and 2 arguments, but 0 were given
#book?.title.length Cannot read property 'length' on String?

What the compiler cannot handle (a T(String).valueOf(...) call, a text with a ${property} placeholder) is left to the SpEL interpreter at run time: its entry in expressions is null. The classes such an expression reaches, and the beans whose methods it calls, then get the Introspection the interpreter needs (see Only what runs). Entities never get one.

@Procedure, watch…By and changes…By

A method with @Procedure('name') (a database function) is written as a ProcedureMethod constant and a call of operations.procedure<R>, or operations.procedureStream<E> for a Stream:

static const _over = ProcedureMethod(
  r'over',
  Procedure(r'books_over'),
  parameters: [r'minYear'],
  element: ClassType<Book>(),
);

@override
Future<List<Book>> over(int minYear) =>
    this.operations.procedure<List<Book>>(_over, [minYear]);

The classes its rows become are described as a @Query's are. The build refuses a Page or a Slice result, a Pageable or a Sort parameter, an empty function name, and @Procedure together with @Query, @Modifying or @Lock.

Two prefixes are derived like a find, for a store that reports the changes of its rows: watch…By (Stream<List<T>>, a call of operations.watch) and changes…By (Stream<RowChange<T>>, a call of operations.changes). Any other return type is a build error that names the expected one; a changes…By name takes conditions only.

What a method needs of its store

The generated class tells the repository's operations what each method needs of its store, as StoreRequirements: @Lock (locks), @Query (queries), @Procedure (functions), a watch or changes method (changes), @Transactional on a method (transactions).

operations<Book, int>(
  r'Ledger',
  annotations: const [UseStore(r'jdbc')],
  functions: [_over],
  requirements: const [
    StoreRequirement(r'over', DataStoreCapability.functions),
    StoreRequirement(r'findByIsbn', DataStoreCapability.transactions),
  ],
)

The run time compares them with the store when the repository is created. The build does it earlier when it knows the store: it reads the @DataStoreDeclaration constants declared or exported by lib/spring_auto_configuration.dart of the application's dependencies, and takes the store of a repository from its @UseStore, a @UseDataSource (the SQL store), spring.data.store of application.yml or application.properties (without a profile), or the first described store whose defaultWhen holds. A capability the store lacks is then one of the repository's problems, and a @Transactional bean (without a transactionManager:) on a default store described without transactions fails the build. A store nothing describes is left to the run time.

After an upgrade the repositories must be generated again: the generated class passes requirements:.

For a store described with DataStoreDescriptor(collectionsNeedJson: true) (the SQL store) the build also checks the entity of the repository, and the children of its mapped collections: a Map, a Set, or a List of anything but simple values, with neither @Json nor @MappedCollection, is one of the repository's problems, with the fix (Parcel.meta: a Map<String, Object?> property without @Json has no column on a SQL store: add @Json() to keep it as JSON, or @MappedCollection for rows of a child table). A list of simple values is left to the store, which may keep it in an array column.

See also