{"id":658,"date":"2026-04-09T22:38:00","date_gmt":"2026-04-09T21:38:00","guid":{"rendered":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/?p=658"},"modified":"2026-06-16T22:42:23","modified_gmt":"2026-06-16T21:42:23","slug":"scoped-values-in-java-der-moderne-ersatz-fuer-threadlocal","status":"publish","type":"post","link":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/?p=658","title":{"rendered":"Scoped Values in Java \u2013 Der moderne Ersatz f\u00fcr ThreadLocal"},"content":{"rendered":"\n

Jeder Java-Entwickler kennt das Problem: Ein Request trifft ein, der HTTP-Controller startet einen Service, der ruft ein Repository auf \u2013 und irgendwo in der Tiefe des Stacks soll auf die Request-ID oder den aktuellen Benutzer zugegriffen werden. Ohne sie als Parameter durch alle Methoden zu schleppen. Die klassische L\u00f6sung hei\u00dft ThreadLocal<\/code> \u2013 doch die hat gravierende Nachteile. Mit Java 21 (JEP 446) wurde Scoped Value<\/strong> als Preview-Feature eingef\u00fchrt, das ThreadLocal<\/code> in modernen Codebasen abl\u00f6sen soll. Hinweis: Auch in Java 24 (Stand M\u00e4rz 2025) ist die API noch im Preview-Status (JEP 487) und sollte nicht in Production verwendet werden.<\/p>\n\n\n\n

Das Problem mit ThreadLocal<\/h2>\n\n\n\n

ThreadLocal<\/code> speichert Daten pro Thread, global erreichbar und implizit vererbt. Das klingt praktisch, f\u00fchrt aber zu diesen Problemen:<\/p>\n\n\n\n

    \n
  • Unkontrollierte Mutabilit\u00e4t<\/strong>:\u00a0ThreadLocal.set()<\/code>\u00a0kann von \u00fcberall aufgerufen werden \u2013 eine Einladung f\u00fcr Seiteneffekte<\/li>\n\n\n\n
  • Keine definierte Lebensdauer<\/strong>: Einmal gesetzt bleibt der Wert, bis er aktiv entfernt wird \u2013 Memory Leaks drohen<\/li>\n\n\n\n
  • Probleme mit Virtual Threads<\/strong>: Unter Java 21 k\u00f6nnen Millionen Virtual Threads existieren. Ein\u00a0ThreadLocal<\/code>-wert pro Thread skaliert hier nicht<\/li>\n\n\n\n
  • Kein Scope<\/strong>: Es gibt keine Einschr\u00e4nkung, wo und wie lange ein Wert g\u00fcltig ist<\/li>\n<\/ul>\n\n\n\n

    ScopedValue \u2013 immutable und scoped<\/h2>\n\n\n\n

    ScopedValue<\/code> verfolgt einen fundamental anderen Ansatz: Der Wert ist immutable<\/strong> und nur innerhalb eines definierten Scopes<\/strong> verf\u00fcgbar.<\/p>\n\n\n

    private static<\/span> final ScopedValue<String<\/span>> REQUEST_ID = ScopedValue.newInstance();\n\nScopedValue.where(REQUEST_ID, \"req-abc-123\"<\/span>)\n    .run(() -> {\n        <em>\/\/ In diesem Scope ist der Wert verf\u00fcgbar<\/em><\/span>\n        System.out.println(REQUEST_ID.get()); <em<\/span>><\/span>\/\/ \"req-abc-123\"<\/em<\/span>><\/span><\/span>\n    });\n\n<em<\/span>><\/span>\/\/ Au\u00dferhalb: kein Zugriff \u2013 REQUEST_ID.get() wirft NoSuchElementException<\/em<\/span>><\/span><\/span>\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Der entscheidende Unterschied zu ThreadLocal<\/code>: Der Scope wird explizit ge\u00f6ffnet (where<\/code>) und mit einer Aktion (run<\/code>) verbunden. Beim Verlassen des Scopes ist der Wert automatisch ung\u00fcltig. Kein remove()<\/code>, keine Leaks.<\/p>\n\n\n\n
    Vererbung an Kind-Threads<\/h2>\n\n\n\n
    Scoped Values vererben sich automatisch an Kind-Threads \u2013 allerdings nur bei Verwendung von StructuredTaskScope<\/code> (ebenfalls Preview-Feature). Bei manuell erstellten Virtual Threads via Thread.ofVirtual()<\/code> oder Executors.newVirtualThreadPerTaskExecutor()<\/code> findet keine automatische Vererbung statt:<\/p>\n\n\n
    ScopedValue.where(REQUEST_ID, \"req-abc-123\"<\/span>)\n    .run(() -> {\n        try<\/span> (var<\/span> scope = new<\/span> StructuredTaskScope<Void>()) {\n            scope.fork(() -> {\n                System.out.println(REQUEST_ID.get()); <em<\/span>><\/span>\/\/ \"req-abc-123\" wird vererbt<\/em<\/span>><\/span><\/span>\n                return<\/span> null<\/span>;\n            });\n            scope.join();\n        }\n    });\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    In Kombination mit Structured Concurrency<\/strong> und Virtual Threads<\/strong> entsteht ein nahtloses Kontext-Propagation-Modell:<\/p>\n\n\n
    try<\/span> (var<\/span> scope = new<\/span> StructuredTaskScope.ShutdownOnFailure()) {\n    scope.fork(() -> apiService.rufeMitKontext());\n    scope.fork(() -> datenbankService.ladeMitKontext());\n    scope.join();\n}\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Beide Tasks sehen denselben REQUEST_ID<\/code>-Wert, ohne dass er als Parameter \u00fcbergeben oder manuell kopiert wurde.<\/p>\n\n\n\n
    Vergleich: ThreadLocal vs. ScopedValue<\/h2>\n\n\n
    <em>\/\/ ThreadLocal-Ansatz (legacy)<\/em><\/span>\nThreadLocal<String<\/span>> requestId = new<\/span> ThreadLocal<>();\nrequestId.set(\"abc\"<\/span>);\ntry<\/span> {\n    meinService.verarbeite();\n} finally<\/span> {\n    requestId.remove(); <em<\/span>><\/span>\/\/ Sonst Memory Leak!<\/em<\/span>><\/span><\/span>\n}\n\n<em>\/\/ ScopedValue-Ansatz (modern)<\/em><\/span>\nprivate static<\/span> final ScopedValue<String<\/span>> REQUEST_ID = ScopedValue.newInstance();\nScopedValue.where(REQUEST_ID, \"abc\"<\/span>)\n    .run(() -> meinService.verarbeite());\n<em<\/span>><\/span>\/\/ Kein finally, kein remove \u2013 Scope ist automatisch begrenzt<\/em<\/span>><\/span><\/span>\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Mehrere Werte kombinieren<\/h2>\n\n\n\n
    Scoped Values lassen sich mit where(...).where(...)<\/code> ketten:<\/p>\n\n\n
    private<\/span> static<\/span> final<\/span> ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();\nprivate<\/span> static<\/span> final<\/span> ScopedValue<User>   CURRENT_USER = ScopedValue.newInstance();\n\nScopedValue.where(REQUEST_ID, \"abc\"<\/span>)\n    .where(CURRENT_USER, user)\n    .run(() -> {\n        log.info(\"User {} in Request {}\"<\/span>, CURRENT_USER.get(), REQUEST_ID.get());\n    });\n<\/code><\/span>Code-Sprache:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Rebind \u2013 Wert \u00fcberschreiben innerhalb eines Scopes<\/h2>\n\n\n\n
    Mit callWhere<\/code> l\u00e4sst sich ein Wert innerhalb eines bestehenden Scopes tempor\u00e4r \u00fcberschreiben:<\/p>\n\n\n
    ScopedValue.where(REQUEST_ID, \"outer\"<\/span>)\n    .run(() -> {\n        System.out.println(REQUEST_ID.get()); <em<\/span>><\/span>\/\/ \"outer\"<\/em<\/span>><\/span><\/span>\n        ScopedValue.where(REQUEST_ID, \"inner\"<\/span>)\n            .run(() -> {\n                System.out.println(REQUEST_ID.get()); <em<\/span>><\/span>\/\/ \"inner\"<\/em<\/span>><\/span><\/span>\n            });\n        System.out.println(REQUEST_ID.get()); <em<\/span>><\/span>\/\/ \"outer\" wiederhergestellt<\/em<\/span>><\/span><\/span>\n    });\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Dieses Rebind ist ein wichtiger Unterschied zu ThreadLocal<\/code>, wo set()<\/code> den Wert global-mutabel \u00fcberschreibt.<\/p>\n\n\n\n
    Virtual Threads und Speicher<\/h2>\n\n\n\n
    Ein zentrales Problem von ThreadLocal<\/code> unter Virtual Threads ist der Speicher. Platform Threads (einige Hundert) mit einem ThreadLocal<String><\/code> machen kaum etwas aus. Aber eine Million Virtual Threads, jeder mit seinem eigenen ThreadLocal<\/code>-Wert, summieren sich massiv.<\/p>\n\n\n\n
    ScopedValue<\/code> l\u00f6st das \u00fcber strukturelles Teilen: Da der Wert immutable ist und vom Eltern-Thread vererbt wird, teilen sich Kind-Threads dieselbe Referenz \u2013 kein Kopieren, keine Duplizierung:<\/p>\n\n\n
    ScopedValue.where(REQUEST_ID, \"abc\"<\/span>)\n    .run(() -> {\n        try<\/span> (var<\/span> scope = new<\/span> StructuredTaskScope<Void>()) {\n            for<\/span> (int i = 0<\/span>; i < 100000<\/span>; i++) {\n                scope.fork(() -> {\n                    assert REQUEST_ID.get().equals(\"abc\"<\/span>);\n                    return<\/span> null<\/span>;\n                });\n            }\n            scope.join();\n        }\n    });\n<\/code><\/span>Code-Sprache:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    100.000 Virtual Threads greifen hier auf denselben ScopedValue<\/code> zu \u2013 mit ThreadLocal<\/code> m\u00fcsste der Wert 100.000-mal kopiert werden.<\/p>\n\n\n\n
    Migration von ThreadLocal<\/h2>\n\n\n\n
    Wer eine bestehende ThreadLocal<\/code>-Basis migrieren will, kann schrittweise vorgehen:<\/p>\n\n\n
    <em>\/\/ Vorher: ThreadLocal<\/em><\/span>\npublic<\/span> class<\/span> RequestContext<\/span> <\/span>{\n    private<\/span> static<\/span> final<\/span> ThreadLocal<String> requestId = new<\/span> ThreadLocal<>();\n\n    public<\/span> static<\/span> void setRequestId(String id) {\n        requestId.set(id);\n    }\n\n    public<\/span> static<\/span> String getRequestId() {\n        return<\/span> requestId.get();\n    }\n}\n\n<em>\/\/ Nachher: ScopedValue<\/em><\/span>\npublic<\/span> class<\/span> RequestContext<\/span> <\/span>{\n    private<\/span> static<\/span> final<\/span> ScopedValue<String> REQUEST_ID =\n        ScopedValue.newInstance();\n\n    public<\/span> static<\/span> void withRequestId(String id, Runnable action) {\n        ScopedValue.where(REQUEST_ID, id).run(action);\n    }\n\n    public<\/span> static<\/span> String getRequestId() {\n        return<\/span> REQUEST_ID.get();\n    }\n}\n<\/code><\/span>Code-Sprache:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Der Unterschied: Statt eines flachen set()<\/code> wird jetzt ein Scope ben\u00f6tigt. Das Runnable<\/code> zwingt den Aufrufer, den G\u00fcltigkeitsbereich explizit zu machen \u2013 ein struktureller Vorteil, der Debugging und Wartung vereinfacht.<\/p>\n\n\n\n
    Fazit<\/h2>\n\n\n\n
    Scoped Values sind mehr als ein ThreadLocal<\/code>-Ersatz \u2013 sie sind ein Paradigmenwechsel im Umgang mit Thread-lokalen Daten. Die Immutability, der definierte Lebenszyklus und die automatische Vererbung an Virtual Threads machen sie zur nat\u00fcrlichen Wahl f\u00fcr Java 21+ Projekte. Besonders unter Virtual Threads, wo tausende Threads gleichzeitig laufen k\u00f6nnen, sind Scoped Values durch ihre Referenz-Teilung dem kopierenden ThreadLocal<\/code> \u00fcberlegen. In Verbindung mit Structured Concurrency entsteht ein Programmiermodell, das funktionale Reinheit mit nebenl\u00e4ufiger Leistungsf\u00e4higkeit verbindet. ThreadLocal<\/code> sollte nur noch f\u00fcr Legacy-Code oder spezielle Low-Level-Anwendungen genutzt werden.<\/p>\n\n\n\n
    Wichtig<\/strong>: Sowohl Scoped Values als auch Structured Concurrency sind in Java 24 (Stand M\u00e4rz 2025) noch Preview-Features und nicht f\u00fcr den produktiven Einsatz empfohlen. Die APIs sind stabil, k\u00f6nnen sich aber noch \u00e4ndern. F\u00fcr Production-Code sollte weiterhin ThreadLocal<\/code> verwendet werden, bis diese Features final sind.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Jeder Java-Entwickler kennt das Problem: Ein Request trifft ein, der HTTP-Controller startet einen Service, der ruft ein Repository auf \u2013 und irgendwo in der Tiefe des Stacks soll auf die Request-ID oder den aktuellen Benutzer zugegriffen werden. Ohne sie als Parameter durch alle Methoden zu schleppen. Die klassische L\u00f6sung hei\u00dft ThreadLocal \u2013 doch die hat gravierende Nachteile. […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":["post-658","post","type-post","status-publish","format-standard","hentry","category-plain_java"],"_links":{"self":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/658","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=658"}],"version-history":[{"count":1,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/658\/revisions"}],"predecessor-version":[{"id":659,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=\/wp\/v2\/posts\/658\/revisions\/659"}],"wp:attachment":[{"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=658"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=658"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.xn--javaeinfacherklrt-4qb.de\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=658"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}