
# 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:

```dart
@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):

```dart
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,
  },
)
```

- `parameter: true` marks a property the constructor takes; `writable: true` one that can be set. An immutable entity (only `final` fields) has no `write`.
- A constructor default is kept (`hasDefaultValue: true, defaultValue: 0`).
- `@Transient` properties are described, so the data layer can skip them; `@MappedCollection` properties and their child entities are described too.
- A DTO of a `@Query` method is described like an entity, without annotations. It is found under `Future`, `Stream`, `Set`, `Page` and nullable types.

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:

```dart
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):

```dart
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:

```dart
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:

```text
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.
```

- "did you mean" appears when a property is close enough; otherwise only the available properties are listed.
- A method reports its first problem only (`findByTitelAndYeer` reports `titel`).
- Two repositories with problems each get their error.
- A repository that names no entity (`implements DataRepository` without type arguments), a nullable entity type and a private interface fail too.

## `@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:

```text
  - 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:

```dart
@Query('select * from books where title = :#{#book.title}')
Future<List<Book>> sameTitle(Book book);
```

```dart
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](optimizations/introspection.md)). Entities never get one.

## `@Procedure`, `watch…By` and `changes…By`

A method with [`@Procedure('name')`](../spring-boot-starter-data/database-functions.md) (a database function) is written as a `ProcedureMethod` constant and a call of `operations.procedure<R>`, or `operations.procedureStream<E>` for a `Stream`:

```dart
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](../spring-boot-starter-data/changes.md): `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 `StoreRequirement`s: `@Lock` (locks), `@Query` (queries), `@Procedure` (functions), a `watch` or `changes` method (changes), `@Transactional` on a method (transactions).

```dart
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`](../spring-boot-starter-data/stores.md) 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`](../spring-boot-starter-data/json-columns.md) 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

- [Build-time checks](checks.md)
- [Stores and their capabilities](../spring-boot-starter-data/stores.md)
- [Bean definitions](bean-definitions.md)
- [Tests: @SpringBootTest and @DataTest](tests.md)
- [Only what runs: introspection](optimizations/introspection.md)
- [SpEL](../spring-core-dart/spel/index.md)
