You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by db...@apache.org on 2011/07/10 07:36:21 UTC
svn commit: r1144778 [10/13] - /openejb/site/trunk/content/
Added: openejb/site/trunk/content/service-locator.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/service-locator.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/service-locator.mdtext (added)
+++ openejb/site/trunk/content/service-locator.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,172 @@
+Title: Service Locator
+The functionality of the [openejb.jndiname.format](jndi-names.html)
+ allows for writing some really fun service locator code. Creating the
+exact layout you want using the exact data you want means you can create
+robust libraries for pulling things out of JNDI.
+
+<a name="ServiceLocator-Lookupexamples"></a>
+# Lookup examples
+
+To get the creative juices flowing here are a few examples of lookup
+methods you could create for your service locator, the jndi name formats
+that would work with those lookups, and examples of client code using the
+service locator. For simplicity, we'll assume all the lookup examples
+start with this basic class that has a built-in lookup allowing for a
+common prefix to be optionally applied to the beginning of all lookup
+strings.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>MyLocator.java</B></DIV><DIV class="codeContent panelContent">
+ public class MyLocator {
+ private final Context context;
+
+ public MyLocator() throws NamingException {
+ this(null);
+ }
+
+ public MyLocator(String commonPrefix) throws NamingException {
+ Properties properties = new Properties();
+ properties.put(Context.INITIAL_CONTEXT_FACTORY,
+"org.apache.openejb.client.RemoteInitialContextFactory");
+ properties.put(Context.PROVIDER_URL, "ejbd://localhost:4201/");
+ this.context = new InitialContext(properties);
+ }
+
+ public Object lookup(String name) {
+ try {
+ if (commonPrefix != null) name = commonPrefix + "/" +name;
+ return context.lookup(name);
+ } catch (NamingException e) {
+ throw new IllegalArgumentException(e);
+ }
+ }
+ }
+
+
+<a name="ServiceLocator-Justtheinterface"></a>
+## Just the interface
+Usable with JNDI name formats ending in the full class name of the
+interface such as:
+ - \{interfaceClass}
+
+
+ public <T> T lookup(Class<T> type) {
+ return (T) lookup(type.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{interfaceClass}
+ - ejb/\{moduleId}/\{interfaceClass}
+
+
+ MyLocator locator = new MyLocator("ejb/superbiz");
+ Widget widget = locator.lookup(Widget.class);
+ Store store = locator.lookup(Store.class);
+
+
+
+<a name="ServiceLocator-Interfaceclassandaprefix"></a>
+## Interface class and a prefix
+
+Usable with JNDI name formats including a varying prefix such as ejbName or
+deploymentID
+and ending in the full class name of the interface
+
+ - \{ejbName}/\{interfaceClass}
+ - \{deploymentId}/\{interfaceClass}
+
+
+ public <T> T lookup(String prefix, Class<T> type) {
+ return (T) lookup(prefix + "/" + type.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget redWidget = locator.lookup("RedWidgetBean", Widget.class);
+ Widget blueWidget = locator.lookup("BlueWidgetBean", Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{ejbName}/\{interfaceClass}
+ - ejb/\{moduleId}/\{deploymentId}/\{interfaceClass}
+
+
+ MyLocator locator = new MyLocator("accountingApp");
+ Widget widget = locator.lookup("RedWidgetBean", Widget.class);
+ Store store = locator.lookup("StoreBean", Store.class);
+
+
+<a name="ServiceLocator-Interfaceclassandejbclass"></a>
+## Interface class and ejb class
+
+Usable with JNDI name formats comprised of the interfaceClass and ejbClass
+
+For variation, the interface class is the prefix and the ejb class is the
+suffix. This is neat as the the prefix (the interface class name) becomes
+a jndi context with one binding in it for each implementing ejb class.
+
+Works with:
+ - \{interfaceClass}/\{ejbClass}
+
+
+ public <T> T lookup(Class<T> type, Class ejbClass) {
+ return (T) lookup(type.getName() + "/" + ejbClass.getName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(Widget.class, BlueWidgetBean.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{interfaceClass}/\{ejbClass}
+ - ejb/\{moduleId}/\{interfaceClass}/\{ejbClass}
+
+
+ MyLocator locator = new MyLocator("ejb/purchasingApp");
+ Widget widget = locator.lookup(Widget.class, RedWidgetBean.class);
+ Store store = locator.lookup(Store.class, StoreBean.class);
+
+
+
+<a name="ServiceLocator-Interfaceclassandejbclasswithsimplenames"></a>
+## Interface class and ejb class with simple names
+
+Similar to the above example but using the simple name of the classes
+resulting
+in a JNDI tree that's a bit more human readable.
+ - \{ejbClass.simpleName}/\{interfaceClass.simpleName}
+
+
+ public <T> T lookup(Class ejbClass, Class<T> type) {
+ return (T) lookup(ejbClass.getSimpleName() + "" +
+type.getSimpleName());
+ }
+
+
+
+ MyLocator locator = new MyLocator();
+ Widget widget = locator.lookup(RedWidgetBean.class, Widget.class);
+
+
+Or with a common prefix or with a common prefix supplied in constructor
+such as:
+ - \{moduleId}/\{ejbClass.simpleName}/\{interfaceClass.simpleName}
+ - ejb/\{moduleId}/\{ejbClass.simpleName}/\{interfaceClass.simpleName}
+
+
+ MyLocator locator = new MyLocator("shippingApp");
+ Widget widget = locator.lookup(GreenWidgetBean.class, Widget.class);
+ Store store = locator.lookup(SuperStoreBean.class, Store.class);
+
+
Added: openejb/site/trunk/content/simple-stateful-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/simple-stateful-example.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/simple-stateful-example.cwiki (added)
+++ openejb/site/trunk/content/simple-stateful-example.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,116 @@
+h1. Overview
+
+{span:style=float: right; margin-left: 20px;}
+{html}
+
+<object width="400" height="250"><param name="movie" value="http://www.youtube.com/v/9JqxbfzsWOQ?fs=1&hl=en_US&rel=0"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/9JqxbfzsWOQ?fs=1&hl=en_US&rel=0" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
+
+{html}
+{span}
+{div}
+
+This example shows how to create a Stateful session EJB using annotations.
+
+A Stateful session bean is a session bean whose instances can maintain the conversational state with the client. The conversational state of the stateful session bean, which describes the conversation between a specific client and a session bean, is contained in the fields of the stateful session bean.
+
+Simply put, when you create a stateful bean an actual instance is created by the container and *dedicated* to you and only you. Every call you make will go to your instance. Further, your instance will not be shared with anyone unless you give them a reference to your stateful bean. The instance will last until you remove it or until it times-out and is removed by the container.
+
+With EJB 3.0, it's now possible to write stateful session bean without specifying a deployment descriptor; you basically have to write just a remote or local business interface, which is a plain-old-java-interface, annotated with the @Remote or @Local annotation the stateful session bean implementation, a plain-old-java-object which implements the remote or the local business interface and is annotated with the @Stateful annotation
+
+_This example is the "simple-stateful" example located in the [openejb-examples.zip|OPENEJB:Download] available on the download page._
+
+
+
+{div}
+{div:style=clear:both;}{div}
+
+h1. The Code
+
+In this example we develop a simple counter stateful session EJB. Every stateful session bean implementation must be annotated using the annotation *@Stateful* or marked that way in the ejb-jar.xml file.
+
+h2. Bean
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterImpl.java|lang=java}
+
+In EJB 3.0 session beans do not need to implement the javax.ejb.SessionBean interface. You can simply annotate it as @Stateful if you want it to be a stateful session bean.
+
+Users of EJB 2.x may notice the bean actually implements the business interfaces! In the prior version of EJB implementing the remote interface (which derives from javax.ejb.EJBObject) in your bean was just not allowed. Now there is no javax.ejb.EJBObject requirement, so implementing the business interfaces is standard practice for EJB 3.0.
+
+h2. Local business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterLocal.java|lang=java}
+
+Local interfaces in EJB are *pass-by-reference* interfaces. Meaning that *normal java semantics* are used for passing arguments, return values and exceptions. A business local interface can be any plain java interface. There are no restrictions on the method arguments, return types, or throws clauses.
+
+Unless specified otherwise, every interface your bean implements (and it's parent class implements and so on) is considered to be a local business interface. You can use the *@Local* annotation to explicitly state that an interface is a local interface, but this is not required.
+
+You'll notice that in EJB 3.0 the Local Business Interface of a stateless session bean does not need to extend from javax.ejb.EJBLocalObject and does not need a javax.ejb.EJBLocalHome interface as they did in EJB 2.x and prior. Per the vocabulary of the EJB spec, interfaces that implement javax.ejb.EJBLocalObject or javax.ejb.EJBLocalHome are considered Component Interfaces and the plain java interface above is considered a Business Interface.
+
+h2. Remote business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterRemote.java|lang=java}
+
+Remote interfaces are *pass-by-value* interfaces. Meaning that all method parameters, return values, and exceptions are *serialized* on every call. The result is that you get a copy of the original object and not the original object. The advantage is of course that Remote interfaces can be used to invoke an EJB across a network in a client-server fashion. There are no restrictions on the Remote interface itself, but there are on the data passed in and out of the remote interface. The *values* passed into a method or returned from a method of a Remote interface *must be serializable*. It is fine for the method signature to be, for example, "public Object myMethod(Object myParam)" as long as the *value* passed in and returned implements *java.io.Serializable*.
+
+As stated above, the Remote Business Interface of a bean can be any plain old interface. It does not need to extend javax.ejb.EJBObject, it does not need a javax.ejb.EJBHome, the methods do not need to throw javax.rmi.RemoteException, and the bean class *can* implement it!
+
+At minimum the interface must be annotated with *@Remote* either in the interface itself or in the bean class, or the interface must be declared via <business-remote> in the ejb-jar.xml.
+
+h1. Writing a unit test for the example
+
+Writing an unit test for the stateful session EJB is quite simple. We need just to write a setup method to create and initialize the InitialContext, and then write our test methods
+
+h4. setUp
+
+{snippet:id=setup|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+h4. Test the local business interface
+
+{snippet:id=local|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+h4. Test the remote business interface
+
+{snippet:id=remote|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+{info:title=JNDI Names}
+Note that JNDI names for Java SE clients are not standardized by the EJB spec. This is unfortunate and something being addressed in EJB 3.1. The default schema that OpenEJB uses is ejbName + interfaceType (i.e. Local, Remote, LocalHome, RemoteHome), so in our example "CounterImpl" + "Local" and "CounterImpl" + "Remote". You can in fact change this default to be absolutely [anything you want|JNDI Names] including interface class name, ejb class name, and more.
+{info}
+
+h1. Running
+
+Running the example is fairly simple. In the "simple-stateful" directory of the [examples zip|OPENEJB:Download], just run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+{noformat}
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.superbiz.counter.CounterImplTest
+Apache OpenEJB 3.0 build: 20080408-04:13
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.0/examples/simple-stateful
+INFO - openejb.base = /Users/dblevins/work/openejb-3.0/examples/simple-stateful
+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=Default JDK 1.3 ProxyFactory, type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+INFO - Found EjbModule in classpath: /Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+INFO - Configuring app: /Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container)
+INFO - Auto-creating a container for bean CounterImpl: Container(type=STATEFUL, id=Default Stateful Container)
+INFO - Loaded Module: /Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+INFO - Assembling app: /Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+INFO - Jndi(name=CounterImplLocal) --> Ejb(deployment-id=CounterImpl)
+INFO - Jndi(name=CounterImplRemote) --> Ejb(deployment-id=CounterImpl)
+INFO - Created Ejb(deployment-id=CounterImpl, ejb-name=CounterImpl, container=Default Stateful Container)
+INFO - Deployed Application(path=/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes)
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.698 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
+
Propchange: openejb/site/trunk/content/simple-stateful-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/simple-stateful-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/simple-stateful-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/simple-stateful-example.mdtext (added)
+++ openejb/site/trunk/content/simple-stateful-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,207 @@
+Title: Simple Stateful Example
+<a name="SimpleStatefulExample-Overview"></a>
+# Overview
+
+{span:style=float: right; margin-left: 20px;}
+{html}
+
+<object width="400" height="250"><param name="movie"
+value="http://www.youtube.com/v/9JqxbfzsWOQ?fs=1&hl=en_US&rel=0"></param><param
+name="allowFullScreen" value="true"></param><param name="allowscriptaccess"
+value="always"></param><embed
+src="http://www.youtube.com/v/9JqxbfzsWOQ?fs=1&hl=en_US&rel=0"
+type="application/x-shockwave-flash" allowscriptaccess="always"
+allowfullscreen="true" width="400" height="250"></embed></object>
+
+{html}
+{span}
+{div}
+
+This example shows how to create a Stateful session EJB using annotations.
+
+A Stateful session bean is a session bean whose instances can maintain the
+conversational state with the client. The conversational state of the
+stateful session bean, which describes the conversation between a specific
+client and a session bean, is contained in the fields of the stateful
+session bean.
+
+Simply put, when you create a stateful bean an actual instance is created
+by the container and *dedicated* to you and only you. Every call you make
+will go to your instance. Further, your instance will not be shared with
+anyone unless you give them a reference to your stateful bean. The
+instance will last until you remove it or until it times-out and is removed
+by the container.
+
+With EJB 3.0, it's now possible to write stateful session bean without
+specifying a deployment descriptor; you basically have to write just a
+remote or local business interface, which is a plain-old-java-interface,
+annotated with the @Remote or @Local annotation the stateful session bean
+implementation, a plain-old-java-object which implements the remote or the
+local business interface and is annotated with the @Stateful annotation
+
+_This example is the "simple-stateful" example located in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+
+
+{div}
+{div:style=clear:both;}{div}
+
+<a name="SimpleStatefulExample-TheCode"></a>
+# The Code
+
+In this example we develop a simple counter stateful session EJB. Every
+stateful session bean implementation must be annotated using the annotation
+*@Stateful* or marked that way in the ejb-jar.xml file.
+
+<a name="SimpleStatefulExample-Bean"></a>
+## Bean
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterImpl.java|lang=java}
+
+In EJB 3.0 session beans do not need to implement the javax.ejb.SessionBean
+interface. You can simply annotate it as @Stateful if you want it to be a
+stateful session bean.
+
+Users of EJB 2.x may notice the bean actually implements the business
+interfaces! In the prior version of EJB implementing the remote interface
+(which derives from javax.ejb.EJBObject) in your bean was just not allowed.
+Now there is no javax.ejb.EJBObject requirement, so implementing the
+business interfaces is standard practice for EJB 3.0.
+
+<a name="SimpleStatefulExample-Localbusinessinterface"></a>
+## Local business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterLocal.java|lang=java}
+
+Local interfaces in EJB are *pass-by-reference* interfaces. Meaning that
+*normal java semantics* are used for passing arguments, return values and
+exceptions. A business local interface can be any plain java interface.
+There are no restrictions on the method arguments, return types, or throws
+clauses.
+
+Unless specified otherwise, every interface your bean implements (and it's
+parent class implements and so on) is considered to be a local business
+interface. You can use the *@Local* annotation to explicitly state that an
+interface is a local interface, but this is not required.
+
+You'll notice that in EJB 3.0 the Local Business Interface of a stateless
+session bean does not need to extend from javax.ejb.EJBLocalObject and does
+not need a javax.ejb.EJBLocalHome interface as they did in EJB 2.x and
+prior. Per the vocabulary of the EJB spec, interfaces that implement
+javax.ejb.EJBLocalObject or javax.ejb.EJBLocalHome are considered Component
+Interfaces and the plain java interface above is considered a Business
+Interface.
+
+<a name="SimpleStatefulExample-Remotebusinessinterface"></a>
+## Remote business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateful/src/main/java/org/superbiz/counter/CounterRemote.java|lang=java}
+
+Remote interfaces are *pass-by-value* interfaces. Meaning that all method
+parameters, return values, and exceptions are *serialized* on every call.
+The result is that you get a copy of the original object and not the
+original object. The advantage is of course that Remote interfaces can be
+used to invoke an EJB across a network in a client-server fashion. There
+are no restrictions on the Remote interface itself, but there are on the
+data passed in and out of the remote interface. The *values* passed into a
+method or returned from a method of a Remote interface *must be
+serializable*. It is fine for the method signature to be, for example,
+"public Object myMethod(Object myParam)" as long as the *value* passed in
+and returned implements *java.io.Serializable*.
+
+As stated above, the Remote Business Interface of a bean can be any plain
+old interface. It does not need to extend javax.ejb.EJBObject, it does not
+need a javax.ejb.EJBHome, the methods do not need to throw
+javax.rmi.RemoteException, and the bean class *can* implement it!
+
+At minimum the interface must be annotated with *@Remote* either in the
+interface itself or in the bean class, or the interface must be declared
+via <business-remote> in the ejb-jar.xml.
+
+<a name="SimpleStatefulExample-Writingaunittestfortheexample"></a>
+# Writing a unit test for the example
+
+Writing an unit test for the stateful session EJB is quite simple. We need
+just to write a setup method to create and initialize the InitialContext,
+and then write our test methods
+
+<a name="SimpleStatefulExample-setUp"></a>
+#### setUp
+
+{snippet:id=setup|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+<a name="SimpleStatefulExample-Testthelocalbusinessinterface"></a>
+#### Test the local business interface
+
+{snippet:id=local|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+<a name="SimpleStatefulExample-Testtheremotebusinessinterface"></a>
+#### Test the remote business interface
+
+{snippet:id=remote|url=openejb3/examples/simple-stateful/src/test/java/org/superbiz/counter/CounterImplTest.java|lang=java}
+
+{info:title=JNDI Names}
+Note that JNDI names for Java SE clients are not standardized by the EJB
+spec. This is unfortunate and something being addressed in EJB 3.1. The
+default schema that OpenEJB uses is ejbName + interfaceType (i.e. Local,
+Remote, LocalHome, RemoteHome), so in our example "CounterImpl" + "Local"
+and "CounterImpl" + "Remote". You can in fact change this default to be
+absolutely [anything you want](jndi-names.html)
+ including interface class name, ejb class name, and more.
+{info}
+
+<a name="SimpleStatefulExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "simple-stateful" directory
+of the [examples zip](openejb:download.html)
+, just run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.counter.CounterImplTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful
+ 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=Default JDK 1.3 ProxyFactory,
+type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+ INFO - Found EjbModule in classpath:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+ INFO - Configuring Service(id=Default Stateful Container, type=Container,
+provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean CounterImpl:
+Container(type=STATEFUL, id=Default Stateful Container)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes
+ INFO - Jndi(name=CounterImplLocal) --> Ejb(deployment-id=CounterImpl)
+ INFO - Jndi(name=CounterImplRemote) --> Ejb(deployment-id=CounterImpl)
+ INFO - Created Ejb(deployment-id=CounterImpl, ejb-name=CounterImpl,
+container=Default Stateful Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/simple-stateful/target/classes)
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.698 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
+
Added: openejb/site/trunk/content/simple-stateless-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/simple-stateless-example.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/simple-stateless-example.cwiki (added)
+++ openejb/site/trunk/content/simple-stateless-example.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,118 @@
+h1. Overview
+{span:style=float: right; margin-left: 20px;}
+{html}
+
+<object width="400" height="250"><param name="movie" value="http://www.youtube.com/v/aLx2jta96xU?fs=1&hl=en_US"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/aLx2jta96xU?fs=1&hl=en_US" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
+
+{html}
+{span}
+{div}
+
+
+This example shows how to create a Stateless session EJB using annotations. As stated in the "JSR 220: Enterprise JavaBeansTM,Version 3.0 - EJB Core Contracts and Requirements",
+
+{panel}
+"Stateless session beans are session beans whose instances have no conversational state. This means that all bean instances are equivalent when they are not involved in servicing a client-invoked method. The term 'stateless' signifies that an instance has no state for a specific client."
+{panel}
+
+What this means is quite simply that stateless beans are *shared*. They do in fact have state as you can assign values to the variables, etc. in the bean instance. The only catch is there are a *pool* of identical instances and you are not guaranteed to get the exact same instance on every call. For each call, you get whatever instance happens to be available. This is identical to checking out a book from the library or renting a movie from the video store. You are essentially checking out or renting a new bean instance on each method call.
+
+With EJB 3.0, it's now possible to write stateless session bean without specifying a deployment descriptor; you basically have to write just a remote or local business interface, which is a plain-old-java-interface, annotated with the @Remote or @Local annotation the stateless session bean implementation, a plain-old-java-object which implements the remote or the local business interface and is annotated with the @Stateless annotation
+
+_This example is the "simple-stateless" example located in the [openejb-examples.zip|OPENEJB:Download] available on the download page._
+
+{div}
+{div:style=clear:both;}{div}
+
+h1. The Code
+
+In this example we develop a simple EJB 3 Stateless session EJB. Every stateless session bean implementation must be annotated using the annotation *@Stateless* or marked that way in the ejb-jar.xml file.
+
+Our Stateless bean has 2 business interfaces: CalculatorRemote, a remote business interface, and CalculatorLocal, a local business interface. A minimum of one business interface is required.
+
+h2. Bean
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorImpl.java|lang=java}
+
+In EJB 3.0 session beans do not need to implement the javax.ejb.SessionBean interface. You can simply annotate it as @Stateless if you want it to be a stateless session bean.
+
+Users of EJB 2.x may notice the bean actually implements the business interfaces! In the prior version of EJB implementing the remote interface (which derives from javax.ejb.EJBObject) in your bean was just not allowed. Now there is no javax.ejb.EJBObject requirement, so implementing the business interfaces is standard practice for EJB 3.0.
+
+h2. Local business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorLocal.java|lang=java}
+
+Local interfaces in EJB are *pass-by-reference* interfaces. Meaning that *normal java semantics* are used for passing arguments, return values and exceptions. A business local interface can be any plain java interface. There are no restrictions on the method arguments, return types, or throws clauses.
+
+Unless specified otherwise, every interface your bean implements (and it's parent class implements and so on) is considered to be a local business interface. You can use the *@Local* annotation to explicitly state that an interface is a local interface, but this is not required.
+
+You'll notice that in EJB 3.0 the Local Business Interface of a stateless session bean does not need to extend from javax.ejb.EJBLocalObject and does not need a javax.ejb.EJBLocalHome interface as they did in EJB 2.x and prior. Per the vocabulary of the EJB spec, interfaces that implement javax.ejb.EJBLocalObject or javax.ejb.EJBLocalHome are considered Component Interfaces and the plain java interface above is considered a Business Interface.
+
+h2. Remote business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorRemote.java|lang=java}
+
+Remote interfaces are *pass-by-value* interfaces. Meaning that all method parameters, return values, and exceptions are *serialized* on every call. The result is that you get a copy of the original object and not the original object. The advantage is of course that Remote interfaces can be used to invoke an EJB across a network in a client-server fashion. There are no restrictions on the Remote interface itself, but there are on the data passed in and out of the remote interface. The *values* passed into a method or returned from a method of a Remote interface *must be serializable*. It is fine for the method signature to be, for example, "public Object myMethod(Object myParam)" as long as the *value* passed in and returned implements *java.io.Serializable*.
+
+As stated above, the Remote Business Interface of a bean can be any plain old interface. It does not need to extend javax.ejb.EJBObject, it does not need a javax.ejb.EJBHome, the methods do not need to throw javax.rmi.RemoteException, and the bean class *can* implement it!
+
+At minimum the interface must be annotated with *@Remote* either in the interface itself or in the bean class, or the interface must be declared via <business-remote> in the ejb-jar.xml.
+
+h1. Writing a unit test for the example
+
+Writing an unit test for the stateless session EJb is quite simple. We need just to write a setup method to create and initialize the InitialContext, and then write our test methods
+
+h2. setUp
+
+{snippet:id=setup|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+h2. Test the local business interface
+
+{snippet:id=local|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+h2. Test the remote business interface
+
+{snippet:id=remote|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+{info:title=JNDI Names}
+Note that JNDI names for Java SE clients are not standardized by the EJB spec. This is unfortunate and something being addressed in EJB 3.1. The default schema that OpenEJB uses is ejbName + interfaceType (i.e. Local, Remote, LocalHome, RemoteHome), so in our example "CalculatorImpl" + "Local" and "CalculatorImpl" + "Remote". You can in fact change this default to be absolutely [anything you want|JNDI Names] including interface class name, ejb class name, and more.
+{info}
+
+
+h1. Running
+
+Running the example is fairly simple. In the "simple-stateless" directory of the [examples zip|OPENEJB:Download], just run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+{noformat}
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.superbiz.calculator.CalculatorTest
+Apache OpenEJB 3.0 build: 20080408-04:13
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.0/examples/simple-stateless
+INFO - openejb.base = /Users/dblevins/work/openejb-3.0/examples/simple-stateless
+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=Default JDK 1.3 ProxyFactory, type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+INFO - Found EjbModule in classpath: /Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+INFO - Configuring app: /Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container)
+INFO - Auto-creating a container for bean CalculatorImpl: Container(type=STATELESS, id=Default Stateless Container)
+INFO - Loaded Module: /Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+INFO - Assembling app: /Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+INFO - Jndi(name=CalculatorImplLocal) --> Ejb(deployment-id=CalculatorImpl)
+INFO - Jndi(name=CalculatorImplRemote) --> Ejb(deployment-id=CalculatorImpl)
+INFO - Created Ejb(deployment-id=CalculatorImpl, ejb-name=CalculatorImpl, container=Default Stateless Container)
+INFO - Deployed Application(path=/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes)
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.845 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
Propchange: openejb/site/trunk/content/simple-stateless-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/simple-stateless-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/simple-stateless-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/simple-stateless-example.mdtext (added)
+++ openejb/site/trunk/content/simple-stateless-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,215 @@
+Title: Simple Stateless Example
+<a name="SimpleStatelessExample-Overview"></a>
+# Overview
+{span:style=float: right; margin-left: 20px;}
+{html}
+
+<object width="400" height="250"><param name="movie"
+value="http://www.youtube.com/v/aLx2jta96xU?fs=1&hl=en_US"></param><param
+name="allowFullScreen" value="true"></param><param name="allowscriptaccess"
+value="always"></param><embed
+src="http://www.youtube.com/v/aLx2jta96xU?fs=1&hl=en_US"
+type="application/x-shockwave-flash" allowscriptaccess="always"
+allowfullscreen="true" width="400" height="250"></embed></object>
+
+{html}
+{span}
+{div}
+
+
+This example shows how to create a Stateless session EJB using annotations.
+ As stated in the "JSR 220: Enterprise JavaBeansTM,Version 3.0 - EJB Core
+Contracts and Requirements",
+
+{panel}
+"Stateless session beans are session beans whose instances have no
+conversational state. This means that all bean instances are equivalent
+when they are not involved in servicing a client-invoked method. The term
+'stateless' signifies that an instance has no state for a specific client."
+{panel}
+
+What this means is quite simply that stateless beans are *shared*. They do
+in fact have state as you can assign values to the variables, etc. in the
+bean instance. The only catch is there are a *pool* of identical instances
+and you are not guaranteed to get the exact same instance on every call.
+For each call, you get whatever instance happens to be available. This is
+identical to checking out a book from the library or renting a movie from
+the video store. You are essentially checking out or renting a new bean
+instance on each method call.
+
+With EJB 3.0, it's now possible to write stateless session bean without
+specifying a deployment descriptor; you basically have to write just a
+remote or local business interface, which is a plain-old-java-interface,
+annotated with the @Remote or @Local annotation the stateless session bean
+implementation, a plain-old-java-object which implements the remote or the
+local business interface and is annotated with the @Stateless annotation
+
+_This example is the "simple-stateless" example located in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+{div}
+{div:style=clear:both;}{div}
+
+<a name="SimpleStatelessExample-TheCode"></a>
+# The Code
+
+In this example we develop a simple EJB 3 Stateless session EJB. Every
+stateless session bean implementation must be annotated using the
+annotation *@Stateless* or marked that way in the ejb-jar.xml file.
+
+Our Stateless bean has 2 business interfaces: CalculatorRemote, a remote
+business interface, and CalculatorLocal, a local business interface. A
+minimum of one business interface is required.
+
+<a name="SimpleStatelessExample-Bean"></a>
+## Bean
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorImpl.java|lang=java}
+
+In EJB 3.0 session beans do not need to implement the javax.ejb.SessionBean
+interface. You can simply annotate it as @Stateless if you want it to be a
+stateless session bean.
+
+Users of EJB 2.x may notice the bean actually implements the business
+interfaces! In the prior version of EJB implementing the remote interface
+(which derives from javax.ejb.EJBObject) in your bean was just not allowed.
+Now there is no javax.ejb.EJBObject requirement, so implementing the
+business interfaces is standard practice for EJB 3.0.
+
+<a name="SimpleStatelessExample-Localbusinessinterface"></a>
+## Local business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorLocal.java|lang=java}
+
+Local interfaces in EJB are *pass-by-reference* interfaces. Meaning that
+*normal java semantics* are used for passing arguments, return values and
+exceptions. A business local interface can be any plain java interface.
+There are no restrictions on the method arguments, return types, or throws
+clauses.
+
+Unless specified otherwise, every interface your bean implements (and it's
+parent class implements and so on) is considered to be a local business
+interface. You can use the *@Local* annotation to explicitly state that an
+interface is a local interface, but this is not required.
+
+You'll notice that in EJB 3.0 the Local Business Interface of a stateless
+session bean does not need to extend from javax.ejb.EJBLocalObject and does
+not need a javax.ejb.EJBLocalHome interface as they did in EJB 2.x and
+prior. Per the vocabulary of the EJB spec, interfaces that implement
+javax.ejb.EJBLocalObject or javax.ejb.EJBLocalHome are considered Component
+Interfaces and the plain java interface above is considered a Business
+Interface.
+
+<a name="SimpleStatelessExample-Remotebusinessinterface"></a>
+## Remote business interface
+
+{snippet:id=code|url=openejb3/examples/simple-stateless/src/main/java/org/superbiz/calculator/CalculatorRemote.java|lang=java}
+
+Remote interfaces are *pass-by-value* interfaces. Meaning that all method
+parameters, return values, and exceptions are *serialized* on every call.
+The result is that you get a copy of the original object and not the
+original object. The advantage is of course that Remote interfaces can be
+used to invoke an EJB across a network in a client-server fashion. There
+are no restrictions on the Remote interface itself, but there are on the
+data passed in and out of the remote interface. The *values* passed into a
+method or returned from a method of a Remote interface *must be
+serializable*. It is fine for the method signature to be, for example,
+"public Object myMethod(Object myParam)" as long as the *value* passed in
+and returned implements *java.io.Serializable*.
+
+As stated above, the Remote Business Interface of a bean can be any plain
+old interface. It does not need to extend javax.ejb.EJBObject, it does not
+need a javax.ejb.EJBHome, the methods do not need to throw
+javax.rmi.RemoteException, and the bean class *can* implement it!
+
+At minimum the interface must be annotated with *@Remote* either in the
+interface itself or in the bean class, or the interface must be declared
+via <business-remote> in the ejb-jar.xml.
+
+<a name="SimpleStatelessExample-Writingaunittestfortheexample"></a>
+# Writing a unit test for the example
+
+Writing an unit test for the stateless session EJb is quite simple. We need
+just to write a setup method to create and initialize the InitialContext,
+and then write our test methods
+
+<a name="SimpleStatelessExample-setUp"></a>
+## setUp
+
+{snippet:id=setup|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+<a name="SimpleStatelessExample-Testthelocalbusinessinterface"></a>
+## Test the local business interface
+
+{snippet:id=local|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+<a name="SimpleStatelessExample-Testtheremotebusinessinterface"></a>
+## Test the remote business interface
+
+{snippet:id=remote|url=openejb3/examples/simple-stateless/src/test/java/org/superbiz/calculator/CalculatorTest.java|lang=java}
+
+{info:title=JNDI Names}
+Note that JNDI names for Java SE clients are not standardized by the EJB
+spec. This is unfortunate and something being addressed in EJB 3.1. The
+default schema that OpenEJB uses is ejbName + interfaceType (i.e. Local,
+Remote, LocalHome, RemoteHome), so in our example "CalculatorImpl" +
+"Local" and "CalculatorImpl" + "Remote". You can in fact change this
+default to be absolutely [anything you want](jndi-names.html)
+ including interface class name, ejb class name, and more.
+{info}
+
+
+<a name="SimpleStatelessExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "simple-stateless" directory
+of the [examples zip](openejb:download.html)
+, just run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.calculator.CalculatorTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless
+ 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=Default JDK 1.3 ProxyFactory,
+type=ProxyFactory, provider-id=Default JDK 1.3 ProxyFactory)
+ INFO - Found EjbModule in classpath:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+ INFO - Configuring Service(id=Default Stateless Container, type=Container,
+provider-id=Default Stateless Container)
+ INFO - Auto-creating a container for bean CalculatorImpl:
+Container(type=STATELESS, id=Default Stateless Container)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes
+ INFO - Jndi(name=CalculatorImplLocal) --> Ejb(deployment-id=CalculatorImpl)
+ INFO - Jndi(name=CalculatorImplRemote) -->
+Ejb(deployment-id=CalculatorImpl)
+ INFO - Created Ejb(deployment-id=CalculatorImpl, ejb-name=CalculatorImpl,
+container=Default Stateless Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/simple-stateless/target/classes)
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.845 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
Modified: openejb/site/trunk/content/singleton-beans.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/singleton-beans.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/singleton-beans.cwiki (original)
+++ openejb/site/trunk/content/singleton-beans.cwiki Sun Jul 10 05:36:12 2011
@@ -1 +1,135 @@
-{include:OPENEJBx30:Singleton Beans}
\ No newline at end of file
+h1. Singleton Overview
+For the first time in years EJB has a new bean type, the *@Singleton*. In my opinion, the javax.ejb.Singleton will replace a lot of what people are using @Stateless for today.
+
+The Singleton is essentially what you get if you take a Stateless bean and adjust the pool size to be exactly 1 resulting in there being exactly one instance of the Singleton bean in the application which can be invoked concurrently by multiple threads, like a servlet. It can do everything a Stateless can do such as support local and remote business interfaces, web services, security, transactions, and more. Additionally, the Singleton can have its @PostConstruct method called with the application starts up and its @PreDestroy method called when the application shuts down. This allows it to serve as an application lifecycle listener which is something only Servlets could do before. It has an *@Startup* annotation which is similar in concept to the servlet <load-on-startup>, but unlike servlets it doesn't take a number as an argument. Instead, you can use an *@DependsOn* annotation to say which other Singletons you need and the container will ensure they start before you
.
+
+See the [Singleton Example] for sample bean code and client.
+
+h2. Concurrency
+
+Singletons support two modes of concurrent access, Container-Managed Concurrency (the default) and Bean-Managed Concurrency.
+
+h3. Bean-Managed Concurrency
+
+With Bean-Managed Concurrency, annotated as *@ConcurrencyManagement(BEAN)*, the container sends all invocations into the bean and lets the Singleton bean instance decide how and when to synchronize access, if at all. Here the 'synchronization' keyword is allowed as well as the full javax.util.concurrent set of libraries.
+
+h3. Container-Managed Concurrency
+
+With Container-Managed Concurrency, annotated as *@ConcurrencyManagement(CONTAINER)*, the container will enforce concurrency for you via locking method access to the bean. Two modes, called locks exist and can be assigned to both the bean class and methods of the bean class.
+
+h4. Lock type
+
+The first and the default is a "write" lock, annotated as *@Lock(WRITE)*. Essentially, with a write lock the caller holds an exclusive lock on the bean for the duration of the method call and all other threads for that or any other method must wait.
+
+The second option is a "read" lock, annotated as *@Lock(READ)*. The read lock allows full concurrent access to the methods (assuming no write locks are held). The default mode of "write" essentially makes your bean a single-threaded bean, which is very slow. The more conservative @Lock(WRITE) was chosen as the default as this is how all the other bean types work (only a single thread may access a bean instance at any given time). Those that are aware of how to handle concurrent access can easily put @Lock(READ) on their bean class, thus changing the default, and then @Lock(WRITE) on specific methods if needed.
+
+The locking modes of Container-Managed Concurrency map directly to the *[java.util.concurrent.ReadWriteLock|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html]* API which looks like this:
+
+{code:title=java.util.concurrent.ReadWriteLock}
+public interface ReadWriteLock {
+ /**
+ * Returns the lock used for reading.
+ *
+ * @return the lock used for reading.
+ */
+ Lock readLock();
+
+ /**
+ * Returns the lock used for writing.
+ *
+ * @return the lock used for writing.
+ */
+ Lock writeLock();
+}
+{code}
+
+Literally 100% of the Singleton locking we're talking about is taken from this interface and its javadoc is a great source of information. It's safe to imagine that under the covers the Singleton Container has an instance of ReadWriteLock which it uses to enforce the locking for all the Singleton bean's methods. Essentially:
+
+ - @Lock(READ) == theSingletonReadWriteLock.readLock().lock()
+ - @Lock(WRITE) == theSingletonReadWriteLock.writeLock().lock()
+
+The EJB container may use something other than ReadWriteLock but the semantics of a ReadWriteLock must be followed. Internally, we use an instance of [java.util.concurrent.ReentrantReadWriteLock|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html] which supports correct memory synchronization, some reentrancy, lock downgrading, and [more|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html].
+
+h4. Acquiring the Lock
+
+The *@AccessTimetout* annotation can configure how long a thread will wait to acquire the read or write lock. This annotation can be used on the bean class or individual methods. The annotation maps directly to the [java.util.concurrent.locks.Lock|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/Lock.html] interface.
+
+{code:title=java.util.concurrent.locks.Lock}
+public interface Lock {
+
+ /**
+ * Blocks (potentially) forever
+ *
+ * @AccessTimout with a value of -1
+ */
+ void lock();
+
+ /**
+ * Non-blocking
+ *
+ * @AccessTimout with a value of 0
+ */
+ boolean tryLock();
+
+ /**
+ * Blocks (potentially) up to a limit
+ *
+ * @AccessTimout(30, TimeUnit.SECONDS)
+ */
+ boolean tryLock(long time, TimeUnit unit) throws InterruptedException;
+
+}
+{code}
+
+In the event it is not possible to acquire the lock a *javax.ejb.ConcurrentAccessException* or *javax.ejb.ConcurrentAccessTimeoutException* will be thrown.
+
+h4. Default Timeout
+
+The default value of *@AccessTimeout* annotation is vendor specific. In OpenEJB it defaults to the value of the *AccessTimeout* property which can be configured in many different scopes. Here is the order of preference:
+
+ # bean-level in openejb-jar.xml/<openejb-jar>/<ejb-deployment>/<properties>
+ # jar-level in openejb-jar.xml/<openejb-jar>/<properties>
+ # container-level in openejb.xml/<openejb>/<Container>
+ # boot-level via InitialContext(Properties) or EJBContainer.createEjbContainer(Map<Object,Object>)
+ # system-level in System.getProperties()
+
+The value of the property can be phrased in plain english such as "1 hour and 23 minutes and 17 seconds" see [Configuring Durations] for details.
+
+h2. Startup and Startup Ordering
+
+Singletons have an *@Startup* annotation which can be applied to the bean class. When used, the Container will instantiate the Singleton instance _eagerly_ when the application starts up, otherwise the Container will instantiate the Singleton instance _lazily_ when the bean is first accessed.
+
+If one Singleton refers to another Singleton in the @PostConstruct or @PreDestroy method, there must be some measure taken to ensure the other Singleton exists and is started. This sort of ordering is achieved with the *@DependsOn* annotation which can be used to list the names of Singleton beans that must be started before the Singleton bean using the annotation.
+
+{code}
+@DependsOn({"SingletonB", "SingletonC"})
+@Singleton
+public class SingletonA {
+
+}
+{code}
+
+Circular references are not supported. If BeanA uses @DependsOn to point to BeanB and BeanB also uses @DependsOn to point at BeanA, the result is a deployment exception. Be aware that circular references can happen in less trivial ways such as A referring to B which refers to C which refers to D which refers back to A. We will detect and print all circular dependencies (called circuits) at deploy time.
+
+Note that @DependsOn is only required (and should only be used) if a Singleton *uses* another Singleton in its @PostConstruct method or @PreDestroy method. Simply having a reference to another Singleton and using it in other business methods does not require an @DependsOn declaration. The @DependsOn allows the Container to calculate the correct startup order and shutdown order so that it can guarantee the Singletons you need are available in your @PostConstruct or @PreDestroy methods. All Singletons will automatically be available to your business methods regardless if @DependsOn is used. Because of the greater chance of creating circular dependencies, it is better not to use the @DependsOn annotation "just in case" and should only be used when truly needed.
+
+h1. XML and Annotation Overriding
+
+Singletons can be declared in the ejb-jar.xml as follows:
+
+{code:xml|title=META-INF/ejb-jar.xml}
+<ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>MySingletonBean</ejb-name>
+ <ejb-class>org.superbiz.MySingletonBean</ejb-class>
+ <session-type>Singleton</session-type>
+ <load-on-startup/>
+ <depends-on>
+ <ejb-name>SingletonFoo</ejb-name>
+ <ejb-name>SingletonBar</ejb-name>
+ </depends-on>
+ </session>
+ </enterprise-beans>
+</ejb-jar>
+{code}
Modified: openejb/site/trunk/content/singleton-beans.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/singleton-beans.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/singleton-beans.mdtext (original)
+++ openejb/site/trunk/content/singleton-beans.mdtext Sun Jul 10 05:36:12 2011
@@ -1,2 +1,226 @@
Title: Singleton Beans
-{include:OPENEJBx30:Singleton Beans}
+<a name="SingletonBeans-SingletonOverview"></a>
+# Singleton Overview
+For the first time in years EJB has a new bean type, the *@Singleton*. In
+my opinion, the javax.ejb.Singleton will replace a lot of what people are
+using @Stateless for today.
+
+The Singleton is essentially what you get if you take a Stateless bean and
+adjust the pool size to be exactly 1 resulting in there being exactly one
+instance of the Singleton bean in the application which can be invoked
+concurrently by multiple threads, like a servlet. It can do everything a
+Stateless can do such as support local and remote business interfaces, web
+services, security, transactions, and more. Additionally, the Singleton
+can have its @PostConstruct method called with the application starts up
+and its @PreDestroy method called when the application shuts down. This
+allows it to serve as an application lifecycle listener which is something
+only Servlets could do before. It has an *@Startup* annotation which is
+similar in concept to the servlet <load-on-startup>, but unlike servlets it
+doesn't take a number as an argument. Instead, you can use an *@DependsOn*
+annotation to say which other Singletons you need and the container will
+ensure they start before you.
+
+See the [Singleton Example](singleton-example.html)
+ for sample bean code and client.
+
+<a name="SingletonBeans-Concurrency"></a>
+## Concurrency
+
+Singletons support two modes of concurrent access, Container-Managed
+Concurrency (the default) and Bean-Managed Concurrency.
+
+<a name="SingletonBeans-Bean-ManagedConcurrency"></a>
+### Bean-Managed Concurrency
+
+With Bean-Managed Concurrency, annotated as *@ConcurrencyManagement(BEAN)*,
+the container sends all invocations into the bean and lets the Singleton
+bean instance decide how and when to synchronize access, if at all. Here
+the 'synchronization' keyword is allowed as well as the full
+javax.util.concurrent set of libraries.
+
+<a name="SingletonBeans-Container-ManagedConcurrency"></a>
+### Container-Managed Concurrency
+
+With Container-Managed Concurrency, annotated as
+*@ConcurrencyManagement(CONTAINER)*, the container will enforce concurrency
+for you via locking method access to the bean. Two modes, called locks
+exist and can be assigned to both the bean class and methods of the bean
+class.
+
+<a name="SingletonBeans-Locktype"></a>
+#### Lock type
+
+The first and the default is a "write" lock, annotated as *@Lock(WRITE)*.
+Essentially, with a write lock the caller holds an exclusive lock on the
+bean for the duration of the method call and all other threads for that or
+any other method must wait.
+
+The second option is a "read" lock, annotated as *@Lock(READ)*. The read
+lock allows full concurrent access to the methods (assuming no write locks
+are held). The default mode of "write" essentially makes your bean a
+single-threaded bean, which is very slow. The more conservative
+@Lock(WRITE) was chosen as the default as this is how all the other bean
+types work (only a single thread may access a bean instance at any given
+time). Those that are aware of how to handle concurrent access can easily
+put @Lock(READ) on their bean class, thus changing the default, and then
+@Lock(WRITE) on specific methods if needed.
+
+The locking modes of Container-Managed Concurrency map directly to the *[java.util.concurrent.ReadWriteLock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReadWriteLock.html)
+* API which looks like this:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>java.util.concurrent.ReadWriteLock</B></DIV><DIV class="codeContent panelContent">
+ public interface ReadWriteLock {
+ /**
+ * Returns the lock used for reading.
+ *
+ * @return the lock used for reading.
+ */
+ Lock readLock();
+
+ /**
+ * Returns the lock used for writing.
+ *
+ * @return the lock used for writing.
+ */
+ Lock writeLock();
+ }
+
+
+Literally 100% of the Singleton locking we're talking about is taken from
+this interface and its javadoc is a great source of information. It's safe
+to imagine that under the covers the Singleton Container has an instance of
+ReadWriteLock which it uses to enforce the locking for all the Singleton
+bean's methods. Essentially:
+
+ - @Lock(READ) == theSingletonReadWriteLock.readLock().lock()
+ - @Lock(WRITE) == theSingletonReadWriteLock.writeLock().lock()
+
+The EJB container may use something other than ReadWriteLock but the
+semantics of a ReadWriteLock must be followed. Internally, we use an
+instance of [java.util.concurrent.ReentrantReadWriteLock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html)
+ which supports correct memory synchronization, some reentrancy, lock
+downgrading, and [more|http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html]
+.
+
+<a name="SingletonBeans-AcquiringtheLock"></a>
+#### Acquiring the Lock
+
+The *@AccessTimetout* annotation can configure how long a thread will wait
+to acquire the read or write lock. This annotation can be used on the bean
+class or individual methods. The annotation maps directly to the [java.util.concurrent.locks.Lock](http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/locks/Lock.html)
+ interface.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>java.util.concurrent.locks.Lock</B></DIV><DIV class="codeContent panelContent">
+ public interface Lock {
+
+ /**
+ * Blocks (potentially) forever
+ *
+ * @AccessTimout with a value of -1
+ */
+ void lock();
+
+ /**
+ * Non-blocking
+ *
+ * @AccessTimout with a value of 0
+ */
+ boolean tryLock();
+
+ /**
+ * Blocks (potentially) up to a limit
+ *
+ * @AccessTimout(30, TimeUnit.SECONDS)
+ */
+ boolean tryLock(long time, TimeUnit unit) throws InterruptedException;
+
+ }
+
+
+In the event it is not possible to acquire the lock a
+*javax.ejb.ConcurrentAccessException* or
+*javax.ejb.ConcurrentAccessTimeoutException* will be thrown.
+
+<a name="SingletonBeans-DefaultTimeout"></a>
+#### Default Timeout
+
+The default value of *@AccessTimeout* annotation is vendor specific. In
+OpenEJB it defaults to the value of the *AccessTimeout* property which can
+be configured in many different scopes. Here is the order of preference:
+
+1. bean-level in
+openejb-jar.xml/<openejb-jar>/<ejb-deployment>/<properties>
+1. jar-level in openejb-jar.xml/<openejb-jar>/<properties>
+1. container-level in openejb.xml/<openejb>/<Container>
+1. boot-level via InitialContext(Properties) or
+EJBContainer.createEjbContainer(Map<Object,Object>)
+1. system-level in System.getProperties()
+
+The value of the property can be phrased in plain english such as "1 hour
+and 23 minutes and 17 seconds" see [Configuring Durations](configuring-durations.html)
+ for details.
+
+<a name="SingletonBeans-StartupandStartupOrdering"></a>
+## Startup and Startup Ordering
+
+Singletons have an *@Startup* annotation which can be applied to the bean
+class. When used, the Container will instantiate the Singleton instance
+_eagerly_ when the application starts up, otherwise the Container will
+instantiate the Singleton instance _lazily_ when the bean is first
+accessed.
+
+If one Singleton refers to another Singleton in the @PostConstruct or
+@PreDestroy method, there must be some measure taken to ensure the other
+Singleton exists and is started. This sort of ordering is achieved with
+the *@DependsOn* annotation which can be used to list the names of
+Singleton beans that must be started before the Singleton bean using the
+annotation.
+
+
+ @DependsOn({"SingletonB", "SingletonC"})
+ @Singleton
+ public class SingletonA {
+
+ }
+
+
+Circular references are not supported. If BeanA uses @DependsOn to point
+to BeanB and BeanB also uses @DependsOn to point at BeanA, the result is a
+deployment exception. Be aware that circular references can happen in less
+trivial ways such as A referring to B which refers to C which refers to D
+which refers back to A. We will detect and print all circular dependencies
+(called circuits) at deploy time.
+
+Note that @DependsOn is only required (and should only be used) if a
+Singleton *uses* another Singleton in its @PostConstruct method or
+@PreDestroy method. Simply having a reference to another Singleton and
+using it in other business methods does not require an @DependsOn
+declaration. The @DependsOn allows the Container to calculate the correct
+startup order and shutdown order so that it can guarantee the Singletons
+you need are available in your @PostConstruct or @PreDestroy methods. All
+Singletons will automatically be available to your business methods
+regardless if @DependsOn is used. Because of the greater chance of
+creating circular dependencies, it is better not to use the @DependsOn
+annotation "just in case" and should only be used when truly needed.
+
+<a name="SingletonBeans-XMLandAnnotationOverriding"></a>
+# XML and Annotation Overriding
+
+Singletons can be declared in the ejb-jar.xml as follows:
+
+{code:xml|title=META-INF/ejb-jar.xml}
+<ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>MySingletonBean</ejb-name>
+ <ejb-class>org.superbiz.MySingletonBean</ejb-class>
+ <session-type>Singleton</session-type>
+ <load-on-startup/>
+ <depends-on>
+ <ejb-name>SingletonFoo</ejb-name>
+ <ejb-name>SingletonBar</ejb-name>
+ </depends-on>
+ </session>
+ </enterprise-beans>
+</ejb-jar>
+
Modified: openejb/site/trunk/content/singleton-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/singleton-example.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/singleton-example.cwiki (original)
+++ openejb/site/trunk/content/singleton-example.cwiki Sun Jul 10 05:36:12 2011
@@ -1 +1,80 @@
-{include:OPENEJBx30:Singleton Example}
\ No newline at end of file
+{tip:title=OpenEJB 3.1 or later required}
+h1. Overview
+
+As the name implies a javax.ejb.Singleton is a session bean with a guarantee that there is at most one instance in the application.
+
+What it gives you that is completely missing in EJB 3.0 and prior versions is the ability to have an EJB that is notified when the application starts and notified when the application stops. So you can do all sorts of things that you previously could only do with a load-on-startup servlet. It also gives you a place to hold data that pertains to the entire application and all users using it, without the need for a static. Additionally, Singleton beans can be invoked by several threads at one time similar to a Servlet.
+
+_See the [Singleton Beans] page for a full description of the javax.ejb.Singleton api._
+
+h1. The Code
+h2. PropertyRegistryBean
+
+Here we see a bean that uses the Bean-Managed Concurrency option as well as the *@Startup* annotation which causes the bean to be instantiated by the container when the application starts. Singleton beans with *@ConcurrencyManagement(BEAN)* are responsible for their own thread-safety. The bean shown is a simple properties "registry" and provides a place where options could be set and retrieved by all beans in the application.
+
+{snippet:url=openejb3/examples/simple-singleton/src/main/java/org/superbiz/registry/PropertyRegistryBean.java|lang=java|id=code}
+
+h2. ComponentRegistryBean
+
+Here we see a bean that uses the Container-Managed Concurrency option, the default. With *@ConcurrencyManagement(CONTAINER)* the container controls whether multi-threaded access should be allowed to the bean (*@Lock(READ)*) or if single-threaded access should be enforced (*@Lock(WRITE)*).
+
+{snippet:url=openejb3/examples/simple-singleton/src/main/java/org/superbiz/registry/ComponentRegistryBean.java|lang=java|id=code}
+
+Unless specified explicitly on the bean class or a method, the default @Lock value is @Lock(WRITE). The code above uses the @Lock(READ) annotation on bean class to change the default so that multi-threaded access is granted by default. We then only need to apply the @Lock(WRITE) annotation to the methods that modify the state of the bean.
+
+Essentially @Lock(READ) allows multithreaded access to the Singleton bean instance *unless* someone is invoking an @Lock(WRITE) method. With @Lock(WRITE), the thread invoking the bean will be guaranteed to have exclusive access to the Singleton bean instance for the duration of its invocation. This combination allows the bean instance to use data types that are not normally thread safe. Great care must still be used, though.
+
+In the example we see ComponentRegistryBean using a java.util.HashMap which is not synchronized. To make this ok we do three things:
+
+ # Encapsulation. We don't expose the HashMap instance directly; including its iterators, key set, value set or entry set.
+ # We use @Lock(WRITE) on the methods that mutate the map such as the put() and remove() methods.
+ # We use @Lock(READ) on the get() and values() methods as they do not change the map state and are guaranteed not to be called at the same as any of the @Lock(WRITE) methods, so we know the state of the HashMap is no being mutated and therefore safe for reading.
+
+The end result is that the threading model for this bean will switch from multi-threaded access to single-threaded access dynamically as needed depending on the which methods are being invoked. This gives Singletons a bit of an advantage over Servlets for processing multi-threaded requests.
+
+_See the [Singleton Beans] page for more advanced details on Container-Managed Concurrency._
+
+h1. Test Case
+
+{snippet:url=openejb3/examples/simple-singleton/src/test/java/org/superbiz/registry/ComponentRegistryBeanTest.java|lang=java|id=code}
+
+h1. Running
+
+Running the example is fairly simple. In the "simple-singleton" directory run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+{noformat}
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.superbiz.registry.ComponentRegistryBeanTest
+Apache OpenEJB 3.1-SNAPSHOT build: 20080820-09:53
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb3/examples/simple-singleton
+INFO - openejb.base = /Users/dblevins/work/openejb3/examples/simple-singleton
+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/work/openejb3/examples/simple-singleton/target/classes
+INFO - Beginning load: /Users/dblevins/work/openejb3/examples/simple-singleton/target/classes
+INFO - Configuring enterprise application: classpath.ear
+INFO - Configuring Service(id=Default Singleton Container, type=Container, provider-id=Default Singleton Container)
+INFO - Auto-creating a container for bean ComponentRegistryBean: Container(type=SINGLETON, id=Default Singleton Container)
+INFO - Enterprise application "classpath.ear" loaded.
+INFO - Assembling app: classpath.ear
+INFO - Jndi(name=ComponentRegistryBeanLocal) --> Ejb(deployment-id=ComponentRegistryBean)
+INFO - Jndi(name=PropertyRegistryBeanLocal) --> Ejb(deployment-id=PropertyRegistryBean)
+INFO - Created Ejb(deployment-id=ComponentRegistryBean, ejb-name=ComponentRegistryBean, container=Default Singleton Container)
+INFO - Created Ejb(deployment-id=PropertyRegistryBean, ejb-name=PropertyRegistryBean, container=Default Singleton Container)
+INFO - Deployed Application(path=classpath.ear)
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.879 sec
+Running org.superbiz.registry.PropertiesRegistryBeanTest
+Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.009 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
Modified: openejb/site/trunk/content/singleton-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/singleton-example.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/singleton-example.mdtext (original)
+++ openejb/site/trunk/content/singleton-example.mdtext Sun Jul 10 05:36:12 2011
@@ -1,2 +1,135 @@
Title: Singleton Example
-{include:OPENEJBx30:Singleton Example}
+{tip:title=OpenEJB 3.1 or later required}
+<a name="SingletonExample-Overview"></a>
+# Overview
+
+As the name implies a javax.ejb.Singleton is a session bean with a
+guarantee that there is at most one instance in the application.
+
+What it gives you that is completely missing in EJB 3.0 and prior versions
+is the ability to have an EJB that is notified when the application starts
+and notified when the application stops. So you can do all sorts of things
+that you previously could only do with a load-on-startup servlet. It also
+gives you a place to hold data that pertains to the entire application and
+all users using it, without the need for a static. Additionally, Singleton
+beans can be invoked by several threads at one time similar to a Servlet.
+
+_See the [Singleton Beans](singleton-beans.html)
+ page for a full description of the javax.ejb.Singleton api._
+
+<a name="SingletonExample-TheCode"></a>
+# The Code
+<a name="SingletonExample-PropertyRegistryBean"></a>
+## PropertyRegistryBean
+
+Here we see a bean that uses the Bean-Managed Concurrency option as well as
+the *@Startup* annotation which causes the bean to be instantiated by the
+container when the application starts. Singleton beans with
+*@ConcurrencyManagement(BEAN)* are responsible for their own thread-safety.
+ The bean shown is a simple properties "registry" and provides a place
+where options could be set and retrieved by all beans in the application.
+
+{snippet:url=openejb3/examples/simple-singleton/src/main/java/org/superbiz/registry/PropertyRegistryBean.java|lang=java|id=code}
+
+<a name="SingletonExample-ComponentRegistryBean"></a>
+## ComponentRegistryBean
+
+Here we see a bean that uses the Container-Managed Concurrency option, the
+default. With *@ConcurrencyManagement(CONTAINER)* the container controls
+whether multi-threaded access should be allowed to the bean (*@Lock(READ)*)
+or if single-threaded access should be enforced (*@Lock(WRITE)*).
+
+{snippet:url=openejb3/examples/simple-singleton/src/main/java/org/superbiz/registry/ComponentRegistryBean.java|lang=java|id=code}
+
+Unless specified explicitly on the bean class or a method, the default
+@Lock value is @Lock(WRITE). The code above uses the @Lock(READ)
+annotation on bean class to change the default so that multi-threaded
+access is granted by default. We then only need to apply the @Lock(WRITE)
+annotation to the methods that modify the state of the bean.
+
+Essentially @Lock(READ) allows multithreaded access to the Singleton bean
+instance *unless* someone is invoking an @Lock(WRITE) method. With
+@Lock(WRITE), the thread invoking the bean will be guaranteed to have
+exclusive access to the Singleton bean instance for the duration of its
+invocation. This combination allows the bean instance to use data types
+that are not normally thread safe. Great care must still be used, though.
+
+In the example we see ComponentRegistryBean using a java.util.HashMap which
+is not synchronized. To make this ok we do three things:
+
+1. Encapsulation. We don't expose the HashMap instance directly; including
+its iterators, key set, value set or entry set.
+1. We use @Lock(WRITE) on the methods that mutate the map such as the put()
+and remove() methods.
+1. We use @Lock(READ) on the get() and values() methods as they do not
+change the map state and are guaranteed not to be called at the same as any
+of the @Lock(WRITE) methods, so we know the state of the HashMap is no
+being mutated and therefore safe for reading.
+
+The end result is that the threading model for this bean will switch from
+multi-threaded access to single-threaded access dynamically as needed
+depending on the which methods are being invoked. This gives Singletons a
+bit of an advantage over Servlets for processing multi-threaded requests.
+
+_See the [Singleton Beans](singleton-beans.html)
+ page for more advanced details on Container-Managed Concurrency._
+
+<a name="SingletonExample-TestCase"></a>
+# Test Case
+
+{snippet:url=openejb3/examples/simple-singleton/src/test/java/org/superbiz/registry/ComponentRegistryBeanTest.java|lang=java|id=code}
+
+<a name="SingletonExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "simple-singleton" directory
+run:
+
+$ mvn clean install
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.registry.ComponentRegistryBeanTest
+ Apache OpenEJB 3.1-SNAPSHOT build: 20080820-09:53
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb3/examples/simple-singleton
+ INFO - openejb.base =
+/Users/dblevins/work/openejb3/examples/simple-singleton
+ 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/work/openejb3/examples/simple-singleton/target/classes
+ INFO - Beginning load:
+/Users/dblevins/work/openejb3/examples/simple-singleton/target/classes
+ INFO - Configuring enterprise application: classpath.ear
+ INFO - Configuring Service(id=Default Singleton Container, type=Container,
+provider-id=Default Singleton Container)
+ INFO - Auto-creating a container for bean ComponentRegistryBean:
+Container(type=SINGLETON, id=Default Singleton Container)
+ INFO - Enterprise application "classpath.ear" loaded.
+ INFO - Assembling app: classpath.ear
+ INFO - Jndi(name=ComponentRegistryBeanLocal) -->
+Ejb(deployment-id=ComponentRegistryBean)
+ INFO - Jndi(name=PropertyRegistryBeanLocal) -->
+Ejb(deployment-id=PropertyRegistryBean)
+ INFO - Created Ejb(deployment-id=ComponentRegistryBean,
+ejb-name=ComponentRegistryBean, container=Default Singleton Container)
+ INFO - Created Ejb(deployment-id=PropertyRegistryBean,
+ejb-name=PropertyRegistryBean, container=Default Singleton Container)
+ INFO - Deployed Application(path=classpath.ear)
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.879 sec
+ Running org.superbiz.registry.PropertiesRegistryBeanTest
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.009 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
Modified: openejb/site/trunk/content/space-index.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/space-index.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/space-index.cwiki (original)
+++ openejb/site/trunk/content/space-index.cwiki Sun Jul 10 05:36:12 2011
@@ -1,3 +1,3 @@
+{index}
-{index}
\ No newline at end of file
Modified: openejb/site/trunk/content/space-index.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/space-index.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/space-index.mdtext (original)
+++ openejb/site/trunk/content/space-index.mdtext Sun Jul 10 05:36:12 2011
@@ -1,4 +1,4 @@
Title: Space Index
-
{index}
+
Added: openejb/site/trunk/content/spring-and-openejb-3.0.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/spring-and-openejb-3.0.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/spring-and-openejb-3.0.cwiki (added)
+++ openejb/site/trunk/content/spring-and-openejb-3.0.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,191 @@
+{note}OpenEJB 3.1 and later users should refer to the [Spring] page.{note}
+h1. Bootstrapping OpenEJB in Spring
+
+If you wish to use OpenEJB inside Spring you can do so pretty easily. Include OpenEJB and its dependencies in your classpath as you would in a plain embedded scenario then add a custom factory like the following:
+
+{code:title=OpenEjbFactoryBean.java}
+public class OpenEjbFactoryBean implements org.springframework.beans.factory.FactoryBean {
+
+ private Properties properties = new Properties();
+
+ public OpenEjbFactoryBean() {
+ properties.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
+ }
+
+ public Properties getJndiEnvironment() {
+ return properties;
+ }
+
+ public void setJndiEnvironment(Properties properties) {
+ this.properties.putAll(properties);
+ }
+
+ public Object getObject() {
+ try {
+ return new InitialContext(properties);
+ } catch (NamingException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public Class getObjectType(){
+ return Context.class;
+ }
+
+ boolean isSingleton() {
+ return true;
+ }
+}
+{code}
+
+And include that at the top of your spring xml file as follows:
+
+{code:xml|title=top of spring xml}
+<bean id="OpenEjbContext" class="org.acme.OpenEjbFactoryBean">
+ <property name="jndiEnvironment">
+ <props>
+ <prop key="myDs">new://Resource?type=DataSource</prop>
+ <prop key="myDs.JdbcDriver">com.mysql.jdbc.Driver</prop>
+ <prop key="myDs.JdbcUrl">jdbc:mysql://localhost/midastest?createDatabaseIfNotExist=true</prop>
+ <prop key="myDs.UserName">root</prop>
+ <prop key="myDs.Password"></prop>
+ </props>
+ </property>
+</bean>
+{code}
+
+The value of <props> is meant to be illustrative of the kinds of properties you can pass into OpenEJB. It's possible to create any number of datasources, topics, queues, containers and more this way.
+
+Just as with Unit Testing, OpenEJB will find and automatically deploy all the EJB beans it [finds in the classpath|Application discovery via the classpath]. You can then expose any of these things to other Spring components with custom factory beans.
+
+h1. Injecting OpenEJB-created resources into Spring components
+
+If you want to have any of the Topics, Queues, DataSources, EntityManagers or more that OpenEJB creates injected into components that Spring creates, here's one technique....
+
+Let's say you have a persistence unit called "*OrangeUnit*" declared in a persistence.xml file. One way to get the related *EntityManager* created by OpenEJB is to do as follows. Create an @Stateless bean with an @PersistenceContext ref in it, then use a factory bean to look it up, pull the EntityManager out and return it
+
+{code:title=OrangeUnitBean.java}
+/*
+ * OpenEJB will automatically find this bean. Just put it in the same jar
+ * that your META-INF/persistence.xml file is located in and make sure that
+ * that same jar file also has a META-INF/ejb-jar.xml file. The ejb-jar.xml
+ * need only contain the text "<ejb-jar/>" at minimum.
+ */
+@Stateless
+public class OrangeUnitBean implements OrangeUnitLocal {
+
+ @PersistenceContext(unitName="OrangeUnit")
+ private EntityManager entityManager;
+
+ public EntityManager getEntityManager() {
+ return entityManager;
+ }
+}
+{code}
+
+{code:title=OrangeUnitLocal.java}
+/**
+ * The local interface for the OrangeUnitBean
+ */
+public interface OrangeUnitLocal {
+ public EntityManager getEntityManager();
+}
+{code}
+
+{code:title=OrangeUnitFactoryBean.java}
+/**
+ * This factory bean will lookup the OrangeUnitBean using the javax.naming.Context
+ * that is created via the OpenEjbFactoryBean above. It will simply grab the EntityManager
+ * from that bean and hand it over to Spring. Anyone in Spring-land can then easily get
+ * a reference to the EntityManager by simply referencing this factory bean.
+ */
+public class OrangeUnitFactoryBean implements org.springframework.beans.factory.FactoryBean {
+ private Context context;
+
+ public Context getContext() {
+ return context;
+ }
+
+ public void setContext(Context context) {
+ this.context = context;
+ }
+
+ public Object getObject() {
+ try {
+ ResourceLocal bean = (ResourceLocal) context.lookup("OrangeUnitBeanLocal");
+ return bean.getEntityManager();
+ } catch (NamingException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ public Class getObjectType(){
+ return EntityManager.class;
+ }
+
+ boolean isSingleton() {
+ return true;
+ }
+}
+{code}
+
+The factory bean would then be declared in your spring xml file as follows:
+
+{code:xml|title=in the spring xml}
+<bean id="OrangeUnit" class="org.acme.OrangeUnitFactoryBean">
+ <property name="context" ref="OpenEjbContext">
+</bean>
+{code}
+
+The EntityManager can then easily be consumed by a spring bean.
+
+{code:title=SomePojo.java}
+public class SomePojo {
+
+ private EntityManager entityManager;
+
+ public void setEntityManager(EntityManager entityManager) {
+ this.entityManager = entityManager;
+ }
+
+ ...
+}
+{code}
+{code:xml|title=in the spring xml}
+<bean id="SomePojo" class="org.acme.SomePojo">
+ <property name="entityManager" ref="OrangeUnit">
+</bean>
+{code}
+
+Here's what all three declarations would look like together in your spring xml:
+
+{code:xml|title=spring bean definitions combined}
+<bean id="OpenEjbContext" class="org.acme.OpenEjbFactoryBean">
+ <property name="jndiEnvironment">
+ <props>
+ <prop key="myDs">new://Resource?type=DataSource</prop>
+ <prop key="myDs.JdbcDriver">com.mysql.jdbc.Driver</prop>
+ <prop key="myDs.JdbcUrl">jdbc:mysql://localhost/midastest?createDatabaseIfNotExist=true</prop>
+ <prop key="myDs.UserName">root</prop>
+ <prop key="myDs.Password"></prop>
+ </props>
+ </property>
+</bean>
+
+<bean id="OrangeUnit" class="org.acme.OrangeUnitFactoryBean">
+ <property name="context" ref="OpenEjbContext">
+</bean>
+
+<bean id="SomePojo" class="org.acme.SomePojo">
+ <property name="entityManager" ref="OrangeUnit">
+</bean>
+{code}
+
+{info:title=Some more useful info.}
+Here is a bunch of links suggested by a user. If anybody has time to go through them and write a doc, that would be great. These links explain how to make available spring components to openejb
+http://twasink.net/blog/archives/2007/01/using_spring_wi.html
+http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/ejb/interceptor/SpringBeanAutowiringInterceptor.html
+http://wiki.netbeans.org/MavenSpringEJBsOnGlassfish
+
+{info}
+
Propchange: openejb/site/trunk/content/spring-and-openejb-3.0.cwiki
------------------------------------------------------------------------------
svn:eol-style = native