Every idea is told twice

Once in the words a colleague would use in a review, and once in the words you would use to explain it to someone who has never seen a computer. Both are true. The second one is what you actually remember under pressure.

Whenever a concept is genuinely hard — the persistence context, a database index, a rebase — you will find a sand-coloured box like this one:

And when there is a real trap — something that compiles, passes a quick test, and breaks in production — it is marked as a warning:

There are four other kinds of box. A green example is a thing you can copy and run. A table is a lookup you will come back to. A figure is a picture of a mechanism — if you can redraw it, you understand it. And every chapter ends with Golden rules, which are collected automatically into the Cheat sheet chapter at the end.

# 1. build and run every test — no server, no database needed
mvn verify

# 2. package the WAR and hot-deploy it into WildFly
mvn package

The advert, line by line

This course was assembled around one junior backend job description. Every requirement in it has a chapter, and here is the map.

Read the left column as the recruiter wrote it. The right column is where you go to be able to answer it in an interview — and, more importantly, on the first Monday.

And the four lines the advert files under nice to have — which is where a junior candidate actually wins, because most applicants skip them:

That is one advert. Chapter 36 The market is what happened when thirty of them were read side by side — live junior listings in Bologna, Modena, Milano and Tirana — ranked by how often each requirement appears, with the pay, the contract types, and this same map extended to everything the survey turned up. Chapter 38 The interview is the hundred and forty-eight questions those employers actually ask, and chapter 37 The application is the step in between, where most applications quietly die.

Six chapters exist only because that survey found them: 28 Maven and 29 Migrations, the build and the schema; 30 Modern Java, because the adverts say Java 17 and your course said Java 8; 31 Design and SOLID and 32 The front end; and 34 Reading code with 35 Working with AI, which are about your first month rather than your first interview.

A route through it

Forty-one chapters is six to eight focused weeks. Reading is not the work — the work is the terminal next to the browser.

Golden rules

Four habits that decide whether any of the next forty chapters stick.

1. Read the source file the chapter names.Every claim here points at a real path in src/main/java. A concept you have only read about is a concept you can be talked out of; one you have seen in a file is one you can defend.
2. Break it on purpose, before it breaks you by accident.scripts/break.sh introduces real, documented faults. Recognising an error message once, in calm conditions, is worth more than reading ten explanations of it.
3. Say the plain-language version out loud.If you cannot explain the persistence context without using the words “persistence context”, you have memorised a phrase rather than a mechanism. The sand-coloured boxes exist for exactly this test.
4. The nice-to-haves are where a junior wins.Every applicant claims Java. Far fewer can talk about a Jenkins pipeline, a rebase, a liveness probe or why their own Enrollment has no setter. Chapters 19–21 and 31–33 are short, and chapter 36 counts how rarely other applicants have them.

Jakarta EE is a set of contracts

Jakarta EE is not a library you call. It is a specification — a list of promises an application server makes to your code.

You write a class, mark it with an annotation, and something else takes responsibility for creating it, wrapping it in a transaction, exposing it over HTTP, or handing it a database connection. That "something else" is the container. In this project it is WildFly.

This is the inversion that confuses everyone coming from Spring Boot or plain Java: there is no main() in this codebase. Search for one — you won't find it. The server has the main(). Your code is cargo.

The WAR, and the word provided

Your build produces a WAR — a Web Application Archive. Not a runnable jar. Look at what the build declares:

<packaging>war</packaging>

<dependency>
    <groupId>jakarta.platform</groupId>
    <artifactId>jakarta.jakartaee-api</artifactId>
    <scope>provided</scope>   <!-- ← the whole model, in one word -->
</dependency>

provided means: compile against this, but do not package it. The runtime supplies it. So the WAR contains your classes and no implementation of JPA, CDI, JTA or JAX-RS. Every annotation in the project is an empty marker until WildFly wires it up.

That is why this application's WAR has no WEB-INF/lib directory at all — not one jar sits beside your classes. A Spring Boot fat jar doing the same job is 30–50 MB, because it embeds the server. Neither is wrong — they are opposite answers to "who owns the runtime?"

The four layers, and the rule between them

Requests descend; nothing skips a level. Each layer is allowed to know only about the one directly beneath it.

Golden rules

Four sentences that decide how you read every later chapter.

1. provided means the container owns the runtime.Your WAR ships without a single jar in it because Hibernate, Weld, Narayana and RESTEasy already live in WildFly. Change server, not code, and the same WAR runs on a different set of implementations.
2. An annotation does nothing until something reads it.There is no new anywhere in the service layer. Outside a container every annotation in this project is inert metadata — which is why a unit test has to construct its objects by hand.
3. Requests descend; nothing climbs.service/ never imports a JAX-RS type. The day it does, four folder names are describing one layer, and no compiler will tell you.
4. The package a class lives in is a statement about what it may know.domain/ knows nothing above it, which is what lets the same rules be driven by a REST call, a scheduled job, or a test with no server at all.

The replay

Press play. The left pane is the log; the right pane explains the step you are on; the diagram lights up the layer currently executing.

Now send it for real

The replay above is a recording. This one actually hits your server.

Each attempt generates a fresh correlation ID. Copy it, then grep the WildFly log for that string and you will find the whole request — filter, interceptor, every query, commit.

Eight queries, eight business rules

The service fired eight SQL statements. Each one exists because a rule demanded it — the mapping is one to one.

Golden rules

What the trace teaches, independent of this particular endpoint.

1. Read the SQL log, not the Java, to find out what happened.Two of the eight statements were never written by anyone — getPrerequisites() and getEnrollments() are plain getters that fired queries. The Java is not a reliable description of the database traffic.
2. Every query should be attributable to a rule.Eight statements, eight checks, one to one. A query you cannot attach to a business rule is either dead work or a rule nobody wrote down.
3. Validate everything before mutating anything.All the checks run before the insert, so a rejected enrollment leaves no partial state behind and needs no rollback to clean it up.
4. One request, one id, one grep.CorrelationIdFilter puts an id in the MDC and every later log line carries it. Without that you are searching a shared log by timestamp and hoping.

The equals / hashCode contract

Five clauses for equals, one for hashCode, and only the last one is regularly broken by people who know all six.

Object.equals is specified as an equivalence relation. Any override must keep it one:

Then the one that costs people entire afternoons:

A hash-based collection uses hashCode to pick a bucket and equals to search inside it. If the hash disagrees with equality, the collection looks in the wrong bucket, finds nothing, and reports — perfectly calmly — that the object is not there.

Nothing throws. The set still reports size() == 1. The object is in there, in a bucket no lookup will ever visit again — the closest thing Java has to losing something down the back of a sofa.

Which is exactly why BaseEntity in this project does the thing that looks wrong:

@Override
public boolean equals(Object other) {
    if (this == other) return true;
    if (!(other instanceof BaseEntity)) return false;   // instanceof, not getClass()
    BaseEntity that = (BaseEntity) other;
    return this.getId() != null && this.getId().equals(that.getId());
}

@Override
public int hashCode() {
    return getClass().hashCode();   // constant for the object's whole life
}

• instanceof, not getClass(). Hibernate hands you proxies for lazy associations — generated subclasses. getClass() on a proxy returns something like Student$HibernateProxy$xY7, so a getClass() == other.getClass() test fails against a real Student holding the very same row.
• getId(), not id. Reading the field directly on an uninitialised proxy returns null. The getter triggers initialisation. Every method on an entity should go through getters for this reason.
• A null id equals nothing — including another null id. Two unsaved students are not the same student.
• The hash is constant. Bad distribution — every Student shares one bucket — but correctness first. A hash that changes while the object sits in a set is not a performance problem, it is a data-loss problem.

And the law that trails behind it: compareTo should be consistent with equals. When it is not, a TreeSet and a HashSet disagree about what counts as a duplicate. The canonical example ships with the JDK: new BigDecimal("1.0").equals(new BigDecimal("1.00")) is false — different scale — while compareTo returns 0. Put both into a HashSet and you get two elements; into a TreeSet, one.

Identity is not equality

== asks whether two references point at the same object. For values, that is almost never the question you meant.

Java makes the trap comfortable by caching. Small boxed integers and string literals are shared, so == appears to work — right up to the value where it stops.

The Integer cache is specified, not incidental: Integer.valueOf must return the same instance for every value in −128 … 127. Autoboxing calls valueOf, so == on boxed integers is true inside that window and false outside it. Nothing about your code changes at 128 — only whether two references happen to land on the same object.

The floating-point row is not a curiosity. It is why money is never a double: use BigDecimal with an explicit scale, or store integer cents. A rounding error compounds silently across a million rows and then turns up in an audit.

Immutability, and what final does not give you

final freezes the reference. It says nothing whatsoever about the object on the other end of it.

private final List<String> codes = new ArrayList<>();
codes.add("CS101");         // legal — the list is mutable
codes = new ArrayList<>();   // illegal — the reference is not

An immutable class is one whose observable state cannot change after construction. Getting there takes four things, and people usually stop after two:

1. No setters, and every field final.The obvious half. Necessary, and nowhere near sufficient.
2. The class cannot be subclassed.Make it final, or give it only private constructors plus a static factory — the shape Email uses. A subclass can otherwise add mutable state and override methods.
3. Defensive copies in and out.A constructor that stores the caller's List leaves the caller holding a live reference into your internals. Copy on the way in; copy or wrap on the way out.
4. No this escapes during construction.Registering a listener or starting a thread from inside a constructor publishes a half-built object to somebody else.

The project's answer for outbound state is worth reading closely, because it stops one step short of a copy:

public Set<Course> getPrerequisites() {
    return Collections.unmodifiableSet(prerequisites);
}

unmodifiableSet returns a view. The caller cannot add through it — but the underlying set is still live, so later internal changes are visible through a view the caller already holds. That is the intended behaviour here (the entity stays the single writer, via addPrerequisite), and it is a genuinely different guarantee from Set.copyOf(prerequisites), which snapshots. Know which one you wrote.

A record gives you clauses 1 and 2 for free, plus equals, hashCode and toString derived from the components. It does not give you 3: a record holding a List is only shallowly immutable, and that list is as mutable as ever. Records also cannot be JPA entities — an entity needs a no-arg constructor and non-final fields — which is why the DTOs in this project could be records and the entities could not.

null, Optional, and failing at the right line

A NullPointerException is never thrown where the bug is. It is thrown wherever the null was finally dereferenced — frames away from whoever produced it.

Two tools narrow that gap, and each has a place it belongs.

public T save(T entity) {
    Objects.requireNonNull(entity, "entity must not be null");   // fail here, not later
    ...
}

public Optional<T> findById(Long id) {
    return Optional.ofNullable(entityManager.find(entityClass, id));
}

• requireNonNull asserts a precondition. It converts "something will explode somewhere downstream" into "this caller passed null, on this line". Put it at every boundary you do not control.
• Optional is a statement in the type system. em.find returns null for a missing row; wrapping it makes "might not be there" part of the signature, so the compiler forces the caller to decide.

The rules about where Optional does not belong matter just as much:

Watch how the service turns absence into an HTTP status without a single if:

Student student = studentRepository.findById(cmd.getStudentId())
        .orElseThrow(() -> new ResourceNotFoundException("Student", cmd.getStudentId()));

The exception carries the type and the id; an ExceptionMapper turns it into 404 with a problem document. One decision, expressed once, in the only layer that knows what "missing" means.

Generics: invariant, erased, bounded

Generic types exist for the compiler. At runtime they are gone — and three separate design decisions follow from that single fact.

Erasure means List<String> and List<Integer> are the same class. You cannot write new T[], cannot say T.class, cannot test x instanceof List<String>. Which is why the repository base class carries a constructor parameter that looks redundant and is not:

public abstract class AbstractJpaRepository<T extends BaseEntity> {

    private final Class<T> entityClass;      // because T.class does not exist

    protected AbstractJpaRepository(Class<T> entityClass) {
        this.entityClass = Objects.requireNonNull(entityClass);
    }

    public Optional<T> findById(Long id) {
        return Optional.ofNullable(entityManager.find(entityClass, id));
    }
}

<T extends BaseEntity> is a bounded type parameter: it is what lets this class call entity.isNew() and entity.getId(). With a bare <T> the only methods available would be Object's.

Then the asymmetry that surprises everyone: arrays are covariant and checked at runtime; generics are invariant and checked at compile time.

Object[] arr = new String[1];
arr[0] = 42;                          // compiles. ArrayStoreException at runtime.

List<Object> l = new ArrayList<String>();  // does not compile. Good.

Invariance is the safer design, but it makes some perfectly reasonable code impossible — hence wildcards, and the mnemonic worth memorising:

The same idea drives Page.map in this codebase: it takes a Function<T, R> and returns a Page<R>, which is how the REST layer converts a page of entities into a page of DTOs without the repository ever hearing about DTOs.

Exceptions: a statement about who can recover

Checked or unchecked is not a style preference. It answers one question — can the caller plausibly do something about this?

Every business exception in this project is unchecked, and that is a deliberate, load-bearing decision:

public abstract class BusinessException extends RuntimeException { ... }

1. It rolls back.JTA rolls back automatically on unchecked exceptions only. A checked CourseFullException would let the transaction commit — the seat taken, the rule “enforced”, the data wrong.
2. It does not pollute signatures.enroll() can violate eight rules. Eight throws clauses on every method up the stack is how people learn to write catch (Exception e) {}.
3. It reaches a mapper.JAX-RS ExceptionMappers catch it at the edge and produce one problem document. Nothing in between needs a try.

Four more laws that hold everywhere:

• Never swallow. An empty catch block converts a fault into a mystery. If you genuinely want to ignore it, log at debug and say why in a comment.
• Never return from a finally. It discards any exception in flight, silently. Same for throwing from finally.
• Use try-with-resources. It closes in reverse order and attaches close-failures as suppressed exceptions instead of replacing the real one — which a hand-written finally { r.close(); } does.
• Exceptions are not control flow. Constructing one walks the stack. Throwing one per loop iteration is a performance problem you will find with a profiler and never by reading.

And the wrapping law: when you catch and rethrow, pass the cause — throw new BusinessRuleViolationException(msg, e). Dropping it deletes the only stack trace that pointed at the real line.

Construction order, and why the container avoids constructors

A constructor runs against a half-initialised object. Anything it calls that a subclass can override runs before that subclass exists.

class Base {
    Base() { describe(); }                    // calls the override…
    void describe() { }
}
class Child extends Base {
    private final Integer credits = 5;     // …before this line has run
    @Override void describe() { System.out.println(credits); }
}
new Child();   // prints: null

Initialisation order is fixed and worth being able to recite: static fields and static blocks in textual order, at first active use of the class; then, per instance, the superclass constructor, then instance fields and initialiser blocks in textual order, then the constructor body. The final field really is null during the superclass constructor. final does not mean "already assigned".

This is also why CDI and JPA both insist on a no-argument constructor, and why the real setup work lives elsewhere:

Golden rules

Language-level laws. They hold in every Java program you will ever write, container or not.

1. Equal objects must have equal hash codes. The reverse is not required.The implication runs one way. A collection picks the bucket by hash and searches it by equals, so a hash that disagrees with equality does not throw — it silently stops finding things.
2. Nothing in a hash-based collection may change while it is in there.Mutating a field that hashCode reads moves the object's correct bucket without moving the object. It is now unreachable and still counted by size().
3. == asks “the same object”, which is almost never the question.The Integer cache makes it work up to 127 and fail at 128; string literals make it work until one string is built at runtime. Both make the bug arrive late.
4. final freezes the reference, not the object.A final List field is fully mutable. Immutability needs no setters, no subclassing, defensive copies both ways, and no this escaping the constructor.
5. Optional is a return type.Not a field, not a parameter, never .get(). It exists to make “might be absent” visible in a signature so the compiler can force the caller to decide.
6. Generic type arguments do not exist at runtime.Erasure is why AbstractJpaRepository must be handed a Class<T>, why there is no new T[], and why generics are invariant while arrays are not.
7. Checked versus unchecked answers “can the caller recover?”Here it also decides whether JTA rolls back. Business exceptions extend RuntimeException so a violated rule cannot commit half its work.
8. An injected field is null inside the constructor.Construction happens first, injection second. Setup work belongs in @PostConstruct — or use constructor injection and make the field final.

Three contracts, and choosing an implementation

The interface says what is promised. The class says what it costs — and, crucially, what order you get.

Then the implementations, and the reasons to pick one:

Two of those choices are load-bearing in this codebase, and neither is an accident:

private Set<Course> prerequisites = new LinkedHashSet<>();   // reproducible JSON order

private final Set<EnrollmentStatus> allowed = EnumSet.of(COMPLETED, WITHDRAWN);

• LinkedHashSet makes output deterministic. CourseMapper streams the prerequisites into a JSON array. With a plain HashSet the array order would depend on hash codes — stable within a run, and free to change when a course code changes or the JDK is upgraded. Tests that assert on that array would then fail for no reason a diff can explain.
• EnumSet is a long, not a set. For an enum with ≤64 constants it is a single 64-bit word with one bit per constant. Membership is a bit test. The state machine in EnrollmentStatus is a handful of bitmasks.

Inside a HashMap

An array of buckets, an index derived from the hash, and a rule for what happens when too many keys land in the same place.

Three lines of arithmetic explain almost everything about hash-map behaviour, including why a bad hashCode degrades a map into a list:

h = key.hashCode();
h = h ^ (h >>> 16);        // "spread": mix high bits down into the low ones
index = (table.length - 1) & h;   // cheap modulo — table.length is a power of two

The spread step exists because the index only uses the low bits. Without it, any hashCode that varies only in its high bits — very common for hand-written ones — would collide on every key.

Treeification was added as a defence against hash-flooding — an attacker sending thousands of request parameters engineered to collide, turning every map operation quadratic. It is a safety net, not a licence: a constant hashCode still puts everything in one bucket, and Student is not Comparable, so that bucket cannot even become a tree.

Iterating while modifying

Java's collections are fail-fast: they try to detect concurrent modification and throw, rather than return quietly wrong answers.

for (Enrollment e : enrollments) {
    if (e.isWithdrawn()) enrollments.remove(e);   // ConcurrentModificationException
}

Iterator<Enrollment> it = enrollments.iterator();
while (it.hasNext()) {
    if (it.next().isWithdrawn()) it.remove();    // correct — the iterator knows
}

enrollments.removeIf(Enrollment::isWithdrawn);   // correct, and says what it means

The mechanism is a modCount field: every structural change increments it, and every next() checks that it still matches what the iterator saw when it was created. Two consequences worth internalising:

• The name is misleading. It fires on single-threaded modification too — that is the common case, and the one above.
• It is a best effort, not a guarantee. The javadoc says so explicitly. Never write a catch (ConcurrentModificationException) and treat it as a control-flow signal; it is a bug detector.

Streams are lazy, one-shot, and element-at-a-time

A stream pipeline does nothing until a terminal operation asks for a result — and then it pulls one element through the whole chain before touching the next.

That is not an optimisation detail. It changes how many times your lambdas run, and it is the difference between a limit(2) that reads two rows and one that reads a million.

The source was never fully read: limit short-circuited, and elements after the second match were never even fetched. Now the rules that follow from that model:

response.setPrerequisiteCodes(course.getPrerequisites().stream()
        .map(Course::getCode)
        .sorted()
        .collect(Collectors.toList()));

Three things are worth noticing in four lines. sorted() is a stateful operation: it must buffer every element before it can emit the first, so it defeats short-circuiting downstream. Course::getCode is a method reference, which is a lambda whose body is a single call — same semantics, less noise. And the whole thing runs against a lazily loaded association, which is why the fetch plan matters: if prerequisites was not fetch-joined, the .stream() either fires another SELECT or throws, depending on whether the transaction is still open.

Collectors, and the boxing tax

Two habits that cost measurable performance and are invisible in a code review unless you know to look.

return courses.stream().mapToInt(Course::getCredits).sum();   // IntStream — no boxing

Stream<Integer> allocates an Integer per element and dereferences a pointer per operation. IntStream, LongStream and DoubleStream carry primitives. For sums, averages and counts over a large collection the difference is not subtle — and mapToInt(...).sum() also cannot return null, which reduce(Integer::sum) effectively can.

The collectors worth knowing by name, because they replace whole paragraphs of loop:

And the trap that reaches into the database: a groupingBy over entities is a report you computed in the JVM after loading every row. If the answer is a count, a SELECT ... GROUP BY in the repository does it in the database, returns one row, and does not depend on how many enrollments exist. Streams are excellent at transforming data you already have and a poor substitute for not fetching it.

Golden rules

Data-structure choices leak into your API, your SQL and your tests.

1. HashSet guarantees no iteration order at all.If the collection ends up in a JSON array or an assertion, use LinkedHashSet. Depending on hash order is depending on an accident that is free to change between JDK versions.
2. A bad hashCode turns a map into a list.The index comes from the low bits of a spread hash. A constant hash puts every key in one bucket — and treeification cannot save a key type that is not Comparable.
3. Structurally modify a collection only through its iterator or removeIf.Fail-fast detection is single-threaded too, it is explicitly best-effort, and with a JPA association the same line can trigger a query and a DELETE.
4. No terminal operation, no work.Intermediate operations are lazy and a stream is single-use. Elements are pulled one at a time through the whole chain, which is why limit can stop the source early — and why sorted cannot.
5. Declare the interface, instantiate the class.List, Set, Map in every signature. Naming ArrayList in a parameter type freezes an implementation choice into every caller for no gain.
6. Grouping in Java is a query you decided not to write.groupingBy over entities means every row was loaded first. If the result is an aggregate, GROUP BY in the repository returns one row instead of a million.

Where the threads come from

Undertow keeps a pool of worker threads. Each arriving request is handed to one of them and rides it all the way down and back.

That single sentence has two halves, and both matter. A request is one thread, which is why ThreadLocal-based tooling works at all: the correlation ID lives in the MDC, a per-thread map, and every log line the request produces can read it back. The beans are not per-thread, which is why any field you add to a service is shared by every request in flight.

The three problems, not one

"Thread safety" is shorthand for three independent failures. A fix for one is not a fix for the others.

1. Atomicity.count++ is three operations: read, add, write. Another thread can land between any two of them, and one of the increments is simply lost.
2. Visibility.A write by one thread is not guaranteed to be seen by another, ever. Each core has its own caches and the compiler may keep a value in a register. Without a synchronisation point there is no promise the second thread ever observes the new value.
3. Ordering.The compiler, the JIT and the CPU may reorder instructions as long as a single thread cannot tell. Another thread absolutely can tell.

The demo below is the first of them. Two requests both call an endpoint that reads a counter, adds one, and writes it back — the shape of a mutable field on an @ApplicationScoped bean.

Run the plain version a few times. The result varies — and that is the entire difficulty of this subject. A test that passes is not evidence of correctness; it is evidence that this particular interleaving did not happen this particular time.

happens-before, the only guarantee you get

The Java Memory Model does not promise that writes become visible. It promises something narrower and much more useful: an ordering between specific pairs of actions.

If action A happens-before action B, then everything A did is visible to B. Absent such an edge, the JVM owes you nothing. There are only a handful of ways to create one, and memorising the list is genuinely worth it:

The last row of that table is why immutability is the strongest concurrency tool in the language. An object whose fields are all final and assigned in the constructor is safely published by the JVM: any thread that gets a reference sees fully constructed state, with no synchronisation at the reader at all. That is a guarantee Email, Clock, Instant, String and every value object you write get for free.

The rule for enterprise code

In a container the correct answer is almost never a lock. It is to have no shared mutable state to lock.

Look at what every service in this project holds: injected collaborators, assigned once at injection, never reassigned. No counters, no caches, no "last result", no SimpleDateFormat. Every value that varies per request arrives as a method parameter and lives on the stack — and the stack is private to a thread by construction.

@ApplicationScoped
public class EnrollmentService {

    @Inject private EnrollmentRepository enrollmentRepository;   // set once, then read-only
    @Inject private Clock clock;

    // private int enrollmentsToday = 0;   ← ONE instance. ALL requests. A race.

    @Transactional
    public Enrollment enroll(EnrollCommand cmd) {
        Student student = ...;    // local variable = stack = thread-private
    }
}

Some types are unsafe in ways that are easy to miss, because they look like harmless utilities:

When state genuinely must be shared, the ladder is short and worth climbing in order: an immutable object, then an atomic, then a concurrent collection, then a lock, and only then your own synchronized protocol. Each step down is more powerful and easier to get wrong.

Where the real contention actually is

In an application like this, the interesting race is not between two Java threads. It is between two database transactions.

Java-level synchronisation cannot help you there, and this is the point most people meet late. synchronized guards one JVM. The moment a second server joins the cluster — or the same server restarts mid-flight — the lock protects nothing, because the two competing readers were never in the same process.

The chapters on Persistence and Transactions take those apart. What belongs here is the boundary itself: Java's memory model ends at the JVM. Correctness across processes is a database problem, and the database has its own, stronger vocabulary for it — one that survives a restart.

Golden rules

Five sentences that decide whether your application survives its first busy afternoon.

1. A request is one thread; a bean is not one request.Undertow hands each request a worker thread, but @ApplicationScoped means one bean instance for all of them. Every field you add is shared by every request in flight.
2. Thread safety is three problems, and a fix for one is not a fix for the others.Atomicity (count++ is three operations), visibility (a write may never be seen), ordering (instructions may be reordered). volatile solves the last two and not the first.
3. Without a happens-before edge, the JVM promises nothing.The edges are program order, monitor lock/unlock, volatile write/read, thread start and join, and constructor completion for final fields. If none of those connects your two actions, the second may see stale data forever.
4. Immutable objects are safely published for free.All-final fields assigned in the constructor mean any thread holding the reference sees fully built state with no synchronisation. This is why value objects and DateTimeFormatter are shareable and SimpleDateFormat is not.
5. Never create your own thread inside the container.It carries no transaction, no security context, no MDC, and nothing shuts it down on redeploy. Inject a ManagedExecutorService, or make it a scheduled @Singleton and let the container own the timer.
6. synchronized guards one JVM; a seat is guarded by the database.The moment a second node exists, an in-process lock protects nothing. Cross-process correctness is FOR UPDATE, @Version, or a unique constraint — things that survive a restart.

Tables, rows, and the rules a spreadsheet does not have

A relational database is a set of tables. A table is a set of rows. A row is a fixed list of typed values. That is the entire data model — everything else is a rule about which rows are allowed to exist.

This project has five tables. Read the diagram as: a line means “this column holds the id of a row over there”, and the crow's foot marks the many end.

Keys: the four promises

A key is a constraint, and a constraint is a promise the database will enforce even when your application code forgets to.

The most important line in the whole schema is a two-column unique constraint:

@UniqueConstraint(
    name = "uk_enrollments_student_course",
    columnNames = {"student_id", "course_id"}
)

The service already checks for a duplicate before inserting. So why also constrain it? Because between the check and the insert there is a gap, and another transaction can slip into that gap. Only the database sees every transaction at once, so only the database can make the rule airtight.

Notice also what a primary key is not: it is not a business identifier. student_number is what the university writes on the card, and it is unique — but the primary key is a meaningless generated id. Business identifiers change (people are re-registered, codes are reissued); a surrogate key never does. Both exist here, on purpose.

SELECT, and the order the clauses actually run in

You write a query top to bottom. The database executes it in a completely different order, and knowing that order explains nearly every “why can't I use my alias there” error.

SELECT  c.code,
        c.title,
        c.capacity,
        c.capacity - COUNT(e.id) AS seats_left
FROM    courses c
LEFT JOIN enrollments e
        ON e.course_id = c.id
       AND e.status IN ('ACTIVE', 'FAILED')   -- only these occupy a seat
WHERE   c.academic_year = 2025
  AND   NOW() BETWEEN c.enrollment_opens_at AND c.enrollment_closes_at
GROUP BY c.id, c.code, c.title, c.capacity
HAVING  c.capacity - COUNT(e.id) > 0
ORDER BY seats_left ASC;

Joins, drawn as rows rather than circles

The overlapping-circles picture is where most people learn joins, and it is where most people go wrong: a join does not intersect sets, it matches and multiplies rows.

Indexes, and why the same query is 200× slower

Without an index the database reads every row and checks it. With one, it walks a tree. The difference is not a percentage, it is an order of magnitude.

Four rules cover most of what a junior needs to know about indexing:

• Index what you filter and join on, not what you display. Every foreign key used in a join wants an index; this schema indexes enrollments.student_id and enrollments.course_id for exactly that reason.
• A composite index is ordered, and the order matters. (course_id, status) serves a filter on course_id alone, and one on both — but not one on status alone. Think of a phone book sorted by surname then first name.
• Wrapping the column in a function disables the index. WHERE lower(email) = ? cannot use a plain index on email; you need an index on the expression itself.
• Every index is paid for on write. Six indexes means six trees to update per insert. Indexes are not free storage, they are a read/write trade.

EXPLAIN ANALYZE
SELECT * FROM students WHERE last_name = 'Ferrari';

-- Index Scan using idx_students_last_name  (actual time=0.021..0.024 rows=1)
--   Index Cond: (last_name = 'Ferrari'::text)
--
-- Drop the index and the same query says:
-- Seq Scan on students  (actual time=0.008..3.812 rows=1)
--   Filter: (last_name = 'Ferrari'::text)
--   Rows Removed by Filter: 49999

ACID, and the four ways concurrency lies to you

A transaction is a group of statements that either all happen or none do. That is one letter of four, and the other three are the ones that get asked about in interviews.

Isolation is not a switch, it is a dial — and every step up costs concurrency. The anomalies each level permits are worth memorising, because this is the standard follow-up question after “what is ACID”:

PostgreSQL and Oracle default to READ COMMITTED; MySQL's InnoDB defaults to REPEATABLE READ. This project does not raise the level. Instead it takes a targeted row lock exactly where the race is:

// LockModeType.PESSIMISTIC_WRITE becomes, on PostgreSQL:
SELECT ... FROM courses WHERE id = ? FOR NO KEY UPDATE;

// Request B now waits here until request A commits or rolls back,
// so B can never read a seat count that A is about to change.

That is the mechanism chapter 11 Transactions builds on, and it is the honest answer to “how do you stop two people booking the last seat”: not with a Java synchronized block, which only guards one server, but with a lock held by the one component every server shares.

Four databases, one language, small differences

The advert lists MySQL, PostgreSQL, Oracle and SQL Server as interchangeable. For 90% of the SQL you will write, they are. Here is the 10%.

This is precisely the difference JPA exists to absorb. The project declares one line of configuration and Hibernate emits the right dialect:

<property name="hibernate.dialect"
          value="org.hibernate.dialect.PostgreSQLDialect"/>

<!-- Swap that value for MySQLDialect, OracleDialect or SQLServerDialect
     and the same @Entity classes produce different SQL. That portability
     is real, and it is most of the reason JPA exists at all. -->

Golden rules

What survives from this chapter into every project you will ever work on.

1. A rule that must never break needs a database constraint.The application check gives a friendly 409; the UNIQUE constraint is what actually makes double enrollment impossible, because only the database sees every transaction at once.
2. SELECT runs sixth, not first.FROM → JOIN → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT. That order explains why WHERE cannot see a SELECT alias, and why HAVING filters groups while WHERE filters rows.
3. Filter the optional table in ON, never in WHERE.A condition on the right-hand table in WHERE discards the NULL-padded rows, silently turning a LEFT JOIN into an inner join and losing every unmatched row.
4. Index what you filter and join on — and pay for it on every write.A composite index is usable left-to-right only, and wrapping a column in a function disables it entirely. EXPLAIN is how you find out, rather than guess.
5. Isolation is a dial, and the row lock is usually the better tool.Raising the level costs concurrency everywhere. A SELECT ... FOR UPDATE on the one contended row costs nothing anywhere else, and is what this project uses to protect the last seat.
6. The four vendors differ in spelling, not in concepts.Sequences, LIMIT versus TOP, string concatenation and default isolation. Learn the concepts once; the dialect is a lookup table — and Hibernate hides most of it behind one property.

Entities and the shared base class

Every table in this schema has an id, a version, and timestamps. Rather than repeat them, they live in one place:

@MappedSuperclass
public abstract class BaseEntity implements Serializable {

    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "app_id_generator")
    private Long id;

    @Version                          // optimistic locking — see below
    private long version;

    @Column(name = "created_at", updatable = false)
    private Instant createdAt;
}

@MappedSuperclass is pure code reuse. It is not an entity, has no table of its own, and cannot be queried. Its fields are copied into each subclass's table at mapping time. Contrast that with real JPA inheritance (@Inheritance), where the parent is queryable and the database layout changes.

The Java bit: why equals() is hard here

Two objects representing the same row must be equal. But before persist(), id is null — so an id-based equals makes every new object equal to every other new object, and a HashSet of unsaved entities collapses to one element. This is a genuine, famous JPA trap, and it is why BaseEntity handles it deliberately rather than letting the IDE generate it.

All four relationships, in one class

Course was written to contain every association type you will meet:

// MANY courses → ONE professor. The owning side: this table holds the FK.
@ManyToOne(fetch = FetchType.LAZY, optional = false)
@JoinColumn(name = "professor_id")
private Professor professor;

// SELF-referencing MANY-to-MANY: a course requires other courses.
@ManyToMany(fetch = FetchType.LAZY)
@JoinTable(name = "course_prerequisites",
    joinColumns        = @JoinColumn(name = "course_id"),
    inverseJoinColumns = @JoinColumn(name = "prerequisite_id"))
private Set<Course> prerequisites = new LinkedHashSet<>();

// INVERSE side. mappedBy = "this is mirrored by a field over there".
@OneToMany(mappedBy = "course", fetch = FetchType.LAZY)
private Set<Enrollment> enrollments = new LinkedHashSet<>();

Owning versus inverse is the concept to hold onto. The owning side is whichever one has the foreign-key column; only changes to the owning side are written. Setting the inverse side alone updates your object graph and saves nothing to the database — a bug that looks like "JPA is ignoring me".

Enrollment is not a plain join table: it carries a grade, a status and timestamps. When a relationship has its own data it stops being @ManyToMany and becomes an association entity — two @ManyToOnes pointing outward.

Lazy loading, and the exception it causes

Every association above is LAZY. Accessing one runs a query — but only while the persistence context is still open.

The persistence context is a cache of managed entities that lives for the duration of the transaction. Inside it, a lazy getter transparently fires SQL. Once the transaction commits, entities become detached, and the same getter throws.

Here is that boundary, drawn against the request from Chapter 2:

Run the experiment

This project's query fetch-joins prerequisites so the mapper can read them. Toggle that one clause and watch the endpoint flip:

"SELECT DISTINCT c FROM Course c "
  + "JOIN FETCH c.professor "
  + "LEFT JOIN FETCH c.prerequisites "
  + "WHERE c.id = :id"

N+1, the performance bug you will meet

Load 50 courses in a loop, touch getProfessor() on each, and JPA issues 1 query for the list plus 50 more — one per course. Nothing looks wrong in the Java. The fix is to declare the fetch plan up front:

// N+1: one SELECT for courses, then one per professor
"SELECT c FROM Course c"

// One SELECT, joined
"SELECT c FROM Course c JOIN FETCH c.professor"

You detect it by reading the SQL log, which is exactly why this project sets org.hibernate.SQL to DEBUG. If a single request emits a suspiciously round number of near-identical queries, that is N+1.

Two kinds of locking

Both appear in this codebase, for different problems.

You saw the pessimistic one in the trace: query 2 ended in FOR NO KEY UPDATE. That clause is the lock, and it is why two students cannot both take the last seat.

Golden rules

The five that account for most of the surprises in JPA.

1. Lazy means later — and only while the session is still open.The identical getter succeeds before the commit and throws after it. Nothing about the entity changed; only whether a persistence context is still behind it.
2. A fetch plan is a contract between a query and every consumer of its result.CourseMapper reads getPrerequisites(), so LEFT JOIN FETCH is part of that mapper's requirements. No type, interface or compiler records that link — only a test can.
3. Only the owning side is written.The owning side is whichever one holds the foreign-key column. Setting the mappedBy side alone updates your object graph and saves nothing, which reads as “JPA is ignoring me”.
4. A suspiciously round number of near-identical queries is N+1.1 + 50, never 51 different statements. You find it by reading the log, which is why org.hibernate.SQL sits at DEBUG in this project.
5. Optimistic for edits, pessimistic for counting seats.@Version says “tell me if someone beat me to it”. FOR NO KEY UPDATE says “nobody else moves until I commit”. Only the second can protect a read-decide-insert sequence.

Transient, managed, detached, removed

The same Enrollment object behaves completely differently depending on which of four states it is in — and nothing in its type says which.

The persistence context is the thing doing the knowing. It is a map from primary key to entity instance, created when the transaction begins and thrown away when it commits. Everything below is an operation on that map.

// nothing has touched the database

Dirty checking, and when the SQL actually runs

The provider took a snapshot of every field when it loaded the row. At flush time it compares, and writes only what differs.

@Transactional
public Course changeCapacity(Long id, int capacity) {
    Course course = courseRepository.findById(id)          // now MANAGED
            .orElseThrow(() -> new ResourceNotFoundException("Course", id));
    course.changeCapacity(capacity);                        // just a field write
    return course;                                          // UPDATE happens at commit
}

No repository call is needed for the update, and adding one changes nothing. That surprises people twice: first that it works, then that save() is redundant rather than required.

Flush is the moment pending changes become SQL. It happens at three points, and the middle one is the one people forget:

1. At commit.Always. This is the one you rely on.
2. Before a query that might be affected.The default FlushModeType.AUTO flushes before running a JPQL query whose result could depend on unwritten changes — otherwise your own query would not see your own work.
3. When you call em.flush().Occasionally necessary: to get a generated id early, or to force a constraint violation to surface at a line you control rather than at commit.

persist versus merge, precisely

The single most common JPA bug is calling merge and ignoring what it returns.

public T save(T entity) {
    if (entity.isNew()) {
        entityManager.persist(entity);
        return entity;              // same instance — persist mutates it
    }
    return entityManager.merge(entity);   // DIFFERENT instance — use this one
}

Write repository.save(course); and discard the result and your changes may vanish without a single error. The signature is trying to tell you: it returns something because the something it returns is not what you gave it.

The rest of the operations, compactly:

Cascade: which operations travel down the association

A cascade says "whatever you do to the parent, do to the children too". Choosing ALL because it sounds convenient is how rows disappear.

This project makes two different choices for two structurally similar associations, and the contrast is the lesson:

// Student — an enrollment cannot outlive its student
@OneToMany(mappedBy = "student", cascade = CascadeType.ALL,
           orphanRemoval = true, fetch = FetchType.LAZY)
private Set<Enrollment> enrollments = new LinkedHashSet<>();

// Professor — a course must NOT vanish when a professor leaves
@OneToMany(mappedBy = "professor", fetch = FetchType.LAZY)
private Set<Course> courses = new LinkedHashSet<>();

The test is ownership, not convenience: does the child have any meaning without this parent? An enrollment is a fact about one student and is meaningless without them — it is part of the aggregate. A course outlives whoever teaches it — a different aggregate that happens to be pointed at.

// pick an operation

orphanRemoval is not a cascade — it is stronger. CascadeType.REMOVE fires when you delete the parent; orphanRemoval fires when you merely take the child out of the collection. One line — student.getEnrollments().remove(e) — becomes a DELETE at flush. That is the correct behaviour for a part, and catastrophic for a reference.

The first-level cache, and the one that is switched off

The persistence context is itself a cache, and it is not optional. The second-level cache is, and here it is off.

Inside one transaction, find(Course.class, 55L) twice issues one SELECT. The second call finds the entity in the context and returns the same instance — reference-identical, guaranteed by the spec. That guarantee is why entity equals by id is safe within a transaction, and why it stops being enough across two.

<shared-cache-mode>NONE</shared-cache-mode>

With L2 off, every query you read in the SQL log corresponds to a real round trip — nothing is quietly served from memory, so the log tells the truth. That is worth more while learning than the throughput a cache would buy. In production the setting is ENABLE_SELECTIVE plus @Cacheable on the entities that are read constantly and written rarely — reference data, not enrollments.

Golden rules

The state an entity is in explains more bugs than any other single fact about it.

1. Only a managed entity writes itself to the database.Change a field on a managed entity and the UPDATE appears at commit; change the identical field on a detached one and absolutely nothing happens, with no error.
2. Commit detaches everything at once.The persistence context closes with the transaction. Every entity that was managed becomes detached in the same instant — which is the entire explanation for LazyInitializationException in the mapper.
3. merge returns a different object.persist mutates its argument; merge copies state onto a managed instance and hands it back, leaving your argument detached. Ignoring the return value is the most common JPA bug there is.
4. Cascade follows ownership, not convenience.Ask whether the child means anything without this parent. An enrollment cannot outlive its student (ALL + orphanRemoval); a course outlives its professor (no cascade at all).
5. orphanRemoval deletes on removal from the collection.Stronger than CascadeType.REMOVE, which only fires when the parent is deleted. list.remove(child) becomes a DELETE at the next flush.
6. Within one transaction, the same row is the same instance.The first-level cache is not optional and is guaranteed by the spec. It is also why loading fifty thousand rows to modify one is expensive: every one of them is snapshotted for dirty checking.

Scopes decide lifetime

An annotation on the class tells the container how many instances to keep and how long they live. This project uses four:

Interceptors — the same idea as a decorator

Because the container constructs your beans, it can wrap them. @Loggable is a custom binding; anything annotated with it gets timed:

@Loggable
@Interceptor
public class LoggingInterceptor {

    @AroundInvoke
    public Object logInvocation(InvocationContext ctx) throws Exception {
        // ... log entry, start timer
        Object result = ctx.proceed();     // ← continue the chain
        // ... log exit and elapsed time
        return result;
    }
}

Those -> EnrollmentService.enroll and <- completed in 162ms lines in the trace came from here, not from the service. ctx.proceed() is the hinge: everything before it runs on the way in, everything after on the way out.

This is precisely how @Transactional works. It is an interceptor too — begin before proceed(), commit or roll back after. Understanding one explains the other.

Events, and the phase that matters

The service fires one event. Two observers receive it — and the difference between them is a single clause:

// Runs IMMEDIATELY, inside the transaction. If it throws, everything rolls back.
public void auditEnrollmentCreated(@Observes EnrollmentCreatedEvent e) { ... }

// Runs only AFTER a successful commit.
public void onEnrollmentCreated(
        @Observes(during = TransactionPhase.AFTER_SUCCESS) EnrollmentCreatedEvent e) { ... }

In the trace you can see the commit happen between them:

14:34:40,710  [AUDIT] enrollment.created id=202   ← inside the transaction
14:34:40,710  <- enroll completed in 162ms       ← COMMIT happens here
14:34:40,716  [NOTIFICATION] To matteo...        ← after the commit

Golden rules

Objects the container builds behave differently from ones you build.

1. @ApplicationScoped plus a mutable field is a race condition.One instance is shared by every concurrent request. The 17 application-scoped beans here are stateless on purpose — all state travels in method parameters.
2. ctx.proceed() is the hinge.Everything before it runs on the way in, everything after on the way out. That one idea explains @Loggable, @Transactional and @RolesAllowed at once.
3. An observer inside the transaction can veto it; one after it cannot.A plain @Observes that throws rolls the enrollment back. AFTER_SUCCESS runs only once the row is committed — and by then nothing it does can be undone.
4. Never do anything irreversible inside a transaction.Emails, payments, calls to other systems. The transaction can still roll back after your observer ran; the email cannot.

@Transactional wraps the method

Put it on a method and the container begins a transaction before the body runs and commits when it returns. The whole method is atomic: all eight of those queries either land together or not at all.

It also defines the persistence-context lifetime — which is why the detachment boundary from Chapter 3 sits exactly at the closing brace of enroll().

Rollback rules surprise everyone

By default, Jakarta EE rolls back on unchecked exceptions only.

That last row is not a bug — it comes from a distinction the specification draws between a checked exception (an expected business outcome, e.g. "insufficient funds") and an unchecked one (something broke). It rarely matches intuition, which is why every business exception in this project extends RuntimeException. If you need different behaviour: @Transactional(rollbackOn = ...).

The self-invocation trap

This is the one that silently costs people days.

Interceptors work through a proxy. The container hands callers a wrapper, and the wrapper applies the annotation before delegating to your real object. So a call from outside is intercepted. A call from inside the same object goes straight to this — bypassing the proxy entirely.

The symptom is brutal: the annotation is right there in the source, so the code looks correct, but no transaction is ever started. The fix is to move the annotated method into a different bean and inject it.

Golden rules

Where the boundary is, and what it takes with it.

1. The transaction ends at the closing brace, and takes the persistence context with it.Every entity the method returns is detached from that instant. The mapper always runs on the far side of that line.
2. Unchecked rolls back, checked commits.Counter-intuitive, and specified. It is why every business exception here extends RuntimeException — override it with @Transactional(rollbackOn = ...) only deliberately.
3. this.method() is never intercepted.The call never leaves the object, so the proxy never sees it and the annotation silently does nothing. The fix is another bean, not another annotation.
4. One service method is one unit of work.The boundary belongs to the layer that owns the rules. A resource that opens a transaction has taken the service's job; a repository that opens one has taken it twice.

A resource is a thin translator

@Path("/enrollments")
@Consumes(MediaType.APPLICATION_JSON)
public class EnrollmentResource {

    @POST
    public Response enroll(@Valid @NotNull EnrollRequest request) {
        // validate → delegate → map → status code. No rules live here.
    }
}

No business logic, no SQL, no try/catch. @Valid makes the container validate before your method is entered, and failures are handled centrally. A resource that grows an if about eligibility has taken work that belongs to the service.

DTOs exist to break a coupling

Entities are never returned directly. If they were, a JPA mapping change would silently alter your public API, lazy associations would serialise unpredictably, and every internal field would be exposed. The mapper is the seam — and, as Chapter 3 showed, also where fetch plans get enforced.

Exception mappers: errors handled once

Instead of try/catch in fifty endpoints, each exception type is mapped to a status in one place:

The 409s are worth noticing. 409 Conflict means "your request was well-formed, but the current state of the server forbids it" — a full course, a suspended student, a closed window. That is a different failure from 400 Bad Request, which means the request itself was malformed. Getting this distinction right is most of designing a decent API.

RFC 7807 and correlation IDs

Every error returns the same document shape — a published standard, not a house style:

{
  "type": "https://api.unicam.it/problems/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "errorCode": "INTERNAL_ERROR",
  "instance": "/courses/55",
  "correlationId": "BREAK-2"
}

That correlationId is the operational payoff. CorrelationIdFilter assigns an ID per request and puts it in the MDC — a per-thread map the logging system reads. The log pattern includes %X{correlationId}, so every line that request produced carries it.

A user reports an error and quotes the ID; you grep one string and get that request's entire life — filter, service, all eight queries, the exception. Without it, you are searching a shared log by timestamp and hoping.

Console — provoke every status code

Reading a table of status codes teaches you less than making the server produce them. Each button below is a real request.

The read-only ones are safe to repeat. The two marked writes change data — that is deliberate, because the second click is what demonstrates the duplicate rule.

Golden rules

The API contract, stated as rules rather than as endpoints.

1. A resource translates; it never decides.Validate, delegate, map, choose a status code. An if about eligibility in a JAX-RS method is a rule the scheduled job will never run.
2. 400 means the request is malformed. 409 means the request is fine and the world says no.Full course, suspended student, closed window, duplicate enrollment — all 409. Getting that split right is most of designing a decent API.
3. Handle each failure once, in a mapper.Fifty try/catch blocks are fifty chances to disagree about a status code. One ExceptionMapper per exception type, and the endpoints stay empty of error handling.
4. Never return an entity.Without a DTO, a mapping change becomes an API change, lazy associations serialise unpredictably, and every internal field is public by default.
5. Errors carry an id, not a stack trace.The client gets a correlationId in a problem+json body; the server log gets the detail. A stack trace in a response hands out your library versions for free.

Content negotiation, and what the annotations really say

@Produces and @Consumes are not documentation. They participate in dispatch, and they can make a method unreachable.

@Path("/courses")
@RequestScoped
@Produces(MediaType.APPLICATION_JSON)   // what this resource can write
@Consumes(MediaType.APPLICATION_JSON)   // what it will accept
public class CourseResource {

    @POST
    public Response create(@Valid @NotNull CreateCourseRequest request) { ... }
}

The container matches a request to a method in a fixed order, and each step has a status code it produces on failure. Knowing the order turns three confusing responses into obvious ones:

Path templates are matched by specificity, not by declaration order — literal segments beat template variables, so /courses/open wins over /courses/{id} regardless of which is written first in the file. That is a spec rule, and relying on it is fine; relying on file order is not.

JSON-B: the rules that decide your wire format

Nobody in this project writes a parser. A DTO's field names, types and getters are the JSON contract.

JSON Binding maps by convention, and the conventions are worth knowing because breaking one silently changes your API:

And the requirement that explains why the request DTOs look unlike every other class in the codebase:

/** Required by JSON-B for deserialisation. */
public CreateStudentRequest() { }

Deserialisation needs a no-arg constructor and setters — somewhere to put the values as they are parsed. The domain model is immutable and the DTOs are not, and that is the correct trade: mutability is confined to a class whose entire life is one request, and which no business rule ever reads.

Validation runs twice, deliberately

The same constraint appears on the DTO and on the entity. That is two lines of defence with two different audiences, not copy-paste.

// DTO — runs at the HTTP boundary because of @Valid on the parameter
@NotBlank(message = "email is required")
@Email(message = "email must be a valid address")
private String email;                      // → 400 with per-field messages

// Entity — runs at @PrePersist, on every path including jobs and imports
@NotBlank(message = "{email.notblank}")
@jakarta.validation.constraints.Email
private String value;                      // → ConstraintViolationException, rollback

The boundary check gives a human a useful 400. The entity check protects the database from paths that never touch HTTP — the seeder, the nightly job, a future import. Delete either one and something real stops being guarded.

• @Valid is what triggers it. A DTO covered in constraints and no @Valid on the parameter is validated by nobody. The annotations are inert metadata — the same law as everywhere else in this book.
• @Valid cascades. On a field, it validates the nested object too. Without it, constraints inside a nested DTO are never checked.
• Order is not guaranteed. All constraints on a bean run and all violations come back together — which is why a 400 here lists every bad field at once instead of making the caller fix them one at a time.
• Groups let one class have two contracts. @NotNull(groups = Update.class) plus @Validate(groups = ...) expresses "required when updating, optional when creating" without a second DTO.

Where a constraint cannot be expressed with the built-ins, you write one. This project has exactly one, and it is instructive because the interesting half is not the regex:

@Constraint(validatedBy = StudentNumberValidator.class)
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface StudentNumber {
    String message() default "must be six digits";
    Class<?>[] groups() default {};              // required by the spec
    Class<? extends Payload>[] payload() default {};
}

Those three members are mandatory — a constraint annotation without message, groups and payload fails at deploy time. And the validator itself is a CDI bean, so it can @Inject: a uniqueness check that queries a repository is a perfectly legitimate custom constraint, and a much better place for the rule than the fourth line of a service method.

Choosing the status code

Most API design arguments are really one question asked repeatedly: whose fault is it, and can retrying help?

The 400/409 line is the one that decides whether an API feels well designed. Malformed means the message could never be valid: a missing studentNumber, a date that is not a date. Conflict means the message was perfect and the world said no: the course is full, the student is suspended, the enrollment window closed. A client can fix the first by changing the request and can only fix the second by waiting or doing something else — which is precisely the distinction the status code exists to communicate.

Safe, idempotent, and why it matters more than it sounds

These are not adjectives. They are guarantees that proxies, browsers and retry logic act on without asking you.

The practical consequence: a client that times out on a PUT can safely retry, and a client that times out on POST /api/enrollments cannot — it may have enrolled the student already. That is a real problem with a standard answer: a caller-supplied idempotency key, stored with a unique constraint, so the second attempt collides and returns the first result instead of a second enrollment. This project does not implement one, and the unique constraint on (student, course) quietly does the same job for this particular operation.

Golden rules

The boundary is a translation layer. Every rule here is about not letting the two sides leak into each other.

1. Dispatch fails before your method runs.Path, then verb, then Content-Type, then Accept — producing 404, 405, 415, 406 in that order. A 415 from a valid JSON body means the header was missing, and nothing you wrote ever executed.
2. The getter name is the JSON field name.JSON-B derives the wire format from accessors, serialises enums by name() and omits nulls. Renaming a getter or an enum constant is a breaking API change with no compiler error anywhere.
3. Never accept or return an entity.It permits mass assignment, couples the schema to the contract, cannot describe both create and response shapes, and serialises lazy associations. Four separate problems, one mapper layer.
4. Constraints without @Valid are decoration.The annotation on the parameter is what triggers validation, and @Valid on a field is what makes it cascade into nested objects. Same law as every other annotation: something has to read it.
5. Validate at the boundary and in the entity.The DTO's constraints produce a helpful 400 for a human; the entity's run at @PrePersist and protect the database from the seeder, the nightly job and the import that has not been written yet.
6. 400 is “this message is wrong”; 409 is “the world says no”.A malformed request can be fixed by changing it; a conflict can only be fixed by the state changing. Getting this line right is most of what makes an API feel designed rather than assembled.
7. Idempotency is a promise clients act on.PUT and DELETE are safe to retry, POST is not. Either supply an idempotency key or rely on a unique constraint — a timed-out POST that gets retried is not a hypothetical.

Rich versus anemic

The anemic domain model is the common shape: entities hold data, services hold all logic. It works, but every rule can be bypassed by any code that sets a field directly.

Enrollment takes the other approach — it has no public setter for status. The only way to change it is a method that enforces the rules:

public void recordPass(int grade, boolean withHonours, Instant at) {
    transitionTo(EnrollmentStatus.COMPLETED);      // legal move?

    if (grade < 18 || grade > 30)
        throw new IllegalArgumentException(...);   // Italian scale

    if (withHonours && grade != 30)
        throw new IllegalArgumentException(...);   // lode needs exactly 30
}

You cannot construct an invalid Enrollment through the public API of the class. That is the whole idea: make illegal states unrepresentable rather than merely unlikely.

The state machine — try it

Transitions are declared once, as data, and every mutating method routes through the check. Click a status to see what it can legally become:

Selected: ACTIVE — an enrollment starts here.

map.put(ACTIVE,    EnumSet.of(COMPLETED, WITHDRAWN, FAILED));
map.put(FAILED,    EnumSet.of(ACTIVE, WITHDRAWN));       // retake allowed
map.put(COMPLETED, EnumSet.noneOf(EnrollmentStatus.class));  // terminal
map.put(WITHDRAWN, EnumSet.noneOf(EnrollmentStatus.class));  // terminal

Custom validation

Bean Validation ships with @NotNull, @Size, @Positive and friends. When a rule is domain-specific you write your own — an annotation plus a validator:

@Constraint(validatedBy = StudentNumberValidator.class)
@Target({FIELD, METHOD, PARAMETER, ANNOTATION_TYPE})
@Retention(RUNTIME)
public @interface StudentNumber {
    String message() default "must be a valid student number: exactly 6 digits";
}

// The validator. Pattern is compiled ONCE as a static field —
// String.matches() would recompile it on every single call.
public boolean isValid(String value, ConstraintValidatorContext ctx) {
    return MATRICOLA_PATTERN.matcher(value).matches();
}

@Retention(RUNTIME) is mandatory — without it the annotation is discarded after compilation and the container can never see it. That single missing line is a common cause of "my custom constraint does nothing".

Golden rules

What it means for the rules to live in the objects themselves.

1. No setter for status — only moves.recordPass() checks the transition first and the grade second. There is no public path that sets COMPLETED without passing both.
2. Legal moves are data, not if statements.An EnumMap of EnumSets cannot drift out of sync with the enum, and one transitionTo is the single place a move is approved.
3. Make illegal states unrepresentable, not merely unlikely.Grade 18–30, lode only at exactly 30, enforced by the object that owns the fact. Any caller that forgets is refused rather than trusted.
4. @Retention(RUNTIME) or the container never sees your annotation.Without it the annotation is discarded after compilation. It is the usual cause of “my custom constraint does nothing”, and it fails silently.

Nothing is protecting these endpoints

Not "weak security". None. I searched the codebase.

Every request in this API is anonymous and equally privileged. The console you used in Chapter 6 sent no credentials — it did not need any. And these endpoints exist:

DELETE  /api/students/{id}              // remove a student
POST    /api/students/{id}/suspension   // suspend anyone
DELETE  /api/enrollments/{id}           // withdraw an enrollment
PATCH   /api/courses/{id}/capacity      // resize any course
POST    /api/enrollments/{id}/grade     // award yourself a 30 e lode

Anyone who can reach the port can award grades. That is the honest description, and the README states it plainly under known limitations rather than hiding it.

The one thing standing in the way

So why is this not a catastrophe on your laptop? One line in your server log:

WFLYUT0006: Undertow HTTP listener default listening on 127.0.0.1:8280
WFLYSRV0060: Http management interface listening on http://127.0.0.1:10190

127.0.0.1 is the loopback interface. The operating system will not route external packets to it, so nothing outside your machine can open a connection — not another laptop on your wifi, not the coffee shop network. The API is unauthenticated and unreachable at the same time.

What Jakarta EE would give you

The platform has this built in; the project simply does not use it. Roles are declarative, exactly like the transaction and interceptor annotations from earlier chapters:

@POST
@Path("/{id}/grade")
@RolesAllowed("PROFESSOR")          // only professors grade
public EnrollmentResponse recordGrade(...) { ... }

@DELETE
@Path("/students/{id}")
@RolesAllowed("ADMIN")
public void delete(...) { ... }

// And to know WHO is calling, rather than just what role:
@Inject SecurityContext securityContext;
String caller = securityContext.getCallerPrincipal().getName();

Enforcement is an interceptor, the same mechanism as @Transactional and @Loggable — which is why @RolesAllowed is mentioned in Loggable.java as a sibling example. That also means it inherits the self-invocation trap from Chapter 5: an internal call bypasses the proxy and therefore bypasses the role check.

Where identity comes from

For an API like this one, JWT or OIDC is the realistic answer. WildFly ships Elytron to do the verification, so the application still only writes @RolesAllowed.

What the code does get right

Missing authentication is a design decision. These are the bugs it did not have.

Injection is structurally impossible

Every query binds its inputs — 34 setParameter calls across the repositories, and not one string-concatenated parameter. Bound parameters are sent to the database separately from the SQL text, so a value can never be parsed as code, no matter what it contains.

Test it against your own server. The payloads below are the classics:

The classic ' OR '1'='1 returns fewer rows than a normal search, not more — because the server searched for a student literally named ' OR '1'='1. The payload was treated as data. That is the whole defence, and it is free as long as you never build query strings by concatenation.

Errors do not leak internals

When you broke the fetch plan in Chapter 3, the response was:

{ "detail": "An unexpected error occurred. Please quote the correlation id
              when reporting this problem.",
  "correlationId": "BREAK-2" }

No stack trace, no class names, no SQL, no framework versions. The full detail went to the server log, and the client got a correlation ID to quote. Stack traces in HTTP responses are a genuine disclosure problem — they hand an attacker your library versions and internal structure for free.

Input is validated before your code runs

Bean Validation rejects malformed input at the boundary, and @StudentNumber constrains a field to exactly six digits. That is not an anti-injection measure — parameter binding already handles that — but it shrinks the range of values that ever reach the domain.

Secrets, and the rest of the surface

The CORS question, answered properly

The project sends no CORS headers, and that is frequently misread as a vulnerability. It is the opposite. Without Access-Control-Allow-Origin, browsers refuse to let JavaScript on another origin read the responses — the restrictive default.

Two things follow. First, this tutorial page can call the API only because WildFly serves it from the same origin; that is why the artifact copy cannot. Second, CORS is a browser policy, not an access control: curl, a script, or any non-browser client ignores it entirely. It is not a substitute for authentication, and it never was.

The exercise

Adding authentication is the most valuable change you could make to this codebase, and it touches every layer you have studied.

• Start with roles. Add @RolesAllowed("ADMIN") to one destructive endpoint and watch it return 401 instead of succeeding. One annotation, immediate feedback.
• Then identity. Configure an Elytron JWT realm so a bearer token supplies the caller and their roles.
• Then the domain rule. A professor may grade only their own course. That check belongs in EnrollmentService, beside the eligibility rules — not in an annotation, because it depends on data.
• Then the tests. Assert that an unauthenticated call is refused. A security control with no test is a security control that will be removed by a future refactor without anyone noticing.

The half that is now written

The enrollment API above is still wide open, and deliberately so — it is the specimen. But this page's own accounts are real, and they live in the same WAR, under it.unicam.cs.enrollment.fieldbook. Everything the exercise asks for exists there in working form, which makes it the most useful thing in the repository to read after this chapter.

It is a second bounded context, not an extension of the enrollment model: a learner is not a student, even when they are the same person. One has a matriculation number and a registrar; the other has a password and a reading streak. Merging them looks like reuse for about a week, and then the registrar suspends somebody and the fieldbook logs them out.

The decisions, and what each one cost

What is still missing, stated plainly

No email verification, so an address is never proved. No password reset, which for a real product is not optional and needs a mail server. No multi-factor. No audit log of sign-ins. The rate limiter is in memory, so it resets on redeploy and is per node — on a cluster an attacker gets its budget once per node, and the real answer is a shared store plus a limiter at the ingress. And the enrollment API next door is still completely unauthenticated, on purpose, because it is the thing this chapter is about.

That list is the point of the section. Writing down what you have not built reads as engineering judgement; discovering it in review reads as something else.

Golden rules

The chapter in six lines — and the ones most often got wrong in interviews.

1. Network position is not access control.The only thing standing between this API and a stranger is 127.0.0.1. One flag — -b 0.0.0.0, which the Docker image uses — puts an unauthenticated grade-awarding API on the local network, with no code change at all.
2. Authentication, authorisation and the domain rule are three different checks.Who you are (a verified token), what your role may do (@RolesAllowed), and whether this is your course (a service-layer check, because it depends on data). An annotation can only ever answer the middle one.
3. A role check is an interceptor, so it inherits the self-invocation trap.An internal this.method() call bypasses @RolesAllowed exactly as it bypasses @Transactional. Same proxy, same hole.
4. Bound parameters are the entire SQL-injection defence.34 setParameter calls, zero concatenated queries. The payload arrives at the database as a value, never as text to parse — which is why ' OR '1'='1 returns fewer rows, not more.
5. CORS is a browser policy, not a gate.It stops other origins' JavaScript from reading responses. curl and every script ignore it, so it was never authentication.
6. Write down what you have not secured.A study project claiming to be production-ready teaches the wrong lesson; a real project with an undocumented gap is worse. The README states this one plainly.

Where the server went

Jakarta EE hands a WAR to a server that already exists. Spring Boot puts the server inside the jar and hands you an executable. That single packaging decision is most of the visible difference.

There is one genuinely new thing, and it is the class with main() in it:

@SpringBootApplication
public class EnrollmentApplication {
    public static void main(String[] args) {
        SpringApplication.run(EnrollmentApplication.class, args);
    }
}

// @SpringBootApplication is three annotations in a trench coat:
//   @Configuration        this class may define beans
//   @ComponentScan        scan THIS package and everything under it
//   @EnableAutoConfiguration  configure whatever you find on the classpath

Dependency management: starters and the parent

The advert asks specifically about dependency management. In Spring Boot it means two things: a starter, which is a bundle of dependencies, and a parent, which decides every version so you do not have to.

Compare the two build files. Both projects use Hibernate, both expose JSON over HTTP, both validate input:

<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>10.0.0</version>
  <scope>provided</scope>
</dependency>

<!-- compiled against, never packaged.
     WildFly supplies the implementation. -->

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.3.4</version>
</parent>

<dependency>  <!-- no version -->
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Two words explain that right-hand column.

• A starter is an empty artifact whose only content is other dependencies. spring-boot-starter-web pulls in Spring MVC, Jackson, validation and an embedded Tomcat. You ask for a capability, not for eleven libraries.
• The parent POM contains a BOM — a bill of materials listing a known-compatible version of roughly four hundred libraries. Omit <version> and you inherit the tested one.

# the full tree, including everything pulled in transitively
mvn dependency:tree

# why is THIS library here, and who asked for it?
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind

# which version won, and which were suppressed?
mvn dependency:tree -Dverbose

Auto-configuration — the part that looks like magic

You add a dependency and a feature appears. There is no magic in it: a long list of conditional configuration classes runs at startup and each one asks “is my library present, and has the developer already defined this bean?”

java -jar app.jar --debug

============================
CONDITIONS EVALUATION REPORT
============================

Positive matches:
   DataSourceAutoConfiguration matched:
      - @ConditionalOnClass found 'javax.sql.DataSource'

Negative matches:
   MongoAutoConfiguration:
      - @ConditionalOnClass did not find 'com.mongodb.client.MongoClient'

Configuration, and the order that decides who wins

The same application must run on a laptop, in CI and in production without recompiling. Spring Boot solves this with layered property sources and a strict precedence order.

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://localhost:5433/enrollment
    username: enrollment
    password: ${DB_PASSWORD}          # from the environment, never in git
  jpa:
    hibernate.ddl-auto: validate      # never `update` in production
    properties.hibernate.format_sql: true

enrollment:
  max-courses-per-student: 8          # your own settings live here too

---
spring:
  config.activate.on-profile: test    # mvn test picks this up
  datasource.url: jdbc:h2:mem:enrollment
  jpa.hibernate.ddl-auto: create-drop

When the same key is set in more than one place, the later source wins. From weakest to strongest, the ones you will actually use:

Reading your own settings has two forms, and the second is the one to prefer:

@Value("${enrollment.max-courses-per-student:8}")
private int maxCourses;
// ↑ the :8 is a default. Without it,
//   a missing key fails at startup.

@ConfigurationProperties(prefix = "enrollment")
@Validated
public record EnrollmentProps(
    @Min(1) int maxCoursesPerStudent) {}
// Bad config now fails at STARTUP,
// not at 3am on the first request.

The bean container, next to the one you know

CDI and the Spring container solve the same problem with different vocabulary. If you understood chapter 10, you already understand this section — it is a translation, not a new idea.

@Service
public class EnrollmentService {

    private final EnrollmentRepository enrollments;   // final: cannot be swapped
    private final CourseRepository courses;

    // One constructor → Spring injects it. No @Autowired needed.
    // Field injection (@Autowired on the field) is discouraged:
    // it hides dependencies and cannot be tested without a container.
    public EnrollmentService(EnrollmentRepository enrollments, CourseRepository courses) {
        this.enrollments = enrollments;
        this.courses = courses;
    }
}

Golden rules

What actually differs, and what only looks like it does.

1. The server moved into the jar; nothing else moved.Jakarta EE hands a WAR to a running container, Spring Boot embeds Tomcat and gives you a main(). JPA, transactions, injection and HTTP semantics underneath are the same specifications.
2. The application class must live in the top package.@SpringBootApplication component-scans downward from its own package. Bury it one level too deep and half your beans are invisible — a startup failure that reads like something else entirely.
3. A starter is a bundle; the parent POM is the version list.Ask for a capability, not for eleven libraries, and leave <version> out so you inherit a tested combination. When you must override one, pin it in <dependencyManagement> and own the consequence.
4. Auto-configuration only fills gaps.Every auto-configured bean is guarded by @ConditionalOnMissingBean, so your own definition always wins. --debug prints the whole decision, matched and unmatched, with reasons.
5. Environment beats file, so one artifact serves every environment.The precedence order is what lets you promote the exact jar you tested. Secrets come from the environment; ddl-auto: update never reaches production.
6. Constructor injection, final fields, no @Autowired.A single constructor is injected automatically. It makes dependencies explicit, makes the object impossible to half-build, and makes the class testable with new and no container at all.

@RestController, and where each piece of a request goes

A controller does exactly three things: translate HTTP into Java, delegate to a service, and choose a status code. Any business rule that appears in it is in the wrong layer — that rule is identical in both frameworks.

@RestController
@RequestMapping("/api/students")
public class StudentController {

    private final StudentService students;

    public StudentController(StudentService students) { this.students = students; }

    // GET /api/students/42
    @GetMapping("/{id}")
    public StudentResponse findById(@PathVariable Long id) {
        return StudentMapper.toDetail(students.findById(id));
    }

    // GET /api/students?name=ferrari&page=0&size=20
    @GetMapping
    public Page<StudentResponse> search(
            @RequestParam(required = false) String name,
            @RequestParam(defaultValue = "ACTIVE") StudentStatus status,
            Pageable pageable) {                       // page/size/sort, parsed for you
        return students.search(name, status, pageable).map(StudentMapper::toDetail);
    }

    // POST /api/students
    @PostMapping
    public ResponseEntity<StudentResponse> create(@Valid @RequestBody CreateStudentRequest req) {
        Student created = students.create(StudentMapper.toCommand(req));
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                           .path("/{id}").buildAndExpand(created.getId()).toUri();
        return ResponseEntity.created(location)              // 201 + Location header
                             .body(StudentMapper.toSummary(created));
    }
}

Errors: one place, one shape

This project maps every exception to application/problem+json through a set of ExceptionMapper classes. Spring does the same job with one class and RFC 9457 support built in.

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    ProblemDetail notFound(ResourceNotFoundException ex) {
        ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        p.setTitle("Resource not found");
        p.setProperty("code", "RESOURCE_NOT_FOUND");
        return p;                                    // → 404 application/problem+json
    }

    @ExceptionHandler(BusinessRuleViolationException.class)
    ProblemDetail conflict(BusinessRuleViolationException ex) {
        ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        p.setProperty("code", ex.getCode());        // COURSE_FULL, PREREQUISITES_NOT_MET…
        return p;                                    // → 409
    }

    // Bean Validation failures arrive as this one specific exception.
    @ExceptionHandler(MethodArgumentNotValidException.class)
    ProblemDetail invalid(MethodArgumentNotValidException ex) {
        ProblemDetail p = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        p.setProperty("violations", ex.getBindingResult().getFieldErrors().stream()
            .map(f -> Map.of("field", f.getField(), "message", f.getDefaultMessage()))
            .toList());                              // name every bad field, not just the first
        return p;                                    // → 400
    }
}

Spring Data JPA — the repository you do not write

This project hand-writes its repositories over EntityManager. Spring Data generates the implementation at startup from the interface, and the query from the method name.

public Optional<Student> findByStudentNumber(String n) {
    TypedQuery<Student> q = em()
        .createNamedQuery(
            Student.FIND_BY_STUDENT_NUMBER,
            Student.class);
    q.setParameter("studentNumber", n);
    return q.getResultStream().findFirst();
}

public interface StudentRepository
        extends JpaRepository<Student, Long> {

    Optional<Student> findByStudentNumber(String n);
    // ↑ parsed into:
    //   select s from Student s
    //   where s.studentNumber = ?1
}

The parser understands a small, predictable grammar. Learn these six and you can read almost any Spring Data interface:

@Query("select c from Course c " +
       "left join fetch c.prerequisites "       // ← one query instead of N+1
       "where c.academicYear = :year")
List<Course> findWithPrerequisites(@Param("year") int year);

// Everything chapter 08 said about lazy loading, the persistence context and
// N+1 applies here unchanged. Spring Data generates the boilerplate; it does
// not change JPA. The same getter that throws LazyInitializationException in
// a mapper here throws it there, for exactly the same reason.

Pagination is where the similarity becomes almost literal. This project has its own Page and PageRequest in common/; Spring Data ships the same two types under org.springframework.data.domain, and a controller taking a Pageable parameter gets ?page=0&size=20&sort=lastName,asc parsed for free.

Transactions and testing, briefly

Two more translations and the picture is complete: where the transaction boundary goes, and what a Spring Boot test looks like.

@Service
public class EnrollmentService {

    @Transactional                              // org.springframework.transaction.annotation
    public Enrollment enroll(Long studentId, Long courseId) { ... }

    @Transactional(readOnly = true)              // a real optimisation: no dirty checking
    public Page<Enrollment> search(Pageable p) { ... }
}

// One difference worth memorising, because it is asked constantly:
//   Spring     rolls back on RuntimeException only, unless you say otherwise
//   Jakarta EE rolls back on RuntimeException only, unless you say otherwise
// Same default. But the escape hatches differ:
//   Spring     @Transactional(rollbackFor = Exception.class)
//   Jakarta EE @Transactional(rollbackOn = Exception.class)

@WebMvcTest(StudentController.class)
class StudentControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean StudentService students;      // the real service is not started

    @Test
    void rejects_a_blank_first_name_with_400_and_names_the_field() throws Exception {
        mvc.perform(post("/api/students")
               .contentType(MediaType.APPLICATION_JSON)
               .content("""
                   {"firstName":"","lastName":"Rossi","email":"a@b.it"}
                   """))
           .andExpect(status().isBadRequest())
           .andExpect(jsonPath("$.violations[0].field").value("firstName"));
    }
}

Golden rules

Everything in this chapter that is worth carrying into a code review.

1. A controller translates, delegates and picks a status code.Nothing else. A business rule in a controller cannot be reused by a scheduled job, a message consumer or a second endpoint — and it is the first thing a reviewer will flag.
2. 201 Created needs a Location header.Return the bare object when 200 is correct, and reach for ResponseEntity only to set a status or a header. Creation is the case where you must.
3. 409 exists, and juniors under-use it.400 means the request is malformed; 409 means the request is perfect and the current state refuses it. Course full, already enrolled, student suspended — all 409.
4. One @RestControllerAdvice, one error shape.Every exception becomes problem+json in a single place, and a validation failure names every bad field rather than the first one.
5. Derived query names stop paying past three conditions.Beyond that an explicit @Query is shorter and greppable — and it is where you add join fetch to kill an N+1 that Spring Data will otherwise happily generate for you.
6. Spring Data does not replace JPA, it types less of it.Lazy loading, the persistence context, detachment and N+1 behave identically. Everything chapter 08 taught applies unchanged — which is exactly why this course teaches JPA before it teaches the shortcut.

The translation table

Left column: what is actually in src/main/java of this repository. Right column: what you would type instead. Same mechanism, different import.

The same endpoint, both ways

Real code from api/rest/StudentResource.java, next to the Spring version line for line.

@Path("/students")
@RequestScoped
@Produces(APPLICATION_JSON)
@Consumes(APPLICATION_JSON)
public class StudentResource {

    @Inject StudentService studentService;
    @Inject StudentMapper studentMapper;
    @Context UriInfo uriInfo;

    @POST
    public Response create(
            @Valid @NotNull CreateStudentRequest req) {

        Student created = studentService
            .create(studentMapper.toCommand(req));

        URI location = uriInfo
            .getAbsolutePathBuilder()
            .path(String.valueOf(created.getId()))
            .build();

        return Response.created(location)
            .entity(studentMapper.toSummaryResponse(created))
            .build();
    }

    @GET
    @Path("/{id}")
    public StudentResponse findById(
            @PathParam("id") Long id) {
        return studentMapper.toDetailResponse(
            studentService.findByIdWithEnrollments(id));
    }
}

@RestController
@RequestMapping(
    value = "/api/students",
    produces = APPLICATION_JSON_VALUE)
public class StudentController {

    private final StudentService studentService;
    private final StudentMapper studentMapper;

    public StudentController(StudentService s,
                             StudentMapper m) {
        this.studentService = s;
        this.studentMapper  = m;
    }

    @PostMapping
    public ResponseEntity<StudentResponse> create(
            @Valid @RequestBody CreateStudentRequest req) {

        Student created = studentService
            .create(studentMapper.toCommand(req));

        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();

        return ResponseEntity.created(location)
            .body(studentMapper.toSummaryResponse(created));
    }

    @GetMapping("/{id}")
    public StudentResponse findById(
            @PathVariable Long id) {
        return studentMapper.toDetailResponse(
            studentService.findByIdWithEnrollments(id));
    }
}

What does not translate

Four places where the mapping is not one-to-one, and where assuming it is will cost you an afternoon.

• The deployment model. There is no web.xml, no beans.xml, no persistence.xml and no server to install. A Spring Boot application is configured by properties and by what is on the classpath. Conversely there is no shared server to hold a connection pool for several applications — each jar has its own.
• Transaction management is not JTA by default. Spring uses a local DataSourceTransactionManager or JpaTransactionManager over one datasource. That is simpler and faster, and it means distributed two-phase commit across two databases is not something you get for free — whereas WildFly hands it to you.
• CDI's scoping model is richer, and Spring's is simpler on purpose. @RequestScoped beans, conversation scope and CDI's typesafe resolution have no exact Spring twin. In practice Spring code passes request data as method parameters, which most people find easier to follow.
• Startup order and events. @Observes @Initialized(ApplicationScoped.class) in ApplicationBootstrap becomes an ApplicationRunner bean, and CDI's AFTER_SUCCESS observer becomes @TransactionalEventListener(phase = AFTER_COMMIT). The concept survives; the wiring does not.

Golden rules

How to carry twenty chapters of Jakarta EE into a Spring Boot job without pretending you have used it for years.

1. Learn mechanisms, translate spellings.Proxies, the persistence context, transaction boundaries and HTTP semantics are the transferable knowledge. Annotation names are a lookup table you can keep open on a second monitor.
2. The structure is yours, not the framework's.Mapper, service, repository, validation at the boundary, one error shape — identical in both columns above. Frameworks do not make architectural decisions for you and never have.
3. Say what you actually know.“I have built this in Jakarta EE and I know the Spring equivalents because the specifications are shared” is credible and checkable. “Three years of Spring” falls apart at the first question about proxies.
4. Three files describe any Spring Boot codebase.The build file lists the capabilities, application.yml lists what varies, and the @SpringBootApplication class fixes the scan root. Read those before a single controller.

The three places your work can be

Almost every confusing Git message is really the question “which of these three do you mean?” Learn the picture and half the confusion disappears permanently.

A commit is a snapshot with a parent, and a branch is a sticky note

Git does not store differences. Every commit is a complete snapshot of the tree, identified by a hash, pointing at the commit that came before it. Once you see that, branches stop being mysterious.

git switch main && git pull            # start from what everyone else has
git switch -c feature/withdraw-endpoint  # branch: instant, free, disposable

# ... edit EnrollmentResource.java and EnrollmentService.java ...

git status                               # what changed? read this every single time
git diff                                 # what exactly changed, line by line?
git add src/main/java/it/unicam/cs/enrollment/api/rest/EnrollmentResource.java
git add -p                               # stage the rest hunk by hunk
git commit -m "Add DELETE endpoint for withdrawing from a course"

git push -u origin feature/withdraw-endpoint
# → open a pull request in the browser

Merge or rebase — the only real difference

Both bring your branch up to date with main. One preserves what happened; the other rewrites it into what you wish had happened.

Conflicts are not errors

A conflict means two people changed the same lines and Git is refusing to guess. It is a question, not a failure — and the markers tell you exactly what it is asking.

<<<<<<< HEAD                       // ← what is on YOUR branch right now
    if (occupied >= course.getCapacity())
        throw new CourseFullException(courseId);
=======
    if (occupied >= course.getCapacity())
        throw new BusinessRuleViolationException("COURSE_FULL", ...);
>>>>>>> main                       // ← what is on the branch you are pulling in

Resolving it is four steps, and the third one is the one people skip:

The undo table

Print this. The fear of Git comes almost entirely from not knowing that everything committed is recoverable.

git reflog
c64d96c HEAD@{0}: reset: moving to HEAD~1
12b8188 HEAD@{1}: commit: Add four study tools
264d911 HEAD@{2}: commit: Replace absolute home paths

# the commit is still there. Put the branch back on it:
git reset --hard HEAD@{1}

The workflow a team actually uses

Branch, push, pull request, review, merge. It is the same shape at almost every company, and the pull request is where chapters 20, 21 and 22 meet.

And the commit message. This is the smallest thing on the list and the one that most visibly separates a junior from someone who has worked on a team:

Golden rules

Enough Git to be a safe colleague on day one.

1. Know which of the three places your work is in.Working directory, staging area, repository. git status before every command answers it, and almost every confusing message is really that question.
2. Committed work is recoverable; uncommitted work is not.git reflog finds commits no branch points at for 90 days. git restore on an uncommitted file destroys it instantly. Commit early — it is what makes mistakes cheap.
3. Never rewrite history someone else has.Rebase, --amend and push --force all create new commits and invalidate everyone else's copy. On your own unpushed branch they are free; use --force-with-lease if you must push one.
4. A conflict is a question, not a failure.Read both sides, delete every marker, run the tests, then continue. --abort always puts you back where you started, so there is nothing to fear.
5. Small branches, merged quickly.Conflicts scale with branch lifetime, and so do review quality and deployment risk. A branch that lives a day rarely conflicts; one that lives three weeks always does.
6. Write the commit message for the person debugging in six months.Imperative subject, under fifty characters, and a body explaining why when the why is not obvious. That person is usually you.

Two kinds of test

The split matters because they fail for different reasons. A unit test cannot catch a broken fetch plan — there is no database to fetch from. An integration test is too slow to run on every keystroke. You need both.

The line that makes the test honest

A test that asserts while the persistence context is still open is testing a world that never happens in production.

Optional<Course> found = repository.findByIdWithPrerequisites(id);

entityManager.clear();   // ← detach everything, exactly as the REST layer sees it

Course detached = found.get();
assertThat(catchThrowable(() -> detached.getPrerequisites().size()))
        .as("prerequisites must have been fetch-joined")
        .isNull();

Here is what was measured on this codebase — the fetch join removed, then the same bug tested with and without that clear():

Controlling time

Enrollment windows depend on "now". A test that reads the system clock is a test that fails on a Sunday, or in a different timezone, or at the end of a semester. So the clock is injected:

// Production: the real clock, produced as a CDI bean
@Produces public Clock clock() { return Clock.systemUTC(); }

// Test: pin it. The window is now fully deterministic.
Clock fixed = Clock.fixed(Instant.parse("2025-09-01T10:00:00Z"), ZoneOffset.UTC);

Any value that makes a test non-deterministic — time, randomness, UUIDs — should be a dependency rather than a static call. That is most of what "testable design" means in practice.

Golden rules

How to tell a test that proves something from one that only passes.

1. A test's value is that it would have failed.Delete the fetch join and the endpoint returns 500. With clear() disabled the suite still reports BUILD SUCCESS — a green build over a broken endpoint.
2. Call entityManager.clear() before asserting a fetch plan.Otherwise you assert against an open session, which is a world production never has. The test must stand where the mapper stands: on the detached side.
3. Unit tests prove logic; integration tests prove mapping.A mocked repository cannot notice a missing join, and an in-memory H2 run is too slow to sit under every keystroke. 35 and 25, not 60 of one kind.
4. Anything non-deterministic is a dependency.Time, randomness, ids. Injecting Clock is what stops an enrollment-window test failing on a Sunday or in another timezone.

The problem CI actually solves

Not “running tests automatically”. The problem is that main is a shared claim — everyone believes it works — and without a machine checking, that claim quietly stops being true.

Three consequences follow, and they are the honest reason CI exists:

• The feedback loop shortens from days to minutes. A bug found eleven minutes after you wrote it costs a coffee. The same bug found three weeks later costs an afternoon of archaeology.
• “It works on my machine” stops being an argument. The pipeline builds on a clean agent with no local database, no stale target/ folder and no IDE configuration.
• The build becomes a gate, not a suggestion. A red pipeline blocks the merge. That is the entire mechanism by which a codebase stays healthy for years with people joining and leaving.

What a pipeline is made of

A pipeline is stages in order, each one a gate. Later stages are slower and more expensive, so cheap checks run first — a compile error should never wait for a deployment.

mvn clean verify

# clean    delete target/ — no stale classes, same as a fresh agent
# verify   compile → surefire (unit) → package → failsafe (integration)
#
# Tests: 60, Failures: 0, Errors: 0, Skipped: 0
# BUILD SUCCESS

Jenkins, concretely

Jenkins is a server that watches your repository and runs a script when something changes. The script lives in the repository, in a file called Jenkinsfile — which means the pipeline is reviewed and versioned like any other code.

pipeline {
    agent { docker { image 'maven:3.9-eclipse-temurin-17' } }

    options {
        timeout(time: 20, unit: 'MINUTES')   // a hung build must not block forever
        buildDiscarder(logRotator(numToKeepStr: '30'))
    }

    stages {
        stage('Build') {
            steps { sh 'mvn -B clean compile' }     // -B = batch, no colour codes
        }

        stage('Test') {
            steps { sh 'mvn -B verify' }
            post {
                always { junit 'target/*-reports/TEST-*.xml' }  // results even on failure
            }
        }

        stage('Package') {
            steps {
                sh 'mvn -B package -DskipTests'
                archiveArtifacts artifacts: 'target/enrollment.war', fingerprint: true
            }
        }

        stage('Deploy to staging') {
            when { branch 'main' }                    // feature branches build but do not deploy
            steps {
                withCredentials([usernamePassword(credentialsId: 'wildfly-staging',
                                 usernameVariable: 'U', passwordVariable: 'P')]) {
                    sh './deploy.sh $U $P'            // secrets injected, never in git
                }
            }
        }
    }

    post {
        failure { mail to: 'team@example.com', subject: "FAILED: ${env.JOB_NAME} #${env.BUILD_NUMBER}" }
    }
}

The same pipeline in GitHub Actions

The advert says “Jenkins or similar tools”, because the concepts transfer completely. Here is the identical pipeline in the tool you are most likely to meet on a personal project.

name: build
on:
  push:        { branches: [main] }
  pull_request: { branches: [main] }

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: temurin
          cache: maven                       # ~/.m2 reused between runs

      - name: Build and test
        run: mvn -B clean verify

      - name: Publish test report
        if: always()                        # run even when the tests failed
        uses: mikepenz/action-junit-report@v4
        with:
          report_paths: 'target/*-reports/TEST-*.xml'

      - name: Upload the WAR
        uses: actions/upload-artifact@v4
        with:
          name: enrollment-war
          path: target/enrollment.war

An interviewer asking about Jenkins is checking whether you understand build automation, not whether you know Groovy. “I have used GitHub Actions and the concepts map directly — stages, agents, artifacts, credentials” is a complete and honest answer.

What makes a pipeline worth trusting

A pipeline nobody believes is worse than no pipeline, because it costs time and teaches the team to ignore red.

• It must be fast. Past roughly ten minutes people stop waiting for it and start merging on hope. Parallelise, cache dependencies, and push slow end-to-end suites to a nightly run.
• It must be deterministic. A test that fails one run in twenty is worse than a missing test: it trains everyone to press rebuild, and one day the rebuild hides a real failure. Fix flaky tests or delete them.
• It must build the same way every time. Pinned plugin versions, a pinned JDK, a clean workspace. This project pins Surefire and Failsafe to 3.2.5 in pom.xml for exactly this reason — a build whose behaviour depends on the day it ran is not reproducible.
• Red must actually block. Branch protection that requires the check to pass is what converts the pipeline from advice into a gate. Without it, CI is a very expensive notification system.
• It must say what broke. Publish the JUnit report so the failure is a named test and a line number, not four hundred lines of log for someone to scroll through.

Golden rules

What to say when an interviewer asks whether you have used CI.

1. CI protects a shared claim, not a test suite.The claim is “main works”. A pipeline is simply the only way to keep that claim true while several people change the code every day.
2. Cheap stages first, and fail fast.Compile, unit, integration, package, deploy. Never spend ninety seconds on integration tests for code that does not compile, and stop at the first red stage.
3. The pipeline definition belongs in the repository.Jenkinsfile or .github/workflows/, reviewed in the pull request that changes it. A pipeline configured by clicking in a web UI cannot be reviewed, branched or rolled back.
4. Secrets come from the credentials store, never from the file.Anything committed is in every clone forever. If one leaks, rotate it first and clean history second.
5. A flaky test is worse than a missing one.It teaches the team that red means “press rebuild”, and that habit will one day wave a real failure straight through.
6. Green must block the merge, or it is only a notification.Branch protection is the mechanism that turns a pipeline into a gate. Everything else about CI is optional; this part is not.

Why iterations, and what Agile actually claimed

The original argument was not about ceremonies. It was that you cannot specify software completely in advance, because the people asking for it learn what they want by using it.

Scrum: the vocabulary you will hear on day one

Scrum is the most common way teams put those ideas into a calendar. It is a small framework with a lot of jargon, and the jargon is what makes a new joiner feel lost in the first week.

A user story you can actually build

A ticket that says “improve enrollments” wastes a sprint. The format exists to force three things into the open: who wants it, what they want, and how you will both know it is finished.

Those five bullets are also, almost word for word, the five tests. That is not a coincidence — it is the reason the format survives. And a good story satisfies INVEST:

And beyond the criteria of a single story, a team shares one definition of done — the bar every story clears before anyone calls it finished:

Estimation, and why not in hours

Story points measure size and uncertainty relative to other stories, not hours. The reason is simple: humans are bad at absolute estimates and surprisingly good at comparisons.

Ask someone how many minutes it takes to walk to the station and they will be wrong. Ask whether it is further than the supermarket and they will be right. Points exploit the second ability.

Code review, from both sides

This is where “ability to work in a team” and “attention to detail” stop being CV phrases and become observable behaviour. It is also where most new developers accidentally make a bad impression.

Golden rules

The habits that make you the junior a team is glad they hired.

1. The loop is the point; the ceremonies are the mechanism.Build a small thing, show it, learn, re-order the plan. A team that runs every meeting but never changes the backlog is doing theatre, not Agile.
2. A story without acceptance criteria is not ready to start.Who wants it, what they want, why — and the list of conditions that prove it is finished. Those conditions are also your test list, which is why the format has survived.
3. Say you are blocked, on the day you are blocked.That is what a standup is for. A junior silently stuck for three days costs the team far more than one who asks at the first hour.
4. Points are comparisons, not hours.Humans estimate badly in absolute terms and well in relative ones. A disagreement between 2 and 8 is information, not a problem to average away.
5. Small pull requests get real reviews.You choose which kind of review you get by choosing the size of the diff. Two hundred lines gets thought; two thousand gets a rubber stamp.
6. Review the code, take the review on the code.Comment on the diff and never the person; receive comments as being about the diff and never about you. This one habit does more for a career than any framework.

Read the stack trace properly

A Java stack trace is not a wall of noise. It has a strict structure, and two lines in it carry almost all the information.

jakarta.ws.rs.WebApplicationException: HTTP 500 Internal Server Error
    at org.jboss.resteasy.core.ExceptionHandler.handleException(...)
    at io.undertow.servlet.handlers.ServletHandler.handleRequest(...)
    ... 48 more framework frames you can ignore ...
Caused by: org.hibernate.LazyInitializationException:
        failed to lazily initialize a collection of role:
        it.unicam.cs.enrollment.domain.model.Course.prerequisites:
        could not initialize proxy - no Session
    at org.hibernate.collection.spi.AbstractPersistentCollection.throwLazyInit(...)
    at it.unicam.cs.enrollment.api.mapper.CourseMapper.toDetailResponse(CourseMapper.java:64)
    at it.unicam.cs.enrollment.api.rest.CourseResource.findById(CourseResource.java:118)

Three lines of a fifty-line trace give the complete diagnosis: a lazy collection was touched in CourseMapper at line 64, after the transaction closed. Chapter 08 explains why; the trace already told you where.

The method

When you do not know what is wrong, the temptation is to change something and see. That works occasionally and teaches nothing. This is the alternative, and it is what separates twenty minutes from two days.

Binary search over anything

The single most useful technique in debugging is the one from chapter 07's index: halve the space, repeatedly. It applies to history, to code, and to data.

git bisect start
git bisect bad                    # the current commit is broken
git bisect good c64d96c           # this one was fine

# Git checks out the midpoint. Run the test, then say which it was:
mvn -q verify && git bisect good || git bisect bad

# repeat ~5 times for 40 commits, ~10 times for 1000
git bisect reset                  # back to where you started

The same move, applied elsewhere:

The five failures you will actually meet here

Recognising an error message once, calmly, is worth more than reading ten explanations of it. This project ships a script that causes four of these on purpose.

./scripts/break.sh list          # what is available
./scripts/break.sh n-plus-one    # one line changed in a tracked file
mvn package                      # WildFly hot-redeploys in a second or two
tail -f $WILDFLY/standalone/log/server.log

./scripts/break.sh restore       # git checkout — nothing is ever lost

Two tools make the invisible visible, and both are already switched on here. Hibernate's SQL logging shows you every statement your code caused — including the ones nobody wrote — and the correlation id filter puts one identifier on every log line of a single request:

grep "a3f9c21e" $WILDFLY/standalone/log/server.log

# That id came back to the client in the X-Correlation-Id response header.
# On a server handling 200 requests a second, this is the difference between
# reading one story and reading two hundred interleaved ones.

Asking for help without wasting anyone's time

Knowing when to stop is part of the skill. The convention on most teams is roughly thirty to sixty minutes of genuine effort, then ask — and how you ask decides how useful the answer is.

The right-hand version has a useful side effect: writing it out solves the problem roughly a third of the time before you ever press send. That is the rubber duck effect — explaining a problem in complete sentences forces you to state the assumption that is wrong.

Golden rules

Problem solving as a repeatable procedure.

1. Read the last Caused by, then the first line with your package in it.Those two lines are the diagnosis. Every framework frame between them describes how you arrived, not what broke.
2. Reproduce before you fix.A bug you cannot trigger on demand is a bug you cannot prove you fixed. Making it reproducible is usually most of the work, and it is never wasted.
3. Change one thing at a time.Change three and it works, and you have learned nothing — you now carry two unnecessary changes and possibly a new bug.
4. Halve the search space, whatever the space is.git bisect over history, a breakpoint in the middle of a method, half the rows, half the config. Ten halvings cover a thousand candidates.
5. Every fix gets a test that would have caught it.Otherwise you have fixed it once. With the test, it stays fixed — and the test documents the bug better than any comment.
6. One honest attempt, then a well-written question.Expected, actual, tried, correlation id. Writing it properly solves it outright surprisingly often, and when it does not, it gets answered in minutes rather than ignored.

Where the English actually appears

Almost none of it is conversation. Most of a backend developer's English is read silently and written asynchronously, which means you get time to think — and a dictionary.

Standup, in three sentences

Learn these three patterns and you can fill in the blanks for the rest of your career. Thirty seconds, in this order, every single day.

Three variations worth having ready, because they come up constantly:

The review phrasebook

Code review English is unusually formulaic, and that formula is deliberate: it keeps disagreement about code from sounding like disagreement about people. Learn the hedges.

Writing that other people read

Commit messages, pull request descriptions and bug reports. All three have a fixed shape, and the shape carries more of the meaning than the vocabulary does.

Add DELETE /enrollments/{id} for course withdrawal

Students could enroll but never leave, so a seat freed by a
withdrawal was never returned to the pool. The endpoint moves
the enrollment to WITHDRAWN, which the seat count already
excludes.

Refuses with 409 after the enrollment window closes.

Closes ENR-142

# Subject in the IMPERATIVE: "Add", "Fix", "Remove", "Refactor".
# Test: it must complete "If applied, this commit will ___".
#   Add the endpoint        ✔
#   Added the endpoint      ✘
#   Adding the endpoint     ✘
#   endpoint stuff          ✘

The imperative is not arbitrary: Git itself writes in it (“Merge branch…”, “Revert…”), so your commits read consistently with the tool's own. And the verb list is short:

## What
Adds DELETE /api/enrollments/{id} so a student can withdraw
from a course before the enrollment window closes.

## Why
ENR-142. Seats were never returned to the pool, so popular
courses appeared full for the rest of the semester.

## How to test
1. mvn verify — 4 new integration tests
2. Or: ./scripts/api-tour.sh, step 14

## Notes for the reviewer
I used a pessimistic lock on the course row here, matching
enroll(). Happy to discuss whether optimistic would be enough.

Words that mean something exact

A handful of English words are load-bearing in technical writing: they have a precise meaning, and reading them loosely causes real bugs.

Talking about this project in an interview

The most likely English you will speak this month. Prepare four answers and the rest of the conversation gets much easier, because you stop translating and start remembering.

Golden rules

Enough English to work, without needing to be fluent.

1. Technical English is a small language.Roughly three hundred words, the same grammar every time, no idioms — because half the people speaking it are not native speakers either. It is a much smaller target than “learn English”.
2. Learn three standup sentences and reuse them forever.Yesterday I did · today I am going to · I am blocked on. Past simple for yesterday — “I have finished yesterday” is the classic slip.
3. Hedge when you review, and read hedges as strong.“I think this might not handle the empty case” is the normal register for “this is wrong”, and it leaves room for a reason you had not considered.
4. Commit subjects are imperative and under fifty characters.“If applied, this commit will add the endpoint”. Six verbs cover almost everything: Add, Fix, Remove, Refactor, Update, Document.
5. Structure beats grammar in anything written.What / Why / How to test / Notes for the reviewer. A reviewer forgives an article; they do not forgive not knowing what the change is for.
6. Asking someone to repeat costs nothing.Building the wrong thing because you nodded costs a sprint. “Just to confirm I understood correctly…” is the most valuable sentence in this chapter.

The latency ladder

Orders of magnitude, not exact numbers. Knowing them changes which optimisation you reach for first.

Which reframes the fetch-plan chapter. LEFT JOIN FETCH is not a clever trick; it is the difference between one item on this ladder and a hundred.

The connection pool is your real concurrency limit

Undertow can accept hundreds of requests at once. Twenty-five of them can talk to the database. The rest are in a queue you never wrote.

--min-pool-size=5 \
--max-pool-size=25 \
--pool-prefill=true \

A @Transactional method holds a connection from its first database access until commit. Everything else it does inside that window — mapping, logging, an HTTP call to another service — holds the connection too. So the pool is not sized by "how many users"; it is sized by how long each request keeps a connection.

The law behind it is one line — concurrency = arrival rate × service time — and it is worth carrying around. At 40 requests per second holding a connection for 120 ms you need about 5 connections. Let one slow query push the hold time to 600 ms and you need 24. Nothing about the traffic changed; the pool simply ran out, and every waiting request now blocks a worker thread as well.

The write path: batching and id allocation

Two settings in this project turn 50 inserts into 3 round trips, and they only work together.

<property name="hibernate.jdbc.batch_size" value="25"/>
<property name="hibernate.order_inserts" value="true"/>

@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "app_id_generator")
@SequenceGenerator(name = "app_id_generator", sequenceName = "app_id_seq",
                   allocationSize = 50)

The connection between them is not obvious and is the actual lesson. With GenerationType.IDENTITY the database assigns the id during the INSERT, so Hibernate must execute each INSERT immediately on persist() to learn the id — and can therefore never batch anything. SEQUENCE lets it ask for ids up front, keep the rows in memory, and send them as one JDBC batch at flush.

allocationSize = 50 is the "pooled optimizer": one round trip buys fifty ids held in memory. The cost is gaps in the numbering after a restart, which are harmless — ids are identifiers, not counters. Anyone who needs a gapless sequence needs a different column, computed at report time.

order_inserts matters because a JDBC batch must be one statement repeated. Inserting a student, then an enrollment, then another student produces three statements and no batching; sorting by table first produces two batched statements. Hibernate cannot reorder across a flush, which is why interleaving flush() calls in a loop quietly disables everything above.

Measuring, not guessing

Every performance claim in this chapter is checkable on your machine in about a minute. Check them.

The SQL log is at DEBUG for exactly this reason. Three signatures to recognise in it:

curl -s localhost:8280/enrollment/api/courses/55 > /dev/null
# then: comment out LEFT JOIN FETCH c.prerequisites, mvn package, repeat.
# Count the SELECTs both times. That number is the whole chapter.

• Measure the ninety-fifth percentile, not the average. An average hides the queue. If p50 is 20 ms and p95 is 900 ms, you do not have a slow application — you have a saturated resource, and the ladder above says which one.
• Measure with the log off. show_sql and DEBUG logging are real throughput costs. A benchmark run with them on measures your logger.
• Look at the database's own view. pg_stat_statements ranks queries by total time. It answers "what is actually expensive" without any guessing about what the ORM emitted.
• An index is usually the answer. A sequential scan over a growing table is a bug that gets slower every week. EXPLAIN ANALYZE on the slow query says so in one line.

Memory, and the garbage collector you should not tune

The heap is not a resource you manage. It is a resource whose allocation rate you influence.

Objects are born in the young generation, which is collected constantly and cheaply — most objects die there, and a young collection costs a millisecond or two. Objects that survive long enough are promoted to the old generation, which is collected rarely and expensively. The rule that follows is counter-intuitive and correct: short-lived garbage is almost free; long-lived garbage is what hurts.

All three are design problems wearing a memory costume, and none is fixed by a JVM flag. The pagination in this project is the structural answer to the middle one: PageRequest caps what a single query can materialise, so no endpoint can be asked for a million rows at once.

Golden rules

Performance rules that hold long after the specific numbers change.

1. A round trip costs about a million method calls.Removing one query is worth more than any amount of Java micro-optimisation beside it. That single ratio is why N+1 is the first bug worth hunting and why LEFT JOIN FETCH matters.
2. Concurrency = arrival rate × service time.The pool is sized by how long a request holds a connection, not by how many users exist. Double the hold time and you have halved your capacity without a single extra user.
3. Enlarging the pool moves the queue, it does not remove it.The database has a limit of its own, past which more connections buy contention rather than throughput. Shorten the transaction before widening the pool.
4. IDENTITY makes batching impossible.The id is assigned during the INSERT, so each one must be executed immediately. SEQUENCE with an allocationSize buys ids up front and lets fifty inserts become one batch.
5. Never hold a transaction across a remote call.The connection is held for the whole method. An HTTP call inside a @Transactional block puts a third party's latency directly into your pool's service time.
6. Read the SQL log before changing anything.Every performance claim here is checkable in a minute against a DEBUG log on your own machine. An optimisation applied without a measurement is a guess that now also costs readability.

@Schedule — cron in an annotation

No scheduler library, no configuration file. One annotation and the container runs the method.

// Nightly at 03:00 — withdraw enrollments from finished academic years.
@Schedule(hour = "3", minute = "0", second = "0", persistent = false,
          info = "Nightly stale-enrollment sweep")
public void closeStaleEnrollments() { ... }

// Every 5 minutes, on the clock — a metrics heartbeat.
@Schedule(minute = "*/5", hour = "*", persistent = false,
          info = "Enrollment statistics heartbeat")
public void reportStatistics() { ... }

These are calendar-based expressions, and they are not quite cron. Each unit is its own attribute, so minute = "*/5" means "every fifth minute of every hour" — not "five minutes after startup". The job fires at :00, :05, :10 and so on, aligned to the wall clock. Anything you leave out defaults to 0, which is why the nightly sweep does not also run every minute of hour 3.

persistent = false means the timer lives in memory only. A persistent timer is written to the database and survives a restart — so a nightly sweep missed while the server was down would fire on boot. For a heartbeat that would be pointless catch-up noise, and for the sweep it is a decision you want to make deliberately rather than inherit.

16:25:00,016 INFO [EnrollmentMaintenanceJob] [] [METRICS] students.active=3 students.suspended=1
16:30:00,016 INFO [EnrollmentMaintenanceJob] [] [METRICS] students.active=3 students.suspended=1
16:35:00,059 INFO [EnrollmentMaintenanceJob] [] [METRICS] students.active=3 students.suspended=1

Those empty brackets are where a correlation ID would be. There is none — the MDC is populated per HTTP request by CorrelationIdFilter, and no request happened here. Scheduled work is invisible to request-scoped tooling, which is exactly why the job logs a count on every run: a job that silently does nothing is indistinguishable from a job that is broken.

Two doors into the same service layer

A scheduled job is a second entry point. It reaches the same repositories and the same domain rules as a REST call, without any of the HTTP machinery above it.

This is the practical argument for keeping business rules out of resource classes. Put an eligibility check in a JAX-RS method and the nightly job silently skips it.

@Singleton, and who is allowed in

@Singleton
@ConcurrencyManagement(ConcurrencyManagementType.CONTAINER)
public class EnrollmentMaintenanceJob { ... }

An EJB @Singleton is one instance for the whole application — and by default the container gives every business method a write lock. Calls are serialised: if the nightly sweep is still running at 03:05, the heartbeat waits rather than running alongside it.

That is usually what you want for maintenance work, and it is the opposite of the CDI @ApplicationScoped beans from Chapter 4, which are shared and fully concurrent. Same "one instance" idea, completely different concurrency contract — a distinction worth keeping straight.

REQUIRES_NEW — there is no caller

@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)

A REST request arrives with no transaction, and @Transactional starts one. A timer callback also arrives with none — but it has no caller at all, so there is nothing to inherit and nothing to join. REQUIRES_NEW states plainly: always begin a fresh transaction, always commit it independently.

The payoff is isolation. If the nightly sweep fails, it rolls back its own work and nothing else is affected — there is no surrounding transaction for it to poison.

Bulk updates go around the persistence context

The sweep does not load a single entity. It issues one UPDATE.

return em().createQuery(
        "UPDATE Enrollment e "
      + "SET e.status = :withdrawn, e.updatedAt = :now "
      + "WHERE e.status = :active AND e.course.academicYear < :year")
    ...
    .executeUpdate();     // returns the row count

Loading ten thousand stale enrollments to call withdraw() on each would mean ten thousand objects in memory and ten thousand UPDATE statements. This is one statement, and the database does the work.

The cost is that it bypasses everything JPA normally does for you:

• No entity is loaded, so Enrollment.withdraw() never runs — the state-machine check from Chapter 7 is skipped entirely. The WHERE status = ACTIVE clause is doing that job instead, in SQL.
• No lifecycle callbacks fire, which is why updatedAt is set by hand in the query.
• @Version is not bumped automatically, so optimistic locking does not protect these rows.
• Any entity already in the persistence context is now stale — it holds the old status while the database holds the new one.

Why this breaks on a second server

Deploy this WAR to two nodes and you have two schedulers. Both fire at 03:00. Both run the sweep. The WHERE clause makes it harmless here — the second run updates zero rows — but a job that sends emails or charges cards would do it twice.

The README lists this openly under known limitations, and the fixes are the standard ones:

• A database lock — every node tries to claim a row before running; only one wins.
• An external scheduler — Kubernetes CronJob or Quartz in clustered mode, triggering an endpoint rather than a timer.
• Make the work idempotent, so running it twice is harmless by construction. That is what the WHERE status = ACTIVE clause achieves, and it is the cheapest defence available.

Golden rules

Everything changes when there is no request behind the work.

1. A timer has no request, no MDC, no filter — and no caller.Which is why the job methods say REQUIRES_NEW: there is no transaction to inherit, and nothing above to join.
2. Any rule that lives above the service does not exist for the job.Put an eligibility check in a resource class and the nightly sweep walks straight past it. That is the practical argument for the layer rule from Chapter 01.
3. Everything you omit from @Schedule defaults to zero.minute = "*/5" fires at :00, :05, :10 on the wall clock — not five minutes after boot. And hour = "3" alone would not repeat all hour, because the other fields are already 0.
4. A bulk update buys speed by skipping everything JPA does for you.No entity loaded, so no state machine; no callbacks, so updatedAt by hand; no @Version bump; and anything already in the persistence context is now stale.
5. Two nodes means two schedulers.Make the work idempotent (WHERE status = ACTIVE), take a database lock, or move the trigger outside the application. Hoping is not one of the three.

What is actually inside the WAR

A WAR is a zip with a required layout. Every path in it means something to the server.

WEB-INF/
  classes/                     ← your compiled code + resources
    it/unicam/cs/enrollment/…
    META-INF/persistence.xml   ← must be exactly here for JPA to find it
    db/migration/              ← the schema, versioned — chapter 29
  beans.xml                    ← marks this as a CDI bean archive
  web.xml                      ← servlet-level configuration
  jboss-deployment-structure.xml
index.html  tutorial.html      ← static content, served directly

   there is no WEB-INF/lib/ in that listing, and that is the whole point:
   not one dependency in this project is anything but `provided` or `test`

Two things there carry the whole model. There is no WEB-INF/lib/ directory, because the Jakarta EE API is provided and the runtime supplies every implementation — the largest thing in the archive is in fact this page you are reading. And META-INF/persistence.xml is inside classes/, because the JPA provider scans the classpath for that exact path. Put it one directory higher and the deployment fails with "no persistence unit named enrollmentPU", which is a filesystem problem wearing a configuration error's clothes.

WildFly's modular classloader

There is no single flat classpath. Each deployment gets its own module graph and sees only what it has been given.

This is the reason two applications on one server can use incompatible versions of the same library — a genuinely painful problem in the era of one shared lib/ directory. A deployment sees exactly three things:

1. Its own classes and WEB-INF/lib.Always visible, and always searched first for a class it contains.
2. Implicit modules the server adds.The Jakarta EE APIs, the logging facades, the JDK. This is what makes provided work at runtime.
3. Anything requested explicitly.Which is the entire purpose of the one vendor-specific descriptor in this project.

<deployment>
    <dependencies>
        <module name="org.slf4j"/>
    </dependencies>
</deployment>

WildFly would usually add SLF4J implicitly; declaring it makes the dependency visible instead of relying on a server default that could change between versions. Every other descriptor in WEB-INF/ is standard and portable — this one has an equivalent with a different name on every other server (glassfish-web.xml, weblogic.xml, ibm-web-bnd.xml), which is a fair summary of how portable Jakarta EE really is: the specifications travel, the deployment metadata does not.

The deployment sequence

Six phases, always in this order. Step through it and see what each one can fail on.

Two phases in that sequence are worth extra attention, because both are annotation-driven and both fail silently when misconfigured.

@ApplicationPath("/api")
public class JaxRsActivator extends Application { }

No methods. Because getClasses() and getSingletons() are not overridden, RESTEasy scans the deployment and registers everything annotated @Path or @Provider automatically. Override either method and scanning stops — you now maintain an explicit list, and a new resource silently returns 404 until someone remembers to add it.

The other is CDI discovery, and the mode matters:

Under annotated, a service class that is missing @ApplicationScoped is not a bean, so @Injecting it fails at deploy time with "unsatisfied dependency" rather than at runtime with a null. That is the correct trade, and it is why CDI errors read like compiler errors: the container resolves the entire injection graph before the application starts.

Descriptors, annotations, and where configuration belongs

Every descriptor in this project has an annotation equivalent. Choosing between them is a question about who needs to change the value.

The fourth row is the one with teeth. persistence.xml contains a JNDI name, not a URL:

<jta-data-source>java:jboss/datasources/EnrollmentDS</jta-data-source>

The host, user and password live in the server's configuration, which means the identical WAR deploys to development, staging and production untouched. Credentials are an operational concern; a build artifact that differs per environment is a build artifact you have not really tested. The general form of that rule is the twelve-factor one: anything that varies between deployments is configuration, and configuration comes from the environment, not the archive.

And when both define the same thing, web.xml wins over the annotation — deliberately, so an operator can override a developer without a recompile.

Hot redeploy, and what it cannot do

The development loop here is one command, and understanding why it works tells you when it will not.

mvn package     # writes enrollment.war + enrollment.war.dodeploy into the scanned folder

WildFly's deployment scanner watches that directory. The marker file is the handshake: Maven finishes writing the WAR, then touches .dodeploy, so the scanner never picks up a half-written archive. The server replies with .deployed or .failed — and the .failed file contains the actual reason, which is faster to read than the log.