We have spent two lessons writing entities and relationships, and in the examples we have been using a stationRepository that does not exist yet. Meanwhile, InMemoryStationRepository is still there from 02-01, with its ConcurrentHashMap, its AtomicLong and its six hand-written methods. This lesson retires it.

And it does so in the most striking way possible: by deleting code. Spring Data JPA turns an empty interface into a fully functional repository, with a good twenty methods already implemented, pagination, sorting and exception translation. It is probably the moment in the course where the ratio of effort to result is most favourable. But it is worth understanding what goes on underneath, because several of those inherited methods have semantics that are not what their name suggests —save does not always insert, getReferenceById does not query the database— and mixing them up produces errors that are hard to trace.

1. Spring Data's interface hierarchy
2. How Spring Data creates the implementation
3. Retiring InMemoryStationRepository
4. The inherited methods and their exact semantics
5. findById versus getReferenceById
6. save: insert or merge
7. Optional<T> and handling absence
8. Pagination and sorting
9. Integrating pagination into the REST API
10. Repositories with methods of your own
11. @Repository and exception translation
12. Example and Specification: a first look
13. Common Mistakes and Tips
14. Exercises

What to choose in CicloUrbana. JpaRepository for almost everything: it is what people expect and there is no cost for methods you do not use. The alternative worth considering is extending Repository<T, ID> and declaring only the permitted methods:

It is a defensible design decision: a rental history must never be deleted, and not exposing the method makes the accident impossible. The price is writing by hand the signatures you do want. (A note on ListCrudRepository: it is an addition in Spring Data 3 that returns List<T> where CrudRepository returned Iterable<T>; JpaRepository already extends it.)

This is the question everybody asks: who implements an interface that nobody implements?

At startup, JpaRepositoriesAutoConfiguration (02-06) activates repository scanning from the @SpringBootApplication package. For every interface extending Repository:

1. JpaRepositoryFactoryBean analyses it and determines the entity and the type of its id.
2. It creates an instance of SimpleJpaRepository<T, ID>, the standard implementation containing the real code of save, findById, findAll and so on, written against the EntityManager.
3. It wraps that instance in a Java dynamic proxy implementing your interface.
4. It registers the proxy as a bean in the context.

When you call a method, the proxy decides who to delegate to: if it is inherited (findById, save), to SimpleJpaRepository; if it is a derived query (findByName), it parses the name and generates the query (04-06); if it carries @Query, it runs that query; and if it belongs to a Custom interface you implement, to your implementation (section 10).

This proxy mechanism is the same one from 02-03, taken to the extreme that there is no wrapped object you wrote: the proxy is the only thing that exists of your interface. And a useful consequence: repositories are ordinary singleton beans, injectable through the constructor like any other (02-02).

This is the moment we have been preparing since 02-01. The in-memory implementation was, in summary:

Around eighty lines counting the real file. Its complete replacement:

What disappears:

What has to be adjusted in StationService. The names of our own interface already line up with Spring Data's vocabulary —save, findById, findAll, existsById, deleteById, existsByName—, so the calls stay as they are; what changes are the exact contracts: findById hands back an Optional<Station>, save returns the managed instance you have to keep, and deleteById no longer tells you whether the row existed. That is the only real cost of the change.

You could keep a vocabulary of your own by declaring the methods in the interface and annotating each with @Query, but it does not pay off: Spring Data's names are a shared vocabulary that any Java developer recognises instantly. The domain identifiers stay yours —Station, StationService, StationRepository—; what you adopt is the framework's API, in the same way you write List and not a wrapper of your own.

And the important part: StationController does not change by a single line. The Ribalta REST API stays exactly as it was, with its thirteen endpoints, its DTOs and its status codes. That is the reward for having isolated storage behind an interface from the beginning.

Three warnings that prevent surprises:

deleteAll() versus deleteAllInBatch(). The first loads every entity and issues one DELETE per entity so it can apply cascades and callbacks: with 100,000 rentals, 100,001 statements. deleteAllInBatch() runs a single DELETE FROM rentals, but it skips cascades and the persistence context, which can end up holding entities that no longer exist. Fast and dangerous.

deleteById runs a SELECT before the DELETE, because it needs the entity in order to apply cascades. And if the id does not exist, in Spring Data 3 it throws no exception: it simply does nothing. To return the correct 404 (03-06) you have to check first with existsById and throw ResourceNotFoundException.

count() and existsById() do not load entities. They are pure aggregation queries. Preferring existsById(id) over findById(id).isPresent() is not cosmetic: the latter fetches every column of the row only to throw them away.

This is the most misunderstood difference in the API, and the one that can save the most performance.

The case where getReferenceById shines is exactly CicloUrbana's when starting a rental:

Bike is loaded with findById because we have to read its status and its battery and modify its status. User and Station are only needed to fill user_id and origin_station_id in the INSERT, and for that the id the proxy already holds is enough: we save two SELECTs in the most frequent operation in the whole application.

The risk, which you must be aware of: if the user does not exist, getReferenceById does not fail there but later —when accessing a field of the proxy, or at commit, where the foreign key fails—, and the error arrives dislocated from its cause. The rule: use getReferenceById only to assign associations whose id you have already validated, for instance because it comes from an authenticated user (module 5).

save() looks like a plain "save" and it does two very different things depending on the entity's state (04-01):

The most important practical consequence lies in merge: it returns an instance different from the one you passed in. The one you passed in stays detached.

Always use the value returned by save(). Ignoring it is one of the most common causes of "I modify it and it doesn't get saved".

And the corollary, which we already saw in 04-01 and will develop in 04-07: on a managed entity there is no need to call save(). Inside a transaction, loading with findById, doing station.setActive(false) and calling nothing else is enough and correct: dirty checking generates the UPDATE at commit.

A performance nuance in bulk loads: save() on an entity with an id runs a SELECT before the UPDATE, so it can merge. When inserting thousands of rows with ids already assigned, that SELECT is paid for every one of them. If you know the entity is new, entityManager.persist() avoids it; Spring Data works it out on its own only when the id is null or when the entity implements Persistable.

Spring Data returns Optional<T> from lookups by identifier. It is a deliberate design decision: it makes it impossible to forget the "does not exist" case, which with null is forgotten constantly.

Correct usage in CicloUrbana links directly to the exception hierarchy from 03-06:

It reads straight through: look it up, map it if it is there, and if not throw the exception that the @RestControllerAdvice turns into a 404 with a ProblemDetail.

Frequent incorrect forms:

Useful Optional methods in this context: map to transform, filter to add a condition, orElseThrow to demand presence, orElseGet for a computed default and ifPresentOrElse for two branches. And never use Optional as a method parameter or as an entity field: it is meant for return values.

GET /api/v1/stations today returns Ribalta's four stations. When the network grows to two hundred, or when the year's rentals are listed, returning everything will stop being viable: memory on the server, bandwidth and a client that cannot process it.

The pieces:

The difference in cost matters: Page runs a second SELECT count(*) query which, over a table of millions of rentals with complex filters, can be more expensive than the data query itself. Slice avoids it by asking for one extra row and checking whether it came back.

Nothing has to be declared in the repository: JpaRepository already inherits findAll(Pageable).

And the SQL it generates with PostgreSQL:

A warning about deep pages. OFFSET 100000 forces the database to read and discard a hundred thousand rows before returning twenty. With large tables, cursor-based pagination —"give me the next ones after this id"— is far more efficient (09-01).

Spring MVC resolves Pageable automatically from the query parameters, thanks to PageableHandlerMethodArgumentResolver, which Spring Boot registers on its own.

The API now accepts GET /api/v1/stations?page=0&size=20&sort=capacity,desc.

@PageableDefault matters: without it, the default size is 20 but the client can ask for size=100000 and bring the server down. Cap the maximum globally as well:

Why Page is not returned directly. It is tempting —it works and Jackson serialises it— and it is a mistake. At startup, Spring Boot 3 even warns:

Three concrete reasons: the JSON structure is not stable —PageImpl is an internal Spring Data class whose serialisation has changed across versions and may change again, breaking every Ribalta client on a dependency upgrade—; it leaks internal details, because the JSON includes a pageable object with paged, unpaged and offset, framework concepts alien to the public contract; and it contradicts the discipline of 03-05, since if we do not expose entities, we certainly should not expose the framework's internal classes.

The solution is a DTO of our own, stable and documentable in OpenAPI (03-07):

And in the service, with the mapping inside the transaction as 04-04 demands:

Page.map() transforms the content while preserving the metadata: nothing has to be rebuilt by hand.

The response to the client:

Sometimes a method needs logic that neither derived queries nor @Query can express: direct access to the EntityManager, dynamic construction of criteria or native SQL calls with intermediate processing. Spring Data allows it through a very specific naming convention.

Step 1: the interface with your own methods.

Step 2: the implementation. The name is mandatory: <InterfaceName>Impl.

Step 3: the repository extends both interfaces, with extends JpaRepository<Station, Long>, StationRepositoryCustom.

Spring Data detects that findWithFilters is neither an inherited nor a derivable method, looks for a class called StationRepositoryCustomImpl and delegates to it. The Impl suffix is mandatory —it is configurable with repositoryImplementationPostfix, but there is no reason to change it— and it is mistake number one with this mechanism: with any other name, startup fails with No property findWithFilters found for type Station.

Notice the real value of this pattern: the caller still sees a single interface. StationService injects StationRepository and calls findWithFilters without knowing that its implementation lives in another class. The composition is invisible from outside.

Interfaces do not need the @Repository annotation. Spring Data detects them because they extend Repository. The annotation is necessary on hand-written data access classes, and on StationRepositoryCustomImpl it is optional.

What does matter is what @Repository enables: exception translation. A PersistenceExceptionTranslationPostProcessor —a BeanPostProcessor like the ones from 02-03— wraps the bean and converts provider-specific exceptions into Spring's DataAccessException hierarchy:

The benefit is real: your code catches Spring exceptions and does not depend on Hibernate. If the JPA implementation ever changed, the catch blocks would still be valid.

In CicloUrbana this is put to use in the global handler from 03-06:

It is a safety net, not the main route: the right thing is still to check existsByName before inserting and return a 409 explaining which name is duplicated; this handler covers the race conditions that the prior check cannot avoid. Note as well that the message to the client does not include the exception detail, which contains table and constraint names: to the log yes, to the response no.

Spring Data offers two more mechanisms for dynamic queries. Here is the overview; the detail is in 04-06.

Example (query by example). You build a partially filled entity and Spring Data looks for the ones that resemble it.

It is convenient for simple equality filters, and very limited: it expresses neither ranges (capacity > 20), nor OR, nor conditions over associations. We will not use it in CicloUrbana.

Specification (the Criteria API packaged up). Each condition is an object composable with and and or:

Returning null when the filter is absent is the key: Spring Data ignores those predicates, so the station search accepts any combination of optional filters without a single if concatenating SQL. It is cleaner than the StationRepositoryCustomImpl from section 10, and we will develop it in 04-06.

Ignoring the value returned by save(). With a detached entity, save performs a merge and returns a managed copy; the original stays detached and its changes are lost.

Calling save() on a managed entity. Harmless but unnecessary: dirty checking already generates the UPDATE. It betrays a lack of understanding of the persistence context.

Using findById(id).get(). It throws NoSuchElementException, which without a handler ends up as a 500 instead of the correct 404. Use orElseThrow with ResourceNotFoundException.

Returning Page directly from the controller. JSON that is unstable across versions and framework details in the public contract. Use a PageResponse of your own.

Naming your own implementation wrongly. It must be exactly <InterfaceName>Impl and live in the same package. With any other name, startup fails.

Using deleteAll() on large tables. It loads every entity and issues one DELETE per entity.

Tip: use getReferenceById to assign foreign keys. In a "start rental", it saves two SELECTs in CicloUrbana's most frequent operation.

Tip: prefer existsById over findById(id).isPresent(). The former is a count(*); the latter fetches the whole row.

Tip: cap max-page-size. Without that cap, a client can ask for a million records in a single request.

Tip: do not expose deleteById where it should not exist. Extending Repository and declaring only the permitted methods turns a business rule into a technical impossibility.

For each CicloUrbana repository, choose the base interface and justify it in one or two sentences.

1. StationRepository: full CRUD with paginated listings.
2. RentalRepository: they are created and queried, never deleted; paginated listings per user.
3. FareRepository: five fixed rows, loaded at startup, read-only.
4. IncidentRepository: creation, querying, closing and deletion of the ones that turn out to be false.

Implement the endpoint GET /api/v1/rentals?userId=7&page=0&size=20&sort=startedAt,desc returning a user's rentals paginated. Write the repository, the service and the controller, and explain why you choose Page or Slice.

This service has three defects. Find them, explain the symptom each one produces and fix them.

Solution 1.

1. JpaRepository<Station, Long>. It needs full CRUD and pagination; it is the standard case and there is no reason to restrict the API.
2. Repository<Rental, Long> with hand-declared methods. The rule "a rental is never deleted" is a business rule, and the best way to guarantee it is not to expose the method:

Without deleteById in the interface, nobody can delete a rental by accident: a business rule turned into a technical impossibility.

3. ListCrudRepository<Fare, String>, or even Repository with only findAll and findByCode: five fixed rows need no pagination, and exposing deleteAll over the fare catalogue is an unnecessary risk.
4. JpaRepository<Incident, Long>: it needs all four operations, including the legitimate deletion of false ones.

Solution 2.

Page or Slice. For "my rentals" in a mobile app with infinite scrolling, Slice is better: it saves the SELECT count(*) and the user never sees the total. For an administration dashboard with page numbers, Page is necessary because you have to draw "page 3 of 47". Here we choose Page because the endpoint serves both consumers and the volume per user is moderate —a few hundred rentals—, so the count is cheap; if the history grew to millions of rows per user, we would migrate to Slice or to cursor-based pagination (09-01).

Details not to overlook: @Transactional(readOnly = true) lets Hibernate skip dirty checking (04-07); the mapping to DTO happens inside the transaction, avoiding LazyInitializationException with open-in-view: false; and we check that the user exists, so we return 404 instead of an empty page that would lie about the resource existing.

Solution 3. The three defects:

1. findById(id).get(). If the station does not exist, it throws NoSuchElementException and the client receives a 500 instead of the 404 with ProblemDetail that the 03-06 contract defines.

2. The @Transactional annotations are missing. This is the most serious one: update runs findById and save in two different transactions, so in between the entity is left detached, dirty checking is lost, save has to perform a merge with its extra SELECT and there is no atomicity if something fails in the middle.

3. deleteById without checking existence. It throws no exception if the id does not exist: the client receives a 204 No Content indicating that something which never existed was deleted. And a fourth, minor defect: list returns Page<StationResponse> to the controller, with the JSON stability problem from section 9. Corrected version:

The pattern of @Transactional(readOnly = true) on the class with @Transactional on the methods that write is an excellent convention: everything is read-only by default and writing requires an explicit decision. We will develop it in 04-07.

InMemoryStationRepository is now history. You can place each interface of the Spring Data hierarchy and choose with judgement: JpaRepository as the default option and Repository with hand-declared methods when you want a business rule —"a rental is never deleted"— to be a technical impossibility. You understand how the implementation appears: JpaRepositoryFactoryBean creates a SimpleJpaRepository and wraps it in a dynamic proxy implementing your interface, the same proxy mechanism from 02-03 taken to the point where there is no class of yours underneath. And you have seen the result of the change: eighty lines of concurrent map replaced by an interface of four, without touching a single line of StationController.

You know the exact semantics of the inherited methods, including the three that surprise: save performs a merge if the entity has an id and returns a different instance that you must use; getReferenceById does not query the database and saves two SELECTs every time CicloUrbana starts a rental; and deleteById does not fail when the id does not exist, so the 404 has to be produced by checking beforehand. You handle Optional by linking it to ResourceNotFoundException in an orElseThrow that reads straight through. You have added pagination and sorting to the Ribalta API, telling Page from Slice by the cost of its SELECT count(*), receiving Pageable with @PageableDefault and capping max-page-size so that no client can ask for a million rows. And you return a PageResponse of your own instead of serialising PageImpl, for the same reason you did not expose entities in 03-05. You know how to compose a repository with methods of your own while respecting the Impl suffix, how to use @Repository's exception translation as a safety net against race conditions, and you have a first view of Example and Specification.

What you still cannot do is ask questions. Everything you have queried has been by identifier or the whole table. The Ribalta network needs much more: the stations with free space, the bikes with battery below the threshold, a user's rentals between two dates, the stations nearest to a coordinate, the occupancy report in a single query. Lesson 04-06, Query Methods in Spring Data JPA, covers the whole arsenal: queries derived from the method name with their exhaustive keyword table, @Query with JPQL and projections to DTOs, JOIN FETCH to settle the N+1 of 04-04 once and for all, native PostgreSQL queries for what JPQL cannot reach, @Modifying with its synchronisation traps, projections by interface and by record, @EntityGraph and Specifications for the search with combinable optional filters.