tomee-9.0/examples/access-timeout.html - tomee-site-pub - Git at Google

 <!DOCTYPE html>
 <html lang="en">

 <head>
 	<meta charset="UTF-8">
 	<meta http-equiv="X-UA-Compatible" content="IE=edge">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
 	<title>Apache TomEE</title>
 	<meta name="description"
 		  content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
 	<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
 	<meta name="author" content="Luka Cvetinovic for Codrops" />
 	<link rel="icon" href="../../favicon.ico">
 	<link rel="icon"  type="image/png" href="../../favicon.png">
 	<meta name="msapplication-TileColor" content="#80287a">
 	<meta name="theme-color" content="#80287a">
 	<link rel="stylesheet" type="text/css" href="../../css/normalize.css">
 	<link rel="stylesheet" type="text/css" href="../../css/bootstrap.css">
 	<link rel="stylesheet" type="text/css" href="../../css/owl.css">
 	<link rel="stylesheet" type="text/css" href="../../css/animate.css">
 	<link rel="stylesheet" type="text/css" href="../../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
 	<link rel="stylesheet" type="text/css" href="../../fonts/eleganticons/et-icons.css">
 	<link rel="stylesheet" type="text/css" href="../../css/jqtree.css">
 	<link rel="stylesheet" type="text/css" href="../../css/idea.css">
 	<link rel="stylesheet" type="text/css" href="../../css/cardio.css">

 	<script type="text/javascript">

       var _gaq = _gaq || [];
       _gaq.push(['_setAccount', 'UA-2717626-1']);
       _gaq.push(['_setDomainName', 'apache.org']);
       _gaq.push(['_trackPageview']);

       (function() {
         var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
         ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
       })();

     </script>
 </head>

 <body>
     <div class="preloader">
 		<img src="../../img/loader.gif" alt="Preloader image">
 	</div>
 	    <nav class="navbar">
 		<div class="container">
 		  <div class="row">          <div class="col-md-12">

 			<!-- Brand and toggle get grouped for better mobile display -->
 			<div class="navbar-header">
 				<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
 					<span class="sr-only">Toggle navigation</span>
 					<span class="icon-bar"></span>
 					<span class="icon-bar"></span>
 					<span class="icon-bar"></span>
 				</button>
 				<a class="navbar-brand" href="/">
 				    <span>


                         <img src="../../img/logo-active.png">


                     </span>
 				    Apache TomEE
                 </a>
 			</div>
 			<!-- Collect the nav links, forms, and other content for toggling -->
 			<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
 				<ul class="nav navbar-nav navbar-right main-nav">
 					<li><a href="../../docs.html">Documentation</a></li>
 					<li><a href="../../community/index.html">Community</a></li>
 					<li><a href="../../security/security.html">Security</a></li>
 					<li><a href="../../download-ng.html">Downloads</a></li>
 				</ul>
 			</div>
 			<!-- /.navbar-collapse -->
 		   </div></div>
 		</div>
 		<!-- /.container-fluid -->
 	</nav>


     <div id="main-block" class="container main-block">
         <div class="row title">
           <div class="col-md-12">
             <div class='page-header'>

               <h1>@AccessTimeout Annotation</h1>
             </div>
           </div>
         </div>
         <div class="row">

             <div class="col-md-12">
                 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph">
 <p>Before taking a look at <code>@AccessTimeout</code>, it might help to see when a caller might have to "wait"</p>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_waiting">Waiting</h2>
 <div class="sectionbody">
 <div class="sect2">
 <h3 id="_stateful_bean">Stateful Bean</h3>
 <div class="admonitionblock note">
 <table>
 <tr>
 <td class="icon">
 <i class="fa icon-note" title="Note"></i>
 </td>
 <td class="content">
 By default, clients are allowed to make concurrent calls to a stateful session object and the container is required to serialize such concurrent requests. The container never permits multi-threaded access to the stateful session bean instance. For this reason, Read/Write method locking metadata, as well as the bean-managed concurrency mode, are not applicable to stateful session beans and must not be used.
 </td>
 </tr>
 </table>
 </div>
 <div class="paragraph">
 <p>This means that when a method <code>foo()</code> of a stateful bean instance is being executed and a second request comes in for that method or another method, EJB container would serialize the second request. It would not let the method be executed concurrently but wait until the first request is processed.</p>
 </div>
 <div class="paragraph">
 <p>The client would wait also when <code>@Stateful</code> bean is in a transaction and the client is invoking it from outside that transaction.</p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_stateless_bean">Stateless Bean</h3>
 <div class="paragraph">
 <p>If there are 20 instances of a bean in the pool and all of them are busy.  When the next request comes in, the processing <strong>might wait</strong> for a bean to be available in the pool. (Note: Pooling sematics, if any, are not covered by the spec. The vendor&#8217;s pooling semantics might or might not involve a wait condition)</p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_singleton_bean">Singleton Bean</h3>
 <div class="paragraph">
 <p>The container enforces a single-threaded access by default to singleton beans. That&#8217;s the equivalent of annotating with <code>@Lock(Write)</code>. So when a <code>@Lock(Write)</code> method is executing, all other <code>@Lock(READ)</code> and <code>@Lock(WRITE)</code> method invocations would have to wait.</p>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_summary">Summary</h3>
 <div class="ulist">
 <ul>
 <li>
 <p><code>@Singleton</code> - an <code>@Lock(WRITE)</code> method is being invoked and container-managed concurrency is being used.  All methods are <code>@Lock(WRITE)</code> by default.</p>
 </li>
 <li>
 <p><code>@Stateful</code> - any method of the instance is being invoked and a second invocation occurs.  OR the <code>@Stateful</code> bean is in a transaction and the caller is invoking it from outside that transaction.</p>
 </li>
 <li>
 <p><code>@Stateless</code> - no instances are available in the pool. As noted, however, pooling sematics, if any, are not covered by the spec.  If the vendor&#8217;s pooling semantics do involve a wait condition, the @AccessTimeout should apply.</p>
 </li>
 </ul>
 </div>
 </div>
 </div>
 </div>
 <h1 id="__accesstimeout" class="sect0">@AccessTimeout</h1>
 <div class="paragraph">
 <p>The <code>@AccessTimeout</code> is simply a convenience wrapper around the <code>long</code> and <code>TimeUnit</code> tuples commonly used in the <code>java.util.concurrent</code> API.</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-java" data-lang="java">import java.util.concurrent.TimeUnit;
 @Target({METHOD, TYPE})
 @Retention(RUNTIME)
 public @interface AccessTimeout {
     long value();
     TimeUnit unit() default TimeUnit.MILLISECONDS;
 }</code></pre>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_usage">Usage</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>A method or class can be annotated with <code>@AccessTimeout</code> to specify the maximum time a call might wait for access to the bean should a wait condition occur.</p>
 </div>
 <div class="paragraph">
 <p>The semantics of the value element are as follows:</p>
 </div>
 <div class="ulist">
 <ul>
 <li>
 <p>A <code>value</code> &gt; 0 indicates a timeout value in the units specified by the <code>unit</code> element.</p>
 </li>
 <li>
 <p>A <code>value</code> of 0 means concurrent access is not permitted.</p>
 </li>
 <li>
 <p>A <code>value</code> of -1 indicates that the client request will block indefinitely until forward progress can proceed.</p>
 </li>
 </ul>
 </div>
 <div class="paragraph">
 <p>Just as simple as that !</p>
 </div>
 <div class="admonitionblock note">
 <table>
 <tr>
 <td class="icon">
 <i class="fa icon-note" title="Note"></i>
 </td>
 <td class="content">
 What exception would the client receive, with a timeout ?
 Quoting from the spec, "if a client-invoked business method is in progress on an instance when another client-invoked call, from the same or different client, arrives at the same instance of a stateful session bean, if the second client is a client of the bean&#8217;s business interface or no-interface view, the concurrent invocation must result in the second client receiving a jakarta.ejb.ConcurrentAccessException[15]. If the EJB 2.1 client view is used, the container must throw a java.rmi.RemoteException if the second client is a remote client, or a jakarta.ejb.EJBException if the second client is a local client"
 </td>
 </tr>
 </table>
 </div>
 <div class="sect2">
 <h3 id="_no_standard_default">No standard default</h3>
 <div class="paragraph">
 <p>Note that the <code>value</code> attribute has no default.  This was intentional and intended to communicate that if <code>@AccessTimeout</code> is not explicitly used, the behavior you get is vendor-specific.</p>
 </div>
 <div class="paragraph">
 <p>Some vendors will wait for a preconfigured time and throw <code>jakarta.ejb.ConcurrentAccessException</code>, some vendors will throw it immediately.</p>
 </div>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_example">Example</h2>
 <div class="sectionbody">
 <div class="paragraph">
 <p>Here we have a simple @Singleton bean that has three synchronous methods and one <code>@Asynchronous</code> method.  The bean itself is annotated <code>@Lock(WRITE)</code> so that only one thread may access the <code>@Singleton</code> at a time.  This is the default behavior of an <code>@Singleton</code> bean, so explicit usage of <code>@Lock(WRITE)</code> is not needed but is rather nice for clarity as the single-threaded nature of the bean is important to the example.</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-java" data-lang="java">@Singleton
 @Lock(WRITE)
 public class BusyBee {

     @Asynchronous
     public Future stayBusy(CountDownLatch ready) {
         ready.countDown();

         try {
             new CountDownLatch(1).await();
         } catch (InterruptedException e) {
             Thread.interrupted();
         }

         return null;
     }

     @AccessTimeout(0)
     public void doItNow() {
         // do something
     }

     @AccessTimeout(value = 5, unit = TimeUnit.SECONDS)
     public void doItSoon() {
         // do something
     }

     @AccessTimeout(-1)
     public void justDoIt() {
         // do something
     }
 }</code></pre>
 </div>
 </div>
 <div class="paragraph">
 <p>The <code>@Asynchronous</code> method is not a critical part of <code>@AccessTimeout</code>, but serves as a simple way to "lock" the bean for testing purposes.  It allows us to easily test the concurrent behavior of the bean.</p>
 </div>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-java" data-lang="java">public class BusyBeeTest extends TestCase {

     public void test() throws Exception {

         final Context context = EJBContainer.createEJBContainer().getContext();

         final CountDownLatch ready = new CountDownLatch(1);

         final BusyBee busyBee = (BusyBee) context.lookup("java:global/access-timeout/BusyBee");

         // This asynchronous method will never exit
         busyBee.stayBusy(ready);

         // Are you working yet little bee?
         ready.await();


         // OK, Bee is busy


         { // Timeout Immediately
             final long start = System.nanoTime();

             try {
                 busyBee.doItNow();

                 fail("The bee should be busy");
             } catch (Exception e) {
                 // the bee is still too busy as expected
             }

             assertEquals(0, seconds(start));
         }

         { // Timeout in 5 seconds
             final long start = System.nanoTime();

             try {
                 busyBee.doItSoon();

                 fail("The bee should be busy");
             } catch (Exception e) {
                 // the bee is still too busy as expected
             }

             assertEquals(5, seconds(start));
         }

         // This will wait forever, give it a try if you have that long
         //busyBee.justDoIt();
     }

     private long seconds(long start) {
         return TimeUnit.NANOSECONDS.toSeconds(System.nanoTime() - start);
     }
 }</code></pre>
 </div>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_running">Running</h2>
 <div class="sectionbody">
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-bash" data-lang="bash">mvn clean test</code></pre>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_output">Output</h3>
 <div class="listingblock">
 <div class="content">
 <pre class="highlight"><code class="language-bash" data-lang="bash">-------------------------------------------------------
     T E S T S
 -------------------------------------------------------
 Running org.superbiz.accesstimeout.BusyBeeTest
 Apache OpenEJB 4.0.0-beta-1    build: 20111002-04:06
 http://tomee.apache.org/
 INFO - openejb.home = /Users/dblevins/examples/access-timeout
 INFO - openejb.base = /Users/dblevins/examples/access-timeout
 INFO - Using 'jakarta.ejb.embeddable.EJBContainer=true'
 INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service)
 INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager)
 INFO - Found EjbModule in classpath: /Users/dblevins/examples/access-timeout/target/classes
 INFO - Beginning load: /Users/dblevins/examples/access-timeout/target/classes
 INFO - Configuring enterprise application: /Users/dblevins/examples/access-timeout
 INFO - Configuring Service(id=Default Singleton Container, type=Container, provider-id=Default Singleton Container)
 INFO - Auto-creating a container for bean BusyBee: Container(type=SINGLETON, id=Default Singleton Container)
 INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container)
 INFO - Auto-creating a container for bean org.superbiz.accesstimeout.BusyBeeTest: Container(type=MANAGED, id=Default Managed Container)
 INFO - Enterprise application "/Users/dblevins/examples/access-timeout" loaded.
 INFO - Assembling app: /Users/dblevins/examples/access-timeout
 INFO - Jndi(name="java:global/access-timeout/BusyBee!org.superbiz.accesstimeout.BusyBee")
 INFO - Jndi(name="java:global/access-timeout/BusyBee")
 INFO - Jndi(name="java:global/EjbModule748454644/org.superbiz.accesstimeout.BusyBeeTest!org.superbiz.accesstimeout.BusyBeeTest")
 INFO - Jndi(name="java:global/EjbModule748454644/org.superbiz.accesstimeout.BusyBeeTest")
 INFO - Created Ejb(deployment-id=org.superbiz.accesstimeout.BusyBeeTest, ejb-name=org.superbiz.accesstimeout.BusyBeeTest, container=Default Managed Container)
 INFO - Created Ejb(deployment-id=BusyBee, ejb-name=BusyBee, container=Default Singleton Container)
 INFO - Started Ejb(deployment-id=org.superbiz.accesstimeout.BusyBeeTest, ejb-name=org.superbiz.accesstimeout.BusyBeeTest, container=Default Managed Container)
 INFO - Started Ejb(deployment-id=BusyBee, ejb-name=BusyBee, container=Default Singleton Container)
 INFO - Deployed Application(path=/Users/dblevins/examples/access-timeout)
 Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.071 sec

 Results :

 Tests run: 1, Failures: 0, Errors: 0, Skipped: 0</code></pre>
 </div>
 </div>
 </div>
 </div>
 </div>
             </div>

         </div>
     </div>
 <footer>
 		<div class="container">
 			<div class="row">
 				<div class="col-sm-6 text-center-mobile">
 					<h3 class="white">Be simple.  Be certified. Be Tomcat.</h3>
 					<h5 class="light regular light-white">"A good application in a good server"</h5>
 					<ul class="social-footer">
 						<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
 						<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
 						<li><a href="https://plus.google.com/communities/105208241852045684449"><i class="fa fa-google-plus"></i></a></li>
 					</ul>
 				</div>
 				<div class="col-sm-6 text-center-mobile">
 					<div class="row opening-hours">
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../../latest/docs/" class="white">Documentation</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
 								<li><a href="../../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
 								<li><a href="../../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
 								<li><a href="../../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../../latest/examples/" class="white">Examples</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
 								<li><a href="../../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
 								<li><a href="../../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
 								<li><a href="../../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../../community/index.html" class="white">Community</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="../../community/contributors.html" class="regular light-white">Contributors</a></li>
 								<li><a href="../../community/social.html" class="regular light-white">Social</a></li>
 								<li><a href="../../community/sources.html" class="regular light-white">Sources</a></li>
 							</ul>
 						</div>
 						<div class="col-sm-3 text-center-mobile">
 							<h5><a href="../../security/index.html" class="white">Security</a></h5>
 							<ul class="list-unstyled">
 								<li><a href="http://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
 								<li><a href="http://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
 								<li><a href="http://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
 							</ul>
 						</div>
 					</div>
 				</div>
 			</div>
 			<div class="row bottom-footer text-center-mobile">
 				<div class="col-sm-12 light-white">
 					<p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
 				</div>
 			</div>
 		</div>
 	</footer>
 	<!-- Holder for mobile navigation -->
 	<div class="mobile-nav">
         <ul>
           <li><a hef="../../latest/docs/admin/index.html">Administrators</a>
           <li><a hef="../../latest/docs/developer/index.html">Developers</a>
           <li><a hef="../../latest/docs/advanced/index.html">Advanced</a>
           <li><a hef="../../community/index.html">Community</a>
         </ul>
 		<a href="#" class="close-link"><i class="arrow_up"></i></a>
 	</div>
 	<!-- Scripts -->
 	<script src="../../js/jquery-1.11.1.min.js"></script>
 	<script src="../../js/owl.carousel.min.js"></script>
 	<script src="../../js/bootstrap.min.js"></script>
 	<script src="../../js/wow.min.js"></script>
 	<script src="../../js/typewriter.js"></script>
 	<script src="../../js/jquery.onepagenav.js"></script>
 	<script src="../../js/tree.jquery.js"></script>
 	<script src="../../js/highlight.pack.js"></script>
     <script src="../../js/main.js"></script>
 		</body>

 </html>
	<!DOCTYPE html>
	<html lang="en">

	<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Apache TomEE</title>
	<meta name="description"
	content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
	<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
	<meta name="author" content="Luka Cvetinovic for Codrops" />
	<link rel="icon" href="../../favicon.ico">
	<link rel="icon" type="image/png" href="../../favicon.png">
	<meta name="msapplication-TileColor" content="#80287a">
	<meta name="theme-color" content="#80287a">
	<link rel="stylesheet" type="text/css" href="../../css/normalize.css">
	<link rel="stylesheet" type="text/css" href="../../css/bootstrap.css">
	<link rel="stylesheet" type="text/css" href="../../css/owl.css">
	<link rel="stylesheet" type="text/css" href="../../css/animate.css">
	<link rel="stylesheet" type="text/css" href="../../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
	<link rel="stylesheet" type="text/css" href="../../fonts/eleganticons/et-icons.css">
	<link rel="stylesheet" type="text/css" href="../../css/jqtree.css">
	<link rel="stylesheet" type="text/css" href="../../css/idea.css">
	<link rel="stylesheet" type="text/css" href="../../css/cardio.css">

	<script type="text/javascript">

	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-2717626-1']);
	_gaq.push(['_setDomainName', 'apache.org']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();

	</script>
	</head>

	<body>
	<div class="preloader">
	<img src="../../img/loader.gif" alt="Preloader image">
	</div>
	<nav class="navbar">
	<div class="container">
	<div class="row"> <div class="col-md-12">

	<!-- Brand and toggle get grouped for better mobile display -->
	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="navbar-brand" href="/">
	<span>


	<img src="../../img/logo-active.png">


	</span>
	Apache TomEE
	</a>
	</div>
	<!-- Collect the nav links, forms, and other content for toggling -->
	<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
	<ul class="nav navbar-nav navbar-right main-nav">
	<li><a href="../../docs.html">Documentation</a></li>
	<li><a href="../../community/index.html">Community</a></li>
	<li><a href="../../security/security.html">Security</a></li>
	<li><a href="../../download-ng.html">Downloads</a></li>
	</ul>
	</div>
	<!-- /.navbar-collapse -->
	</div></div>
	</div>
	<!-- /.container-fluid -->
	</nav>


	<div id="main-block" class="container main-block">
	<div class="row title">
	<div class="col-md-12">
	<div class='page-header'>

	<h1>@AccessTimeout Annotation</h1>
	</div>
	</div>
	</div>
	<div class="row">

	<div class="col-md-12">
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph">
	<p>Before taking a look at <code>@AccessTimeout</code>, it might help to see when a caller might have to "wait"</p>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="_waiting">Waiting</h2>
	<div class="sectionbody">
	<div class="sect2">
	<h3 id="_stateful_bean">Stateful Bean</h3>
	<div class="admonitionblock note">
	<table>
	<tr>
	<td class="icon">
	<i class="fa icon-note" title="Note"></i>
	</td>
	<td class="content">
	By default, clients are allowed to make concurrent calls to a stateful session object and the container is required to serialize such concurrent requests. The container never permits multi-threaded access to the stateful session bean instance. For this reason, Read/Write method locking metadata, as well as the bean-managed concurrency mode, are not applicable to stateful session beans and must not be used.
	</td>
	</tr>
	</table>
	</div>
	<div class="paragraph">
	<p>This means that when a method <code>foo()</code> of a stateful bean instance is being executed and a second request comes in for that method or another method, EJB container would serialize the second request. It would not let the method be executed concurrently but wait until the first request is processed.</p>
	</div>
	<div class="paragraph">
	<p>The client would wait also when <code>@Stateful</code> bean is in a transaction and the client is invoking it from outside that transaction.</p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_stateless_bean">Stateless Bean</h3>
	<div class="paragraph">
	<p>If there are 20 instances of a bean in the pool and all of them are busy. When the next request comes in, the processing <strong>might wait</strong> for a bean to be available in the pool. (Note: Pooling sematics, if any, are not covered by the spec. The vendor’s pooling semantics might or might not involve a wait condition)</p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_singleton_bean">Singleton Bean</h3>
	<div class="paragraph">
	<p>The container enforces a single-threaded access by default to singleton beans. That’s the equivalent of annotating with <code>@Lock(Write)</code>. So when a <code>@Lock(Write)</code> method is executing, all other <code>@Lock(READ)</code> and <code>@Lock(WRITE)</code> method invocations would have to wait.</p>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_summary">Summary</h3>
	<div class="ulist">
	<ul>
	<li>
	<p><code>@Singleton</code> - an <code>@Lock(WRITE)</code> method is being invoked and container-managed concurrency is being used. All methods are <code>@Lock(WRITE)</code> by default.</p>
	</li>
	<li>
	<p><code>@Stateful</code> - any method of the instance is being invoked and a second invocation occurs. OR the <code>@Stateful</code> bean is in a transaction and the caller is invoking it from outside that transaction.</p>
	</li>
	<li>
	<p><code>@Stateless</code> - no instances are available in the pool. As noted, however, pooling sematics, if any, are not covered by the spec. If the vendor’s pooling semantics do involve a wait condition, the @AccessTimeout should apply.</p>
	</li>
	</ul>
	</div>
	</div>
	</div>
	</div>
	<h1 id="__accesstimeout" class="sect0">@AccessTimeout</h1>
	<div class="paragraph">
	<p>The <code>@AccessTimeout</code> is simply a convenience wrapper around the <code>long</code> and <code>TimeUnit</code> tuples commonly used in the <code>java.util.concurrent</code> API.</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlight"><code class="language-java" data-lang="java">import java.util.concurrent.TimeUnit;
	@Target({METHOD, TYPE})
	@Retention(RUNTIME)
	public @interface AccessTimeout {
	long value();
	TimeUnit unit() default TimeUnit.MILLISECONDS;
	}</code></pre>
	</div>
	</div>
	<div class="sect1">
	<h2 id="_usage">Usage</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>A method or class can be annotated with <code>@AccessTimeout</code> to specify the maximum time a call might wait for access to the bean should a wait condition occur.</p>
	</div>
	<div class="paragraph">
	<p>The semantics of the value element are as follows:</p>
	</div>
	<div class="ulist">
	<ul>
	<li>
	<p>A <code>value</code> > 0 indicates a timeout value in the units specified by the <code>unit</code> element.</p>
	</li>
	<li>
	<p>A <code>value</code> of 0 means concurrent access is not permitted.</p>
	</li>
	<li>
	<p>A <code>value</code> of -1 indicates that the client request will block indefinitely until forward progress can proceed.</p>
	</li>
	</ul>
	</div>
	<div class="paragraph">
	<p>Just as simple as that !</p>
	</div>
	<div class="admonitionblock note">
	<table>
	<tr>
	<td class="icon">
	<i class="fa icon-note" title="Note"></i>
	</td>
	<td class="content">
	What exception would the client receive, with a timeout ?
	Quoting from the spec, "if a client-invoked business method is in progress on an instance when another client-invoked call, from the same or different client, arrives at the same instance of a stateful session bean, if the second client is a client of the bean’s business interface or no-interface view, the concurrent invocation must result in the second client receiving a jakarta.ejb.ConcurrentAccessException[15]. If the EJB 2.1 client view is used, the container must throw a java.rmi.RemoteException if the second client is a remote client, or a jakarta.ejb.EJBException if the second client is a local client"
	</td>
	</tr>
	</table>
	</div>
	<div class="sect2">
	<h3 id="_no_standard_default">No standard default</h3>
	<div class="paragraph">
	<p>Note that the <code>value</code> attribute has no default. This was intentional and intended to communicate that if <code>@AccessTimeout</code> is not explicitly used, the behavior you get is vendor-specific.</p>
	</div>
	<div class="paragraph">
	<p>Some vendors will wait for a preconfigured time and throw <code>jakarta.ejb.ConcurrentAccessException</code>, some vendors will throw it immediately.</p>
	</div>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="_example">Example</h2>
	<div class="sectionbody">
	<div class="paragraph">
	<p>Here we have a simple @Singleton bean that has three synchronous methods and one <code>@Asynchronous</code> method. The bean itself is annotated <code>@Lock(WRITE)</code> so that only one thread may access the <code>@Singleton</code> at a time. This is the default behavior of an <code>@Singleton</code> bean, so explicit usage of <code>@Lock(WRITE)</code> is not needed but is rather nice for clarity as the single-threaded nature of the bean is important to the example.</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlight"><code class="language-java" data-lang="java">@Singleton
	@Lock(WRITE)
	public class BusyBee {

	@Asynchronous
	public Future stayBusy(CountDownLatch ready) {
	ready.countDown();

	try {
	new CountDownLatch(1).await();
	} catch (InterruptedException e) {
	Thread.interrupted();
	}

	return null;
	}

	@AccessTimeout(0)
	public void doItNow() {
	// do something
	}

	@AccessTimeout(value = 5, unit = TimeUnit.SECONDS)
	public void doItSoon() {
	// do something
	}

	@AccessTimeout(-1)
	public void justDoIt() {
	// do something
	}
	}</code></pre>
	</div>
	</div>
	<div class="paragraph">
	<p>The <code>@Asynchronous</code> method is not a critical part of <code>@AccessTimeout</code>, but serves as a simple way to "lock" the bean for testing purposes. It allows us to easily test the concurrent behavior of the bean.</p>
	</div>
	<div class="listingblock">
	<div class="content">
	<pre class="highlight"><code class="language-java" data-lang="java">public class BusyBeeTest extends TestCase {

	public void test() throws Exception {

	final Context context = EJBContainer.createEJBContainer().getContext();

	final CountDownLatch ready = new CountDownLatch(1);

	final BusyBee busyBee = (BusyBee) context.lookup("java:global/access-timeout/BusyBee");

	// This asynchronous method will never exit
	busyBee.stayBusy(ready);

	// Are you working yet little bee?
	ready.await();


	// OK, Bee is busy


	{ // Timeout Immediately
	final long start = System.nanoTime();

	try {
	busyBee.doItNow();

	fail("The bee should be busy");
	} catch (Exception e) {
	// the bee is still too busy as expected
	}

	assertEquals(0, seconds(start));
	}

	{ // Timeout in 5 seconds
	final long start = System.nanoTime();

	try {
	busyBee.doItSoon();

	fail("The bee should be busy");
	} catch (Exception e) {
	// the bee is still too busy as expected
	}

	assertEquals(5, seconds(start));
	}

	// This will wait forever, give it a try if you have that long
	//busyBee.justDoIt();
	}

	private long seconds(long start) {
	return TimeUnit.NANOSECONDS.toSeconds(System.nanoTime() - start);
	}
	}</code></pre>
	</div>
	</div>
	</div>
	</div>
	<div class="sect1">
	<h2 id="_running">Running</h2>
	<div class="sectionbody">
	<div class="listingblock">
	<div class="content">
	<pre class="highlight"><code class="language-bash" data-lang="bash">mvn clean test</code></pre>
	</div>
	</div>
	<div class="sect2">
	<h3 id="_output">Output</h3>
	<div class="listingblock">
	<div class="content">
	<pre class="highlight"><code class="language-bash" data-lang="bash">-------------------------------------------------------
	T E S T S
	-------------------------------------------------------
	Running org.superbiz.accesstimeout.BusyBeeTest
	Apache OpenEJB 4.0.0-beta-1 build: 20111002-04:06
	http://tomee.apache.org/
	INFO - openejb.home = /Users/dblevins/examples/access-timeout
	INFO - openejb.base = /Users/dblevins/examples/access-timeout
	INFO - Using 'jakarta.ejb.embeddable.EJBContainer=true'
	INFO - Configuring Service(id=Default Security Service, type=SecurityService, provider-id=Default Security Service)
	INFO - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager)
	INFO - Found EjbModule in classpath: /Users/dblevins/examples/access-timeout/target/classes
	INFO - Beginning load: /Users/dblevins/examples/access-timeout/target/classes
	INFO - Configuring enterprise application: /Users/dblevins/examples/access-timeout
	INFO - Configuring Service(id=Default Singleton Container, type=Container, provider-id=Default Singleton Container)
	INFO - Auto-creating a container for bean BusyBee: Container(type=SINGLETON, id=Default Singleton Container)
	INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container)
	INFO - Auto-creating a container for bean org.superbiz.accesstimeout.BusyBeeTest: Container(type=MANAGED, id=Default Managed Container)
	INFO - Enterprise application "/Users/dblevins/examples/access-timeout" loaded.
	INFO - Assembling app: /Users/dblevins/examples/access-timeout
	INFO - Jndi(name="java:global/access-timeout/BusyBee!org.superbiz.accesstimeout.BusyBee")
	INFO - Jndi(name="java:global/access-timeout/BusyBee")
	INFO - Jndi(name="java:global/EjbModule748454644/org.superbiz.accesstimeout.BusyBeeTest!org.superbiz.accesstimeout.BusyBeeTest")
	INFO - Jndi(name="java:global/EjbModule748454644/org.superbiz.accesstimeout.BusyBeeTest")
	INFO - Created Ejb(deployment-id=org.superbiz.accesstimeout.BusyBeeTest, ejb-name=org.superbiz.accesstimeout.BusyBeeTest, container=Default Managed Container)
	INFO - Created Ejb(deployment-id=BusyBee, ejb-name=BusyBee, container=Default Singleton Container)
	INFO - Started Ejb(deployment-id=org.superbiz.accesstimeout.BusyBeeTest, ejb-name=org.superbiz.accesstimeout.BusyBeeTest, container=Default Managed Container)
	INFO - Started Ejb(deployment-id=BusyBee, ejb-name=BusyBee, container=Default Singleton Container)
	INFO - Deployed Application(path=/Users/dblevins/examples/access-timeout)
	Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.071 sec

	Results :

	Tests run: 1, Failures: 0, Errors: 0, Skipped: 0</code></pre>
	</div>
	</div>
	</div>
	</div>
	</div>
	</div>

	</div>
	</div>
	<footer>
	<div class="container">
	<div class="row">
	<div class="col-sm-6 text-center-mobile">
	<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
	<h5 class="light regular light-white">"A good application in a good server"</h5>
	<ul class="social-footer">
	<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
	<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
	<li><a href="https://plus.google.com/communities/105208241852045684449"><i class="fa fa-google-plus"></i></a></li>
	</ul>
	</div>
	<div class="col-sm-6 text-center-mobile">
	<div class="row opening-hours">
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../../latest/docs/" class="white">Documentation</a></h5>
	<ul class="list-unstyled">
	<li><a href="../../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
	<li><a href="../../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
	<li><a href="../../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
	<li><a href="../../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../../latest/examples/" class="white">Examples</a></h5>
	<ul class="list-unstyled">
	<li><a href="../../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
	<li><a href="../../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
	<li><a href="../../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
	<li><a href="../../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../../community/index.html" class="white">Community</a></h5>
	<ul class="list-unstyled">
	<li><a href="../../community/contributors.html" class="regular light-white">Contributors</a></li>
	<li><a href="../../community/social.html" class="regular light-white">Social</a></li>
	<li><a href="../../community/sources.html" class="regular light-white">Sources</a></li>
	</ul>
	</div>
	<div class="col-sm-3 text-center-mobile">
	<h5><a href="../../security/index.html" class="white">Security</a></h5>
	<ul class="list-unstyled">
	<li><a href="http://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
	<li><a href="http://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
	<li><a href="http://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
	</ul>
	</div>
	</div>
	</div>
	</div>
	<div class="row bottom-footer text-center-mobile">
	<div class="col-sm-12 light-white">
	<p>Copyright © 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
	</div>
	</div>
	</div>
	</footer>
	<!-- Holder for mobile navigation -->
	<div class="mobile-nav">
	<ul>
	<li><a hef="../../latest/docs/admin/index.html">Administrators</a>
	<li><a hef="../../latest/docs/developer/index.html">Developers</a>
	<li><a hef="../../latest/docs/advanced/index.html">Advanced</a>
	<li><a hef="../../community/index.html">Community</a>
	</ul>
	<a href="#" class="close-link"><i class="arrow_up"></i></a>
	</div>
	<!-- Scripts -->
	<script src="../../js/jquery-1.11.1.min.js"></script>
	<script src="../../js/owl.carousel.min.js"></script>
	<script src="../../js/bootstrap.min.js"></script>
	<script src="../../js/wow.min.js"></script>
	<script src="../../js/typewriter.js"></script>
	<script src="../../js/jquery.onepagenav.js"></script>
	<script src="../../js/tree.jquery.js"></script>
	<script src="../../js/highlight.pack.js"></script>
	<script src="../../js/main.js"></script>
	</body>

	</html>