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 [5/13] - /openejb/site/trunk/content/
Added: openejb/site/trunk/content/ejb-ref.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/ejb-ref.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/ejb-ref.mdtext (added)
+++ openejb/site/trunk/content/ejb-ref.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,53 @@
+Title: ejb-ref
+<a name="ejb-ref-Viaannotation"></a>
+# Via annotation
+
+<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>Usable by EJB, Interceptor, Servlet, Filter, or Listener</B></DIV><DIV class="codeContent panelContent">
+ package org.superbiz.refs;
+
+ import javax.ejb.EJB;
+ import javax.ejb.Stateless;
+ import javax.naming.InitialContext;
+
+ @Stateless
+ @EJB(name = "myFooEjb", beanInterface = FooRemote.class)
+ public class MyEjbRemoteRefBean implements MyBeanInterface {
+
+ @EJB
+ private BarRemote myBarEjb;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarEjb == null) throw new NullPointerException("myBarEjb not
+injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ FooRemote fooRemote = (FooRemote)
+context.lookup("java:comp/env/myFooEjb");
+ BarRemote barRemote = (BarRemote)
+context.lookup("java:comp/env/org.superbiz.refs.MyEjbRemoteRefBean/myBarEjb");
+ }
+ }
+
+
+<a name="ejb-ref-Viaxml"></a>
+# Via xml
+
+The above @EJB annotation usage is 100% equivalent to the following xml.
+
+{code:xml|title=ejb-jar.xml or web.xml}
+<ejb-ref>
+ <ejb-ref-name>myFooEjb</ejb-ref-name>
+ <remote>org.superbiz.refs.FooRemote</remote>
+</ejb-ref>
+<ejb-ref>
+
+<ejb-ref-name>org.superbiz.refs.MyEjbRemoteRefBean/myBarEjb</ejb-ref-name>
+ <remote>org.superbiz.refs.BarRemote</remote>
+ <injection-target>
+
+<injection-target-class>org.superbiz.refs.MyEjbRemoteRefBean</injection-target-class>
+ <injection-target-name>myBarEjb</injection-target-name>
+ </injection-target>
+</ejb-ref>
+
Added: openejb/site/trunk/content/ejb-refs.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/ejb-refs.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/ejb-refs.cwiki (added)
+++ openejb/site/trunk/content/ejb-refs.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,104 @@
+h2. Referencing a bean in another jar (with annotations)
+
+When using annotations to reference a bean from another ejb in your ear you have to supplement the @EJB reference with a small chunk of xml in the ejb-jar.xml of the referring bean.
+
+So in ejb app A colorsApp.jar you have this bean:
+
+{code}
+package com.foo.colors;
+
+import javax.ejb.Stateless;
+
+@Stateless
+public class OrangeBean implements OrangeRemote {
+}
+{code}
+
+Then in ejb app B shapesApp.jar you have this bean with a reference to OrangeRemote:
+
+{code}
+package com.foo.shapes;
+
+import javax.ejb.Stateless;
+import com.foo.colors.OrangeRemote;
+
+@Stateless
+public class SquareBean implements SquareRemote {
+ @EJB OrangeRemote orangeRemote;
+}
+{code}
+
+To hook this reference up you need to override this ref and add more info in the ejb-jar.xml of shapesApp.jar as follows:
+
+{code:xml}
+<ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+</ejb-jar>
+{code}
+
+h2. Referencing a bean in another jar (xml only, no annotations)
+
+The same basic approach applies and dependency injection is still possible, however more information must be described in the xml.
+
+
+In ejb app A colorsApp.jar you have this bean:
+
+{code}
+package com.foo.colors;
+
+import javax.ejb.Stateless;
+
+@Stateless
+public class OrangeBean implements OrangeRemote {
+}
+{code}
+
+Then in ejb app B shapesApp.jar -- note there is no @EJB annotation:
+
+{code}
+package com.foo.shapes;
+
+import javax.ejb.Stateless;
+import com.foo.colors.OrangeRemote;
+
+@Stateless
+public class SquareBean implements SquareRemote {
+ OrangeRemote orangeRemote;
+}
+{code}
+
+Here's how you would hook this reference up, injection and all, with just xml. The following would be added to the ejb-jar.xml of shapesApp.jar:
+
+{code:xml}
+<ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <remote>com.foo.colors.OrangeRemote</remote>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ <injection-target>
+ <injection-target-class>com.foo.shapes.SquareBean</injection-target-class>
+ <injection-target-name>orangeRemote</injection-target-name>
+ </injection-target>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+</ejb-jar>
+{code}
+
+Note that the value of <ejb-ref-name> could actually be anything and the above example would still work as there is no annotation that needs to match the <ejb-ref-name> and no one will likely be looking up the EJB as it's injected.
\ No newline at end of file
Propchange: openejb/site/trunk/content/ejb-refs.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/ejb-refs.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/ejb-refs.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/ejb-refs.mdtext (added)
+++ openejb/site/trunk/content/ejb-refs.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,117 @@
+Title: EJB Refs
+<a name="EJBRefs-Referencingabeaninanotherjar(withannotations)"></a>
+## Referencing a bean in another jar (with annotations)
+
+When using annotations to reference a bean from another ejb in your ear you
+have to supplement the @EJB reference with a small chunk of xml in the
+ejb-jar.xml of the referring bean.
+
+So in ejb app A colorsApp.jar you have this bean:
+
+
+ package com.foo.colors;
+
+ import javax.ejb.Stateless;
+
+ @Stateless
+ public class OrangeBean implements OrangeRemote {
+ }
+
+
+Then in ejb app B shapesApp.jar you have this bean with a reference to
+OrangeRemote:
+
+
+ package com.foo.shapes;
+
+ import javax.ejb.Stateless;
+ import com.foo.colors.OrangeRemote;
+
+ @Stateless
+ public class SquareBean implements SquareRemote {
+ @EJB OrangeRemote orangeRemote;
+ }
+
+
+To hook this reference up you need to override this ref and add more info
+in the ejb-jar.xml of shapesApp.jar as follows:
+
+
+ <ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+ </ejb-jar>
+
+
+<a name="EJBRefs-Referencingabeaninanotherjar(xmlonly,noannotations)"></a>
+## Referencing a bean in another jar (xml only, no annotations)
+
+The same basic approach applies and dependency injection is still possible,
+however more information must be described in the xml.
+
+
+In ejb app A colorsApp.jar you have this bean:
+
+
+ package com.foo.colors;
+
+ import javax.ejb.Stateless;
+
+ @Stateless
+ public class OrangeBean implements OrangeRemote {
+ }
+
+
+Then in ejb app B shapesApp.jar -- note there is no @EJB annotation:
+
+
+ package com.foo.shapes;
+
+ import javax.ejb.Stateless;
+ import com.foo.colors.OrangeRemote;
+
+ @Stateless
+ public class SquareBean implements SquareRemote {
+ OrangeRemote orangeRemote;
+ }
+
+
+Here's how you would hook this reference up, injection and all, with just
+xml. The following would be added to the ejb-jar.xml of shapesApp.jar:
+
+
+ <ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <remote>com.foo.colors.OrangeRemote</remote>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ <injection-target>
+
+<injection-target-class>com.foo.shapes.SquareBean</injection-target-class>
+ <injection-target-name>orangeRemote</injection-target-name>
+ </injection-target>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+ </ejb-jar>
+
+
+Note that the value of <ejb-ref-name> could actually be anything and the
+above example would still work as there is no annotation that needs to
+match the <ejb-ref-name> and no one will likely be looking up the EJB as
+it's injected.
Added: openejb/site/trunk/content/ejb-servlet.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/ejb-servlet.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/ejb-servlet.cwiki (added)
+++ openejb/site/trunk/content/ejb-servlet.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,41 @@
+{code}
+package org.superbiz;
+
+import org.apache.openejb.loader.SystemInstance;
+import org.apache.openejb.server.ServiceException;
+import org.apache.openejb.server.ejbd.EjbServer;
+
+import javax.servlet.ServletConfig;
+import javax.servlet.ServletException;
+import javax.servlet.ServletInputStream;
+import javax.servlet.ServletOutputStream;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+
+public class EjbServerServlet extends HttpServlet {
+ private EjbServer ejbServer;
+
+ public void init(ServletConfig config) throws ServletException {
+ ejbServer = new EjbServer();
+
+ try {
+ ejbServer.init(System.getProperties());
+ } catch (Exception e) {
+ throw new ServletException(e);
+ }
+ }
+
+ protected void service(HttpServletRequest request, HttpServletResponse response)
+ throws ServletException, IOException {
+ ServletInputStream in = request.getInputStream();
+ ServletOutputStream out = response.getOutputStream();
+ try {
+ ejbServer.service(in, out);
+ } catch (ServiceException e) {
+ throw new ServletException("ServerService error", e);
+ }
+ }
+}
+{code}
\ No newline at end of file
Propchange: openejb/site/trunk/content/ejb-servlet.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/ejb-servlet.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/ejb-servlet.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/ejb-servlet.mdtext (added)
+++ openejb/site/trunk/content/ejb-servlet.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,43 @@
+Title: EJB Servlet
+
+ package org.superbiz;
+
+ import org.apache.openejb.loader.SystemInstance;
+ import org.apache.openejb.server.ServiceException;
+ import org.apache.openejb.server.ejbd.EjbServer;
+
+ import javax.servlet.ServletConfig;
+ import javax.servlet.ServletException;
+ import javax.servlet.ServletInputStream;
+ import javax.servlet.ServletOutputStream;
+ import javax.servlet.http.HttpServlet;
+ import javax.servlet.http.HttpServletRequest;
+ import javax.servlet.http.HttpServletResponse;
+ import java.io.IOException;
+
+ public class EjbServerServlet extends HttpServlet {
+ private EjbServer ejbServer;
+
+ public void init(ServletConfig config) throws ServletException {
+ ejbServer = new EjbServer();
+
+ try {
+ ejbServer.init(System.getProperties());
+ } catch (Exception e) {
+ throw new ServletException(e);
+ }
+ }
+
+ protected void service(HttpServletRequest request, HttpServletResponse
+response)
+ throws ServletException, IOException {
+ ServletInputStream in = request.getInputStream();
+ ServletOutputStream out = response.getOutputStream();
+ try {
+ ejbServer.service(in, out);
+ } catch (ServiceException e) {
+ throw new ServletException("ServerService error", e);
+ }
+ }
+ }
+
Added: openejb/site/trunk/content/embedded-and-remotable.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedded-and-remotable.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/embedded-and-remotable.cwiki (added)
+++ openejb/site/trunk/content/embedded-and-remotable.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,115 @@
+h1. Overview
+
+This example shows how to use OpenEJB3's remoting capabilities in an embedded scenario. By remoting we mean that you wish to allow *clients in other vms* access your ejbs. _Note, you do not need to go to this extreme to unit test ejbs with remote interfaces._
+
+The basic recipe is the same for a standard embedded scenario but with these added ingreditents:
+
+ * *openejb.embedded.remotable* property
+ * *openejb-ejbd* jar
+
+While creating the InitialContext, pass in the openejb.embedded.remotable property with the value of "true". When this is seen by the LocalInitialContextFactory, it will boot up the Server ServiceManager in the VM which will in turn look for ServerServices in the classpath.
+
+Provided you have the openejb-ejbd jar in your classpath along with it's dependencies (openejb-server, openejb-client, openejb-core), then those services will be brought online and remote clients will be able to connect into your vm and invoke beans.
+
+If you want to add more ServerServices such as the http version of the ejbd protocol you'd simply add the openejb-httpejbd jar to your classpath. A number of ServerServices are available currently:
+
+ * openejb-ejbd
+ * openejb-http
+ * openejb-telnet
+ * openejb-derbynet
+ * openejb-hsql
+ * openejb-activemq
+
+_The source for this example is in the "telephone-stateful" directory located in the [openejb-examples.zip|OPENEJB:Download] available on the download page._
+
+{note}
+If your goal is simply to unit test beans with remote interfaces, this is *not* the right example for you. The LocalInitialContextFactory completely supports remote interfaces and all spec required pass-by-value (serialization) semantics without the need for network sockets. This example shows the use of OpenEJB in an embedded environment where connection *outside* the
+vm is required.{note}
+
+h1. The Code
+
+For this example we have a simple Stateful bean called TelephoneBean as defined below. As a simple way of demonstrating the state we have to methods: speak and listen. You call _speak_ and pass in some text, then you call _listen_ to get your answer.
+
+h2. bean
+
+{snippet:id=code|url=openejb3/examples/telephone-stateful/src/main/java/org/superbiz/telephone/TelephoneBean.java|lang=java}
+
+h2. business interface
+
+{snippet:id=code|url=openejb3/examples/telephone-stateful/src/main/java/org/superbiz/telephone/Telephone.java|lang=java}
+
+{tip:title=EJB3 Notes}
+The bean class uses the annotation *@Remote* but does not specify a list of interfaces as is normally required. Per EJB3 rules, if the bean implements exactly *one business interface* it may use @Remote with no other values and that business interface is then implied to be a remote business interface. The same rule applies to identical usage of @Local.
+
+The critical thing to know is that if you add another interface the rules change and require that you specify both interfaces in the @Remote annotation as in @Remote(\{Telephone.class, SecondInterface.class\}).
+{tip}
+
+h1. Embedding
+
+We're going to embed OpenEJB3 into a plain JUnit TestCase as a simple means of demonstrating the remote capabilities. We'll do the embedding in our test setUp method, then will make two test methods:
+ - one for invoking the bean's remote interface via the *LocalInitialContextFactory* which goes straight against the embedded container system
+ - one for invoking the bean's remote interface via the *RemoteInitialContextFactory* which connects to a Socket and communicates to the embedded container system over the ejbd protocol.
+
+h2. setUp
+
+{snippet:id=setup|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+h2. LocalInitialContextFactory: making in-vm calls to a remote business interface
+
+{snippet:id=localcontext|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+h2. RemoteInitialContextFactory: making networked calls to a remote business interface
+
+This is the part you would want to do in apps that are running a different VM than the one in which the ejb container is embedded. These "client" VMs need only have the the *openejb-client jar* in their classpath and connect to OpenEJB via the RemoteInitialContextFactory like any other remote EJB client.
+
+{snippet:id=remotecontext|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+h1. Maven setup
+
+{snippet:id=desc|url=openejb3/examples/telephone-stateful/pom.xml}
+
+{snippet:id=openejbdep|url=openejb3/examples/telephone-stateful/pom.xml|lang=xml}
+
+
+h1. Running
+
+Running the example is fairly simple. In the "telephone-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.telephone.TelephoneTest
+Apache OpenEJB 3.0 build: 20080408-04:13
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.0/examples/telephone-stateful
+INFO - openejb.base = /Users/dblevins/work/openejb-3.0/examples/telephone-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/telephone-stateful/target/classes
+INFO - Configuring app: /Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container)
+INFO - Auto-creating a container for bean TelephoneBean: Container(type=STATEFUL, id=Default Stateful Container)
+INFO - Loaded Module: /Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+INFO - Assembling app: /Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+INFO - Jndi(name=TelephoneBeanRemote) --> Ejb(deployment-id=TelephoneBean)
+INFO - Created Ejb(deployment-id=TelephoneBean, ejb-name=TelephoneBean, container=Default Stateful Container)
+INFO - Deployed Application(path=/Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes)
+ ** Starting Services **
+ NAME IP PORT
+ ejbd 127.0.0.1 4201
+ admin thread 127.0.0.1 4200
+-------
+Ready!
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.89 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
Propchange: openejb/site/trunk/content/embedded-and-remotable.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/embedded-and-remotable.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedded-and-remotable.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/embedded-and-remotable.mdtext (added)
+++ openejb/site/trunk/content/embedded-and-remotable.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,179 @@
+Title: Embedded and Remotable
+<a name="EmbeddedandRemotable-Overview"></a>
+# Overview
+
+This example shows how to use OpenEJB3's remoting capabilities in an
+embedded scenario. By remoting we mean that you wish to allow *clients in
+other vms* access your ejbs. _Note, you do not need to go to this extreme
+to unit test ejbs with remote interfaces._
+
+The basic recipe is the same for a standard embedded scenario but with
+these added ingreditents:
+
+ * *openejb.embedded.remotable* property
+ * *openejb-ejbd* jar
+
+While creating the InitialContext, pass in the openejb.embedded.remotable
+property with the value of "true". When this is seen by the
+LocalInitialContextFactory, it will boot up the Server ServiceManager in
+the VM which will in turn look for ServerServices in the classpath.
+
+Provided you have the openejb-ejbd jar in your classpath along with it's
+dependencies (openejb-server, openejb-client, openejb-core), then those
+services will be brought online and remote clients will be able to connect
+into your vm and invoke beans.
+
+If you want to add more ServerServices such as the http version of the ejbd
+protocol you'd simply add the openejb-httpejbd jar to your classpath. A
+number of ServerServices are available currently:
+
+ * openejb-ejbd
+ * openejb-http
+ * openejb-telnet
+ * openejb-derbynet
+ * openejb-hsql
+ * openejb-activemq
+
+_The source for this example is in the "telephone-stateful" directory
+located in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+{note}
+If your goal is simply to unit test beans with remote interfaces, this is
+*not* the right example for you. The LocalInitialContextFactory completely
+supports remote interfaces and all spec required pass-by-value
+(serialization) semantics without the need for network sockets. This
+example shows the use of OpenEJB in an embedded environment where
+connection *outside* the
+vm is required.{note}
+
+<a name="EmbeddedandRemotable-TheCode"></a>
+# The Code
+
+For this example we have a simple Stateful bean called TelephoneBean as
+defined below. As a simple way of demonstrating the state we have to
+methods: speak and listen. You call _speak_ and pass in some text, then
+you call _listen_ to get your answer.
+
+<a name="EmbeddedandRemotable-bean"></a>
+## bean
+
+{snippet:id=code|url=openejb3/examples/telephone-stateful/src/main/java/org/superbiz/telephone/TelephoneBean.java|lang=java}
+
+<a name="EmbeddedandRemotable-businessinterface"></a>
+## business interface
+
+{snippet:id=code|url=openejb3/examples/telephone-stateful/src/main/java/org/superbiz/telephone/Telephone.java|lang=java}
+
+{tip:title=EJB3 Notes}
+The bean class uses the annotation *@Remote* but does not specify a list of
+interfaces as is normally required. Per EJB3 rules, if the bean implements
+exactly *one business interface* it may use @Remote with no other values
+and that business interface is then implied to be a remote business
+interface. The same rule applies to identical usage of @Local.
+
+The critical thing to know is that if you add another interface the rules
+change and require that you specify both interfaces in the @Remote
+annotation as in @Remote(\{Telephone.class, SecondInterface.class\}).
+{tip}
+
+<a name="EmbeddedandRemotable-Embedding"></a>
+# Embedding
+
+We're going to embed OpenEJB3 into a plain JUnit TestCase as a simple means
+of demonstrating the remote capabilities. We'll do the embedding in our
+test setUp method, then will make two test methods:
+ - one for invoking the bean's remote interface via the
+*LocalInitialContextFactory* which goes straight against the embedded
+container system
+ - one for invoking the bean's remote interface via the
+*RemoteInitialContextFactory* which connects to a Socket and communicates
+to the embedded container system over the ejbd protocol.
+
+<a name="EmbeddedandRemotable-setUp"></a>
+## setUp
+
+{snippet:id=setup|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+h2. LocalInitialContextFactory: making in-vm calls to a remote business
+interface
+
+{snippet:id=localcontext|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+h2. RemoteInitialContextFactory: making networked calls to a remote
+business interface
+
+This is the part you would want to do in apps that are running a different
+VM than the one in which the ejb container is embedded. These "client" VMs
+need only have the the *openejb-client jar* in their classpath and connect
+to OpenEJB via the RemoteInitialContextFactory like any other remote EJB
+client.
+
+{snippet:id=remotecontext|url=openejb3/examples/telephone-stateful/src/test/java/org/superbiz/telephone/TelephoneTest.java|lang=java}
+
+<a name="EmbeddedandRemotable-Mavensetup"></a>
+# Maven setup
+
+{snippet:id=desc|url=openejb3/examples/telephone-stateful/pom.xml}
+
+{snippet:id=openejbdep|url=openejb3/examples/telephone-stateful/pom.xml|lang=xml}
+
+
+<a name="EmbeddedandRemotable-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "telephone-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.telephone.TelephoneTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/telephone-stateful
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/telephone-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/telephone-stateful/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+ INFO - Configuring Service(id=Default Stateful Container, type=Container,
+provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean TelephoneBean:
+Container(type=STATEFUL, id=Default Stateful Container)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes
+ INFO - Jndi(name=TelephoneBeanRemote) --> Ejb(deployment-id=TelephoneBean)
+ INFO - Created Ejb(deployment-id=TelephoneBean, ejb-name=TelephoneBean,
+container=Default Stateful Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/telephone-stateful/target/classes)
+ ** Starting Services **
+ NAME IP PORT
+ ejbd 127.0.0.1 4201
+ admin thread 127.0.0.1 4200
+ -------
+ Ready!
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.89 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
Added: openejb/site/trunk/content/embedded-configuration.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedded-configuration.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/embedded-configuration.cwiki (added)
+++ openejb/site/trunk/content/embedded-configuration.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,91 @@
+h1. Defaults, Overrides and Order
+
+When booting up OpenEJB for testing via the LocalInitialContextFactory there is quite a bit of flexibility to how things are configured.
+
+OpenEJB will function fine with no configuration at all and will happily create things as needed and select defaults for everything. So in a real sense configuration is all about overriding those defaults. There are several places to put your overrides and an a specific order how they are applied. Here they are in order of preference; 1 = highest, 5 = lowest.
+
+# InitialContext properties
+# jndi.properties from the classpath
+# System properties
+# openejb.xml declarations/properties
+# service-jar.xml declarations/properties (internal concept, no need to worry about it)
+
+It opens up some interesting possibilities in how you configure your environment. You could do 100% of your configuration in your test case via InitialContext propertes, or you could do say 80% in a jndi.properties file or openejb.xml file and 20% in your test case via InitialContext properties. You can put 100% of your configuration in a jndi.properties or openejb.xml file and override them via InitialContext properties.
+
+You can manage the properties how you wish and there is no need for redundant definitions if you do not want them.
+
+h1. What is configurable?
+
+Everything you can configure via an openejb.xml (minus the <Deployment> element) can be configured/overridden via properties. See [Configuring Containers in Tests] and [Configuring DataSources in Tests].
+
+Everything in your logging.properties can be configured/overridden via properties. See [Configuring Logging in Tests].
+
+The properties of persistence units declared in a persistence.xml can be configured/overridden via properties. See [Configuring PersistenceUnits in Tests].
+
+OpenEJB has many flags that can also be set as properties. See [OpenEJB Properties] for details on those.
+
+h1. Example of using InitialContext properties
+
+{code}
+Properties p = new Properties();
+
+// set the initial context factory
+p.put("java.naming.factory.initial ", " org.apache.openejb.client.LocalInitialContextFactory");
+
+// change some logging
+p.put("log4j.category.OpenEJB.options ", " debug");
+p.put("log4j.category.OpenEJB.startup ", " debug");
+p.put("log4j.category.OpenEJB.startup.config ", " debug");
+
+// create some resources
+p.put("movieDatabase = new://Resource?type", "DataSource");
+p.put("movieDatabase.JdbcDriver ", " org.hsqldb.jdbcDriver");
+p.put("movieDatabase.JdbcUrl ", " jdbc:hsqldb:mem:moviedb");
+
+// override properties on your "movie-unit" persistence unit
+p.put("movie-unit.hibernate.dialect ", " org.hibernate.dialect.HSQLDialect");
+
+// set some openejb flags
+p.put("openejb.jndiname.format ", " {ejbName}/{interfaceClass}");
+p.put("openejb.descriptors.output ", " true");
+p.put("openejb.validation.output.level ", " verbose");
+
+InitialContext initialContext = new InitialContext(p);
+{code}
+
+h1. Example of using jndi.properties
+
+Here's an example of the same properties being specified via a jndi.properties file. This file just needs to be placed in the classpath, not in a subdirectory of a path in the classpath such as META-INF, but at the root of any of the paths in the classpath.
+
+{code:title=jndi.properties}
+# set the initial context factory
+java.naming.factory.initial = org.apache.openejb.client.LocalInitialContextFactory
+
+# change some logging
+log4j.category.OpenEJB.options = debug
+log4j.category.OpenEJB.startup = debug
+log4j.category.OpenEJB.startup.config = debug
+
+# create some resources
+movieDatabase = new://Resource?type=DataSource
+movieDatabase.JdbcDriver = org.hsqldb.jdbcDriver
+movieDatabase.JdbcUrl = jdbc:hsqldb:mem:moviedb
+
+# override properties on your "movie-unit" persistence unit
+movie-unit.hibernate.dialect = org.hibernate.dialect.HSQLDialect
+
+# set some openejb flags
+openejb.jndiname.format = {ejbName}/{interfaceClass}
+openejb.descriptors.output = true
+openejb.validation.output.level = verbose
+{code}
+
+Then OpenEJB can be booted via the InitialContext as normal. Properties can still be used to override any of the above properties:
+
+{code}
+Properties p = new Properties();
+
+p.put("openejb.validation.output.level ", " medium");
+
+InitialContext initialContext = new InitialContext(p);
+{code}
Propchange: openejb/site/trunk/content/embedded-configuration.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/embedded-configuration.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedded-configuration.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/embedded-configuration.mdtext (added)
+++ openejb/site/trunk/content/embedded-configuration.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,123 @@
+Title: Embedded Configuration
+<a name="EmbeddedConfiguration-Defaults,OverridesandOrder"></a>
+# Defaults, Overrides and Order
+
+When booting up OpenEJB for testing via the LocalInitialContextFactory
+there is quite a bit of flexibility to how things are configured.
+
+OpenEJB will function fine with no configuration at all and will happily
+create things as needed and select defaults for everything. So in a real
+sense configuration is all about overriding those defaults. There are
+several places to put your overrides and an a specific order how they are
+applied. Here they are in order of preference; 1 = highest, 5 = lowest.
+
+1. InitialContext properties
+1. jndi.properties from the classpath
+1. System properties
+1. openejb.xml declarations/properties
+1. service-jar.xml declarations/properties (internal concept, no need to
+worry about it)
+
+It opens up some interesting possibilities in how you configure your
+environment. You could do 100% of your configuration in your test case via
+InitialContext propertes, or you could do say 80% in a jndi.properties file
+or openejb.xml file and 20% in your test case via InitialContext
+properties. You can put 100% of your configuration in a jndi.properties or
+openejb.xml file and override them via InitialContext properties.
+
+You can manage the properties how you wish and there is no need for
+redundant definitions if you do not want them.
+
+<a name="EmbeddedConfiguration-Whatisconfigurable?"></a>
+# What is configurable?
+
+Everything you can configure via an openejb.xml (minus the <Deployment>
+element) can be configured/overridden via properties. See [Configuring Containers in Tests](configuring-containers-in-tests.html)
+ and [Configuring DataSources in Tests]
+.
+
+Everything in your logging.properties can be configured/overridden via
+properties. See [Configuring Logging in Tests](configuring-logging-in-tests.html)
+.
+
+The properties of persistence units declared in a persistence.xml can be
+configured/overridden via properties. See [Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html)
+.
+
+OpenEJB has many flags that can also be set as properties. See [OpenEJB Properties](openejb-properties.html)
+ for details on those.
+
+<a name="EmbeddedConfiguration-ExampleofusingInitialContextproperties"></a>
+# Example of using InitialContext properties
+
+
+ Properties p = new Properties();
+
+ // set the initial context factory
+ p.put("java.naming.factory.initial ", "
+org.apache.openejb.client.LocalInitialContextFactory");
+
+ // change some logging
+ p.put("log4j.category.OpenEJB.options ", " debug");
+ p.put("log4j.category.OpenEJB.startup ", " debug");
+ p.put("log4j.category.OpenEJB.startup.config ", " debug");
+
+ // create some resources
+ p.put("movieDatabase = new://Resource?type", "DataSource");
+ p.put("movieDatabase.JdbcDriver ", " org.hsqldb.jdbcDriver");
+ p.put("movieDatabase.JdbcUrl ", " jdbc:hsqldb:mem:moviedb");
+
+ // override properties on your "movie-unit" persistence unit
+ p.put("movie-unit.hibernate.dialect ", "
+org.hibernate.dialect.HSQLDialect");
+
+ // set some openejb flags
+ p.put("openejb.jndiname.format ", " {ejbName}/{interfaceClass}");
+ p.put("openejb.descriptors.output ", " true");
+ p.put("openejb.validation.output.level ", " verbose");
+
+ InitialContext initialContext = new InitialContext(p);
+
+
+<a name="EmbeddedConfiguration-Exampleofusingjndi.properties"></a>
+# Example of using jndi.properties
+
+Here's an example of the same properties being specified via a
+jndi.properties file. This file just needs to be placed in the classpath,
+not in a subdirectory of a path in the classpath such as META-INF, but at
+the root of any of the paths in the classpath.
+
+<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>jndi.properties</B></DIV><DIV class="codeContent panelContent">
+ # set the initial context factory
+ java.naming.factory.initial =
+org.apache.openejb.client.LocalInitialContextFactory
+
+ # change some logging
+ log4j.category.OpenEJB.options = debug
+ log4j.category.OpenEJB.startup = debug
+ log4j.category.OpenEJB.startup.config = debug
+
+ # create some resources
+ movieDatabase = new://Resource?type=DataSource
+ movieDatabase.JdbcDriver = org.hsqldb.jdbcDriver
+ movieDatabase.JdbcUrl = jdbc:hsqldb:mem:moviedb
+
+ # override properties on your "movie-unit" persistence unit
+ movie-unit.hibernate.dialect = org.hibernate.dialect.HSQLDialect
+
+ # set some openejb flags
+ openejb.jndiname.format = {ejbName}/{interfaceClass}
+ openejb.descriptors.output = true
+ openejb.validation.output.level = verbose
+
+
+Then OpenEJB can be booted via the InitialContext as normal. Properties
+can still be used to override any of the above properties:
+
+
+ Properties p = new Properties();
+
+ p.put("openejb.validation.output.level ", " medium");
+
+ InitialContext initialContext = new InitialContext(p);
+
Modified: openejb/site/trunk/content/embedding.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedding.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/embedding.cwiki (original)
+++ openejb/site/trunk/content/embedding.cwiki Sun Jul 10 05:36:12 2011
@@ -1 +1,23 @@
-{include:OPENEJBx30:Embedding}
\ No newline at end of file
+The basic process for embedding OpenEJB:
+
+# Add the OpenEJB libraries to your classpath
+# Ensure your EJB modules are discoverable
+# Use the LocalInitialContextFactory to boot OpenEJB
+
+
+h2. Important docs
+
+- [Application discovery via the classpath]
+- [Embedded Configuration]
+- [Configuring DataSources in Tests]
+- [Configuring PersistenceUnits in Tests]
+- [Configuring Containers in Tests]
+- [Configuring Logging in Tests]
+- [Alternate Descriptors]
+- [Unit Testing Transactions]
+- [TestCase with TestBean inner-class]
+- [TestCase Injection (@LocalClient)|Local Client Injection]
+
+h2. Examples
+
+{include:Examples Table}
Modified: openejb/site/trunk/content/embedding.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/embedding.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/embedding.mdtext (original)
+++ openejb/site/trunk/content/embedding.mdtext Sun Jul 10 05:36:12 2011
@@ -1,2 +1,26 @@
Title: Embedding
-{include:OPENEJBx30:Embedding}
+The basic process for embedding OpenEJB:
+
+1. Add the OpenEJB libraries to your classpath
+1. Ensure your EJB modules are discoverable
+1. Use the LocalInitialContextFactory to boot OpenEJB
+
+
+<a name="Embedding-Importantdocs"></a>
+## Important docs
+
+- [Application discovery via the classpath](application-discovery-via-the-classpath.html)
+- [Embedded Configuration](embedded-configuration.html)
+- [Configuring DataSources in Tests](configuring-datasources-in-tests.html)
+- [Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html)
+- [Configuring Containers in Tests](configuring-containers-in-tests.html)
+- [Configuring Logging in Tests](configuring-logging-in-tests.html)
+- [Alternate Descriptors](alternate-descriptors.html)
+- [Unit Testing Transactions](unit-testing-transactions.html)
+- [TestCase with TestBean inner-class](testcase-with-testbean-inner-class.html)
+- [TestCase Injection (@LocalClient)](local-client-injection.html)
+
+<a name="Embedding-Examples"></a>
+## Examples
+
+{include:Examples Table}
Added: openejb/site/trunk/content/examples-table.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/examples-table.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/examples-table.cwiki (added)
+++ openejb/site/trunk/content/examples-table.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,99 @@
+{span:class=ExamplesTable}
+|| title || description || APIs used ||
+| {div:class=Cel1}*[Simple Stateless|Simple Stateless Example]*{div} | Simple EJB3 *@Stateless* bean with local and remote business interfaces and unit test. | - javax.ejb.Remote
+ - javax.ejb.Local
+ - javax.ejb.Stateless
+|
+| *[Simple Stateful|Simple Stateful Example]* | Simple EJB3 *@Stateful* bean with local and remote business interfaces and unit test. | - javax.ejb.Remote
+ - javax.ejb.Stateful
+|
+| *[EJB 3.1 Singleton|Singleton Example]* | Shows two EJB 3.1 *@Singleton* beans. One configured to load on startup via *@Startup* and using Bean-Managed Concurrency and synchronization. Another using Container-Managed Concurrency via *@Lock(READ)* and *@Lock(WRITE)*. | - javax.annotation.PostConstruct
+ - javax.annotation.PreDestroy
+ - javax.ejb.ConcurrencyManagement
+ - javax.ejb.Lock
+ - javax.ejb.Singleton
+ - javax.ejb.Startup
+ - javax.ejb.ConcurrencyManagementType.BEAN
+ - javax.ejb.LockType.READ
+ - javax.ejb.LockType.WRITE
+|
+| *[EJB 2.1 Compatibility|EJB 2.1 Compatibility Example]* | Shows an EJB 3.0 Stateful bean with Business interfaces and EJB 2.1 interfaces (now called "component" interfaces) using the *@LocalHome* and *@RemoteHome*. Four interfaces in total. | - javax.ejb.CreateException
+ - javax.ejb.EJBHome
+ - javax.ejb.EJBLocalHome
+ - javax.ejb.EJBLocalObject
+ - javax.ejb.EJBObject
+ - javax.ejb.Init
+ - javax.ejb.Local
+ - javax.ejb.LocalHome
+ - javax.ejb.Remote
+ - javax.ejb.RemoteHome
+ - javax.ejb.Remove
+ - javax.ejb.Stateful
+|
+| *[Injection of env-entry|Injection of env-entry Example]* | Shows how *@Resource* can be used to inject *{{env-entry}}* values declared in an ejb-jar.xml file | - javax.annotation.Resource
+ - javax.ejb.Local
+ - javax.ejb.Remote
+ - javax.ejb.Stateful
+|
+| *[Injection of env-entry 2|Custom Injection]* | Same as the above example but shows how to use a *properties file* to declare the injection values and demonstrates how to get injection of *more types* such as java.util.Date, java.lang.Class, java.net.URI and more. _OpenEJB specific feature_. | - javax.annotation.Resource
+ - javax.ejb.Stateless
+|
+| *[Injection of other EJBs|Injection of other EJBs Example]* | Shows use of *@EJB* in a Stateless to have another Stateless bean injected into it. | - javax.ejb.EJB
+ - javax.ejb.Local
+ - javax.ejb.Remote
+ - javax.ejb.Stateless
+|
+| *[Injection of DataSource|Injection of DataSource Example]* | Shows use of *@Resource* to have a JDBC *DataSource* injected into a Stateful bean. The Stateful bean does basic INSERT, SELECT and DELETE SQL operations. | - javax.annotation.PostConstruct
+ - javax.annotation.Resource
+ - javax.ejb.Stateful
+ - javax.sql.DataSource
+|
+| *[Injection of EntityManager|Injection of EntityManager Example]* | Shows use of *@PersistenceContext* to have an *EntityManager* with an *EXTENDED* persistence context injected into a @Stateful bean. An EJB 3 *@Entity* bean is used with the EntityManager to create, persist and merge data to a database. | - javax.ejb.Stateful
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.EXTENDED
+ - javax.persistence.Query
+|
+| *[Testing Transactions|Testing Transactions Example]* | Shows use of @PersistenceContext to have an *EntityManager* with an *TRANSACTION* persistence context injected into a *@Stateful* bean using the *@TransactionAttribute* annotation and a TestCase that runs test code in a JTA *Transaction*. An EJB 3 @Entity bean is used with the EntityManager to create, persist and merge data to a database. | - javax.ejb.Stateful
+ - javax.ejb.Stateless
+ - javax.ejb.TransactionAttribute
+ - javax.ejb.TransactionAttributeType.MANDATORY
+ - javax.ejb.TransactionAttributeType.REQUIRES_NEW
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.TRANSACTION
+ - javax.persistence.Query
+|
+| *[Testing Security|Testing Security Example]* | Builds upon the [Injection of EntityManager Example] but adds the use of *@RolesAllowed* and *@PermitAll* in the @Stateful bean to restrict who can perform create, persist and remove operations on the EntityManager. Shows a TestCase using the *@RunAs* annotation to execute and test the bean code as various users. | - javax.annotation.security.PermitAll
+ - javax.annotation.security.RolesAllowed
+ - javax.annotation.security.RunAs
+ - javax.ejb.EJBAccessException
+ - javax.ejb.Stateful
+ - javax.ejb.Stateless
+ - javax.ejb.TransactionAttribute
+ - javax.ejb.TransactionAttributeType.SUPPORTS
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.EXTENDED
+ - javax.persistence.Query
+|
+| *[Embedded and Remotable]* | Demonstrates how to use an OpenEJB feature that allows people embedding OpenEJB into their applications to support remote clients in other VMs. This is not required for unit testing. | - javax.ejb.Remote
+ - javax.ejb.Stateful
+|
+| *[Helloworld Weblogic]* | Demonstrates OpenEJBs ability to understand and support the WebLogic deployment descriptors so people using that platform in production can still use OpenEJB in their IDE or build to unit test their EJB applications. | - javax.ejb.CreateException
+ - javax.ejb.EJBLocalHome
+ - javax.ejb.EJBLocalObject
+ - javax.ejb.LocalHome
+ - javax.ejb.Stateless
+|
+| *[JSF Injection Support]* | Demonstrates OpenEJBs ability to inject EJB's into JSF managed beans. | - javax.ejb.Stateless
+|
+| *[Struts with OpenEJB and Tomcat]* | Demonstrates the usage of Struts within an OpenEJB + Tomcat environment. | - javax.ejb.Stateless
+|
+| *[Applets with OpenEJB]* | Demonstrates how an applet can communicate with a remote stateless session bean. The stateless session bean is deployed in an OpenEJB + Tomcat environment | - javax.ejb.Stateless
+|
+{span}
+
Propchange: openejb/site/trunk/content/examples-table.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/examples-table.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/examples-table.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/examples-table.mdtext (added)
+++ openejb/site/trunk/content/examples-table.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,170 @@
+Title: Examples Table
+{span:class=ExamplesTable}
+<table>
+<tr><th> title </th><th> description </th><th> APIs used </th></tr>
+<tr><td> {div:class=Cel1}*[Simple Stateless](simple-stateless-example.html)
+*{div} </td><td> Simple EJB3 *@Stateless* bean with local and remote business
+interfaces and unit test. </td><td> - javax.ejb.Remote
+</tr>
+ - javax.ejb.Local
+ - javax.ejb.Stateless
+<tr></tr>
+<tr><td> *[Simple Stateful](simple-stateful-example.html)
+* </td><td> Simple EJB3 *@Stateful* bean with local and remote business interfaces
+and unit test. </td><td> - javax.ejb.Remote
+</tr>
+ - javax.ejb.Stateful
+<tr></tr>
+<tr><td> *[EJB 3.1 Singleton](singleton-example.html)
+* </td><td> Shows two EJB 3.1 *@Singleton* beans. One configured to load on
+startup via *@Startup* and using Bean-Managed Concurrency and
+synchronization. Another using Container-Managed Concurrency via
+*@Lock(READ)* and *@Lock(WRITE)*. </td><td> - javax.annotation.PostConstruct
+</tr>
+ - javax.annotation.PreDestroy
+ - javax.ejb.ConcurrencyManagement
+ - javax.ejb.Lock
+ - javax.ejb.Singleton
+ - javax.ejb.Startup
+ - javax.ejb.ConcurrencyManagementType.BEAN
+ - javax.ejb.LockType.READ
+ - javax.ejb.LockType.WRITE
+<tr></tr>
+<tr><td> *[EJB 2.1 Compatibility](ejb-2.1-compatibility-example.html)
+* </td><td> Shows an EJB 3.0 Stateful bean with Business interfaces and EJB 2.1
+interfaces (now called "component" interfaces) using the *@LocalHome* and
+*@RemoteHome*. Four interfaces in total. </td><td> - javax.ejb.CreateException
+</tr>
+ - javax.ejb.EJBHome
+ - javax.ejb.EJBLocalHome
+ - javax.ejb.EJBLocalObject
+ - javax.ejb.EJBObject
+ - javax.ejb.Init
+ - javax.ejb.Local
+ - javax.ejb.LocalHome
+ - javax.ejb.Remote
+ - javax.ejb.RemoteHome
+ - javax.ejb.Remove
+ - javax.ejb.Stateful
+<tr></tr>
+<tr><td> *[Injection of env-entry](injection-of-env-entry-example.html)
+* </td><td> Shows how *@Resource* can be used to inject **env-entry** values
+declared in an ejb-jar.xml file </td><td> - javax.annotation.Resource
+</tr>
+ - javax.ejb.Local
+ - javax.ejb.Remote
+ - javax.ejb.Stateful
+<tr></tr>
+<tr><td> *[Injection of env-entry 2](custom-injection.html)
+* </td><td> Same as the above example but shows how to use a *properties file* to
+declare the injection values and demonstrates how to get injection of *more
+types* such as java.util.Date, java.lang.Class, java.net.URI and more.
+_OpenEJB specific feature_. </td><td> - javax.annotation.Resource
+</tr>
+ - javax.ejb.Stateless
+<tr></tr>
+<tr><td> *[Injection of other EJBs](injection-of-other-ejbs-example.html)
+* </td><td> Shows use of *@EJB* in a Stateless to have another Stateless bean
+injected into it. </td><td> - javax.ejb.EJB
+</tr>
+ - javax.ejb.Local
+ - javax.ejb.Remote
+ - javax.ejb.Stateless
+<tr></tr>
+<tr><td> *[Injection of DataSource](injection-of-datasource-example.html)
+* </td><td> Shows use of *@Resource* to have a JDBC *DataSource* injected into a
+Stateful bean. The Stateful bean does basic INSERT, SELECT and DELETE SQL
+operations. </td><td> - javax.annotation.PostConstruct
+</tr>
+ - javax.annotation.Resource
+ - javax.ejb.Stateful
+ - javax.sql.DataSource
+<tr></tr>
+<tr><td> *[Injection of EntityManager](injection-of-entitymanager-example.html)
+* </td><td> Shows use of *@PersistenceContext* to have an *EntityManager* with an
+*EXTENDED* persistence context injected into a @Stateful bean. An EJB 3
+*@Entity* bean is used with the EntityManager to create, persist and merge
+data to a database. </td><td> - javax.ejb.Stateful
+</tr>
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.EXTENDED
+ - javax.persistence.Query
+<tr></tr>
+<tr><td> *[Testing Transactions](testing-transactions-example.html)
+* </td><td> Shows use of @PersistenceContext to have an *EntityManager* with an
+*TRANSACTION* persistence context injected into a *@Stateful* bean using
+the *@TransactionAttribute* annotation and a TestCase that runs test code
+in a JTA *Transaction*. An EJB 3 @Entity bean is used with the
+EntityManager to create, persist and merge data to a database. </td><td> -
+javax.ejb.Stateful
+</tr>
+ - javax.ejb.Stateless
+ - javax.ejb.TransactionAttribute
+ - javax.ejb.TransactionAttributeType.MANDATORY
+ - javax.ejb.TransactionAttributeType.REQUIRES_NEW
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.TRANSACTION
+ - javax.persistence.Query
+<tr></tr>
+<tr><td> *[Testing Security](testing-security-example.html)
+* </td><td> Builds upon the [Injection of EntityManager Example]
+ but adds the use of *@RolesAllowed* and *@PermitAll* in the @Stateful bean
+to restrict who can perform create, persist and remove operations on the
+EntityManager. Shows a TestCase using the *@RunAs* annotation to execute
+and test the bean code as various users. </td><td> -
+javax.annotation.security.PermitAll
+</tr>
+ - javax.annotation.security.RolesAllowed
+ - javax.annotation.security.RunAs
+ - javax.ejb.EJBAccessException
+ - javax.ejb.Stateful
+ - javax.ejb.Stateless
+ - javax.ejb.TransactionAttribute
+ - javax.ejb.TransactionAttributeType.SUPPORTS
+ - javax.persistence.Entity
+ - javax.persistence.EntityManager
+ - javax.persistence.PersistenceContext
+ - javax.persistence.PersistenceContextType.EXTENDED
+ - javax.persistence.Query
+<tr></tr>
+<tr><td> *[Embedded and Remotable](embedded-and-remotable.html)
+* </td><td> Demonstrates how to use an OpenEJB feature that allows people embedding
+OpenEJB into their applications to support remote clients in other VMs.
+This is not required for unit testing. </td><td> - javax.ejb.Remote
+</tr>
+ - javax.ejb.Stateful
+<tr></tr>
+<tr><td> *[Helloworld Weblogic](helloworld-weblogic.html)
+* </td><td> Demonstrates OpenEJBs ability to understand and support the WebLogic
+deployment descriptors so people using that platform in production can
+still use OpenEJB in their IDE or build to unit test their EJB
+applications. </td><td> - javax.ejb.CreateException
+</tr>
+ - javax.ejb.EJBLocalHome
+ - javax.ejb.EJBLocalObject
+ - javax.ejb.LocalHome
+ - javax.ejb.Stateless
+<tr></tr>
+<tr><td> *[JSF Injection Support](jsf-injection-support.html)
+* </td><td> Demonstrates OpenEJBs ability to inject EJB's into JSF managed beans. </td><td>
+ - javax.ejb.Stateless
+</tr>
+<tr></tr>
+<tr><td> *[Struts with OpenEJB and Tomcat](struts-with-openejb-and-tomcat.html)
+* </td><td> Demonstrates the usage of Struts within an OpenEJB + Tomcat
+environment. </td><td> - javax.ejb.Stateless
+</tr>
+<tr></tr>
+<tr><td> *[Applets with OpenEJB](applets-with-openejb.html)
+* </td><td> Demonstrates how an applet can communicate with a remote stateless
+session bean. The stateless session bean is deployed in an OpenEJB + Tomcat
+environment </td><td> - javax.ejb.Stateless
+</tr>
+<tr></tr>
+{span}
+</table>
+
Modified: openejb/site/trunk/content/examples.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/examples.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/examples.cwiki (original)
+++ openejb/site/trunk/content/examples.cwiki Sun Jul 10 05:36:12 2011
@@ -1 +1,5 @@
-{include:OPENEJBx30:Examples}
\ No newline at end of file
+h1. EJB3 Examples
+
+All examples come with JUnit unit tests that can be run in any IDE, Maven or Ant without special plugins using OpenEJB as an embedded EJB container. The easiest way to run the examples in your IDE is to use maven ({{mvn eclipse:eclipse}} or {{mvn idea:idea}}) to generate project descriptors.
+
+{include:Examples Table}
\ No newline at end of file
Modified: openejb/site/trunk/content/examples.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/examples.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/examples.mdtext (original)
+++ openejb/site/trunk/content/examples.mdtext Sun Jul 10 05:36:12 2011
@@ -1,2 +1,10 @@
Title: Examples
-{include:OPENEJBx30:Examples}
+<a name="Examples-EJB3Examples"></a>
+# EJB3 Examples
+
+All examples come with JUnit unit tests that can be run in any IDE, Maven
+or Ant without special plugins using OpenEJB as an embedded EJB container.
+The easiest way to run the examples in your IDE is to use maven ({{mvn
+eclipse:eclipse}} or *mvn idea:idea*) to generate project descriptors.
+
+{include:Examples Table}
Added: openejb/site/trunk/content/failover.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/failover.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/failover.cwiki (added)
+++ openejb/site/trunk/content/failover.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,221 @@
+h1. Overview
+
+OpenEJB supports stateless failover. Specifically, the ability for an EJB client to failover from one server to the next if a request cannot be completed. No application state information is communicated between the servers, so this functionality should be used only with applications that are inherently stateless. A common term for this sort of setup is a server farm.
+
+The basic design assumption is that all servers in the same group have the same applications deployed and are capable of doing the same job. Servers can be brought online and offline while clients are running. As members join/leave this information is sent to the client as part of normal EJB request/response communication so active clients always have the most current information on servers that can process their request should communication with a particular server fail.
+
+h2. Failover
+
+On each request to the server, the client will send the version number associated with the list of servers in the cluster it is aware of. Initially this version will be zero and the list will be empty. Only when the server sees the client has an old list will the server send the updated list. This is an important distinction as the list is not transmitted back and forth on every request, only on change. If the membership of the cluster is stable there is essentially no clustering overhead to the protocol -- 8 byte overhead to each request and 1 byte on each response -- so you will *not* see an exponential slowdown in response times the more members are added to the cluster. This new list takes affect for all proxies that share the same connection.
+
+When a server shuts down, more connections are refused, existing connections not in mid-request are closed, any remaining connections are closed immediately after completion of the request in progress and clients can failover gracefully to the next server in the list. If a server crashes requests are retried on the next server in the list (or depending on the ConnectionStrategy). This failover pattern is followed until there are no more servers in the list at which point the client attempts a final multicast search (if it was created with a multicast PROVIDER_URL) before abandoning the request and throwing an exception to the caller.
+
+By default, the failover is ordered but random selection is supported. The multicast discovery aspect of the client adds a nice randomness to the selection of the first server.
+
+h2. Discovery
+
+Each discoverable service has a URI which is broadcast as a heartbeat to other servers in the cluster. This URI advertises the service's type, its cluster group, and its location in the format of 'group:type:location'. Say for example "cluster1:ejb:ejbd://thehost:4201". The URI is sent out repeatedly in a pulse and its presence on the network indicates its availability and its absence indicates the service is no longer available.
+
+The sending of this pulse (the heartbeat) can be done via UDP or TCP: multicast and "multipoint" respectively. More on that in the following section. The rate at which the heartbeat is pulsed to the network can be specified via the 'heart_rate' property. The default is 500 milliseconds. This rate is also used when listening for services on the network. If a service goes missing for the duration of 'heart_rate' multiplied by 'max_missed_heartbeats', then the service is considered dead.
+
+The 'group' property, cluster1 in the example, is used to dissect the servers on the network into smaller logical clusters. A given server will broadcast all it's services with the group prefixed in the URI, as well it will ignore any services it sees broadcast if they do not share the same group name.
+
+h1. Multicast (UDP)
+
+Multicast is the preferred way to broadcast the heartbeat on the network. The simple technique of broadcasting a non-changing service URI on the network has specific advantages to multicast. The URI itself is essentially stateless and there is no "i'm alive" URI or an "i'm dead" URI.
+
+In this way the issues with UDP being unordered and unreliable melt away as state is no longer a concern and packet sizes are always small. Complicated libraries that ride atop UDP and attempt to offer reliability (retransmission) and ordering on UDP can be avoided. As well the advantages UDP has over TCP are retained as there are no java layers attempting to force UDP communication to be more TCP-like. The simple design means UDP/Multicast is only used for discovery and from there on out critical information is transmitted over TCP/IP which is obviously going to do a better job at ensuring reliability and ordering.
+
+h2. Server Configuration
+
+When you boot the server there should be a conf/multicast.properties file containing:
+
+{code}
+server = org.apache.openejb.server.discovery.MulticastDiscoveryAgent
+bind = 239.255.2.3
+port = 6142
+disabled = true
+group = default
+{code}
+
+Just need to enable that by setting 'disabled=false'. All of the above settings except {{server}} can be changed. The {{port}} and {{bind}} must be valid for general multicast/udp network communication.
+
+The {{group}} setting can be changed to further group servers that may use the same multicast channel. As shown below the client also has a {{group}} setting which can be used to select an appropriate server from the multicast channel.
+
+h2. Multicast Client
+
+The multicast functionality is not just for servers to find each other in a cluster, it can also be used for EJB clients to discover a server. A special "multicast://" URL can be used in the InitialContext properties to signify that multicast should be used to seed the connection process. Such as:
+
+{code:java}
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+p.put(Context.PROVIDER_URL, "multicast://239.255.2.3:6142?group=default");
+InitialContext remoteContext = new InitialContext(p);
+{code}
+
+The URL has optional query parameters such as "schemes" and "group" and "timeout" which allow you to zero in on a particular type of service of a particular cluster group as well as set how long you are willing to wait in the discovery process till finally giving up. The first matching service that it sees "flowing" around on the UDP stream is the one it picks and sticks to for that and subsequent requests, ensuring UDP is only used when there are no other servers to talk to.
+
+Note that EJB clients do not need to use multicast to find a server. If the client knows the URL of a server in the cluster, it may use it and connect directly to that server, at which point that server will share the full list of its peers.
+
+h2. Multicast Servers with TCP Clients
+
+Note that clients do not need to use multicast to communicate with servers. Servers can use multicast to discover each other, but clients are still free to connect to servers in the network using the server's TCP address.
+
+{code:java}
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+p.put(Context.PROVIDER_URL, "ejbd://192.168.1.30:4201");
+InitialContext remoteContext = new InitialContext(p);
+{code}
+
+When the client connects, the server will send the URLs of all the servers in the group and failover will take place normally.
+
+h1. Multipoint (TCP)
+{info:title=Since OpenEJB 3.1.3}
+{span:style=float: right;}
+{gliffy:name=Multipoint|space=OPENEJBx30|page=Failover|align=right|border=false|size=L|version=9}
+{span}
+As TCP has no real broadcast functionality to speak of, communication of who is in the network is achieved by each server having a physical connection to each other server in the network.
+
+To join the network, the server must be configured to know the address of at least one server in the network and connect to it. When it does both servers will exchange the full list of all the other servers each knows about. Each server will then connect to any new servers they've just learned about and repeat the processes with those new servers. The end result is that everyone has a direct connection to everyone 100% of the time, hence the made-up term "multipoint" to describe this situation of each server having multiple point-to-point connections which create a fully connected graph.
+
+On the client side things are similar. It needs to know the address of at least one server in the network and be able to connect to it. When it does it will get the full (and dynamically maintained) list of every server in the network. The client doesn't connect to each of those servers immediately, but rather consults the list in the event of a failover, using it to decide who to connect to next.
+
+The entire process is essentially the art of using a statically maintained list to bootstrap getting the more valuable dynamically maintained list.
+
+{div:style=clear:both;}{div}
+
+h2. Server Configuration
+
+
+In the server this list can be specified via the {{conf/multipoint.properties}} file like so:
+
+{code}
+server = org.apache.openejb.server.discovery.MultipointDiscoveryAgent
+bind = 127.0.0.1
+port = 4212
+disabled = false
+initialServers = 192.168.1.20:4212, 192.168.1.30:4212, 192.168.1.40:4212
+{code}
+
+The above configuration shows the server has an port 4212 open for connections by other servers for multipoint communication. The {{initialServers}} list should be a comma separated list of other similar servers on the network. Only one of the servers listed is required to be running when this server starts up -- it is not required to list all servers in the network.
+
+h2. Client Configuration
+
+Configuration in the client is similar, but note that EJB clients do not participate directly in multipoint communication and do *not* connect to the multipoint port. The server list is simply a list of the regular "ejbd://" urls that a client normally uses to connect to a server.
+
+{code:java}
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+p.put(Context.PROVIDER_URL, "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201");
+InitialContext remoteContext = new InitialContext(p);
+{code}
+
+h2. Considerations
+
+h3. Network size
+
+The general disadvantage of this topology is the number of connections required. The number of connections for the network of servers is equal to "(n * n - n) / 2 ", where n is the number of servers. For example, with 5 servers you need 10 connections, with 10 servers you need 45 connections, and with 50 servers you need 1225 connections. This is of course the number of connections across the entire network, each individual server only needs "n - 1" connections.
+
+The handling of these sockets is all asynchronous Java NIO code which allows the server to handle many connections (all of them) with one thread. From a pure threading perspective, the option is extremely efficient with just one thread to listen and broadcast to many peers.
+
+h3. Double connect
+
+It is possible in this process that two servers learn of each other at the same time and each attempts to connect to the other simultaneously, resulting in two connections between the same two servers. When this happens both servers will detect the extra connection and one of the connections will be dropped and one will be kept. In practice this race condition rarely happens and can be avoided almost entirely by fanning out server startup by as little as 100 milliseconds.
+
+h1. Multipoint Configuration Recommendations
+
+As mentioned above the {{initialServers}} is only used for bootstrapping the multipoint network. Once running, all servers will dynamically establish direct connections with each other and there is no single point of failure.
+
+However to ensure that the bootstrapping process can occur successfully, the {{initialServers}} property of the {{conf/multipoint.properties}} file must be set carefully and with a specific server start order in mind. Each server consults its {{initialServers}} list exactly once in the bootstrapping phase at startup, after that time connections are made dynamically.
+
+This means that at least one of the servers listed in {{initialServers}} must already be running when the server starts or the server might never become introduced and connected to all the other servers in the network.
+
+h2. Failed scenario (background)
+
+As an example of a failed scenario, imagine there are three servers; server1, server2, server3. They are setup only to point to the server in front of them making a chain:
+
+ * server1; initialServers = server2
+ * server2; initialServers = server3
+ * server3; initialServers = <blank>
+
+Which is essentially server1 -> server2 -> server3. This scenario could work, but they servers would have to be started in exactly the opposite order:
+
+ # server3 starts
+ # server2 starts
+ #* static: connect to server3
+ # server1 starts
+ #* static: connect to server2
+ #* dynamic: connect to server3
+
+At this point all servers would be fully connected. But the above setup is flawed and could easily fail. The first flaw is server3 lists nothing in its {{initialServers}} list, so if it were restarted it would leave the multipoint network and not know how to get back in.
+
+The second flaw is if you started them in any other order, you would also not get a fully connected multipoint network. Say the servers were started in "front" order:
+
+ # server1 starts
+ #* static: connect to server2 - failed, server2 not started.
+ # server2 starts
+ #* static: connect to server3 - failed, server3 not started.
+ # server3 starts
+ #* no connection attempts, initialServers list is empty.
+
+After startup completes, all servers will be completely isolated and failover will not work. The described setup is weaker than it needs to be. Listing just one server means the listed server is a potential point of weakness. As a matter of trivia, it is interesting to point out that you could bring a fourth server online temporarily that lists all three servers. Once it makes the introductions and all servers learn of each other, you could shut it down again.
+
+The above setup is easily fixable via better configuration. If server3 listed both server1 and server2 in its initialServers list, rather than listing nothing at all, then all servers would fully discover each other regardless of startup order; assuming all three servers did eventually start.
+
+h2. Bootstrapping Three Servers or Less
+
+In a three sever scenario, we recommend simply having all three servers list all three servers.
+
+ * server1/conf/multipoint.properties
+ ** initialServers = server1, server2, server3
+ * server2/conf/multipoint.properties
+ ** initialServers = server1, server2, server3
+ * server3/conf/multipoint.properties
+ ** initialServers = server1, server2, server3
+
+There's no harm to a server listing itself. It gives you one clean list to maintain and it will work even if you decide not to start one of the three servers.
+
+h2. Bootstrapping Four Servers or More
+{span:style=float: right;}
+{gliffy:name=MultipointFour|space=OPENEJBx30|page=Failover|align=right|border=false|size=L|version=3}
+{span}
+
+In a scenario of four or more, we recommend picking at least to servers and focus on always keeping at least one of them running. Lets refer to them as "root" servers for simplicity sake.
+
+ * server1/conf/multipoint.properties
+ ** initialServers = server2
+ * server2/conf/multipoint.properties
+ ** initialServers = server1
+
+Root server1 would list root server2 so they would always be linked to each other regardless of start order or if one of them went down. Server1 could be shutdown and reconnect on startup to the full multipoint network through server2, and vice versa.
+
+All other servers would simply list the root servers (server1, server2) in their initialServers list.
+
+ * server3/conf/multipoint.properties
+ ** initialServers = server1, server2
+ * server4/conf/multipoint.properties
+ ** initialServers = server1, server2
+ * serverN/conf/multipoint.properties
+ ** initialServers = server1, server2
+
+As long as at least one root server (server1 or server2) was running, you can bring other servers on and offline at will and always have a fully connected graph.
+
+Of course all servers once running and connected will have a full list of all other servers in the network, so if at any time the "root" servers weren't around to make initial introductions to new servers it would be no trouble. It's possible to reconfigure new servers to point at any other server in the network as all servers will have the full list. So these "root" servers are no real point of failure in function, but only of convenience.
+
+{div:style=clear:both;}{div}
+
+h2. Command line overrides
+
+Always remember that any property in a conf/<server-service>.properties file can be overridden on the command line or via system properties. So it is possible easily set the initialServers list in startup scripts.
+
+A bash example might look something like:
+{code}
+#!/bin/bash
+
+OPENEJB_HOME=/opt/openejb-3.1.3
+INITIAL_LIST=$(cat /some/shared/directory/our_initial_servers.txt)
+
+$OPENEJB_HOME/bin/openejb start -Dmultipoint.initialServers=$INITIAL_LIST
+{code}
+
Propchange: openejb/site/trunk/content/failover.cwiki
------------------------------------------------------------------------------
svn:eol-style = native