svn commit: r1195113 - /openejb/trunk/openejb/examples/access-timeout/README.md

[db...@apache.org]

Author: dblevins
Date: Sun Oct 30 04:22:05 2011
New Revision: 1195113

URL: http://svn.apache.org/viewvc?rev=1195113&view=rev
Log:
Patch from Vishwanath, OPENEJB-1638: Examples documentation
Thanks, Vishwanath!

Modified:
    openejb/trunk/openejb/examples/access-timeout/README.md

Modified: openejb/trunk/openejb/examples/access-timeout/README.md
URL: http://svn.apache.org/viewvc/openejb/trunk/openejb/examples/access-timeout/README.md?rev=1195113&r1=1195112&r2=1195113&view=diff
==============================================================================
--- openejb/trunk/openejb/examples/access-timeout/README.md (original)
+++ openejb/trunk/openejb/examples/access-timeout/README.md Sun Oct 30 04:22:05 2011
@@ -1,11 +1,32 @@
 Title: @AccessTimeout annotation
 
-In a general sense this annotation portably specifies up to how long a caller will wait if a wait condition occurs with concurrent access.  Specific to each bean type, wait conditions will occur when:
+Before taking a look at `@AccessTimeout`, it might help to see when a caller might have to "wait"
+
+## Waiting
+
+###Stateful Bean
+>By default, clients are allowed to make concurrent calls to a stateful session object and the container is required to serialize such concurrent requests. Note that the container never permits multi-threaded access to the actual 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.
+
+This means that when a method `foo()` 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.
+
+The client would wait also when `@Stateful` bean is in a transaction and the client is invoking it from outside that transaction.
+
+###Stateless Bean
+
+Say there are 20 instances of a bean in the pool and all of them are busy. Now when the next request comes in, the processing *might wait* 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)
+
+###Singleton Bean
+
+The container enforces a single-threaded access by default to singleton beans. That's the equivalent of annotating with `@Lock(Write)`. So when a `@Lock(Write)` method is executing, all other `@Lock(READ)` and `@Lock(WRITE)` method invocations would have to wait.
+
+### Summary
 
  - `@Singleton` - an `@Lock(WRITE)` method is being invoked and container-managed concurrency is being used.  All methods are `@Lock(WRITE)` by default.
- - `@Stateful` - any method of the instance is being invoked and a second invocation occurs.  OR the @Stateful bean is in a transaction and the caller is invoking it from outside that transaction.
+ - `@Stateful` - any method of the instance is being invoked and a second invocation occurs.  OR the `@Stateful` bean is in a transaction and the caller is invoking it from outside that transaction.
  - `@Stateless` - 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.
 
+# @AccessTimeout
+
 The `@AccessTimeout` is simply a convenience wrapper around the `long` and `TimeUnit` tuples commonly used in the `java.util.concurrent` API.
 
     import java.util.concurrent.TimeUnit;
@@ -16,19 +37,26 @@ The `@AccessTimeout` is simply a conveni
         TimeUnit unit() default TimeUnit.MILLISECONDS;
     }
 
-When explicitly set on a bean class or method, it has three possible meanings:
+## Usage
 
- - `@AccessTimeout(-1)` - Never timeout, wait as long as it takes.  Potentially forever.
- - `@AccessTimeout(0)` - Never wait. Immediately throw `ConcurrentAccessException` if a wait condition would have occurred.
- - `@AccessTimout(30, TimeUnit.SECONDS)` - Wait up to 30 seconds if a wait condition occurs.  After that, throw `ConcurrentAccessTimeoutExcpetion`
+A method or class can be annotated with @AccessTimeout to specify the maximum time a call might wait for access to the bean wait should a wait condition occur.
 
-## No standard default
+The semantics of the value element are as follows:
 
-Note that the `value` attribute has no default.  This was intentional and intended to communicate that if `@AccessTimeout` is not explicitly used, the behavior you get is vendor-specific.
+ - A `value` > 0 indicates a timeout value in the units specified by the `unit` element.
+ - A `value` of 0 means concurrent access is not permitted.
+ - A `value` of -1 indicates that the client request will block indefinitely until forward progress it can proceed.
+
+Just as simple as that !
 
-Some vendors will wait for a preconfigured time and throw `javax.ejb.ConcurrentAccessException`, some vendors will throw it immediately.  When we were defining this annotation it became clear that all of us vendors were doing things a bit differently and enforcing a default would cause problems for existing apps.
+###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 javax.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 javax.ejb.EJBException if the second client is a local client"
+
+### No standard default
+
+Note that the `value` attribute has no default.  This was intentional and intended to communicate that if `@AccessTimeout` is not explicitly used, the behavior you get is vendor-specific.
 
-On a similar note, prior to EJB 3.0 there was no default transaction attribute and it was different for every vendor.  Thank goodness EJB 3.0 was different enough that we could finally say, "For EJB 3.0 beans the default is REQUIRED."
+Some vendors will wait for a preconfigured time and throw `javax.ejb.ConcurrentAccessException`, some vendors will throw it immediately.
 
 # Example