From 4e85258ae8337cb24a6e82c8075b75030a7fcce6 Mon Sep 17 00:00:00 2001
From: Daniel Flassak <daniel.flassak@dm.de>
Date: Tue, 5 Dec 2023 15:54:29 +0100
Subject: [PATCH] update Readme for 3.0.0

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 35c59a1..255b486 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Structured Logging 
+# Structured Logging
 
 [<img src="https://opensourcelogos.aws.dmtech.cloud/dmTECH_opensource_logo.svg" height="20" width="130">](https://dmtech.de/) 
 [![Apache License 2](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -48,9 +48,11 @@ all without writing more code, because you already have all information you need
   * [Step 5: (also Optional) Test your logging](#step-5-also-optional-test-your-logging)
 * [Advanced usage](#advanced-usage)
   * [Define how Objects should be named in MDC](#define-how-objects-should-be-named-in-mdc)
+  * [Use try-with-resources instead of a callback](#use-try-with-resources-instead-of-a-callback)
   * [Changing serialization by using Jackson annotations](#changing-serialization-by-using-jackson-annotations)
   * [Changing serialization by using a custom ObjectMapper](#changing-serialization-by-using-a-custom-objectmapper)
 * [Changes](#changes)
+  * [3.0.0](#300)
   * [2.0.6](#206)
   * [2.0.5](#205)
   * [2.0.4](#204)
@@ -178,26 +180,37 @@ The following configuration can be used as an example:
 
 ### Step 3: Put Objects into the logging context
 
-Create a new `MdcContext` in a try-with-resources statement to define the scope in which context information should
-be set:
+use MdcContext.mdc(...) to define the scope in which context information should be set:
 
 ```java
+import static de.dm.prom.structuredlogging.MdcContext.mdc;
+
+...
+
 log.info("a message without context");
 
 TimeMachine timeMachine=TimeMachineBuilder.build();
 
-//set the MdcContext as soon as possible after object (timeMachine) creation
-try(var c = MdcContext.of(timeMachine)){
+mdc(timeMachine, () -> {
     log.info("time machine found. Trying to use it");
 
-    travelSomewhereWith(timeMachine);
-
     timeMachine.setFluxFactor(42);
 
     MdcContext.update(timeMachine);
 
-    travelSomewhereWith(timeMachine);
-}
+    travelSomewhenWith(timeMachine);
+});
+
+log.info("another message without context");
+```
+
+you can also return values:
+
+```java
+var currentTime = mdc(timeMachine, () -> {
+    timeMachine.setFluxFactor(42);
+    return travelSomewhenWith(timeMachine);
+});
 
 log.info("another message without context");
 ```
@@ -264,11 +277,11 @@ There are three ways to define the MDC key for the objects you put into the cont
 **2. Define it manually**
 
 ```java
-try(var c = MdcContext.of("de_lorean", timeMachine)){
+mdc("de_lorean", timeMachine, () -> {
     ...
     MdcContext.update("de_lorean", timeMachine);
     ...
-}
+});
 ```
 
 **3. Provide an MdcKeySupplier**
@@ -292,11 +305,31 @@ Then use it:
 
 ```java
 //MdcContext.of(...) is defined so that you can only use TimeMachineKey with a TimeMachine.
-try(var c = MdcContext.of(TimeMachineKey.class, timeMachine)){
+mdc(TimeMachineKey.class, timeMachine, () -> {
     ...
     MdcContext.update(TimeMachineKey.class, timeMachine);
     ...
-}
+});
+```
+
+### Use try-with-resources instead of a callback
+
+You can also use try-with-resources to manage your MDC context if you prefer that or need to.
+
+For example, the following code would ...
+
+1. ... not be possible with the callback API because `availableSeats` is not effectively final
+1. ... be inconvenient, because there are multiple values in the MDC context, which would require nested callbacks
+
+```java
+int availableSeats = 0;
+seats.forEach(seat -> {
+    try (var s = MdcContext.of(seat); var c = MdcContext.of(cinema)) {
+        if (seat.isAvailable()) { // isAvailable() also logs
+            availableSeats++;
+        }
+    }
+});
 ```
 
 ### Changing serialization by using Jackson annotations
@@ -319,6 +352,12 @@ If you want to use your own ObjectMapper for serialization, you can exchange the
 
 ## Changes
 
+### 3.0.0
+
+* **Breaking Change**: Structured Logging now requires Java 17
+* **New Feature**: Convenience methods as an alternative to try-with-resources
+* updated dependencies
+
 ### 2.0.6
 
 * **New Feature**: Made the used ObjectMapper configurable