You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by lp...@apache.org on 2026/01/30 22:57:15 UTC
(shiro-site) branch asf-site updated: update for scoped values
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 <le...@flowlogix.com>
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:security@shiro.apache.org
-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>