http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/access-timeout-meta.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/access-timeout-meta.adoc b/src/main/jbake/content/examples/access-timeout-meta.adoc new file mode 100755 index 0000000..345b7c3 --- /dev/null +++ b/src/main/jbake/content/examples/access-timeout-meta.adoc @@ -0,0 +1,291 @@ += @AccessTimeout the Meta-Annotation Way +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example access-timeout-meta can be browsed at https://github.com/apache/tomee/tree/master/examples/access-timeout-meta + + +Any annotation that takes parameters can benefit from meta-annotations. Here we see how `@AccessTimeout` can be far more understandable and manageable through meta-annotations. +We'll use the link:access-timeout.html[access-timeout] example as our use-case. + +The value of the parameters supplied to `@AccessTimeout` have a dramatic affect on how what that annotation actually does. Moreover, `@AccessTimeout` has one of those designs +where `-1` and `0` have signifcantly different meanings. One means "wait forever", the other means "never wait". Only a lucky few can remember which is which on a daily basis. +For the rest of us it is a constant source of bugs. + +Meta-Annotations to the rescue! + += Creating the Meta-Annotations + +As a matter of best-practices, we will put our meta-annotations in a package called `api`, for this example that gives us `org.superbiz.accesstimeout.api`. The package `org.superbiz.api` would work just as well. + +The basic idea is to have a package where "approved' annotations are used and to prohibit usage of the non-meta versions of the annotations. All the real configuration will +then be centralized in the `api` package and changes to timeout values will be localized to that package and automatically be reflected throuhout the application. + +An interesting side-effect of this approach is that if the `api` package where the meta-annotation definitions exist is kept in a separate jar as well, then one can effectively +change the configuration of an entire application by simply replacing the `api` jar. + +== @Metatype <small>The "root" Meta-Annotation</small> + +As with all meta-annotation usage, you first need to create your own "root" meta-annotation. This is as easy as creating an annotation +named `Metatype` that is annotated with itself and has `ElementType.ANNOTATION_TYPE` as its target. + + + +[source,java] +---- +package org.superbiz.accesstimeout.api; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Metatype +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.ANNOTATION_TYPE) +public @interface Metatype { +} +---- + + +== @AwaitNever + +When the `@AccessTimeout` annotation has the value of `0` that has the implication that one should never wait to access the bean. If the bean is busy, the caller will immediately +receive an `ConcurrentAccessException`. This is hard to remember and definitely not self-documenting for those that never knew the details. + +To create a meta-annotation version of `@AccessTimeout(0)` we simply need to think of a good annotation name, create that annotation, and annotate it with both `@AccessTimeout` +and `@Metatype` + + +[source,java] +---- +package org.superbiz.accesstimeout.api; + +import javax.ejb.AccessTimeout; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Metatype +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) + +@AccessTimeout(0) +public @interface AwaitNever { +} +---- + + +== @AwaitForever + +Just as `0` carries the special meaning of "never wait", a value of `-1` means "wait forever." + +As long as we're being picky, which we can be with meta-annotations, +Technically "wait forever" is not the best description. The actual methods of the `javax.util.concurrent` APIs use "await" rather than "wait". One (wait) perphaps implies a +command to wait, which this is not, and the other (await) perhaps better implies that waiting is possible but not a certainty. So we will use "await" in our annotation names. + +We make our own `@AwaitForever` and annotate it with `@AccessTimeout(0)` and `@Metatype` + + +[source,java] +---- +package org.superbiz.accesstimeout.api; + +import javax.ejb.AccessTimeout; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +@Metatype +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) + +@AccessTimeout(-1) +public @interface AwaitForever { +} +---- + + +== @AwaitBriefly + +Non `-1` and `0` values to `@AccessTimeout` actually involve the full breadth of the annotation. Here is where you get to specify the maximum number minutes, seconds, +milliseconds, etc. where one might await access to the bean instance. + + +[source,java] +---- +@Metatype +@Retention(RetentionPolicy.RUNTIME) +@Target({ElementType.METHOD, ElementType.TYPE}) + +@AccessTimeout(value = 5, unit = TimeUnit.SECONDS) +public @interface AwaitBriefly { +} +---- + + += Configuration vs Operation + +Once you create a few meta-annotations and the fun becomes common-place, questoins start to raise in your mind on how to best get the benefits of meta-annotations. + +You have to really start thinking about how you want to approach your usage of meta-annotation and really put your designer hat on. The fundamental question is +**configuration vs operation** and the answer is subjective; how much flexibility do you want to design into your applications and where? + +== Configuration names <small>describing the configuration</small> + +The simplest approach is to name your meta-annotations after the **configuration** they encapsulate. We've been following that format so far with `@AwaitNever` and `@AwaitForever` +to clearly reflect the contents of each meta-annotation (`@AccessTimeout(-1)` and `@AccessTimeout(0)` respectively). + +The **cons** of this approach is that should you want to change the configuration of the application by only changing the meta-annotations -- this is one of the potential benefits +of meta-annotations. Certainly, the `@AwaitNever` meta-annotation can have no other value than `0` if it is to live up to its name. + +== Operation names <small>describing the code</small> + +The alternate approach is to name your meta-annotations after the **operations** they apply to. In short, to describe the code itself and not the configuration. So, names like +`@OrderCheckTimeout` or `@TwitterUpdateTimeout`. These names are configuration-change-proof. They would not change if the configuration changes and in fact they can facilitate +finder-grained control over the configuration of an application. + +The **cons** are of course it is requires far more deliberation and consideration, not to mention more annotations. Your skills as an architect, designer and ability to think as +a administrator will be challenged. You must be good at wearing your dev-opts hat. + +== Pragmatism <small>best of both worlds</small> + +Fortunately, meta-annotations are recursive. You can do a little of both. + + +[source,java] +---- +@Metatype +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) + +@AwaitBriefly +public @interface TwitterUpdateTimeout { +} +---- + + +Of course you still need to be very deliberate on how your annotations are used. When using a "configuration" named meta-annotation in code it can help to say to yourself, +"I do not want to reconfigure this later." If that doesn't feel quite right, put the extra effort into creating an operation named annotation and use in that code. + += Applying the Meta-Annotations + +Putting it all together, here's how we might apply our meta-annotations to the link:access-timeout.html[access-timeout] example. + +== Before + + +[source,java] +---- +package org.superbiz.accesstimeout; + +import javax.ejb.AccessTimeout; +import javax.ejb.Asynchronous; +import javax.ejb.Lock; +import javax.ejb.Singleton; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Future; +import java.util.concurrent.TimeUnit; + +import static javax.ejb.LockType.WRITE; + +/** + * @version $Revision$ $Date$ + */ +@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 + } + +} +---- + + +== After + + +[source,java] +---- +package org.superbiz.accesstimeout; + +import org.superbiz.accesstimeout.api.AwaitBriefly; +import org.superbiz.accesstimeout.api.AwaitForever; +import org.superbiz.accesstimeout.api.AwaitNever; + +import javax.ejb.Asynchronous; +import javax.ejb.Lock; +import javax.ejb.Singleton; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.Future; + +import static javax.ejb.LockType.WRITE; + +/** + * @version $Revision$ $Date$ + */ +@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; + } + + @AwaitNever + public void doItNow() { + // do something + } + + @AwaitBriefly + public void doItSoon() { + // do something + } + + @AwaitForever + public void justDoIt() { + // do something + } + +} +---- +
http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/access-timeout.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/access-timeout.adoc b/src/main/jbake/content/examples/access-timeout.adoc new file mode 100755 index 0000000..8adbf40 --- /dev/null +++ b/src/main/jbake/content/examples/access-timeout.adoc @@ -0,0 +1,225 @@ += @AccessTimeout annotation +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example access-timeout can be browsed at https://github.com/apache/tomee/tree/master/examples/access-timeout + + +Before taking a look at `@AccessTimeout`, it might help to see when a caller might have to "wait" + +== Waiting + +=== Stateful Bean + +NOTE: 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. + - `@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. + + +[source,java] +---- +import java.util.concurrent.TimeUnit; +@Target({METHOD, TYPE}) +@Retention(RUNTIME) +public @interface AccessTimeout { + long value(); + TimeUnit unit() default TimeUnit.MILLISECONDS; +} +---- + + +== Usage + +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. + +The semantics of the value element are as follows: + + - 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 ! + +=== 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. + +Some vendors will wait for a preconfigured time and throw `javax.ejb.ConcurrentAccessException`, some vendors will throw it immediately. + += Example + +Here we have a simple @Singleton bean that has three synchronous methods and one `@Asynchronous` method. The bean itself is annotated `@Lock(WRITE)` so that only one thread may access the `@Singleton` at a time. This is the default behavior of an `@Singleton` bean, so explicit usage of `@Lock(WRITE)` is not needed but is rather nice for clarity as the single-threaded nature of the bean is important to the example. + + +[source,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 + } + +} +---- + + +The `@Asynchronous` method is not a critical part of `@AccessTimeout`, 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. + + +[source,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); + } +} +---- + + + += Running + + + +[source] +---- +------------------------------------------------------- + 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 'javax.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 +---- + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/alternate-descriptors.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/alternate-descriptors.adoc b/src/main/jbake/content/examples/alternate-descriptors.adoc new file mode 100755 index 0000000..6946ce0 --- /dev/null +++ b/src/main/jbake/content/examples/alternate-descriptors.adoc @@ -0,0 +1,177 @@ += Alternate Descriptors +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example alternate-descriptors can be browsed at https://github.com/apache/tomee/tree/master/examples/alternate-descriptors + + +See the link:../../alternate-descriptors.html[Alternate Descriptors] page for the full details of how this feature works. + +For our example we'll use the standard "moviefun" code which contains a `Movie` entity and `Movies` session bean. To add a twist +for testing and demonstrate alternate descriptors, we will create an interceptor that will be used only in our test cases. + +To add this to our application, we simply need a `test.ejb-jar.xml` in the same location that the regular `ejb-jar.xml` would be expected. + +That gives us the following files in our project: + + - src/main/resources/META-INF/ejb-jar.xml + - src/main/resources/META-INF/persistence.xml + - src/main/resources/META-INF/test.ejb-jar.xml + +== The test.ejb-jar.xml + +The normal `ejb-jar.xml` simply contains `<ejb-jar/>`, however the `test.ejb-jar.xml` we add an extra interceptor: + + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> +<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee";> + <assembly-descriptor> + <interceptor-binding> + <ejb-name>Movies</ejb-name> + <interceptor-class>org.superbiz.altdd.MoviesTest$Interceptor</interceptor-class> + </interceptor-binding> + </assembly-descriptor> +</ejb-jar> +---- + + +== The TestCase + +To enable our `test.ejb-jar.xml` in the test case, we simply set the `openejb.altdd.prefix` property when creating the embedded `EJBContainer` + + public class MoviesTest extends TestCase { + + @EJB + private Movies movies; + + @Resource + private UserTransaction userTransaction; + + @PersistenceContext + private EntityManager entityManager; + + public void setUp() throws Exception { + Properties p = new Properties(); + p.put("movieDatabase", "new://Resource?type=DataSource"); + p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver"); + p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); + + p.put("openejb.altdd.prefix", "test"); + + EJBContainer.createEJBContainer(p).getContext().bind("inject", this); + } + + public void test() throws Exception { + + userTransaction.begin(); + + try { + entityManager.persist(new Movie("Quentin Tarantino", "Reservoir Dogs", 1992)); + entityManager.persist(new Movie("Joel Coen", "Fargo", 1996)); + entityManager.persist(new Movie("Joel Coen", "The Big Lebowski", 1998)); + + List<Movie> list = movies.getMovies(); + assertEquals("List.size()", 3, list.size()); + + for (Movie movie : list) { + movies.deleteMovie(movie); + } + + assertEquals("Movies.getMovies()", 0, movies.getMovies().size()); + + } finally { + try { + userTransaction.commit(); + fail("Transaction should have been rolled back"); + } catch (RollbackException e) { + // Good, we don't want to clean up the db + } + } + } + + public static class Interceptor { + + @Resource + private SessionContext sessionContext; + + @AroundInvoke + public Object invoke(InvocationContext context) throws Exception { + + sessionContext.setRollbackOnly(); + + return context.proceed(); + } + } + } + +As noted in link:../../alternate-descriptors.html[the documentation], several prefixes can be used at once. + += Running + + + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running org.superbiz.altdd.MoviesTest +Apache OpenEJB 4.0.0-beta-1 build: 20111002-04:06 +http://tomee.apache.org/ +INFO - openejb.home = /Users/dblevins/examples/alternate-descriptors +INFO - openejb.base = /Users/dblevins/examples/alternate-descriptors +INFO - Using 'javax.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 - Configuring Service(id=movieDatabase, type=Resource, provider-id=Default JDBC Database) +INFO - Found EjbModule in classpath: /Users/dblevins/examples/alternate-descriptors/target/classes +INFO - Beginning load: /Users/dblevins/examples/alternate-descriptors/target/classes +INFO - AltDD ejb-jar.xml -> file:/Users/dblevins/examples/alternate-descriptors/target/classes/META-INF/test.ejb-jar.xml +INFO - Configuring enterprise application: /Users/dblevins/examples/alternate-descriptors +WARN - Method 'lookup' is not available for 'javax.annotation.Resource'. Probably using an older Runtime. +INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container) +INFO - Auto-creating a container for bean Movies: Container(type=STATEFUL, id=Default Stateful Container) +INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container) +INFO - Auto-creating a container for bean org.superbiz.altdd.MoviesTest: Container(type=MANAGED, id=Default Managed Container) +INFO - Configuring PersistenceUnit(name=movie-unit) +INFO - Auto-creating a Resource with id 'movieDatabaseNonJta' of type 'DataSource for 'movie-unit'. +INFO - Configuring Service(id=movieDatabaseNonJta, type=Resource, provider-id=movieDatabase) +INFO - Adjusting PersistenceUnit movie-unit <non-jta-data-source> to Resource ID 'movieDatabaseNonJta' from 'movieDatabaseUnmanaged' +INFO - Enterprise application "/Users/dblevins/examples/alternate-descriptors" loaded. +INFO - Assembling app: /Users/dblevins/examples/alternate-descriptors +INFO - PersistenceUnit(name=movie-unit, provider=org.apache.openjpa.persistence.PersistenceProviderImpl) - provider time 411ms +INFO - Jndi(name="java:global/alternate-descriptors/Movies!org.superbiz.altdd.Movies") +INFO - Jndi(name="java:global/alternate-descriptors/Movies") +INFO - Jndi(name="java:global/EjbModule1893321675/org.superbiz.altdd.MoviesTest!org.superbiz.altdd.MoviesTest") +INFO - Jndi(name="java:global/EjbModule1893321675/org.superbiz.altdd.MoviesTest") +INFO - Created Ejb(deployment-id=Movies, ejb-name=Movies, container=Default Stateful Container) +INFO - Created Ejb(deployment-id=org.superbiz.altdd.MoviesTest, ejb-name=org.superbiz.altdd.MoviesTest, container=Default Managed Container) +INFO - Started Ejb(deployment-id=Movies, ejb-name=Movies, container=Default Stateful Container) +INFO - Started Ejb(deployment-id=org.superbiz.altdd.MoviesTest, ejb-name=org.superbiz.altdd.MoviesTest, container=Default Managed Container) +INFO - Deployed Application(path=/Users/dblevins/examples/alternate-descriptors) +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.569 sec + +Results : + +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +---- + + += Warning on Tooling + +If you split your descriptors into separate directories, this support will not work. Specifically, this will not work: + + - src/main/resources/META-INF/ejb-jar.xml + - src/main/resources/META-INF/persistence.xml + - src/**test**/resources/META-INF/test.ejb-jar.xml + +This support is **not** aware of any Maven, Gradle, Ant, IntelliJ, NetBeans, Eclipse or other settings. + + + + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/applet.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/applet.adoc b/src/main/jbake/content/examples/applet.adoc new file mode 100755 index 0000000..b3bba7d --- /dev/null +++ b/src/main/jbake/content/examples/applet.adoc @@ -0,0 +1,196 @@ += Applet +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example applet can be browsed at https://github.com/apache/tomee/tree/master/examples/applet + + +*Help us document this example! Click the blue pencil icon in the upper right to edit this page.* + +== Calculator + + +[source,java] +---- +package org.superbiz.applet; + +import javax.ejb.Remote; + +@Remote +public interface Calculator { + public double add(double x, double y); +} +---- + + +== CalculatorApplet + + +[source,java] +---- +package org.superbiz.applet; + +import javax.naming.Context; +import javax.naming.InitialContext; +import javax.naming.NamingException; +import javax.rmi.PortableRemoteObject; +import javax.swing.JApplet; +import javax.swing.JButton; +import javax.swing.JLabel; +import javax.swing.JTextArea; +import javax.swing.JTextField; +import javax.swing.SwingUtilities; +import java.awt.GridLayout; +import java.awt.event.ActionEvent; +import java.awt.event.ActionListener; +import java.util.Properties; + +public class CalculatorApplet extends JApplet { + JTextArea area; + + JTextField field1; + JTextField field2; + JLabel label1; + JLabel label2; + JButton button; + JLabel label3; + Context ctx; + + public void init() { + try { + SwingUtilities.invokeAndWait(new Runnable() { + public void run() { + createUI(); + } + }); + } catch (Exception e) { + System.err.println("createGUI didn't successfully complete"); + } + } + + private void createUI() { + field1 = new JTextField(); + field2 = new JTextField(); + label1 = new JLabel("Enter first number"); + label2 = new JLabel("Enter second number"); + label3 = new JLabel("RESULT="); + button = new JButton("Add"); + + setLayout(new GridLayout(3, 2)); + add(label1); + add(field1); + add(label2); + add(field2); + add(button); + add(label3); + Properties props = new Properties(); + props.put(Context.INITIAL_CONTEXT_FACTORY, + "org.apache.openejb.client.RemoteInitialContextFactory"); + props.put(Context.PROVIDER_URL, "http://127.0.0.1:8080/applet/ejb";); + try { + ctx = new InitialContext(props); + } catch (NamingException e) { + throw new RuntimeException(e); + } + button.addActionListener(new ActionListener() { + + public void actionPerformed(ActionEvent e) { + + try { + final Object ref = ctx.lookup("CalculatorImplRemote"); + Calculator calc = (Calculator) PortableRemoteObject.narrow( + ref, Calculator.class); + String text1 = field1.getText(); + String text2 = field2.getText(); + int num1 = Integer.parseInt(text1); + int num2 = Integer.parseInt(text2); + double result = calc.add(num1, num2); + label3.setText("RESULT=" + result); + } catch (NamingException ex) { + throw new RuntimeException(ex); + } + } + }); + } +} +---- + + +== CalculatorImpl + + +[source,java] +---- +package org.superbiz.applet; + +import javax.ejb.Stateless; + +@Stateless +public class CalculatorImpl implements Calculator { + + public double add(double x, double y) { + return x + y; + } +} +---- + + +== web.xml + + +[source,xml] +---- +<web-app> + <servlet> + <servlet-name>ServerServlet</servlet-name> + <servlet-class>org.apache.openejb.server.httpd.ServerServlet</servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>ServerServlet</servlet-name> + <url-pattern>/ejb/*</url-pattern> + </servlet-mapping> +</web-app> +---- + + + +== JNDILookupTest + + +[source,java] +---- +package org.superbiz; + +import org.junit.Assert; +import org.junit.Test; +import org.superbiz.applet.Calculator; + +import javax.naming.Context; +import javax.naming.InitialContext; +import javax.rmi.PortableRemoteObject; +import java.util.Properties; + + +public class JNDILookupTest { + + @Test + public void test() { + Properties props = new Properties(); + props.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory"); + props.put(Context.PROVIDER_URL, "http://127.0.0.1:8080/tomee/ejb";); + try { + Context ctx = new InitialContext(props); + System.out.println("Found context " + ctx); + final Object ref = ctx.lookup("CalculatorImplRemote"); + Calculator calc = (Calculator) PortableRemoteObject.narrow(ref, Calculator.class); + double result = calc.add(10, 30); + Assert.assertEquals(40, result, 0.5); + } catch (Exception e) { + e.printStackTrace(); + } + } +} +---- + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/application-composer.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/application-composer.adoc b/src/main/jbake/content/examples/application-composer.adoc new file mode 100755 index 0000000..cf32a75 --- /dev/null +++ b/src/main/jbake/content/examples/application-composer.adoc @@ -0,0 +1,180 @@ += Application Composer +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example application-composer can be browsed at https://github.com/apache/tomee/tree/master/examples/application-composer + + +The `org.apache.openejb.junit.ApplicationComposer` is JUnit test runner modeled after the way we've done testing internally in OpenEJB for years (since about 2006). +It involves no classpath scanning at all. If you want something to be in the app, you must build it directly in your testcase. + +With the `ApplicationComposer` you can do identical testing that OpenEJB uses internally, but with limited dependency on OpenEJB itself. The main dependency is on the code +that is used to build the actual applications: + + +[source,xml] +---- +<dependency> + <groupId>org.apache.openejb</groupId> + <artifactId>openejb-jee</artifactId> + <version>4.0.0-beta-1</version> +</dependency> +---- + + += Composing an Application + +The main difference to the embedded `EJBContainer` API is building the application in the test code. This is done with one or more methods in the test case annotated +with `org.apache.openejb.junit.Module` using the following format: + + +[source,java] +---- +@Module +public <return-value> <module-name>() { + +Where **module-name** is the name you wish to use for that module and **return-value** can be any one of the following: + + - java.lang.Class + - java.lang.Class[] + - org.apache.openejb.jee.EjbJar + - org.apache.openejb.jee.EnterpriseBean + - org.apache.openejb.jee.Application + - org.apache.openejb.jee.Connector + - org.apache.openejb.jee.Beans + - org.apache.openejb.jee.jpa.unit.Persistence + - org.apache.openejb.jee.jpa.unit.PersistenceUnit + +# Example + +Used in an actual testcase, that might look like so: + +import junit.framework.TestCase; +import org.apache.openejb.jee.EjbJar; +import org.apache.openejb.jee.StatefulBean; +import org.apache.openejb.jee.jpa.unit.PersistenceUnit; +import org.apache.openejb.junit.ApplicationComposer; +import org.apache.openejb.junit.Configuration; +import org.apache.openejb.junit.Module; +import org.junit.Test; +import org.junit.runner.RunWith; + +import javax.annotation.Resource; +import javax.ejb.EJB; +import javax.persistence.EntityManager; +import javax.persistence.PersistenceContext; +import javax.transaction.UserTransaction; +import java.util.List; +import java.util.Properties; + +@RunWith(ApplicationComposer.class) +public class MoviesTest extends TestCase { + + @EJB + private Movies movies; + + @Resource + private UserTransaction userTransaction; + + @PersistenceContext + private EntityManager entityManager; + + @Module + public PersistenceUnit persistence() { + PersistenceUnit unit = new PersistenceUnit("movie-unit"); + unit.setJtaDataSource("movieDatabase"); + unit.setNonJtaDataSource("movieDatabaseUnmanaged"); + unit.getClazz().add(Movie.class.getName()); + unit.setProperty("openjpa.jdbc.SynchronizeMappings", "buildSchema(ForeignKeys=true)"); + return unit; + } + + @Module + public EjbJar beans() { + EjbJar ejbJar = new EjbJar("movie-beans"); + ejbJar.addEnterpriseBean(new StatefulBean(MoviesImpl.class)); + return ejbJar; + } + + @Configuration + public Properties config() throws Exception { + Properties p = new Properties(); + p.put("movieDatabase", "new://Resource?type=DataSource"); + p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver"); + p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb"); + return p; + } + + @Test + public void test() throws Exception { + + userTransaction.begin(); + + try { + entityManager.persist(new Movie("Quentin Tarantino", "Reservoir Dogs", 1992)); + entityManager.persist(new Movie("Joel Coen", "Fargo", 1996)); + entityManager.persist(new Movie("Joel Coen", "The Big Lebowski", 1998)); + + List<Movie> list = movies.getMovies(); + assertEquals("List.size()", 3, list.size()); + + for (Movie movie : list) { + movies.deleteMovie(movie); + } + + assertEquals("Movies.getMovies()", 0, movies.getMovies().size()); + + } finally { + userTransaction.commit(); + } + } +} +---- + + += Running + + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running org.superbiz.composed.MoviesTest +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 - Configuring Service(id=movieDatabase, type=Resource, provider-id=Default JDBC Database) +INFO - Configuring enterprise application: /Users/dblevins/examples/application-composer/MoviesTest +WARN - Method 'lookup' is not available for 'javax.annotation.Resource'. Probably using an older Runtime. +INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container) +INFO - Auto-creating a container for bean org.superbiz.composed.MoviesTest: Container(type=MANAGED, id=Default Managed Container) +INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container) +INFO - Auto-creating a container for bean MoviesImpl: Container(type=STATEFUL, id=Default Stateful Container) +INFO - Configuring PersistenceUnit(name=movie-unit) +INFO - Auto-creating a Resource with id 'movieDatabaseNonJta' of type 'DataSource for 'movie-unit'. +INFO - Configuring Service(id=movieDatabaseNonJta, type=Resource, provider-id=movieDatabase) +INFO - Adjusting PersistenceUnit movie-unit <non-jta-data-source> to Resource ID 'movieDatabaseNonJta' from 'movieDatabaseUnmanaged' +INFO - Enterprise application "/Users/dblevins/examples/application-composer/MoviesTest" loaded. +INFO - Assembling app: /Users/dblevins/examples/application-composer/MoviesTest +INFO - PersistenceUnit(name=movie-unit, provider=org.apache.openjpa.persistence.PersistenceProviderImpl) - provider time 449ms +INFO - Jndi(name=org.superbiz.composed.MoviesTestLocalBean) --> Ejb(deployment-id=org.superbiz.composed.MoviesTest) +INFO - Jndi(name=global/MoviesTest/EjbModule2027711095/MoviesTest!org.superbiz.composed.MoviesTest) --> Ejb(deployment-id=org.superbiz.composed.MoviesTest) +INFO - Jndi(name=global/MoviesTest/EjbModule2027711095/MoviesTest) --> Ejb(deployment-id=org.superbiz.composed.MoviesTest) +INFO - Jndi(name=MoviesImplLocal) --> Ejb(deployment-id=MoviesImpl) +INFO - Jndi(name=global/MoviesTest/movie-beans/MoviesImpl!org.superbiz.composed.Movies) --> Ejb(deployment-id=MoviesImpl) +INFO - Jndi(name=global/MoviesTest/movie-beans/MoviesImpl) --> Ejb(deployment-id=MoviesImpl) +INFO - Created Ejb(deployment-id=org.superbiz.composed.MoviesTest, ejb-name=MoviesTest, container=Default Managed Container) +INFO - Created Ejb(deployment-id=MoviesImpl, ejb-name=MoviesImpl, container=Default Stateful Container) +INFO - Started Ejb(deployment-id=org.superbiz.composed.MoviesTest, ejb-name=MoviesTest, container=Default Managed Container) +INFO - Started Ejb(deployment-id=MoviesImpl, ejb-name=MoviesImpl, container=Default Stateful Container) +INFO - Deployed Application(path=/Users/dblevins/examples/application-composer/MoviesTest) +INFO - Undeploying app: /Users/dblevins/examples/application-composer/MoviesTest +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.221 sec + +Results : + +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +---- + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/applicationcomposer-jaxws-cdi.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/applicationcomposer-jaxws-cdi.adoc b/src/main/jbake/content/examples/applicationcomposer-jaxws-cdi.adoc new file mode 100755 index 0000000..7116a9f --- /dev/null +++ b/src/main/jbake/content/examples/applicationcomposer-jaxws-cdi.adoc @@ -0,0 +1,9 @@ += applicationcomposer-jaxws-cdi +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example applicationcomposer-jaxws-cdi can be browsed at https://github.com/apache/tomee/tree/master/examples/applicationcomposer-jaxws-cdi + +No README.md yet, be the first to contribute one! http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/applicationexception.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/applicationexception.adoc b/src/main/jbake/content/examples/applicationexception.adoc new file mode 100755 index 0000000..72cdda6 --- /dev/null +++ b/src/main/jbake/content/examples/applicationexception.adoc @@ -0,0 +1,129 @@ += @ApplicationException annotation +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example applicationexception can be browsed at https://github.com/apache/tomee/tree/master/examples/applicationexception + + += Declaring an @ApplicationException + + +[source,java] +---- +import javax.ejb.ApplicationException; + +/** + * @version $Rev: 784112 $ $Date: 2009-06-12 06:23:57 -0700 (Fri, 12 Jun 2009) $ + */ +@ApplicationException(rollback = true) +public abstract class BusinessException extends RuntimeException { +} +---- + + +By default, @ApplicationException is inherited + + +[source,java] +---- +public class ValueRequiredException extends BusinessException { +} +---- + + += In the bean code + + +[source,java] +---- +@Stateless +public class ThrowBusinessExceptionImpl implements ThrowBusinessException { + + public void throwValueRequiredException() throws BusinessException { + throw new ValueRequiredException(); + } + +} +---- + + +Normally throwing a `RuntimeException` would cause the container to both rollback the transaction and destroy the bean instance that threw the exception. + +As `BusinessException` has been annotated `@ApplicationException(rollback = true)` only the transaction rollback will occur and the bean will not get destroyed. + += The TestCase + + +[source,java] +---- +import org.junit.Assert; +import org.junit.Before; +import org.junit.Test; + +import javax.naming.Context; +import javax.naming.InitialContext; +import java.util.Properties; + +public class ThrowBusinessExceptionImplTest { + + private InitialContext initialContext; + + @Before + public void setUp() throws Exception { + Properties properties = new Properties(); + properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory"); + + initialContext = new InitialContext(properties); + } + + @Test(expected = ValueRequiredException.class) + public void testCounterViaRemoteInterface() throws Exception { + Object object = initialContext.lookup("ThrowBusinessExceptionImplRemote"); + + Assert.assertNotNull(object); + Assert.assertTrue(object instanceof ThrowBusinessException); + ThrowBusinessException bean = (ThrowBusinessException) object; + bean.throwValueRequiredException(); + } +} +---- + + += Running + + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running org.superbiz.appexception.ThrowBusinessExceptionImplTest +Apache OpenEJB 4.0.0-beta-1 build: 20111002-04:06 +http://tomee.apache.org/ +INFO - openejb.home = /Users/dblevins/examples/applicationexception +INFO - openejb.base = /Users/dblevins/examples/applicationexception +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/applicationexception/target/classes +INFO - Beginning load: /Users/dblevins/examples/applicationexception/target/classes +INFO - Configuring enterprise application: /Users/dblevins/examples/applicationexception/classpath.ear +INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container) +INFO - Auto-creating a container for bean ThrowBusinessExceptionImpl: Container(type=STATELESS, id=Default Stateless Container) +INFO - Enterprise application "/Users/dblevins/examples/applicationexception/classpath.ear" loaded. +INFO - Assembling app: /Users/dblevins/examples/applicationexception/classpath.ear +INFO - Jndi(name=ThrowBusinessExceptionImplRemote) --> Ejb(deployment-id=ThrowBusinessExceptionImpl) +INFO - Jndi(name=global/classpath.ear/applicationexception/ThrowBusinessExceptionImpl!org.superbiz.appexception.ThrowBusinessException) --> Ejb(deployment-id=ThrowBusinessExceptionImpl) +INFO - Jndi(name=global/classpath.ear/applicationexception/ThrowBusinessExceptionImpl) --> Ejb(deployment-id=ThrowBusinessExceptionImpl) +INFO - Created Ejb(deployment-id=ThrowBusinessExceptionImpl, ejb-name=ThrowBusinessExceptionImpl, container=Default Stateless Container) +INFO - Started Ejb(deployment-id=ThrowBusinessExceptionImpl, ejb-name=ThrowBusinessExceptionImpl, container=Default Stateless Container) +INFO - Deployed Application(path=/Users/dblevins/examples/applicationexception/classpath.ear) +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.434 sec + +Results : + +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +---- + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/arquillian-jpa.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/arquillian-jpa.adoc b/src/main/jbake/content/examples/arquillian-jpa.adoc new file mode 100755 index 0000000..287e933 --- /dev/null +++ b/src/main/jbake/content/examples/arquillian-jpa.adoc @@ -0,0 +1,180 @@ += Arquillian Persistence Extension +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example arquillian-jpa can be browsed at https://github.com/apache/tomee/tree/master/examples/arquillian-jpa + + +A sample showing how to use TomEE, Arquillian and its Persistence Extension. + +Note that it doesn't work with embedded containers (openejb, tomee-embedded) +if you don't use workarounds like https://github.com/rmannibucau/persistence-with-openejb-and-arquillian +(see src/test/resources folder). + += Running (output) + + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running org.superbiz.arquillian.test.persistence.PersistenceTest +oct. 01, 2014 6:30:23 PM org.apache.openejb.arquillian.common.Setup findHome +INFOS: Unable to find home in: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote +oct. 01, 2014 6:30:23 PM org.apache.openejb.arquillian.common.MavenCache getArtifact +INFOS: Downloading org.apache.openejb:apache-tomee:7.0.0-SNAPSHOT:zip:webprofile please wait... +oct. 01, 2014 6:30:23 PM org.apache.openejb.arquillian.common.Zips unzip +INFOS: Extracting '/home/rmannibucau/.m2/repository/org/apache/openejb/apache-tomee/7.0.0-SNAPSHOT/apache-tomee-7.0.0-SNAPSHOT-webprofile.zip' to '/home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote' +oct. 01, 2014 6:30:24 PM org.apache.tomee.arquillian.remote.RemoteTomEEContainer configure +INFOS: Downloaded container to: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote/apache-tomee-webprofile-7.0.0-SNAPSHOT +INFOS - Server version: Apache Tomcat/8.0.14 +INFOS - Server built: Sep 24 2014 09:01:51 +INFOS - Server number: 8.0.14.0 +INFOS - OS Name: Linux +INFOS - OS Version: 3.13.0-35-generic +INFOS - Architecture: amd64 +INFOS - JVM Version: 1.7.0_67-b01 +INFOS - JVM Vendor: Oracle Corporation +INFOS - The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /usr/java/packages/lib/amd64:/usr/lib64:/lib64:/lib:/usr/lib +INFOS - Initializing ProtocolHandler ["http-nio-52256"] +INFOS - Using a shared selector for servlet write/read +INFOS - Initializing ProtocolHandler ["ajp-nio-40071"] +INFOS - Using a shared selector for servlet write/read +INFOS - Using 'openejb.jdbc.datasource-creator=org.apache.tomee.jdbc.TomEEDataSourceCreator' +INFOS - ******************************************************************************** +INFOS - OpenEJB http://tomee.apache.org/ +INFOS - Startup: Wed Oct 01 18:30:26 CEST 2014 +INFOS - Copyright 1999-2013 (C) Apache OpenEJB Project, All Rights Reserved. +INFOS - Version: 7.0.0-SNAPSHOT +INFOS - Build date: 20141001 +INFOS - Build time: 04:53 +INFOS - ******************************************************************************** +INFOS - openejb.home = /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote/apache-tomee-webprofile-7.0.0-SNAPSHOT +INFOS - openejb.base = /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote/apache-tomee-webprofile-7.0.0-SNAPSHOT +INFOS - Created new singletonService org.apache.openejb.cdi.ThreadSingletonServiceImpl@13158bbd +INFOS - Succeeded in installing singleton service +INFOS - openejb configuration file is '/home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote/apache-tomee-webprofile-7.0.0-SNAPSHOT/conf/tomee.xml' +INFOS - Configuring Service(id=Tomcat Security Service, type=SecurityService, provider-id=Tomcat Security Service) +INFOS - Configuring Service(id=Default Transaction Manager, type=TransactionManager, provider-id=Default Transaction Manager) +INFOS - Configuring Service(id=demoDataSource, type=Resource, provider-id=Default JDBC Database) +INFOS - Using 'openejb.system.apps=true' +INFOS - Configuring enterprise application: openejb +INFOS - Using openejb.deploymentId.format '{ejbName}' +INFOS - Auto-deploying ejb openejb/Deployer: EjbDeployment(deployment-id=openejb/Deployer) +INFOS - Auto-deploying ejb openejb/ConfigurationInfo: EjbDeployment(deployment-id=openejb/ConfigurationInfo) +INFOS - Auto-deploying ejb MEJB: EjbDeployment(deployment-id=MEJB) +INFOS - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container) +INFOS - Auto-creating a container for bean openejb/Deployer: Container(type=STATELESS, id=Default Stateless Container) +INFOS - Enterprise application "openejb" loaded. +INFOS - Creating TransactionManager(id=Default Transaction Manager) +INFOS - Creating SecurityService(id=Tomcat Security Service) +INFOS - Creating Resource(id=demoDataSource) +INFOS - Disabling testOnBorrow since no validation query is provided +INFOS - Creating Container(id=Default Stateless Container) +INFOS - Not creating another application classloader for openejb +INFOS - Assembling app: openejb +INFOS - Using 'openejb.jndiname.format={deploymentId}{interfaceType.openejbLegacyName}' +INFOS - Jndi(name=openejb/DeployerBusinessRemote) --> Ejb(deployment-id=openejb/Deployer) +INFOS - Jndi(name=global/openejb/openejb/Deployer!org.apache.openejb.assembler.Deployer) --> Ejb(deployment-id=openejb/Deployer) +INFOS - Jndi(name=global/openejb/openejb/Deployer) --> Ejb(deployment-id=openejb/Deployer) +INFOS - Jndi(name=openejb/ConfigurationInfoBusinessRemote) --> Ejb(deployment-id=openejb/ConfigurationInfo) +INFOS - Jndi(name=global/openejb/openejb/ConfigurationInfo!org.apache.openejb.assembler.classic.cmd.ConfigurationInfo) --> Ejb(deployment-id=openejb/ConfigurationInfo) +INFOS - Jndi(name=global/openejb/openejb/ConfigurationInfo) --> Ejb(deployment-id=openejb/ConfigurationInfo) +INFOS - Jndi(name=MEJB) --> Ejb(deployment-id=MEJB) +INFOS - Jndi(name=global/openejb/MEJB!javax.management.j2ee.ManagementHome) --> Ejb(deployment-id=MEJB) +INFOS - Jndi(name=global/openejb/MEJB) --> Ejb(deployment-id=MEJB) +INFOS - Created Ejb(deployment-id=openejb/Deployer, ejb-name=openejb/Deployer, container=Default Stateless Container) +INFOS - Created Ejb(deployment-id=MEJB, ejb-name=MEJB, container=Default Stateless Container) +INFOS - Created Ejb(deployment-id=openejb/ConfigurationInfo, ejb-name=openejb/ConfigurationInfo, container=Default Stateless Container) +INFOS - Started Ejb(deployment-id=openejb/Deployer, ejb-name=openejb/Deployer, container=Default Stateless Container) +INFOS - Started Ejb(deployment-id=MEJB, ejb-name=MEJB, container=Default Stateless Container) +INFOS - Started Ejb(deployment-id=openejb/ConfigurationInfo, ejb-name=openejb/ConfigurationInfo, container=Default Stateless Container) +INFOS - Deployed MBean(openejb.user.mbeans:application=openejb,group=org.apache.openejb.assembler.monitoring,name=JMXDeployer) +INFOS - Deployed Application(path=openejb) +INFOS - Creating ServerService(id=cxf-rs) +INFOS - ** Bound Services ** +INFOS - NAME IP PORT +INFOS - ------- +INFOS - Ready! +INFOS - Initialization processed in 2589 ms +INFOS - Importing a Tomcat Resource with id 'UserDatabase' of type 'org.apache.catalina.UserDatabase'. +INFOS - Creating Resource(id=UserDatabase) +INFOS - Démarrage du service Catalina +INFOS - Starting Servlet Engine: Apache Tomcat (TomEE)/8.0.14 (7.0.0-SNAPSHOT) +INFOS - Starting ProtocolHandler ["http-nio-52256"] +INFOS - Starting ProtocolHandler ["ajp-nio-40071"] +INFOS - Server startup in 140 ms +oct. 01, 2014 6:30:30 PM org.apache.openejb.client.EventLogger log +INFOS: RemoteInitialContextCreated{providerUri=http://localhost:52256/tomee/ejb} +INFOS - Extracting jar: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest.war +INFOS - Extracted path: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest +INFOS - using default host: localhost +INFOS - ------------------------- localhost -> /UserPersistenceTest +INFOS - Using 'openejb.session.manager=org.apache.tomee.catalina.session.QuickSessionManager' +INFOS - Configuring enterprise application: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest +INFOS - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container) +INFOS - Auto-creating a container for bean UserPersistenceTest_org.superbiz.arquillian.test.persistence.PersistenceTest: Container(type=MANAGED, id=Default Managed Container) +INFOS - Creating Container(id=Default Managed Container) +INFOS - Using directory /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/apache-tomee-remote/apache-tomee-webprofile-7.0.0-SNAPSHOT/temp for stateful session passivation +INFOS - Configuring PersistenceUnit(name=demoApplicationPU) +INFOS - Auto-creating a Resource with id 'demoDataSourceNonJta' of type 'DataSource for 'demoApplicationPU'. +INFOS - Configuring Service(id=demoDataSourceNonJta, type=Resource, provider-id=demoDataSource) +INFOS - Creating Resource(id=demoDataSourceNonJta) +INFOS - Disabling testOnBorrow since no validation query is provided +INFOS - Adjusting PersistenceUnit demoApplicationPU <non-jta-data-source> to Resource ID 'demoDataSourceNonJta' from 'null' +INFOS - Enterprise application "/home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest" loaded. +INFOS - Assembling app: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest +INFOS - OpenJPA dynamically loaded a validation provider. +INFOS - Starting OpenJPA 2.4.0-nonfinal-1598334 +INFOS - Using dictionary class "org.apache.openjpa.jdbc.sql.HSQLDictionary" (HSQL Database Engine 2.3.2 ,HSQL Database Engine Driver 2.3.2). +INFOS - Connected to HSQL Database Engine version 2.2 using JDBC driver HSQL Database Engine Driver version 2.3.2. +INFOS - SELECT SEQUENCE_SCHEMA, SEQUENCE_NAME FROM INFORMATION_SCHEMA.SYSTEM_SEQUENCES --> 0ms +INFOS - CREATE TABLE User (id BIGINT NOT NULL, name VARCHAR(255), PRIMARY KEY (id)) --> 0ms +INFOS - PersistenceUnit(name=demoApplicationPU, provider=org.apache.openjpa.persistence.PersistenceProviderImpl) - provider time 1075ms +INFOS - Existing thread singleton service in SystemInstance(): org.apache.openejb.cdi.ThreadSingletonServiceImpl@13158bbd +INFOS - OpenWebBeans Container is starting... +INFOS - Adding OpenWebBeansPlugin : [CdiPlugin] +INFOS - All injection points were validated successfully. +INFOS - OpenWebBeans Container has started, it took 224 ms. +INFOS - Deployed Application(path=/home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest) +INFOS - At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that were scanned but no TLDs were found in them. Skipping unneeded JARs during scanning can improve startup time and JSP compilation time. +AVERTISSEMENT - Potential problem found: The configured data type factory 'class org.dbunit.dataset.datatype.DefaultDataTypeFactory' might cause problems with the current database 'HSQL Database Engine' (e.g. some datatypes may not be supported properly). In rare cases you might see this message because the list of supported database products is incomplete (list=[derby]). If so please request a java-class update via the forums.If you are using your own IDataTypeFactory extending DefaultDataTypeFactory, ensure that you override getValidDbProducts() to specify the supported database products. +INFOS - insert into USER (ID, NAME) values (1, TomEE) --> 1ms +INFOS - insert into USER (ID, NAME) values (1, 2)TomEE,Old) --> 0ms +INFOS - SELECT COUNT(t0.id) FROM User t0 --> 0ms +INFOS - SELECT t0.name FROM User t0 WHERE t0.id = 2 --> 0ms +INFOS - UPDATE User SET name = OpenEJB WHERE id = 2 --> 1ms +INFOS - select ID, NAME from USER order by ID --> 0ms +INFOS - select ID, NAME from USER order by ID --> 0ms +INFOS - select ID, NAME from USER order by ID --> 0ms +INFOS - select ID, NAME from USER order by ID --> 0ms +INFOS - delete from USER --> 0ms +oct. 01, 2014 6:30:34 PM org.apache.openejb.client.EventLogger log +INFOS: RemoteInitialContextCreated{providerUri=http://localhost:52256/tomee/ejb} +INFOS - Undeploying app: /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0/UserPersistenceTest +oct. 01, 2014 6:30:34 PM org.apache.openejb.arquillian.common.TomEEContainer undeploy +INFOS: cleaning /home/rmannibucau/dev/Apache/tomee-trunk/examples/arquillian-jpa/target/arquillian-test-working-dir/0 +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 11.242 sec +INFOS - A valid shutdown command was received via the shutdown port. Stopping the Server instance. +INFOS - Pausing ProtocolHandler ["http-nio-52256"] +INFOS - Pausing ProtocolHandler ["ajp-nio-40071"] +INFOS - Arrêt du service Catalina +INFOS - Stopping ProtocolHandler ["http-nio-52256"] +INFOS - Stopping ProtocolHandler ["ajp-nio-40071"] +INFOS - Stopping server services +INFOS - Undeploying app: openejb +INFOS - Closing DataSource: demoDataSource +INFOS - Closing DataSource: demoDataSourceNonJta +INFOS - Destroying ProtocolHandler ["http-nio-52256"] +INFOS - Destroying ProtocolHandler ["ajp-nio-40071"] + +Results : + +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +---- + + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/async-methods.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/async-methods.adoc b/src/main/jbake/content/examples/async-methods.adoc new file mode 100755 index 0000000..c4a0527 --- /dev/null +++ b/src/main/jbake/content/examples/async-methods.adoc @@ -0,0 +1,178 @@ += @Asynchronous Methods +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example async-methods can be browsed at https://github.com/apache/tomee/tree/master/examples/async-methods + + +The @Asynchronous annotation was introduced in EJB 3.1 as a simple way of creating asynchronous processing. + +Every time a method annotated `@Asynchronous` is invoked by anyone it will immediately return regardless of how long the method actually takes. Each invocation returns a [Future][1] object that essentially starts out *empty* and will later have its value filled in by the container when the related method call actually completes. Returning a `Future` object is not required and `@Asynchronous` methods can of course return `void`. + += Example + +Here, in `JobProcessorTest`, + +`final Future<String> red = processor.addJob("red");` +proceeds to the next statement, + +`final Future<String> orange = processor.addJob("orange");` + +without waiting for the addJob() method to complete. And later we could ask for the result using the `Future<?>.get()` method like + +`assertEquals("blue", blue.get());` + +It waits for the processing to complete (if its not completed already) and gets the result. If you did not care about the result, you could simply have your asynchronous method as a void method. + +[Future][1] Object from docs, + + +NOTE: A Future represents the result of an asynchronous computation. Methods are provided to check if the computation is complete, to wait for its completion, and to retrieve the result of the computation. The result can only be retrieved using method get when the computation has completed, blocking if necessary until it is ready. Cancellation is performed by the cancel method. Additional methods are provided to determine if the task completed normally or was cancelled. Once a computation has completed, the computation cannot be cancelled. If you would like to use a Future for the sake of cancellability but not provide a usable result, you can declare types of the form Future<?> and return null as a result of the underlying task + + + + += The code + +[source,java] +---- +@Singleton +public class JobProcessor { +@Asynchronous +@Lock(READ) +@AccessTimeout(-1) +public Future<String> addJob(String jobName) { + + // Pretend this job takes a while + doSomeHeavyLifting(); + + // Return our result + return new AsyncResult<String>(jobName); +} +---- + + + private void doSomeHeavyLifting() { + try { + Thread.sleep(SECONDS.toMillis(10)); + } catch (InterruptedException e) { + Thread.interrupted(); + throw new IllegalStateException(e); + } + } + } += Test + +[source,java] +---- +public class JobProcessorTest extends TestCase { + +public void test() throws Exception { + + final Context context = EJBContainer.createEJBContainer().getContext(); + + final JobProcessor processor = (JobProcessor) context.lookup("java:global/async-methods/JobProcessor"); + + final long start = System.nanoTime(); + + // Queue up a bunch of work + final Future<String> red = processor.addJob("red"); + final Future<String> orange = processor.addJob("orange"); + final Future<String> yellow = processor.addJob("yellow"); + final Future<String> green = processor.addJob("green"); + final Future<String> blue = processor.addJob("blue"); + final Future<String> violet = processor.addJob("violet"); + + // Wait for the result -- 1 minute worth of work + assertEquals("blue", blue.get()); + assertEquals("orange", orange.get()); + assertEquals("green", green.get()); + assertEquals("red", red.get()); + assertEquals("yellow", yellow.get()); + assertEquals("violet", violet.get()); + + // How long did it take? + final long total = TimeUnit.NANOSECONDS.toSeconds(System.nanoTime() - start); + + // Execution should be around 9 - 21 seconds + // The execution time depends on the number of threads available for asynchronous execution. + // In the best case it is 10s plus some minimal processing time. + assertTrue("Expected > 9 but was: " + total, total > 9); + assertTrue("Expected < 21 but was: " + total, total < 21); + + } +} +---- + += Running + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running org.superbiz.async.JobProcessorTest +Apache OpenEJB 7.0.0-SNAPSHOT build: 20110801-04:02 +http://tomee.apache.org/ +INFO - openejb.home = G:\Workspace\fullproject\openejb3\examples\async-methods +INFO - openejb.base = G:\Workspace\fullproject\openejb3\examples\async-methods +INFO - Using 'javax.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: g:\Workspace\fullproject\openejb3\examples\async-methods\target\classes +INFO - Beginning load: g:\Workspace\fullproject\openejb3\examples\async-methods\target\classes +INFO - Configuring enterprise application: g:\Workspace\fullproject\openejb3\examples\async-methods +INFO - Configuring Service(id=Default Singleton Container, type=Container, provider-id=Default Singleton Container) +INFO - Auto-creating a container for bean JobProcessor: 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.async.JobProcessorTest: Container(type=MANAGED, id=Default Managed Container) +INFO - Enterprise application "g:\Workspace\fullproject\openejb3\examples\async-methods" loaded. +INFO - Assembling app: g:\Workspace\fullproject\openejb3\examples\async-methods +INFO - Jndi(name="java:global/async-methods/JobProcessor!org.superbiz.async.JobProcessor") +INFO - Jndi(name="java:global/async-methods/JobProcessor") +INFO - Jndi(name="java:global/EjbModule100568296/org.superbiz.async.JobProcessorTest!org.superbiz.async.JobProcessorTest") +INFO - Jndi(name="java:global/EjbModule100568296/org.superbiz.async.JobProcessorTest") +INFO - Created Ejb(deployment-id=org.superbiz.async.JobProcessorTest, ejb-name=org.superbiz.async.JobProcessorTest, container=Default Managed Container) +INFO - Created Ejb(deployment-id=JobProcessor, ejb-name=JobProcessor, container=Default Singleton Container) +INFO - Started Ejb(deployment-id=org.superbiz.async.JobProcessorTest, ejb-name=org.superbiz.async.JobProcessorTest, container=Default Managed Container) +INFO - Started Ejb(deployment-id=JobProcessor, ejb-name=JobProcessor, container=Default Singleton Container) +INFO - Deployed Application(path=g:\Workspace\fullproject\openejb3\examples\async-methods) +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 13.305 sec + +Results : + +Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +---- + + + [INFO] ------------------------------------------------------------------------ + [INFO] BUILD SUCCESS + [INFO] ------------------------------------------------------------------------ + [INFO] Total time: 21.097s + [INFO] Finished at: Wed Aug 03 22:48:26 IST 2011 + [INFO] Final Memory: 13M/145M + [INFO] ------------------------------------------------------------------------ + += How it works <small>under the covers</small> + +Under the covers what makes this work is: + + - The `JobProcessor` the caller sees is not actually an instance of `JobProcessor`. Rather it's a subclass or proxy that has all the methods overridden. Methods that are supposed to be asynchronous are handled differently. + - Calls to an asynchronous method simply result in a `Runnable` being created that wraps the method and parameters you gave. This runnable is given to an [Executor][3] which is simply a work queue attached to a thread pool. + - After adding the work to the queue, the proxied version of the method returns an implementation of `Future` that is linked to the `Runnable` which is now waiting on the queue. + - When the `Runnable` finally executes the method on the *real* `JobProcessor` instance, it will take the return value and set it into the `Future` making it available to the caller. + +Important to note that the `AsyncResult` object the `JobProcessor` returns is not the same `Future` object the caller is holding. It would have been neat if the real `JobProcessor` could just return `String` and the caller's version of `JobProcessor` could return `Future<String>`, but we didn't see any way to do that without adding more complexity. So the `AsyncResult` is a simple wrapper object. The container will pull the `String` out, throw the `AsyncResult` away, then put the `String` in the *real* `Future` that the caller is holding. + +To get progress along the way, simply pass a thread-safe object like [AtomicInteger][4] to the `@Asynchronous` method and have the bean code periodically update it with the percent complete. + += Related Examples + +For complex asynchronous processing, JavaEE's answer is `@MessageDrivenBean`. Have a look at the link:simple-mdb.html[simple-mdb] example + +[1]: http://download.oracle.com/javase/6/docs/api/java/util/concurrent/Future.html +[3]: http://download.oracle.com/javase/6/docs/api/java/util/concurrent/Executor.html +[4]: http://download.oracle.com/javase/6/docs/api/java/util/concurrent/atomic/AtomicInteger.html + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/async-postconstruct.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/async-postconstruct.adoc b/src/main/jbake/content/examples/async-postconstruct.adoc new file mode 100755 index 0000000..c0ee098 --- /dev/null +++ b/src/main/jbake/content/examples/async-postconstruct.adoc @@ -0,0 +1,140 @@ += @Asynchronous @PostConstruct +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example async-postconstruct can be browsed at https://github.com/apache/tomee/tree/master/examples/async-postconstruct + + +Placing `@Asynchronous` on the `@PostConstruct` of an EJB is not a supported part of Java EE, but this example shows a pattern which works just as well with little effort. + +The heart of this pattern is to: + + - pass the construction "logic" to an `@Asynchronous` method via a `java.util.concurrent.Callable` + - ensure the bean does not process invocations till construction is complete via an `@AroundInvoke` method on the bean and the `java.util.concurrent.Future` + +Simple and effective. The result is a faster starting application that is still thread-safe. + + +[source,java] +---- +package org.superbiz.asyncpost; + +import javax.annotation.PostConstruct; +import javax.ejb.EJB; +import javax.ejb.Lock; +import javax.ejb.LockType; +import javax.ejb.Singleton; +import javax.interceptor.AroundInvoke; +import javax.interceptor.InvocationContext; +import java.util.concurrent.Callable; +import java.util.concurrent.Future; + +import static java.util.concurrent.TimeUnit.SECONDS; + +@Singleton +@Lock(LockType.READ) +public class SlowStarter { + + @EJB + private Executor executor; + + private Future construct; + + private String color; + private String shape; + + @PostConstruct + private void construct() throws Exception { + construct = executor.submit(new Callable() { + @Override + public Object call() throws Exception { + Thread.sleep(SECONDS.toMillis(10)); + SlowStarter.this.color = "orange"; + SlowStarter.this.shape = "circle"; + return null; + } + }); + } + + @AroundInvoke + private Object guaranteeConstructionComplete(InvocationContext context) throws Exception { + construct.get(); + return context.proceed(); + } + + public String getColor() { + return color; + } + + public String getShape() { + return shape; + } +} +---- + + + +The `Executor` is a simple pattern, useful for many things, which exposes an interface functionaly equivalent to `java.util.concurrent.ExecutorService`, but +with the underlying thread pool controlled by the container. + + +[source,java] +---- +package org.superbiz.asyncpost; + +import javax.ejb.AsyncResult; +import javax.ejb.Asynchronous; +import javax.ejb.Lock; +import javax.ejb.LockType; +import javax.ejb.Singleton; +import java.util.concurrent.Callable; +import java.util.concurrent.Future; + +@Singleton +@Lock(LockType.READ) +public class Executor { + + @Asynchronous + public <T> Future<T> submit(Callable<T> task) throws Exception { + return new AsyncResult<T>(task.call()); + } + +} +---- + + + +Finally a test case shows the usefulness of `@AroundInvoke` call in our bean that calls `construct.get()` + + +[source,java] +---- +package org.superbiz.asyncpost; + +import junit.framework.Assert; +import org.junit.Test; + +import javax.ejb.EJB; +import javax.ejb.embeddable.EJBContainer; + +public class SlowStarterTest { + + @EJB + private SlowStarter slowStarter; + + @Test + public void test() throws Exception { + + // Start the Container + EJBContainer.createEJBContainer().getContext().bind("inject", this); + + // Immediately access the fields initialized in the PostConstruct + // This will fail without the @AroundInvoke call to construct.get() + Assert.assertEquals("orange", slowStarter.getColor()); + Assert.assertEquals("circle", slowStarter.getShape()); + } +} +---- + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/bean-validation-design-by-contract.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/bean-validation-design-by-contract.adoc b/src/main/jbake/content/examples/bean-validation-design-by-contract.adoc new file mode 100755 index 0000000..e21f0dd --- /dev/null +++ b/src/main/jbake/content/examples/bean-validation-design-by-contract.adoc @@ -0,0 +1,240 @@ += bean-validation-design-by-contract +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example bean-validation-design-by-contract can be browsed at https://github.com/apache/tomee/tree/master/examples/bean-validation-design-by-contract + += Bean Validation - Design By Contract + +Bean Validation (aka JSR 303) contains an optional appendix dealing with method validation. + +Some implementions of this JSR implement this appendix (Apache bval, Hibernate validator for example). + +OpenEJB provides an interceptor which allows you to use this feature to do design by contract. + += Design by contract + +The goal is to be able to configure with a finer grain your contract. In the example you specify +the minimum centimeters a sport man should jump at pole vaulting: + + +[source,java] +---- +@Local +public interface PoleVaultingManager { + int points(@Min(120) int centimeters); +} +---- + + += Usage + +TomEE and OpenEJB do not provide anymore `BeanValidationAppendixInterceptor` since +Bean Validation 1.1 does it (with a slighly different usage but the exact same feature). + +So basically you don't need to configure anything to use it. += Errors + +If a parameter is not validated an exception is thrown, it is an EJBException wrapping a ConstraintViolationException: + + try { + gamesManager.addSportMan("I lose", "EN"); + fail("no space should be in names"); + } catch (EJBException wrappingException) { + assertTrue(wrappingException.getCause() instanceof ConstraintViolationException); + ConstraintViolationException exception = ConstraintViolationException.class.cast(wrappingException.getCausedByException()); + assertEquals(1, exception.getConstraintViolations().size()); + } + += Example + +== OlympicGamesManager + + +[source,java] +---- +package org.superbiz.designbycontract; + +import javax.ejb.Stateless; +import javax.validation.constraints.NotNull; +import javax.validation.constraints.Pattern; +import javax.validation.constraints.Size; + +@Stateless +public class OlympicGamesManager { + public String addSportMan(@Pattern(regexp = "^[A-Za-z]+$") String name, @Size(min = 2, max = 4) String country) { + if (country.equals("USA")) { + return null; + } + return new StringBuilder(name).append(" [").append(country).append("]").toString(); + } +} +---- + + +== PoleVaultingManager + + +[source,java] +---- +package org.superbiz.designbycontract; + +import javax.ejb.Local; +import javax.validation.constraints.Min; + +@Local +public interface PoleVaultingManager { + int points(@Min(120) int centimeters); +} +---- + + +== PoleVaultingManagerBean + + +[source,java] +---- +package org.superbiz.designbycontract; + +import javax.ejb.Stateless; + +@Stateless +public class PoleVaultingManagerBean implements PoleVaultingManager { + @Override + public int points(int centimeters) { + return centimeters - 120; + } +} +---- + + +== OlympicGamesTest + + +[source,java] +---- +public class OlympicGamesTest { + private static Context context; + + @EJB + private OlympicGamesManager gamesManager; + + @EJB + private PoleVaultingManager poleVaultingManager; + + @BeforeClass + public static void start() { + Properties properties = new Properties(); + properties.setProperty(BeanContext.USER_INTERCEPTOR_KEY, BeanValidationAppendixInterceptor.class.getName()); + context = EJBContainer.createEJBContainer(properties).getContext(); + } + + @Before + public void inject() throws Exception { + context.bind("inject", this); + } + + @AfterClass + public static void stop() throws Exception { + if (context != null) { + context.close(); + } + } + + @Test + public void sportMenOk() throws Exception { + assertEquals("IWin [FR]", gamesManager.addSportMan("IWin", "FR")); + } + + @Test + public void sportMenKoBecauseOfName() throws Exception { + try { + gamesManager.addSportMan("I lose", "EN"); + fail("no space should be in names"); + } catch (EJBException wrappingException) { + assertTrue(wrappingException.getCause() instanceof ConstraintViolationException); + ConstraintViolationException exception = ConstraintViolationException.class.cast(wrappingException.getCausedByException()); + assertEquals(1, exception.getConstraintViolations().size()); + } + } + + @Test + public void sportMenKoBecauseOfCountry() throws Exception { + try { + gamesManager.addSportMan("ILoseTwo", "TOO-LONG"); + fail("country should be between 2 and 4 characters"); + } catch (EJBException wrappingException) { + assertTrue(wrappingException.getCause() instanceof ConstraintViolationException); + ConstraintViolationException exception = ConstraintViolationException.class.cast(wrappingException.getCausedByException()); + assertEquals(1, exception.getConstraintViolations().size()); + } + } + + @Test + public void polVaulting() throws Exception { + assertEquals(100, poleVaultingManager.points(220)); + } + + @Test + public void tooShortPolVaulting() throws Exception { + try { + poleVaultingManager.points(119); + fail("the jump is too short"); + } catch (EJBException wrappingException) { + assertTrue(wrappingException.getCause() instanceof ConstraintViolationException); + ConstraintViolationException exception = ConstraintViolationException.class.cast(wrappingException.getCausedByException()); + assertEquals(1, exception.getConstraintViolations().size()); + } + } +} +---- + + += Running + + + +[source] +---- +------------------------------------------------------- + T E S T S +------------------------------------------------------- +Running OlympicGamesTest +Apache OpenEJB 4.0.0-beta-1 build: 20111002-04:06 +http://tomee.apache.org/ +INFO - openejb.home = /Users/dblevins/examples/bean-validation-design-by-contract +INFO - openejb.base = /Users/dblevins/examples/bean-validation-design-by-contract +INFO - Using 'javax.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/bean-validation-design-by-contract/target/classes +INFO - Beginning load: /Users/dblevins/examples/bean-validation-design-by-contract/target/classes +INFO - Configuring enterprise application: /Users/dblevins/examples/bean-validation-design-by-contract +INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container) +INFO - Auto-creating a container for bean PoleVaultingManagerBean: Container(type=STATELESS, id=Default Stateless Container) +INFO - Configuring Service(id=Default Managed Container, type=Container, provider-id=Default Managed Container) +INFO - Auto-creating a container for bean OlympicGamesTest: Container(type=MANAGED, id=Default Managed Container) +INFO - Enterprise application "/Users/dblevins/examples/bean-validation-design-by-contract" loaded. +INFO - Assembling app: /Users/dblevins/examples/bean-validation-design-by-contract +INFO - Jndi(name="java:global/bean-validation-design-by-contract/PoleVaultingManagerBean!org.superbiz.designbycontract.PoleVaultingManager") +INFO - Jndi(name="java:global/bean-validation-design-by-contract/PoleVaultingManagerBean") +INFO - Jndi(name="java:global/bean-validation-design-by-contract/OlympicGamesManager!org.superbiz.designbycontract.OlympicGamesManager") +INFO - Jndi(name="java:global/bean-validation-design-by-contract/OlympicGamesManager") +INFO - Jndi(name="java:global/EjbModule236054577/OlympicGamesTest!OlympicGamesTest") +INFO - Jndi(name="java:global/EjbModule236054577/OlympicGamesTest") +INFO - Created Ejb(deployment-id=OlympicGamesManager, ejb-name=OlympicGamesManager, container=Default Stateless Container) +INFO - Created Ejb(deployment-id=PoleVaultingManagerBean, ejb-name=PoleVaultingManagerBean, container=Default Stateless Container) +INFO - Created Ejb(deployment-id=OlympicGamesTest, ejb-name=OlympicGamesTest, container=Default Managed Container) +INFO - Started Ejb(deployment-id=OlympicGamesManager, ejb-name=OlympicGamesManager, container=Default Stateless Container) +INFO - Started Ejb(deployment-id=PoleVaultingManagerBean, ejb-name=PoleVaultingManagerBean, container=Default Stateless Container) +INFO - Started Ejb(deployment-id=OlympicGamesTest, ejb-name=OlympicGamesTest, container=Default Managed Container) +INFO - Deployed Application(path=/Users/dblevins/examples/bean-validation-design-by-contract) +Tests run: 5, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.245 sec + +Results : + +Tests run: 5, Failures: 0, Errors: 0, Skipped: 0 +---- + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/examples/bval-evaluation-redeployment.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/examples/bval-evaluation-redeployment.adoc b/src/main/jbake/content/examples/bval-evaluation-redeployment.adoc new file mode 100755 index 0000000..0b201bb --- /dev/null +++ b/src/main/jbake/content/examples/bval-evaluation-redeployment.adoc @@ -0,0 +1,8 @@ += bval-evaluation-redeployment +:jbake-date: 2016-09-06 +:jbake-type: page +:jbake-tomeepdf: +:jbake-status: published + +Example bval-evaluation-redeployment can be browsed at https://github.com/apache/tomee/tree/master/examples/bval-evaluation-redeployment +
