This is an automated email from the ASF dual-hosted git repository.
lprimak pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/shiro-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new cb789872a update for scoped values
cb789872a is described below
commit cb789872a93dc6fe35e866803ea938ba1b9c152c
Author: lprimak <[email protected]>
AuthorDate: Fri Jan 30 16:57:04 2026 -0600
update for scoped values
---
.well-known/security.txt | 2 +-
feed.xml | 2 +-
subject.html | 33 +++++++++++++++++++++++----------
3 files changed, 25 insertions(+), 12 deletions(-)
diff --git a/.well-known/security.txt b/.well-known/security.txt
index f84201c7f..c2fe92d3b 100644
--- a/.well-known/security.txt
+++ b/.well-known/security.txt
@@ -1,5 +1,5 @@
Contact: mailto:[email protected]
-Expires: 2027-01-30T17:47:25Z
+Expires: 2027-01-30T22:56:47Z
Preferred-Languages: en
Canonical: https://shiro.apache.org/.well-known/security.txt
Policy: https://shiro.apache.org/security-reports.html
\ No newline at end of file
diff --git a/feed.xml b/feed.xml
index cf445f6f8..57ad33167 100644
--- a/feed.xml
+++ b/feed.xml
@@ -4,7 +4,7 @@
<subtitle>Simple. Java. Security.</subtitle>
<link href="https://shiro.apache.org/"/>
<link rel="self" href="https://shiro.apache.org/feed.xml"; />
- <updated>2026-01-30T17:47:26Z</updated>
+ <updated>2026-01-30T22:56:47Z</updated>
<author>
<name>Les Hazlewood</name>
diff --git a/subject.html b/subject.html
index 21e5f81ba..89fae2a82 100644
--- a/subject.html
+++ b/subject.html
@@ -226,7 +226,7 @@
<li><a href="#Subject-ThreadAssociation">Thread Association</a>
<ul class="sectlevel3">
<li><a href="#Subject-AutomaticAssociation">Automatic Association</a></li>
-<li><a href="#Subject-ManualAssociation">Manual Association</a></li>
+<li><a href="#Subject-ManualAssociation">Manual Association
(Deprecated)</a></li>
<li><a href="#a_different_thread">A Different Thread</a></li>
</ul>
</li>
@@ -536,38 +536,51 @@ Subject subject = new
Subject.Builder().principals(principals).buildSubject();</
<p>You can then use the built <code>Subject</code> instance and make calls on
it as expected. But <strong>note</strong>:</p>
</div>
<div class="paragraph">
-<p>The built <code>Subject</code> instance is <strong>not</strong>
automatically bound to the application (thread) for further use.
-If you want it to be available to any code that calls
<code>SecurityUtils.getSubject()</code>, you must ensure a Thread is associated
with the constructed <code>Subject</code>.</p>
+<p>The built <code>Subject</code> instance is <strong>not</strong>
automatically bound to the thread’s scope for further use.
+If you want it to be available to any code that calls
<code>SecurityUtils.getSubject()</code>, you must ensure that thread’s
scope is associated with the constructed <code>Subject</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="Subject-ThreadAssociation">Thread Association</h3>
<div class="paragraph">
-<p>As stated above, just building a <code>Subject</code> instance does not
associate it with a thread - a usual requirement if any calls to
<code>SecurityUtils.getSubject()</code> during thread execution are to work
properly. There are three ways of ensuring a thread is associated with a
<code>Subject</code>:</p>
+<p>As stated above, just building a <code>Subject</code> instance does not
associate it with a thread’s scope - a usual requirement if any calls to
<code>SecurityUtils.getSubject()</code> during thread execution are to work
properly. There are three ways of ensuring a thread’s scope is associated
with a <code>Subject</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p><strong>Automatic Association</strong> - A <code>Callable</code> or
<code>Runnable</code> executed via the <code>Subject.execute</code>* methods
will automatically bind and unbind the Subject to the thread before and after
<code>Callable</code>/<code>Runnable</code> execution.</p>
+<p><strong>Automatic Association</strong> - A <code>Callable</code> or
<code>Runnable</code> executed via the <code>Subject.execute</code>* methods
will automatically associate the Subject during
<code>Callable</code>/<code>Runnable</code> execution.</p>
</li>
<li>
-<p><strong>Manual Association</strong> - You manually bind and unbind the
<code>Subject</code> instance to the currently executing thread. This is
usually useful for framework developers.</p>
+<p><strong>Different Thread</strong> - A <code>Callable</code> or
<code>Runnable</code> is associated with a <code>Subject</code> by calling the
<code>Subject.associateWith</code>* methods and then the returned
<code>Callable</code>/<code>Runnable</code> is executed by another thread. This
is the preferred approach if you need to execute work on another thread as the
<code>Subject</code>.</p>
</li>
<li>
-<p><strong>Different Thread</strong> - A <code>Callable</code> or
<code>Runnable</code> is associated with a <code>Subject</code> by calling the
<code>Subject.associateWith</code>* methods and then the returned
<code>Callable</code>/<code>Runnable</code> is executed by another thread. This
is the preferred approach if you need to execute work on another thread as the
<code>Subject</code>.</p>
+<p><strong>Manual Association</strong> - You manually bind and unbind the
<code>Subject</code> instance to the currently executing thread.
<strong>Note:</strong> This approach can be considered deprecated since
it’s error-prone and uses ThreadLocals directly instead of Java
25’s ScopedValue when available.</p>
</li>
</ul>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+On JDK 25 and above, Shiro 3.0 or later uses Java’s ScopedValue
mechanism instead of ThreadLocals for associating Subjects with scopes. The
principles of association remain the same, but the implementation details
differ. The following explanation primarily focuses on JDK versions prior to
25, where ThreadLocals are used.
+[/NOTE]
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>The important thing to know about thread association is that 2 things must
always occur:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
-<p>The Subject is <em>bound</em> to the thread, so it is available at all
points of the thread’s execution. Shiro does this via its
<code>ThreadState</code> mechanism which is an abstraction on top of a
<code>ThreadLocal</code>.</p>
+<p>(JDK < 25) The Subject is <em>bound</em> to the thread, so it is
available at all points of the thread’s execution. Shiro does this via
its <code>ThreadState</code> mechanism which is an abstraction on top of a
<code>ThreadLocal</code>.</p>
</li>
<li>
-<p>The Subject is <em>unbound</em> at some point later, even if the thread
execution results in an error. This ensures the thread remains clean and clear
of any previous <code>Subject</code> state in a pooled/reusable thread
environment.</p>
+<p>(JDK < 25> The Subject is <em>unbound</em> at some point later, even
if the thread execution results in an error. This ensures the thread remains
clean and clear of any previous <code>Subject</code> state in a pooled/reusable
thread environment.</p>
</li>
</ol>
</div>
@@ -635,7 +648,7 @@ return subject.execute(new Callable() {
</div>
</div>
<div class="sect3">
-<h4 id="Subject-ManualAssociation">Manual Association</h4>
+<h4 id="Subject-ManualAssociation">Manual Association (Deprecated)</h4>
<div class="paragraph">
<p>While the <code>Subject.execute</code>* methods automatically clean up the
thread state after they return, there might be some scenarios where you want to
manage the <code>ThreadState</code> yourself. This is almost always done in
framework-level development when integrating w/ Shiro and is rarely used even
in bootstrap/daemon scenarios (where the <code>Subject.execute(callable)</code>
example above is more frequent).</p>
</div>
