blob: 7e67055ea9eb75707b96be2026d35860c053fe1f [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>ManagedExecutorService</title>
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="ManagedExecutorService";
}
}
catch(err) {
}
//-->
</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><a href="../../../jakarta/enterprise/concurrent/ManagedExecutors.html" title="class in jakarta.enterprise.concurrent"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../jakarta/enterprise/concurrent/ManagedScheduledExecutorService.html" title="interface in jakarta.enterprise.concurrent"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?jakarta/enterprise/concurrent/ManagedExecutorService.html" target="_top">Frames</a></li>
<li><a href="ManagedExecutorService.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>Method</li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li>Method</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</div>
<h2 title="Interface ManagedExecutorService" class="title">Interface ManagedExecutorService</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Superinterfaces:</dt>
<dd>java.util.concurrent.Executor, java.util.concurrent.ExecutorService</dd>
</dl>
<dl>
<dt>All Known Subinterfaces:</dt>
<dd><a href="../../../jakarta/enterprise/concurrent/ManagedScheduledExecutorService.html" title="interface in jakarta.enterprise.concurrent">ManagedScheduledExecutorService</a></dd>
</dl>
<hr>
<br>
<pre>public interface <span class="typeNameLabel">ManagedExecutorService</span>
extends java.util.concurrent.ExecutorService</pre>
<div class="block">A manageable version of a <code>ExecutorService</code>.
<p>
A ManagedExecutorService extends the Java&trade; SE ExecutorService to provide
methods for submitting tasks for execution in a Jakarta&trade; EE environment.
Implementations of the ManagedExecutorService are
provided by a Jakarta EE Product Provider. Application Component Providers
use the Java Naming and Directory Interface&trade; (JNDI) to look-up instances of one
or more ManagedExecutorService objects using resource environment references.
ManagedExecutorService instances can also be injected into application
components through the use of the <code>Resource</code> annotation.
<p>
The Jakarta Concurrency specification describes several
behaviors that a ManagedExecutorService can implement. The Application
Component Provider and Deployer identify these requirements and map the
resource environment reference appropriately.
<p>
The most common uses for a ManagedExecutorService is to run short-duration asynchronous
tasks such as for processing of asynchronous methods in Jakarta
Enterprise Beans or for processing async tasks for Servlets that
supports asynchronous processing.
<p>
Tasks are run in managed threads provided by the Jakarta EE Product Provider
and are run within the application component context that submitted the task.
All tasks run without an explicit transaction (they do not enlist in the application
component's transaction). If a transaction is required, use a
<a href="../../../jakarta/transaction/UserTransaction.html" title="interface in jakarta.transaction"><code>UserTransaction</code></a> instance. A UserTransaction instance is
available in JNDI using the name: &quot;java:comp/UserTransaction&quot; or by
requesting an injection of a <a href="../../../jakarta/transaction/UserTransaction.html" title="interface in jakarta.transaction"><code>UserTransaction</code></a> object
using the <code>Resource</code> annotation.
<p>
Example:
<pre>
public run() {
// Begin of task
InitialContext ctx = new InitialContext();
UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
ut.begin();
// Perform transactional business logic
ut.commit();
}
</pre>
Tasks can optionally provide an <a href="../../../jakarta/enterprise/concurrent/ManagedTaskListener.html" title="interface in jakarta.enterprise.concurrent"><code>ManagedTaskListener</code></a> to receive
notifications of lifecycle events, through the use of <a href="../../../jakarta/enterprise/concurrent/ManagedTask.html" title="interface in jakarta.enterprise.concurrent"><code>ManagedTask</code></a>
interface.
<p>
Example:
<pre>
public class MyRunnable implements Runnable, ManagedTask {
...
public void run() {
...
}
public ManagedTaskListener getManagedTaskListener() {
return myManagedTaskListener;
}
...
}
MyRunnable task = ...;
ManagedExecutorService executor = ...;
executor.submit(task); // lifecycle events will be notified to myManagedTaskListener
</pre>
Asynchronous tasks are typically submitted to the ManagedExecutorService using one
of the <code>submit</code> methods, each of which return a <code>Future</code>
instance. The <code>Future</code> represents the result of the task and can also be used to
check if the task is complete or wait for its completion.
<p>
If the task is canceled, the result for the task is a
<code>CancellationException</code> exception. If the task is unable
to run due to a reason other than cancellation, the result is a
<a href="../../../jakarta/enterprise/concurrent/AbortedException.html" title="class in jakarta.enterprise.concurrent"><code>AbortedException</code></a> exception.
<p>
Example:
<pre>
&#47;**
* Retrieve all accounts from several account databases in parallel.
* Resource Mappings:
* type: jakarta.enterprise.concurrent.ManagedExecutorService
* jndi-name: concurrent/ThreadPool
*&#47;
public List&lt;Account&gt; getAccounts(long accountId) {
try {
javax.naming.InitialContext ctx = new InitialContext();
<b>ManagedExecutorService mes = (ManagedExecutorService)
ctx.lookup("java:comp/env/concurrent/ThreadPool");</b>
// Create a set of tasks to perform the account retrieval.
ArrayList&lt;Callable&lt;Account&gt;&gt; retrieverTasks = new ArrayList&lt;Callable&lt;Account&gt;&gt;();
retrieverTasks.add(new EISAccountRetriever());
retrieverTasks.add(new RDBAccountRetriever());
// Submit the tasks to the thread pool and wait for them
// to complete (successfully or otherwise).
<b>List&lt;Future&lt;Account&gt;&gt; taskResults= mes.invokeAll(retrieverTasks);</b>
// Retrieve the results from the resulting Future list.
ArrayList&lt;Account&gt; results = new ArrayList&lt;Account&gt;();
for(Future&lt;Account&gt; taskResult : taskResults) {
try {
<b>results.add(taskResult.get());</b>
} catch (ExecutionException e) {
Throwable cause = e.getCause();
// Handle the AccountRetrieverError.
}
}
return results;
} catch (NamingException e) {
// Throw exception for fatal error.
} catch (InterruptedException e) {
// Throw exception for shutdown or other interrupt condition.
}
}
public class EISAccountRetriever implements Callable&lt;Account&gt; {
public Account call() {
// Connect to our eis system and retrieve the info for the account.
//...
return null;
}
}
public class RDBAccountRetriever implements Callable&lt;Account>&gt; {
public Account call() {
// Connect to our database and retrieve the info for the account.
//...
}
}
public class Account {
// Some account data...
}
</pre>
<P></div>
<dl>
<dt><span class="simpleTagLabel">Since:</span></dt>
<dd>1.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>
<ul class="blockList">
<li class="blockList"><a name="methods.inherited.from.class.java.util.concurrent.ExecutorService">
<!-- -->
</a>
<h3>Methods inherited from interface&nbsp;java.util.concurrent.ExecutorService</h3>
<code>awaitTermination, invokeAll, invokeAll, invokeAny, invokeAny, isShutdown, isTerminated, shutdown, shutdownNow, submit, submit, submit</code></li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="methods.inherited.from.class.java.util.concurrent.Executor">
<!-- -->
</a>
<h3>Methods inherited from interface&nbsp;java.util.concurrent.Executor</h3>
<code>execute</code></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><a href="../../../jakarta/enterprise/concurrent/ManagedExecutors.html" title="class in jakarta.enterprise.concurrent"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../jakarta/enterprise/concurrent/ManagedScheduledExecutorService.html" title="interface in jakarta.enterprise.concurrent"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?jakarta/enterprise/concurrent/ManagedExecutorService.html" target="_top">Frames</a></li>
<li><a href="ManagedExecutorService.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>Method</li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li>Method</li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>