blob: 3275098d8a4f82322fb3221c69843f22d8cfbfc8 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<title>ThreadContextProvider</title>
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
<link rel="shortcut icon" href="/img/jakarta-favicon.ico">
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="ThreadContextProvider";
}
}
catch(err) {
}
//-->
var methods = {"i0":6,"i1":6,"i2":6};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Class</li>
<li><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextRestorer.html" title="interface in jakarta.enterprise.concurrent.spi"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?jakarta/enterprise/concurrent/spi/ThreadContextProvider.html" target="_top">Frames</a></li>
<li><a href="ThreadContextProvider.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">jakarta.enterprise.concurrent.spi</div>
<h2 title="Interface ThreadContextProvider" class="title">Interface ThreadContextProvider</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>public interface <span class="typeNameLabel">ThreadContextProvider</span></pre>
<div class="block">Third party providers of thread context implement this interface to
participate in thread context capture and propagation.
<p>
Application code must never access the classes within this <code>spi</code>
package. Instead, application code uses the various interfaces that are defined
by the Jakarta Concurrency specification, such as
<a href="../../../../jakarta/enterprise/concurrent/ManagedExecutorService.html" title="interface in jakarta.enterprise.concurrent"><code>ManagedExecutorService</code></a>
and <a href="../../../../jakarta/enterprise/concurrent/ContextService.html" title="interface in jakarta.enterprise.concurrent"><code>ContextService</code></a>.
<p>
The <code>ThreadContextProvider</code> implementation and related classes are
packaged within the third party provider's JAR file. The implementation is made
discoverable via the <code>ServiceLoader</code> mechanism. The JAR file
that packages it must include a file with the following name and location,
<p>
<code>META-INF/services/jakarta.enterprise.concurrent.spi.ThreadContextProvider</code>
<p>
The content of the aforementioned file must be one or more lines, each specifying
the fully qualified name of a <code>ThreadContextProvider</code> implementation
that is provided within the JAR file.
<p>
The Jakarta EE Product Provider must use the
<code>ServiceLoader</code> to identify all available implementations of
<code>ThreadContextProvider</code> that can participate in thread context capture
and propagation and must invoke them either to capture current thread context or establish
default thread context per the configuration of the
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html" title="annotation in jakarta.enterprise.concurrent"><code>ContextServiceDefinition</code></a>,
or vendor-specific configuration, and execution properties such as
<a href="../../../../jakarta/enterprise/concurrent/ManagedTask.html#TRANSACTION"><code>ManagedTask.TRANSACTION</code></a>
that override context propagation configuration.</div>
<dl>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>3.0</dd>
</dl>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t3" class="tableTab"><span><a href="javascript:show(4);">Abstract Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextSnapshot.html" title="interface in jakarta.enterprise.concurrent.spi">ThreadContextSnapshot</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextProvider.html#clearedContext-java.util.Map-">clearedContext</a></span>(java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;props)</code>
<div class="block">Returns empty/cleared context of the provided type.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextSnapshot.html" title="interface in jakarta.enterprise.concurrent.spi">ThreadContextSnapshot</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextProvider.html#currentContext-java.util.Map-">currentContext</a></span>(java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;props)</code>
<div class="block">Captures from the current thread a snapshot of the provided thread context type.</div>
</td>
</tr>
<tr id="i2" class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextProvider.html#getThreadContextType--">getThreadContextType</a></span>()</code>
<div class="block">Returns a human readable identifier for the type of thread context that is
captured by this <code>ThreadContextProvider</code> implementation.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="currentContext-java.util.Map-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>currentContext</h4>
<pre><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextSnapshot.html" title="interface in jakarta.enterprise.concurrent.spi">ThreadContextSnapshot</a>&nbsp;currentContext(java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;props)</pre>
<div class="block">Captures from the current thread a snapshot of the provided thread context type.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>props</code> - execution properties, which are optionally provided
by some types of tasks and contextual proxies.
Thread context providers that do not supply or use execution properties
can ignore this parameter.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>immutable snapshot of the provided type of context, captured from the
current thread.</dd>
</dl>
</li>
</ul>
<a name="clearedContext-java.util.Map-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>clearedContext</h4>
<pre><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextSnapshot.html" title="interface in jakarta.enterprise.concurrent.spi">ThreadContextSnapshot</a>&nbsp;clearedContext(java.util.Map&lt;java.lang.String,java.lang.String&gt;&nbsp;props)</pre>
<div class="block">Returns empty/cleared context of the provided type. This context is not
captured from the current thread, but instead represents the behavior that you
get for this context type when no particular context has been applied to the
thread.
<p>
This is used in cases where the provided type of thread context should not be
propagated from the requesting thread or inherited from the thread of execution,
in which case it is necessary to establish an empty/cleared context in its place,
so that an action does not unintentionally inherit context of the thread that
happens to run it.
<p>
For example, a security context provider's empty/cleared context ensures there
is no authenticated user on the thread. A transaction context provider's
empty/cleared context ensures that any active transaction is suspended.
And so forth.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>props</code> - execution properties, which are optionally provided
by some types of tasks and contextual proxies.
Thread context providers that do not supply or use execution properties
can ignore this parameter.</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>immutable empty/default context of the provided type.</dd>
</dl>
</li>
</ul>
<a name="getThreadContextType--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>getThreadContextType</h4>
<pre>java.lang.String&nbsp;getThreadContextType()</pre>
<div class="block">Returns a human readable identifier for the type of thread context that is
captured by this <code>ThreadContextProvider</code> implementation.
<p>
To ensure portability of applications, this is typically be a keyword that
is defined by the same specification that defines the thread context type.
<p>
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html" title="annotation in jakarta.enterprise.concurrent"><code>ContextServiceDefinition</code></a>
defines identifiers for built-in thread context types, including
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html#APPLICATION"><code>Application</code></a>,
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html#SECURITY"><code>Security</code></a>, and
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html#TRANSACTION"><code>Transaction</code></a>,
as well as the
<a href="../../../../jakarta/enterprise/concurrent/ContextServiceDefinition.html#ALL_REMAINING"><code>Remaining</code></a>
identifer which covers all remaining context.
These identifiers must not be returned from this method.
<p>
Applications use a combination of built-in identifiers and those that are
defined by other specifications and third-party context
types when configuring a <code>ContextServiceDefinition</code>
to capture and propagate only specific types of thread context.
<p>
For example:
<pre>
<code> @ContextServiceDefinition(</code>
name = "java:module/concurrent/MyCustomContext",
propagated = MyCustomContextProvider.CONTEXT_NAME,
cleared = { ContextServiceDefinition.SECURITY, ContextServiceDefinition.TRANSACTION },
unchanged = ContextServiceDefinition.ALL_REMAINING)
</pre>
<p>
It is an error for multiple thread context providers of an identical type to be
simultaneously available.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>identifier for the provided type of thread context.</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev&nbsp;Class</li>
<li><a href="../../../../jakarta/enterprise/concurrent/spi/ThreadContextRestorer.html" title="interface in jakarta.enterprise.concurrent.spi"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?jakarta/enterprise/concurrent/spi/ThreadContextProvider.html" target="_top">Frames</a></li>
<li><a href="ThreadContextProvider.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>