{
  "isbn": "978-0000000001",
  "title": "Effective Java",
  "author": "Joshua Bloch",
  "publicationYear": 2018,
  "available": true,
  "categories": ["Java", "Best practices"],
  "publisher": {
    "name": "Addison-Wesley",
    "country": "USA"
  },
  "addedDate": "2026-01-15",
  "rating": null
}

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <!-- no version: Spring Boot's BOM manages it (11-05) -->
</dependency>

<!-- Support for java.time (section 10) -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

// WRONG: creates a mapper on every call. Throws the cache away every time.
public String toJson(Material material) {
    return new ObjectMapper().writeValueAsString(material);   // slow and wasteful
}

// RIGHT: a single one, shared
private static final ObjectMapper MAPPER = new ObjectMapper();

public String toJson(Material material) {
    return MAPPER.writeValueAsString(material);
}

@Service
public class CatalogExporter {

    private final ObjectMapper mapper;   // Spring injects its own, already configured

    public CatalogExporter(ObjectMapper mapper) {
        this.mapper = mapper;
    }
}

package com.nexussoftware.bibliotech.persistence;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;

public class JsonExporter {

    private final ObjectMapper mapper;

    public JsonExporter(ObjectMapper mapper) { this.mapper = mapper; }

    public String export(Material material) {
        try {
            return mapper.writeValueAsString(material);
        } catch (JsonProcessingException e) {
            // Module 6's layered strategy: wrap, preserve the cause
            throw new ExportException("Could not serialise " + material.getIsbn(), e);
        }
    }

    public String exportPretty(Material material) {
        try {
            return mapper.writerWithDefaultPrettyPrinter().writeValueAsString(material);
        } catch (JsonProcessingException e) {
            throw new ExportException("Could not serialise", e);
        }
    }

    public void exportToFile(List<Material> catalogue, Path target) throws IOException {
        mapper.writeValue(target.toFile(), catalogue);      // without loading it all in memory
    }
}

{"isbn":"978-0000000001","title":"Effective Java","author":"Joshua Bloch","availableCopies":3}

{
  "isbn" : "978-0000000001",
  "title" : "Effective Java",
  "author" : "Joshua Bloch",
  "availableCopies" : 3
}

public Material importMaterial(String json) {
    try {
        return mapper.readValue(json, Book.class);
    } catch (JsonProcessingException e) {
        throw new ImportException("Invalid material JSON", e);
    }
}

Book fromString = mapper.readValue(json, Book.class);
Book fromFile   = mapper.readValue(Path.of("book.json").toFile(), Book.class);
Book fromStream = mapper.readValue(input, Book.class);
Book fromUrl    = mapper.readValue(new URL("https://..."), Book.class);

com.fasterxml.jackson.databind.exc.InvalidDefinitionException:
Cannot construct instance of `com.nexussoftware.bibliotech.domain.Book`
(no Creators, like default constructor, exist)

public class BookMetadata {

    private String isbn;
    private String title;
    private String author;
    private int publicationYear;

    public BookMetadata() { }   // required by Jackson

    // getters and setters...
}

public record BookMetadata(String isbn, String title, String author, int publicationYear) { }

public record BookMetadata(
        String isbn,
        String title,
        Author author,                  // nested object
        List<String> categories,        // array
        LocalDate publicationDate) {    // ISO date (section 10)

    public record Author(String name, String country) { }
}

{
  "isbn": "978-0000000001",
  "title": "Effective Java",
  "author": { "name": "Joshua Bloch", "country": "USA" },
  "categories": ["Java", "Best practices"],
  "publicationDate": "2018-01-06"
}

package com.nexussoftware.bibliotech.network;

import com.fasterxml.jackson.annotation.*;
import java.time.LocalDate;
import java.util.List;

@JsonIgnoreProperties(ignoreUnknown = true)      // indispensable: section 8
@JsonInclude(JsonInclude.Include.NON_NULL)       // do not serialise nulls
public record MetadataResponse(

        @JsonProperty("isbn_13")                 // the API uses snake_case
        String isbn,

        @JsonAlias({"title", "book_title"})      // the API changed the name in v2
        String title,

        @JsonProperty("authors")
        List<String> authors,

        @JsonProperty("publish_date")
        @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
        LocalDate publicationDate,

        @JsonProperty("number_of_pages")
        Integer pages) {
}

public class UserDto {
    private String email;

    @JsonIgnore
    private String passwordHash;     // must NEVER leave in a response
}

public record BookMetadata(String isbn, String title) { }

{
  "isbn": "978-0000000001",
  "title": "Effective Java",
  "language": "en"
}

com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException:
Unrecognized field "language" (class BookMetadata), not marked as ignorable

@JsonIgnoreProperties(ignoreUnknown = true)
public record BookMetadata(String isbn, String title) { }

mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

spring:
  jackson:
    deserialization:
      fail-on-unknown-properties: false   # the default in Spring Boot

// DOES NOT WORK the way you expect
List<BookMetadata> list = mapper.readValue(json, List.class);
// -> returns List<LinkedHashMap>, and blows up when used:
// ClassCastException: LinkedHashMap cannot be cast to BookMetadata

List<BookMetadata> list = mapper.readValue(json,
        new TypeReference<List<BookMetadata>>() { });

// List
List<Material> materials = mapper.readValue(json, new TypeReference<>() { });

// Map
Map<String, List<Loan>> byEmployee = mapper.readValue(json, new TypeReference<>() { });

// Your own generic: the Result<T> of 10-01
Result<Material> result = mapper.readValue(json, new TypeReference<Result<Material>>() { });

JavaType type = mapper.getTypeFactory().constructCollectionType(List.class, Material.class);
List<Material> materials = mapper.readValue(json, type);

com.fasterxml.jackson.databind.exc.InvalidDefinitionException:
Java 8 date/time type `java.time.LocalDate` not supported by default:
add Module "com.fasterxml.jackson.datatype:jackson-datatype-jsr310"

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new JavaTimeModule());
mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);   // important!

ObjectMapper mapper = JsonMapper.builder()
        .findAndAddModules()
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
        .build();

// Enabled (Jackson's default): number of seconds since 1970
{"recordedAt": 1774000800.000000000}

// Disabled: ISO-8601, readable and interoperable
{"recordedAt": "2026-03-20T09:00:00Z"}

spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false
    time-zone: Europe/Madrid
    default-property-inclusion: non_null

CsvMapper mapper = new CsvMapper();
CsvSchema schema = mapper.schemaFor(MaterialCsv.class).withHeader().withColumnSeparator(';');

// Writing
mapper.writer(schema).writeValue(file, materials);

// Reading
List<MaterialCsv> materials = mapper.readerFor(MaterialCsv.class)
        .with(schema).<MaterialCsv>readValues(file).readAll();

JsonNode root = mapper.readTree(json);

String title = root.path("title").asText();
int year     = root.path("publicationYear").asInt(0);           // 0 if missing
String land  = root.path("publisher").path("country").asText("Unknown");

// Walking an array
for (JsonNode category : root.path("categories")) {
    System.out.println(category.asText());
}

// Checking existence
if (root.has("rating") && !root.get("rating").isNull()) {
    double rating = root.get("rating").asDouble();
}

// Building JSON by hand
ObjectNode created = mapper.createObjectNode();
created.put("isbn", "978-0000000001");
created.put("title", "Effective Java");
created.putArray("categories").add("Java").add("Best practices");
String json = mapper.writeValueAsString(created);

// Without a custom serialiser: {"isbn": {"value": "978-0000000001"}}
// With a custom serialiser:    {"isbn": "978-0000000001"}

package com.nexussoftware.bibliotech.persistence;

import com.fasterxml.jackson.core.*;
import com.fasterxml.jackson.databind.*;
import java.io.IOException;

public class IsbnSerialiser extends JsonSerializer<Isbn> {
    @Override
    public void serialize(Isbn isbn, JsonGenerator gen, SerializerProvider sp)
            throws IOException {
        gen.writeString(isbn.value());
    }
}

public class IsbnDeserialiser extends JsonDeserializer<Isbn> {
    @Override
    public Isbn deserialize(JsonParser p, DeserializationContext ctx) throws IOException {
        String text = p.getText();
        try {
            return new Isbn(text);           // the record's validation kicks in here
        } catch (InvalidIsbnException e) {
            throw JsonMappingException.from(p, "Invalid ISBN: " + text, e);
        }
    }
}

// Option 1: on the field
public record MaterialDto(
        @JsonSerialize(using = IsbnSerialiser.class)
        @JsonDeserialize(using = IsbnDeserialiser.class)
        Isbn isbn,
        String title) { }

// Option 2: in a module, applied to ALL Isbn values
SimpleModule module = new SimpleModule("BiblioTech");
module.addSerializer(Isbn.class, new IsbnSerialiser());
module.addDeserializer(Isbn.class, new IsbnDeserialiser());
mapper.registerModule(module);

@Bean
public Module biblioTechModule() {
    SimpleModule module = new SimpleModule("BiblioTech");
    module.addSerializer(Isbn.class, new IsbnSerialiser());
    module.addDeserializer(Isbn.class, new IsbnDeserialiser());
    return module;
}

// 09-06: the "teaching stopgap", acknowledged as such
public class MetadataClient {

    public Optional<String> extractTitle(String json) {
        int start = json.indexOf("\"title\":\"");
        if (start < 0) return Optional.empty();
        start += 9;
        int end = json.indexOf("\"", start);
        if (end < 0) return Optional.empty();
        return Optional.of(json.substring(start, end));
    }

    public Optional<String> extractAuthor(String json) {
        // ... the same thing, all over again
    }
}

package com.nexussoftware.bibliotech.network;

import com.fasterxml.jackson.annotation.*;
import java.time.LocalDate;
import java.util.List;

/** Response of the external metadata API. It is a DTO: it mirrors the JSON, not the domain. */
@JsonIgnoreProperties(ignoreUnknown = true)   // the API can add fields whenever it likes
public record MetadataResponse(

        @JsonProperty("isbn_13")     String isbn,
        @JsonAlias({"title"})        String title,
        @JsonProperty("authors")     List<Author> authors,
        @JsonProperty("publish_date") LocalDate publicationDate,
        @JsonProperty("number_of_pages") Integer pages,
        @JsonProperty("publishers")  List<String> publishers) {

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Author(String name, String key) { }

    /** Translates the external DTO into BiblioTech's domain model. */
    public BookMetadata toDomain() {
        String joinedAuthors = authors == null ? null
                : authors.stream().map(Author::name).collect(Collectors.joining(", "));
        String publisher = publishers == null || publishers.isEmpty()
                ? null : publishers.get(0);
        return new BookMetadata(joinedAuthors, publicationDate, publisher, pages);
    }
}

package com.nexussoftware.bibliotech.network;

import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Optional;
import org.slf4j.*;
import org.springframework.stereotype.Component;

@Component
public class HttpMetadataGateway implements MetadataGateway {

    private static final Logger log = LoggerFactory.getLogger(HttpMetadataGateway.class);

    private final HttpClient http;          // a single one, injected (11-02)
    private final ObjectMapper mapper;      // a single one, injected
    private final String baseUrl;

    public HttpMetadataGateway(HttpClient http, ObjectMapper mapper,
                               @Value("${bibliotech.metadata.url}") String baseUrl) {
        this.http = http;
        this.mapper = mapper;
        this.baseUrl = baseUrl;
    }

    @Override
    public Optional<BookMetadata> findByIsbn(String isbn) {

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/isbn/" + isbn + ".json"))
                .header("Accept", "application/json")
                .timeout(Duration.ofSeconds(5))
                .GET()
                .build();

        try {
            HttpResponse<String> response =
                    http.send(request, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() == 404) {
                log.debug("The API does not know ISBN {}", isbn);
                return Optional.empty();
            }
            if (response.statusCode() >= 500) {
                throw new GatewayUnavailableException(
                        "The API returned " + response.statusCode());
            }

            // ONE LINE. No indexOf, no substring, no uncovered edge cases.
            MetadataResponse dto = mapper.readValue(response.body(), MetadataResponse.class);

            log.info("Metadata obtained for {}: {}", isbn, dto.title());
            return Optional.of(dto.toDomain());

        } catch (JsonProcessingException e) {
            log.warn("Invalid JSON response for {}", isbn, e);
            throw new GatewayUnavailableException("Unreadable response from the API", e);
        } catch (IOException | InterruptedException e) {
            if (e instanceof InterruptedException) Thread.currentThread().interrupt();
            throw new GatewayUnavailableException("Network error while querying " + isbn, e);
        }
    }
}

// DANGEROUS with external data
mapper.activateDefaultTyping(LaissezFaireSubTypeValidator.instance,
                             ObjectMapper.DefaultTyping.NON_FINAL);

{"@class": "com.example.DangerousClass", "property": "value"}

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = BookDto.class,     name = "BOOK"),
    @JsonSubTypes.Type(value = MagazineDto.class, name = "MAGAZINE"),
    @JsonSubTypes.Type(value = DvdDto.class,      name = "DVD")
})
public sealed interface MaterialDto permits BookDto, MagazineDto, DvdDto { }

public class Employee {

    private Long id;
    private String email;
    private String name;
    private String department;

    public Employee() { }

    public Employee(String email, String name, String department) {
        this.email = email;
        this.name = name;
        this.department = department;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getDepartment() { return department; }
    public void setDepartment(String department) { this.department = department; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Employee)) return false;
        Employee other = (Employee) o;
        return Objects.equals(email, other.email);
    }

    @Override
    public int hashCode() { return Objects.hash(email); }

    @Override
    public String toString() {
        return "Employee{email='" + email + "', name='" + name + "'}";
    }
}

@Getter @Setter
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(of = "email")
@ToString(of = {"email", "name"})
public class Employee {
    private Long id;
    private String email;
    private String name;
    private String department;
}

javap -p target/classes/com/nexussoftware/bibliotech/domain/Employee.class

public class com.nexussoftware.bibliotech.domain.Employee {
  private java.lang.Long id;
  private java.lang.String email;
  public java.lang.Long getId();
  public void setId(java.lang.Long);
  public java.lang.String getEmail();
  ...
}

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <scope>provided</scope>   <!-- compile time only (11-05) -->
    <optional>true</optional>
</dependency>

@Slf4j
@Service
public class LoanManager {
    public void lend(String isbn) {
        log.info("Lending {}", isbn);        // 'log' exists, generated by Lombok
    }
}

@SneakyThrows
public String read(Path file) {
    return Files.readString(file);      // IOException not declared
}

@Builder
@Getter
public class Loan {
    private final Material material;
    private final Employee employee;
    private final LocalDate loanDate;
    private final LocalDate dueDate;
    @Builder.Default
    private final LoanStatus status = LoanStatus.ACTIVE;
}

Loan loan = Loan.builder()
        .material(book)
        .employee(marta)
        .loanDate(LocalDate.now(clock))
        .dueDate(LocalDate.now(clock).plusDays(15))
        .build();

@Service
@RequiredArgsConstructor        // constructor with ALL the final fields
public class LoanManager {

    private final MaterialRepository materials;
    private final EmployeeRepository employees;
    private final LoanRepository loans;
    private final FineCalculator calculator;
    private final NoticeService notices;
    private final Clock clock;

    // Lombok generates the 6-parameter constructor
}

# Stops the configuration lookup from going up into parent directories
config.stopBubbling = true

# Adds @lombok.Generated to generated code: JaCoCo EXCLUDES it from coverage (12-05)
lombok.addLombokGeneratedAnnotation = true

# Forbids @Data and @Value: they force you to be explicit (see section 21)
lombok.data.flagUsage = error
lombok.value.flagUsage = warning

# Forbids @SneakyThrows: it breaks module 6's exception contract
lombok.sneakyThrows.flagUsage = error

# Copies these annotations onto the generated constructor (useful with Spring and Jackson)
lombok.copyableAnnotations += org.springframework.beans.factory.annotation.Qualifier

// WHAT NOT TO DO
@Entity
@Data                       // <- includes @EqualsAndHashCode with EVERY field
public class Material {

    @Id @GeneratedValue
    private Long id;

    private String isbn;
    private String title;

    @OneToMany(mappedBy = "material", fetch = FetchType.LAZY)
    private List<Loan> loans;
}

Material book = new Book("978-0000000001", "Effective Java", 3, "J. Bloch");
Set<Material> set = new HashSet<>();
set.add(book);                              // id = null -> hashCode X

repository.save(book);                      // JPA assigns id = 42 -> hashCode Y

assertThat(set.contains(book));             // FALSE! It is in the wrong bucket

log.debug("Material: {}", material);
// -> toString() calls getLoans()
// -> the lazy collection gets initialised
// -> SELECT * FROM loans WHERE material_id = 42

@Entity
@Getter                                       // getters only
@Setter(AccessLevel.PROTECTED)                // restricted setters
@NoArgsConstructor(access = AccessLevel.PROTECTED)   // the one JPA requires
@ToString(of = { "id", "isbn", "title" })     // ONLY scalar fields
@EqualsAndHashCode(of = "isbn")               // ONLY the business key, immutable
public class Material {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String isbn;                      // business key: it never changes

    private String title;

    @OneToMany(mappedBy = "material", fetch = FetchType.LAZY)
    private List<Loan> loans = new ArrayList<>();
}

// Lombok
@Value
public class BookMetadata {
    String author;
    LocalDate publicationDate;
    String publisher;
}

// Java 16+, no dependencies
public record BookMetadata(String author, LocalDate publicationDate, String publisher) { }

package com.nexussoftware.bibliotech.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class LoanManager {

    private static final Logger log = LoggerFactory.getLogger(LoanManager.class);

    public Loan lend(String isbn, String email) {
        log.debug("Loan request: isbn={}, employee={}", isbn, email);
        // ...
        log.info("Loan created: id={}, due={}", loan.getId(), loan.getDueDate());
        return loan;
    }
}

logging.level.com.nexussoftware.bibliotech=DEBUG
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.springframework=INFO

@Slf4j
public class LoanManager { ... }

// WRONG: concatenation
log.debug("Loan " + loan.getId() + " of material " + material.getTitle()
          + " for " + employee.getName());

// RIGHT: parameterised
log.debug("Loan {} of material {} for {}",
          loan.getId(), material.getTitle(), employee.getName());

// Exceptions: ALWAYS as the LAST argument, WITHOUT {}
log.error("Could not lend {}", isbn, exception);   // logs the full stack trace

// WRONG: loses the stack trace, which is the only useful part
log.error("Could not lend " + isbn + ": " + exception.getMessage());

// If the argument is EXPENSIVE to compute, check the level
if (log.isDebugEnabled()) {
    log.debug("Full catalogue state: {}", catalog.fullDump());
}

log.atDebug().setMessage("Catalogue: {}")
   .addArgument(() -> catalog.fullDump())        // lambda: only evaluated if needed
   .log();

// ERROR: action is needed. Somebody should get an alert.
log.error("Could not connect to the database after 3 attempts", exception);

// WARN: anomalous but recovered.
log.warn("The metadata API did not respond for {}; carrying on without enriching", isbn);

// INFO: business events. It must be readable in production without noise.
log.info("Loan {} created for {} due on {}", id, email, dueDate);

// DEBUG: for diagnosis. Disabled in production.
log.debug("Evaluating {} pending reservations with {} days ahead", total, days);

// TRACE: very fine. Almost never enabled.
log.trace("Reservation {} : requestDate={}, expires={}", id, request, expiry);

// WRONG: the same exception will appear three times in the log
catch (IOException e) {
    log.error("Read error", e);
    throw new PersistenceException("Read error", e);
}

// RIGHT: either you log (because it is handled here) or you rethrow (and whoever handles it logs)
catch (IOException e) {
    throw new PersistenceException("Error reading " + file, e);
}

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <property name="CONSOLE_PATTERN"
              value="%d{HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{36}) - %msg%n"/>
    <property name="FILE_PATTERN"
              value="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{40} [%X{requestId}] - %msg%n"/>

    <!-- APPENDER 1: console -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>${CONSOLE_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- APPENDER 2: file rolling by date AND size -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>logs/bibliotech.log</file>
        <encoder>
            <pattern>${FILE_PATTERN}</pattern>
            <charset>UTF-8</charset>
        </encoder>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>logs/bibliotech-%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>50MB</maxFileSize>      <!-- rolls over when it passes 50 MB -->
            <maxHistory>30</maxHistory>          <!-- keeps 30 days -->
            <totalSizeCap>2GB</totalSizeCap>     <!-- never more than 2 GB in total -->
        </rollingPolicy>
    </appender>

    <!-- APPENDER 3: asynchronous. Writing does not block the business thread -->
    <appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
        <appender-ref ref="FILE"/>
        <queueSize>512</queueSize>
        <discardingThreshold>0</discardingThreshold>   <!-- do not discard messages -->
    </appender>

    <!-- LEVELS PER PACKAGE -->
    <logger name="com.nexussoftware.bibliotech" level="DEBUG"/>
    <logger name="org.hibernate.SQL" level="DEBUG"/>
    <logger name="org.hibernate.orm.jdbc.bind" level="TRACE"/>
    <logger name="org.springframework" level="INFO"/>

    <!-- SPRING PROFILES (11-02) -->
    <springProfile name="dev">
        <root level="DEBUG">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <springProfile name="prod">
        <root level="INFO">
            <appender-ref ref="ASYNC_FILE"/>
        </root>
        <logger name="com.nexussoftware.bibliotech" level="INFO"/>
        <logger name="org.hibernate.SQL" level="OFF"/>
    </springProfile>

</configuration>

logging:
  level:
    root: INFO
    com.nexussoftware.bibliotech: DEBUG
    org.hibernate.SQL: DEBUG
  file:
    name: logs/bibliotech.log
  logback:
    rollingpolicy:
      max-file-size: 50MB
      max-history: 30
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level %logger{36} - %msg%n"

import org.slf4j.MDC;

public class CorrelationFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {

        String requestId = Optional
                .ofNullable(((HttpServletRequest) request).getHeader("X-Request-Id"))
                .orElse(UUID.randomUUID().toString());

        MDC.put("requestId", requestId);
        MDC.put("user", currentUser());

        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear();   // ESSENTIAL: the thread goes back to the pool (module 8)
        }
    }
}

2026-03-20 10:15:23.451 INFO  [http-nio-8080-exec-3] c.n.b.s.LoanManager [a3f2-9b21] - Loan 4218 created
2026-03-20 10:15:23.502 DEBUG [http-nio-8080-exec-3] c.n.b.p.LoanRepository [a3f2-9b21] - Saving loan
2026-03-20 10:15:23.510 INFO  [http-nio-8080-exec-7] c.n.b.s.LoanManager [7c81-4e55] - Loan 4219 created

{"@timestamp":"2026-03-20T10:15:23.451+01:00","level":"INFO","logger":"com.nexussoftware.bibliotech.service.LoanManager","thread":"http-nio-8080-exec-3","message":"Loan 4218 created","requestId":"a3f2-9b21","user":"[email protected]"}

<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>requestId</includeMdcKeyName>
        <includeMdcKeyName>user</includeMdcKeyName>
    </encoder>
</appender>

logging:
  structured:
    format:
      console: ecs      # Elastic Common Schema

import java.util.logging.Level;
import java.util.logging.Logger;

public class LoanManager {

    private static final Logger LOG = Logger.getLogger(LoanManager.class.getName());

    public Loan lend(String isbn, String email) {
        if (LOG.isLoggable(Level.FINE)) {                   // manual check
            LOG.fine("Lending " + isbn + " to " + email);   // concatenation
        }
        try {
            // ...
            LOG.info("Loan created: " + loan.getId());
            return loan;
        } catch (Exception e) {
            LOG.log(Level.SEVERE, "Error lending " + isbn, e);      // awkward API
            throw e;
        }
    }
}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class LoanManager {

    private static final Logger log = LoggerFactory.getLogger(LoanManager.class);

    public Loan lend(String isbn, String email) {
        log.debug("Lending {} to {}", isbn, email);            // parameterised, deferred

        Loan loan = /* ... */;
        log.info("Loan created: id={}, due={}",
                 loan.getId(), loan.getDueDate());
        return loan;
    }
}

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>jul-to-slf4j</artifactId>
</dependency>

./mvnw dependency:tree | grep -E "slf4j|logback|log4j"

SLF4J: Class path contains multiple SLF4J bindings.
SLF4J: Found binding in [.../logback-classic-1.5.6.jar!/org/slf4j/impl/StaticLoggerBinder.class]
SLF4J: Found binding in [.../slf4j-simple-2.0.13.jar!/org/slf4j/impl/StaticLoggerBinder.class]

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

// Your CsvReader from 07-07: 70 lines, not covering quotes or embedded breaks
// With OpenCSV:
try (var reader = new CsvToBeanBuilder<MaterialCsv>(new FileReader(file, UTF_8))
        .withType(MaterialCsv.class)
        .withSeparator(';')
        .build()) {
    List<MaterialCsv> materials = reader.parse();
}

@Mapper(componentModel = "spring")
public interface MaterialMapper {
    MaterialDto toDto(Material material);
    List<MaterialDto> toDtos(List<Material> materials);
}

@Test
void theDomainDoesNotDependOnSpringOrJpa() {
    JavaClasses classes = new ClassFileImporter()
            .importPackages("com.nexussoftware.bibliotech");

    noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("org.springframework..", "jakarta.persistence..")
            .check(classes);
}

{
  "request_id": "req-8821",
  "generated_at": "2026-03-20T10:15:23Z",
  "items": [
    {
      "isbn_13": "978-0000000001",
      "book_title": "Effective Java",
      "stock": { "available": 3, "reserved": 1, "warehouse": "MAD-01" },
      "unit_price": 54.95,
      "currency": "EUR",
      "last_updated": "2026-03-19",
      "tags": ["java", "best-practices"],
      "discontinued": false
    }
  ],
  "warnings": []
}

@Entity
@Table(name = "materials")
@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Material {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String isbn;

    private String title;

    private int availableCopies = 1;

    @OneToMany(mappedBy = "material", fetch = FetchType.LAZY)
    private List<Loan> loans = new ArrayList<>();

    @ManyToMany(fetch = FetchType.LAZY)
    private Set<Category> categories = new HashSet<>();

    @Version
    private Long version;
}

public class ReturnManager {

    private static final Logger LOG = Logger.getLogger(ReturnManager.class.getName());

    public ReturnResult returnItem(Long loanId) {

        LOG.info("Starting return of loan " + loanId);

        Loan loan = loans.findById(loanId).orElse(null);
        if (loan == null) {
            LOG.severe("Loan not found: " + loanId);
            throw new LoanNotFoundException(loanId);
        }

        if (LOG.isLoggable(Level.FINE)) {
            LOG.fine("Loan state: " + loan.toString()
                     + " with material " + loan.getMaterial().toString());
        }

        BigDecimal fine = calculator.calculate(loan);
        LOG.info("Fine calculated: " + fine);

        try {
            loan.returnItem(LocalDate.now(clock));
            loans.save(loan);
        } catch (Exception e) {
            LOG.log(Level.SEVERE, "Error saving the return of " + loanId, e);
            throw new PersistenceException("Error returning " + loanId, e);
        }

        LOG.info("Return completed");
        return new ReturnResult(loan, fine, false);
    }
}

package com.nexussoftware.bibliotech.network;

import com.fasterxml.jackson.annotation.*;
import java.math.BigDecimal;
import java.time.*;
import java.util.List;

/** (1) DTO of the external availability API. It mirrors the JSON, not the domain. */
@JsonIgnoreProperties(ignoreUnknown = true)          // (1) survives new fields
public record AvailabilityResponse(

        @JsonProperty("request_id")   String requestId,
        @JsonProperty("generated_at") Instant generatedAt,     // (4) absolute instant
        @JsonProperty("items")        List<Item> items,
        @JsonProperty("warnings")     List<String> warnings) {

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Item(

            @JsonProperty("isbn_13") String isbn,

            // (2) API v1 uses "book_title", v2 uses "title"
            @JsonProperty("book_title")
            @JsonAlias({"title"})
            String title,

            @JsonProperty("stock") Stock stock,

            // (3) BigDecimal, NEVER double for money (01-04, 11-03)
            @JsonProperty("unit_price") BigDecimal unitPrice,

            @JsonProperty("currency") String currency,

            // (4) business date with no time: LocalDate (10-05)
            @JsonProperty("last_updated") LocalDate lastUpdated,

            @JsonProperty("tags") List<String> tags,

            @JsonProperty("discontinued") boolean discontinued) {

        @JsonIgnoreProperties(ignoreUnknown = true)
        public record Stock(
                @JsonProperty("available") int available,
                @JsonProperty("reserved")  int reserved,
                @JsonProperty("warehouse") String warehouse) { }

        // (5) translation into the domain
        public MaterialAvailability toDomain() {
            return new MaterialAvailability(
                    isbn,
                    title,
                    stock == null ? 0 : stock.available(),     // defensive: the JSON may omit it
                    unitPrice,
                    lastUpdated);
        }
    }

    /** (5) Every item, already translated into the domain. */
    public List<MaterialAvailability> toDomain() {
        return items == null ? List.of() : items.stream().map(Item::toDomain).toList();
    }
}

// (5) The DOMAIN record: our own names, with no trace of the external API
public record MaterialAvailability(
        String isbn,
        String title,
        int available,
        BigDecimal price,
        LocalDate updated) {

    public boolean inStock() { return available > 0; }
}

@Configuration
public class JacksonConfiguration {

    @Bean
    public ObjectMapper objectMapper() {
        return JsonMapper.builder()

                // java.time support: without this, LocalDate and Instant fail
                .addModule(new JavaTimeModule())

                // Dates in ISO-8601, not as a number of seconds.
                // Readable, interoperable and consistent with what 10-05 decided.
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)

                // Redundant with @JsonIgnoreProperties, but it protects
                // any DTO where somebody forgets the annotation.
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)

                // JSON decimals are read as BigDecimal, not as double.
                // Essential for amounts: it avoids 54.949999999999996.
                .enable(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS)

                // Do not serialise null fields: smaller responses.
                .serializationInclusion(JsonInclude.Include.NON_NULL)

                .build();
    }
}

class AvailabilityResponseTest {

    private final ObjectMapper mapper = new JacksonConfiguration().objectMapper();

    @Test
    @DisplayName("deserialises the response and translates it to the domain, ignoring unknown fields")
    void deserialisesAndTranslates() throws Exception {
        String json = """
                {
                  "request_id": "req-8821",
                  "generated_at": "2026-03-20T10:15:23Z",
                  "server_region": "eu-west-1",
                  "items": [
                    {
                      "isbn_13": "978-0000000001",
                      "book_title": "Effective Java",
                      "stock": { "available": 3, "reserved": 1, "warehouse": "MAD-01" },
                      "unit_price": 54.95,
                      "currency": "EUR",
                      "last_updated": "2026-03-19",
                      "tags": ["java", "best-practices"],
                      "discontinued": false,
                      "promo_code": "SPRING26"
                    }
                  ],
                  "warnings": []
                }
                """;   // text block from 10-06

        AvailabilityResponse response =
                mapper.readValue(json, AvailabilityResponse.class);

        // The unknown fields (server_region, promo_code) break nothing
        assertThat(response.requestId()).isEqualTo("req-8821");
        assertThat(response.generatedAt()).isEqualTo(Instant.parse("2026-03-20T10:15:23Z"));
        assertThat(response.warnings()).isEmpty();

        assertThat(response.toDomain()).singleElement().satisfies(a -> {
            assertThat(a.isbn()).isEqualTo("978-0000000001");
            assertThat(a.title()).isEqualTo("Effective Java");
            assertThat(a.available()).isEqualTo(3);
            assertThat(a.price()).isEqualByComparingTo("54.95");    // exact, no error
            assertThat(a.updated()).isEqualTo(LocalDate.of(2026, 3, 19));
            assertThat(a.inStock()).isTrue();
        });
    }

    @Test
    @DisplayName("also accepts the old name of the title field")
    void acceptsTheLegacyAlias() throws Exception {
        String jsonV2 = """
                {"items":[{"isbn_13":"978-0000000002","title":"Design Patterns",
                           "stock":{"available":2},"unit_price":49.00,
                           "last_updated":"2026-03-18"}]}
                """;

        var response = mapper.readValue(jsonV2, AvailabilityResponse.class);

        assertThat(response.toDomain()).singleElement()
                .extracting(MaterialAvailability::title)
                .isEqualTo("Design Patterns");
    }

    @Test
    @DisplayName("the price is read as an exact BigDecimal, not as a double")
    void exactPrice() throws Exception {
        String json = """
                {"items":[{"isbn_13":"978-0000000003","book_title":"Refactoring",
                           "stock":{"available":1},"unit_price":0.1,
                           "last_updated":"2026-03-20"}]}
                """;

        var a = mapper.readValue(json, AvailabilityResponse.class).toDomain().get(0);

        // With a double it would be 0.1000000000000000055511151231257827
        assertThat(a.price()).isEqualByComparingTo(new BigDecimal("0.1"));
        assertThat(a.price().toPlainString()).isEqualTo("0.1");
    }
}

Material book = Material.builder().isbn("978-0000000001").title("Effective Java").build();
Set<Material> selection = new HashSet<>();
selection.add(book);                     // id = null -> hashCode H1 -> bucket A

repository.save(book);                   // JPA assigns id = 42 -> hashCode H2

selection.contains(book);                // looks in bucket B -> FALSE

log.debug("Material: {}", material);

material.setId(99L);        // corrupts the entity's identity
material.setVersion(0L);    // breaks 11-03's optimistic locking

private int availableCopies = 1;
private List<Loan> loans = new ArrayList<>();
private Set<Category> categories = new HashSet<>();

Material m = Material.builder().isbn("978-0000000001").build();
m.getAvailableCopies();         // 0, not 1
m.getLoans();                   // null, not an empty list -> NullPointerException

package com.nexussoftware.bibliotech.domain;

import jakarta.persistence.*;
import java.util.*;
import lombok.*;

@Entity
@Table(name = "materials")
@Getter                                                   // public read only
@Setter(AccessLevel.PROTECTED)                            // setters restricted to JPA/subclasses
@NoArgsConstructor(access = AccessLevel.PROTECTED)        // the one JPA requires (11-03)
@ToString(of = { "id", "isbn", "title", "availableCopies" })   // ONLY scalars
@EqualsAndHashCode(of = "isbn")                           // IMMUTABLE business key
public class Material {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 20, updatable = false)
    private String isbn;                                  // updatable=false: it never changes

    @Column(nullable = false, length = 200)
    private String title;

    @Column(name = "available_copies", nullable = false)
    private int availableCopies;

    @OneToMany(mappedBy = "material", fetch = FetchType.LAZY)
    private List<Loan> loans = new ArrayList<>();

    @ManyToMany(fetch = FetchType.LAZY)
    @JoinTable(name = "material_category",
               joinColumns = @JoinColumn(name = "material_id"),
               inverseJoinColumns = @JoinColumn(name = "category_id"))
    private Set<Category> categories = new HashSet<>();

    @Version
    private Long version;

    /** Public constructor with validation: replaces @Builder and @AllArgsConstructor. */
    public Material(String isbn, String title, int availableCopies) {
        this.isbn = Objects.requireNonNull(isbn, "The ISBN is mandatory");
        this.title = Objects.requireNonNull(title, "The title is mandatory");
        if (availableCopies < 0) {
            throw new IllegalArgumentException("Copies cannot be negative");
        }
        this.availableCopies = availableCopies;
    }

    // DOMAIN methods with validation, instead of open setters
    public void lendOneCopy() {
        if (availableCopies <= 0) throw new NoCopiesAvailableException(isbn);
        availableCopies--;
    }

    public void returnOneCopy() { availableCopies++; }

    /** Defensive copy: nobody modifies the collection from outside (11-03 §13). */
    public List<Loan> getLoans() { return List.copyOf(loans); }
}

@Test
@DisplayName("a Material remains findable in a HashSet after receiving its id")
void stableIdentityAfterPersisting() {

    Material book = new Material("978-0000000001", "Effective Java", 3);
    Set<Material> selection = new HashSet<>();
    selection.add(book);

    // Simulates what JPA does when persisting: assigning the generated id
    ReflectionTestUtils.setField(book, "id", 42L);

    // With @Data this FAILS: the hashCode changed and the object is in another bucket
    assertThat(selection).contains(book);
    assertThat(selection.contains(book)).isTrue();
}

@Test
@DisplayName("toString does not touch the lazy relations")
void toStringWithoutRelations() {
    Material book = new Material("978-0000000001", "Effective Java", 3);

    assertThat(book.toString())
            .contains("978-0000000001")
            .contains("Effective Java")
            .doesNotContain("loans")          // it would have fired the query
            .doesNotContain("categories");
}

@DataJpaTest
class MaterialToStringIT {

    @Autowired private TestEntityManager em;

    @Test
    @DisplayName("toString does not cause LazyInitializationException outside the session")
    void toStringIsSafeOutsideTheSession() {
        Material book = em.persistAndFlush(new Material("978-0000000001", "Effective Java", 3));
        em.clear();                                   // simulates the context closing

        Material detached = em.getEntityManager()
                .getReference(Material.class, book.getId());

        assertThatCode(detached::toString).doesNotThrowAnyException();
    }
}

config.stopBubbling = true

# @Data is the root of both incidents: forbidden across the project
lombok.data.flagUsage = error

# @Value is immutable but incompatible with JPA: warn
lombok.value.flagUsage = warning

# @AllArgsConstructor allows entities to be built without validation
lombok.allArgsConstructor.flagUsage = warning

# @SneakyThrows breaks module 6's exception contract
lombok.sneakyThrows.flagUsage = error

# Generated methods do not count towards coverage (12-05)
lombok.addLombokGeneratedAnnotation = true

package com.nexussoftware.bibliotech.service;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.UUID;
import org.slf4j.*;
import org.springframework.dao.DataAccessException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@RequiredArgsConstructor          // Lombok: constructor injection (11-02)
public class ReturnManager {

    private static final Logger log = LoggerFactory.getLogger(ReturnManager.class);
    // (or simply @Slf4j on the class)

    private final LoanRepository loans;
    private final FineCalculator calculator;
    private final Clock clock;

    @Transactional
    public ReturnResult returnItem(Long loanId) {

        // (3) MDC: correlation of every line of this return
        MDC.put("operation", "return");
        MDC.put("loanId", String.valueOf(loanId));
        MDC.put("operationId", UUID.randomUUID().toString());

        try {
            // (5) DEBUG, not INFO: the start of an operation is of no interest in production
            log.debug("Starting return");

            Loan loan = loans.findById(loanId)
                    .orElseThrow(() -> {
                        // (4) DEBUG, not ERROR: it is a business case, not a system failure
                        log.debug("Loan not found");
                        return new LoanNotFoundException(loanId);
                    });

            // (1)(2)(7) parameterised, no entity toString(), no isLoggable
            log.debug("Loan located: isbn={}, dueDate={}, status={}",
                    loan.getMaterial().getIsbn(),         // SCALAR fields only
                    loan.getDueDate(),
                    loan.getStatus());

            BigDecimal fine = calculator.calculate(loan);

            loan.returnItem(LocalDate.now(clock));
            loans.save(loan);
            // (3) no catch: the persistence exception rises and whoever handles it logs it

            // (5)(6) ONE INFO line per operation, with ALL the relevant context
            log.info("Return completed: isbn={}, employee={}, fine={} EUR, daysLate={}",
                    loan.getMaterial().getIsbn(),
                    loan.getEmployee().getEmail(),
                    fine,
                    loan.daysLate(LocalDate.now(clock)));

            if (fine.compareTo(BigDecimal.ZERO) > 0) {
                log.warn("Return with a fine: isbn={}, amount={} EUR",
                        loan.getMaterial().getIsbn(), fine);
            }

            return new ReturnResult(loan, fine, false);

        } finally {
            MDC.clear();   // (3) ESSENTIAL: the thread goes back to the pool (10-07)
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <!-- ============ DEVELOPMENT: readable console ============ -->
    <springProfile name="dev">

        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} %highlight(%-5level) [%thread] %cyan(%logger{30}) [%X{operationId:-no-id}] - %msg%n</pattern>
                <charset>UTF-8</charset>
            </encoder>
        </appender>

        <logger name="com.nexussoftware.bibliotech" level="DEBUG"/>
        <logger name="org.hibernate.SQL" level="DEBUG"/>            <!-- SQL only in dev -->
        <logger name="org.hibernate.orm.jdbc.bind" level="TRACE"/>  <!-- parameters -->
        <logger name="org.springframework" level="INFO"/>

        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <!-- ============ PRODUCTION: rolled JSON file ============ -->
    <springProfile name="prod">

        <appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>logs/bibliotech.json</file>

            <encoder class="net.logstash.logback.encoder.LogstashEncoder">
                <includeMdcKeyName>operationId</includeMdcKeyName>
                <includeMdcKeyName>loanId</includeMdcKeyName>
                <includeMdcKeyName>operation</includeMdcKeyName>
                <customFields>{"application":"bibliotech","environment":"prod"}</customFields>
            </encoder>

            <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
                <fileNamePattern>logs/bibliotech-%d{yyyy-MM-dd}.%i.json.gz</fileNamePattern>
                <maxFileSize>100MB</maxFileSize>
                <maxHistory>30</maxHistory>
                <totalSizeCap>5GB</totalSizeCap>
            </rollingPolicy>
        </appender>

        <!-- Asynchronous: writing to disk does not block the business thread -->
        <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
            <appender-ref ref="JSON_FILE"/>
            <queueSize>1024</queueSize>
            <discardingThreshold>0</discardingThreshold>
        </appender>

        <logger name="com.nexussoftware.bibliotech" level="INFO"/>
        <logger name="org.hibernate.SQL" level="OFF"/>       <!-- NEVER SQL in production -->
        <logger name="org.springframework" level="WARN"/>

        <root level="INFO">
            <appender-ref ref="ASYNC"/>
        </root>
    </springProfile>

</configuration>