Update docs for v2 and v3

Author: damianmalczewski

docs/02-problem4j-core.md

@@ -13,14 +13,14 @@ higher is required to use this library.
        <dependency>
            <groupId>io.github.problem4j</groupId>
            <artifactId>problem4j-core</artifactId>
-           <version>1.4.3</version>
+           <version>2.0.0</version>
        </dependency>
    </dependencies>
    ```
 2. Gradle (Groovy or Kotlin DSL):
    ```kt
    dependencies {
-       implementation("io.github.problem4j:problem4j-core:1.4.3")
+       implementation("io.github.problem4j:problem4j-core:2.0.0")
    }
     ```
 
@@ -116,8 +116,8 @@ throw new InterpolatedException("sub", "boom");
 ```
 
 After catching such exception, to be able to convert it to `Problem` object, you must have an instance of
-`ProblemMapper`. Problem4J Core provides a default implementation available from `ProblemMapper.create()` method, but
-you may use `AbstractProblemMapper` as a base to customize it further.
+`ProblemMapper`. Problem4J Core provides a default implementation - `DefaultProblemMapper`, but you may
+extend from it to customize it further.
 
 Note that `ProblemMapper` returns a `ProblemBuilder` instance.
 
@@ -127,7 +127,7 @@ import io.github.problem4j.core.ProblemMapper;
 
 // ...
 
-ProblemMapper problemMapper = ProblemMapper.create();
+ProblemMapper problemMapper = new DefaultProblemMapper();
 try {
   // ...
 } catch (InterpolatedException e) {
@@ -173,7 +173,7 @@ import io.github.problem4j.core.ProblemMapper;
 // ...
 
 String traceId = someTracingFramework.getTraceId();
-ProblemMapper problemMapper = ProblemMapper.create();
+ProblemMapper problemMapper = new DefaultProblemMapper();
 try {
   // ...
 } catch (TracingAwareException e) {

docs/03-problem4j-jackson.md

@@ -67,26 +67,26 @@ not** declare `jackson-databind` as a transitive dependency.
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
-           <version>2.20.1</version>
+           <version>2.21.3</version>
        </dependency>
        <dependency>
            <groupId>io.github.problem4j</groupId>
            <artifactId>problem4j-core</artifactId>
-           <version>1.4.3</version>
+           <version>2.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.problem4j</groupId>
            <artifactId>problem4j-jackson2</artifactId>
-           <version>1.4.3</version>
+           <version>2.0.0</version>
        </dependency>
    </dependencies>
    ```
 2. Gradle (Kotlin DSL):
    ```kt
    dependencies {
-       implementation("com.fasterxml.jackson.core:jackson-databind:2.20.0")
-       implementation("io.github.problem4j:problem4j-core:1.4.3")
-       implementation("io.github.problem4j:problem4j-jackson2:1.4.3")
+       implementation("com.fasterxml.jackson.core:jackson-databind:2.21.3")
+       implementation("io.github.problem4j:problem4j-core:2.0.0")
+       implementation("io.github.problem4j:problem4j-jackson2:2.0.0")
    }
    ```
 
@@ -150,26 +150,26 @@ not** declare `jackson-databind` as a transitive dependency.
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
-           <version>3.0.3</version>
+           <version>3.1.2</version>
        </dependency>
        <dependency>
            <groupId>io.github.problem4j</groupId>
            <artifactId>problem4j-core</artifactId>
-           <version>1.4.3</version>
+           <version>2.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.problem4j</groupId>
            <artifactId>problem4j-jackson3</artifactId>
-           <version>1.4.3</version>
+           <version>2.0.0</version>
        </dependency>
    </dependencies>
    ```
 2. Gradle (Kotlin DSL):
    ```kt
    dependencies {
-       implementation("tools.jackson.core:jackson-databind:3.0.3")
-       implementation("io.github.problem4j:problem4j-core:1.4.3")
-       implementation("io.github.problem4j:problem4j-jackson3:1.4.3")
+       implementation("tools.jackson.core:jackson-databind:3.1.2")
+       implementation("io.github.problem4j:problem4j-core:2.0.0")
+       implementation("io.github.problem4j:problem4j-jackson3:2.0.0")
    }
    ```
 

docs/04-problem4j-spring/01-setting-up-and-configuration.md

@@ -11,13 +11,11 @@ Setting up dependencies and application properties.
 Add library as dependency to Maven or Gradle. See the actual versions on [Maven Central][maven-central]. Add it along
 with repository in your dependency manager. **Java 17** or higher is required to use this library.
 
-Version `problem4j-spring-v1.x` is backwards compatible down to **Spring Boot `3.0.x`**, although it was tested mostly
-on versions between `3.2.x` and `3.5.x`. Integration with **Spring Boot 4** is released as `problem4j-spring-v2.x`.
-
-| Spring Boot Version | Problem4J Spring Version |
-|---------------------|--------------------------|
-| `3.x`               | `1.x` (latest - `1.2.9`) |
-| `4.x`               | `2.x` (latest - `2.2.4`) |
+| Problem4J Spring Version | About                                   |
+|--------------------------|-----------------------------------------|
+| `3.x` (latest - `3.0.0`) | Spring Boot `4.x`, `problem4j-core-2.x` | 
+| `2.x` (latest - `2.2.4`) | Spring Boot `4.x`, `problem4j-core-1.x` |
+| `1.x` (latest - `1.2.9`) | Spring Boot `3.x`, `problem4j-core-1.x` |
 
 Use version from the above table while managing your dependency or visit Maven Central to find out latest version in
 given generation.
@@ -66,8 +64,8 @@ errors generated by the library and those from your application.
 ### `problem4j.tracing-header-name`
 
 Property that specifies the name of the HTTP header used for tracing requests. If set, the trace identifier from this
-header is extracted and made available within the request context (`ProblemContext`). This value can be referenced in
-other configuration properties using the `{context.traceId}` placeholder. Defaults to `null` (disabled).
+header is extracted and stored in the request context (`ProblemContext`) under the `traceId` key. This value can be
+referenced in override templates using the `{context.traceId}` placeholder. Defaults to `null` (disabled).
 
 See [Simple Tracing](./additional-features#simple-tracing) chapter for more info.
 
@@ -78,6 +76,13 @@ identifiers to environment-specific URIs (for example, production vs. staging).
 
 See [Problem Post-Processor](./problem-post-processor) chapter for more info.
 
+### `problem4j.title-override`
+
+Defines a template for overriding the `"title"` field of `Problem` responses. Useful for applying a consistent title
+format across all problems or injecting runtime context into the title. Defaults to `null` (disabled).
+
+See [Problem Post-Processor](./problem-post-processor) chapter for more info.
+
 ### `problem4j.instance-override`
 
 Defines a template for overriding the `"instance"` field of `Problem` responses. Useful for appending runtime context
@@ -93,14 +98,4 @@ stable set of exception / resolver types.
 
 See [Resolver Caching](./additional-features#resolver-caching) chapter for more info.
 
-### `problem4j.resolver-caching.max-cache-size`
-
-Maximum number of resolver entries stored when caching is enabled. Defaults to `-1` (unbounded). Uses LRU (least
-recently used) eviction once the limit is exceeded. Values `<= 0` mean the cache is unbounded (no eviction).
-
-**Note** that in most cases, there's no need to ever limit max cache size for problem resolvers, as the number of
-resolvers or exception types never increase at runtime.
-
-See [Resolver Caching](./additional-features#resolver-caching) chapter for more info.
-
 [maven-central]: https://central.sonatype.com/namespace/io.github.problem4j

docs/04-problem4j-spring/02-exception-handling.md

@@ -115,7 +115,7 @@ public class ExampleExceptionResolver implements ProblemResolver {
   }
 
   @Override
-  public ProblemBuilder resolveBuilder(
+  public Problem resolve(
       ProblemContext context, Exception ex, HttpHeaders headers, HttpStatusCode status) {
     ExampleException e = (ExampleException) ex;
     return Problem.builder()
@@ -125,7 +125,8 @@ public class ExampleExceptionResolver implements ProblemResolver {
         .detail("bad input for user " + e.getUserId())
         .instance("https://example.org/instances/" + context.getTraceId())
         .extension("userId", e.getUserId())
-        .extension("fieldName", e.getFieldName());
+        .extension("fieldName", e.getFieldName())
+        .build();
   }
 }
 ```
@@ -147,9 +148,6 @@ Will result in following response body:
 You can also override existing `ProblemResolver` implementations to extend models provided by this module. Build-in
 resolvers come with `@ConditionalOnMissingBean`, so they can be shadowed by custom ones in target applications.
 
-`ProblemResolver` implementations return a `ProblemBuilder` for flexibility in constructing the final `Problem` object.
-It's a convenience method for further extending `Problem` object by processing downstream.
-
 ## Custom `@RestControllerAdvice`
 
 While creating your own `@RestControllerAdvice`, make sure to position it with right `@Order`. In order for your custom

docs/04-problem4j-spring/06-problem-post-processor.md

@@ -8,33 +8,44 @@ Final modification of `Problem` responses before HTTP response.
 
 Problem4J provides a **post-processing mechanism** that allows modifying certain fields of a `Problem` object after it
 has been constructed. This feature makes it possible to generate environment-dependent or runtime-resolved URIs for
-fields such as `"type"` and `"instance"`, without embedding such logic into exception classes or resolvers.
+fields such as `"type"`, `"title"`, and `"instance"`, without embedding such logic into exception classes or resolvers.
 
 Currently, the following fields can be overridden:
 
 - `type` - the logical category of the problem
+- `title` - a short, human-readable summary of the problem
 - `instance` - an identifier of a specific occurrence, often a URI or trace reference
 
 These overrides are applied by a **global post-processor** using templates defined in configuration properties.
 Templates for overriding problem fields may include placeholders that are dynamically replaced at runtime.
 
-Available placeholders include:
+Available placeholders:
 
 - for overriding `"type"` field:
     - `{problem.type}` - the original `"type"` value of the problem
-- for overriding "instance" field:
+    - `{context.<key>}` - any value from the current request context (e.g. `{context.traceId}`)
+- for overriding `"title"` field:
+    - `{problem.title}` - the original `"title"` value of the problem
+    - `{context.<key>}` - any value from the current request context
+- for overriding `"instance"` field:
     - `{problem.instance}` - the original `"instance"` value of the problem
-    - `{context.traceId}` - the trace identifier from the current request (if tracing is enabled)
+    - `{context.<key>}` - any value from the current request context (e.g. `{context.traceId}`)
+
+The `{context.<key>}` placeholder resolves values stored in `ProblemContext` for the current request. The built-in
+[Simple Tracing](./additional-features#simple-tracing) feature stores the trace identifier under the `traceId` key,
+making it available as `{context.traceId}`. You can also populate the context with custom keys by providing your own
+`ProblemContextFilter`.
 
 General post-processing rules:
 
 - Overrides are applied **only if all placeholders in the template can be resolved**:
     - `{problem.type}` - applied if the original `type` is **non-null**, **non-empty**, not `"about:blank"`.
+    - `{problem.title}` - applied if the original `title` is **non-null** and **non-empty**.
     - `{problem.instance}` - applied if the original `instance` is **non-null** and **non-empty**.
-    - `{context.traceId}` - applied if the context provides a **non-null**, **non-empty** trace ID.
+    - `{context.<key>}` - applied if the context provides a **non-null**, **non-empty** value for that key.
 - If any referenced placeholder cannot be resolved, **the override is skipped** (occurrences of unknown placeholders
   also abort the override for that field).
-- The resulting values are **non-empty strings** and treated as valid URIs.
+- The resulting values are **non-empty strings** and treated as valid URIs (for `type` and `instance`).
 - If no override is set, fields remain as in the original `Problem`.
 - **Static templates** (no placeholders) are always applied, regardless of the original value.
 
@@ -43,6 +54,7 @@ These rules ensure that field transformation is safe and predictable while allow
 Available configuration properties:
 
 - [`problem4j.type-override`](./setting-up-and-configuration#problem4jtype-override)
+- [`problem4j.title-override`](./setting-up-and-configuration#problem4jtitle-override)
 - [`problem4j.instance-override`](./setting-up-and-configuration#problem4jinstance-override)
 
 **Example:**

docs/04-problem4j-spring/07-additional-features.md

@@ -4,47 +4,37 @@ sidebar_position: 7
 
 # Additional Features
 
-Additional, incubating and/or experimental features of Problem4J Spring.
+Additional features of Problem4J Spring.
 
 ## Resolver Caching
 
-| Feature Status | Info                                                                      |
-|----------------|---------------------------------------------------------------------------|
-| **INCUBATING** | internal implementation might change, but public API should stay the same |
-
 Resolving an exception involves finding the correct `ProblemResolver` by walking through the exception’s inheritance
 hierarchy - since resolvers can be defined generically for base exception types. This lookup process can involve
 reflection and multiple comparisons, which may introduce overhead when performed frequently (e.g., in high-throughput
 applications).
 
 To improve performance, the resolver lookup results can be cached. Once an exception type has been resolved, the
 corresponding resolver is stored in a cache, allowing subsequent resolutions of the same type to be served instantly
-without re-evaluating the inheritance chain. Caching uses **LRU (least recently used)** eviction once the limit is
-exceeded, according to configuration.
+without re-evaluating the inheritance chain.
 
 Available configuration properties:
 
 - [`problem4j.resolver-caching.enabled`](./setting-up-and-configuration#problem4jresolver-cachingenabled)
-- [`problem4j.resolver-caching.max-cache-size`](./setting-up-and-configuration#problem4jresolver-cachingmax-cache-size)
 
-The caching mechanism in `CachingProblemResolverStore` uses a `LinkedHashMap` wrapped with `synchronized` if eviction is
-enabled (`max-cache-size > 0`) or `ConcurrentHashMap` (`max-cache-size <= 0`) to avoid external dependencies. This is
-intentionally minimalistic and users can override it by supplying your own `ProblemResolverStore`implementation (or
-extending `AbstractProblemResolverStore`), backed by a proper caching provider and declaring it as `@Component` (all
-`@Bean`-s provided by this library are `@ConditionalOnMissingBean`).
+The caching mechanism in `CachingProblemResolverStore` uses a `ConcurrentHashMap` to avoid external dependencies. This
+is intentionally minimalistic and users can override it by supplying your own `ProblemResolverStore` implementation,
+backed by a proper caching provider and declaring it as `@Component` (all `@Bean`-s provided by this library are
+`@ConditionalOnMissingBean`).
 
 **Example:**
 
 ```properties
 problem4j.resolver-caching.enabled=true
-problem4j.resolver-caching.max-cache-size=256
 ```
 
 Notes:
 
-- As number of exceptions types do not increase at runtime, keeping default `max-cache-size = -1` (unbounded) is usually
-  fine.
-- If you rarely introduce new resolver types, a small cache (64-256) is usually enough.
+- As the number of exception types does not increase at runtime, the cache is unbounded by design and safe to enable.
 - Leave disabled if startup / reflection cost is negligible or resolver set is highly dynamic.
 
 ## Simple Tracing

docs/05-tutorials/01-problem4j-and-spring-boot.md

@@ -13,14 +13,14 @@ The premier integration of Problem4J with Spring Boot.
     <dependency>
         <groupId>io.github.problem4j</groupId>
         <artifactId>problem4j-spring-webmvc</artifactId>
-        <version>2.2.4</version>
+        <version>3.0.0</version>
     </dependency>
 </dependencies>
 ```
 
 ```kt
 dependencies {
-    implementation("io.github.problem4j:problem4j-spring-webmvc:2.2.4")
+    implementation("io.github.problem4j:problem4j-spring-webmvc:3.0.0")
 }
 ```
 

docs/05-tutorials/02-problem4j-and-javalin.md

@@ -17,20 +17,20 @@ long as you can catch exceptions and convert them to `Problem` instances. This p
     <dependency>
         <groupId>io.github.problem4j</groupId>
         <artifactId>problem4j-core</artifactId>
-        <version>1.4.3</version>
+        <version>2.0.0</version>
     </dependency>
     <dependency>
         <groupId>io.github.problem4j</groupId>
         <artifactId>problem4j-jackson3</artifactId>
-        <version>1.4.3</version>
+        <version>2.0.0</version>
     </dependency>
 </dependencies>
 ```
 
 ```kt
 dependencies {
-    implementation("io.github.problem4j:problem4j-core:1.4.3")
-    implementation("io.github.problem4j:problem4j-jackson3:1.4.3")
+    implementation("io.github.problem4j:problem4j-core:2.0.0")
+    implementation("io.github.problem4j:problem4j-jackson3:2.0.0")
 }
 ```
 
@@ -39,7 +39,7 @@ the compatible [Problem4J Jackson](../problem4j-jackson) module.
 
 ```java
 JsonMapper jsonMapper = JsonMapper.builder().findAndAddModules().build();
-ProblemMapper problemMapper = ProblemMapper.create();
+ProblemMapper problemMapper = new DefaultProblemMapper();
 
 Javalin app = Javalin.create();