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 [7/13] - /openejb/site/trunk/content/
Added: openejb/site/trunk/content/injection-of-entitymanager-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/injection-of-entitymanager-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/injection-of-entitymanager-example.mdtext (added)
+++ openejb/site/trunk/content/injection-of-entitymanager-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,121 @@
+Title: Injection of EntityManager Example
+<a name="InjectionofEntityManagerExample-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/s4uiIoAehgQ?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/s4uiIoAehgQ?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}
+
+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.
+
+If you need to use a TRANSACTION persistence context, see [this example](testing-transactions-example.html)
+.
+
+_The source for this example is in the "injection-of-entitymanager"
+directory located in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+{div}
+{div:style=clear:both;}{div}
+
+<a name="InjectionofEntityManagerExample-TheCode"></a>
+# The Code
+
+<a name="InjectionofEntityManagerExample-TheStatefulbean"></a>
+## The Stateful bean
+{snippet:id=code|url=openejb3/examples/injection-of-entitymanager/src/main/java/org/superbiz/injection/jpa/MoviesImpl.java|lang=java}
+
+<a name="InjectionofEntityManagerExample-TheEntitybean"></a>
+## The Entity bean
+{snippet:id=code|url=openejb3/examples/injection-of-entitymanager/src/main/java/org/superbiz/injection/jpa/Movie.java|lang=java}
+
+<a name="InjectionofEntityManagerExample-Thepersistenceunit"></a>
+## The persistence unit
+
+{snippet:id=code|url=openejb3/examples/injection-of-entitymanager/src/main/resources/META-INF/persistence.xml|lang=xml}
+
+<a name="InjectionofEntityManagerExample-Writingaunittestfortheexample"></a>
+# Writing a unit test for the example
+
+{snippet:id=code|url=openejb3/examples/injection-of-entitymanager/src/test/java/org/superbiz/injection/jpa/MoviesTest.java|lang=java}
+
+Curious on the InitialContext parameters used? See the [Injection of DataSource Example](injection-of-datasource-example.html)
+ for an explanation of how any Resource can be configured via properties in
+the TestCase itself or via an openejb.xml file.
+
+<a name="InjectionofEntityManagerExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "injection-of-entitymanager"
+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.injection.jpa.MoviesTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager
+ 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=movieDatabaseUnmanaged, type=Resource,
+provider-id=Default JDBC Database)
+ INFO - Configuring Service(id=movieDatabase, type=Resource,
+provider-id=Default JDBC Database)
+ 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/injection-of-entitymanager/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager/target/classes
+ INFO - Configuring Service(id=Default Stateful Container, type=Container,
+provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean Movies: Container(type=STATEFUL,
+id=Default Stateful Container)
+ INFO - Configuring PersistenceUnit(name=movie-unit)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager/target/classes
+ INFO - PersistenceUnit(name=movie-unit,
+provider=org.apache.openjpa.persistence.PersistenceProviderImpl)
+ ERROR - JAVA AGENT NOT INSTALLED. The JPA Persistence Provider requested
+installation of a ClassFileTransformer which requires
+ a JavaAgent. See http://openejb.apache.org/3.0/javaagent.html
+ INFO - Jndi(name=MoviesLocal) --> Ejb(deployment-id=Movies)
+ INFO - Created Ejb(deployment-id=Movies, ejb-name=Movies, container=Default
+Stateful Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/injection-of-entitymanager/target/classes)
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.095 sec
+
+ Results :
+
+ Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+
+
Added: openejb/site/trunk/content/injection-of-env-entry-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/injection-of-env-entry-example.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/injection-of-env-entry-example.cwiki (added)
+++ openejb/site/trunk/content/injection-of-env-entry-example.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,80 @@
+h1. Overview
+
+The EJB 3.0 spec added Dependency Injection as a main feature. The *@Resource* annotation can be used to inject several things including EntityManagers, DataSources, Topics, Queues, etc. Most of these are container supplied objects. It is possible, however, to supply your own values to be injected via an *<env-entry>* in your ejb-jar.xml deployment descriptor. EJB 3.0 supported env-entry types are limited to the following:
+
+ - java.lang.String
+ - java.lang.Integer
+ - java.lang.Short
+ - java.lang.Float
+ - java.lang.Double
+ - java.lang.Byte
+ - java.lang.Character
+ - java.lang.Boolean
+
+It should be noted that OpenEJB does not restrict you to just these data types and allows for anything convertible from a String to be injected provided there is a java.beans.PropertyEditor installed to handle the type you want. Additionally, a plain properties file packed in your META-INF directory can be used to supply the injected values instead of using the ejb-jar.xml. See the [Custom Injection] example for details.
+
+_The source for this example is the "injection-of-env-entry" directory located in the [openejb-examples.zip|OPENEJB:Download] available on the download page._
+
+h1. The Code
+
+h2. Annotated Bean Class
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/main/java/org/superbiz/injection/InvoiceBean.java|lang=java}
+
+The use of the *@Resource* annotation isn't limited to setters. For example, this annotation could have been used on the corresponding *field* like so:
+
+{code}
+@Resource
+private int maxLineItems;
+{code}
+
+h2. ejb-jar.xml
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/main/resources/META-INF/ejb-jar.xml|lang=xml}
+
+h1. Test Case
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/test/java/org/superbiz/injection/InvoiceBeanTest.java|lang=java}
+
+h1. Running it
+
+Running the example is fairly simple. In the "injection-of-env-entry" directory of the [examples zip|OPENEJB:Download], just run:
+
+{quote}
+$ mvn clean install
+{quote}
+
+Which should create output like the following.
+
+{noformat}
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.superbiz.injection.PurchaseOrderBeanTest
+Apache OpenEJB 3.0 build: 20080408-04:13
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry
+INFO - openejb.base = /Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry
+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/injection-of-env-entry/target/classes
+INFO - Configuring app: /Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+INFO - Configuring Service(id=Default Stateful Container, type=Container, provider-id=Default Stateful Container)
+INFO - Auto-creating a container for bean InvoiceBean: Container(type=STATEFUL, id=Default Stateful Container)
+INFO - Loaded Module: /Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+INFO - Assembling app: /Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+INFO - Jndi(name=InvoiceBeanRemote) --> Ejb(deployment-id=InvoiceBean)
+INFO - Jndi(name=PurchaseOrderBeanRemote) --> Ejb(deployment-id=PurchaseOrderBean)
+INFO - Created Ejb(deployment-id=InvoiceBean, ejb-name=InvoiceBean, container=Default Stateful Container)
+INFO - Created Ejb(deployment-id=PurchaseOrderBean, ejb-name=PurchaseOrderBean, container=Default Stateful Container)
+INFO - Deployed Application(path=/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes)
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.331 sec
+Running org.superbiz.injection.InvoiceBeanTest
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.068 sec
+
+Results :
+
+Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
Propchange: openejb/site/trunk/content/injection-of-env-entry-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/injection-of-env-entry-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/injection-of-env-entry-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/injection-of-env-entry-example.mdtext (added)
+++ openejb/site/trunk/content/injection-of-env-entry-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,120 @@
+Title: Injection of env-entry Example
+<a name="Injectionofenv-entryExample-Overview"></a>
+# Overview
+
+The EJB 3.0 spec added Dependency Injection as a main feature. The
+*@Resource* annotation can be used to inject several things including
+EntityManagers, DataSources, Topics, Queues, etc. Most of these are
+container supplied objects. It is possible, however, to supply your own
+values to be injected via an *<env-entry>* in your ejb-jar.xml deployment
+descriptor. EJB 3.0 supported env-entry types are limited to the
+following:
+
+ - java.lang.String
+ - java.lang.Integer
+ - java.lang.Short
+ - java.lang.Float
+ - java.lang.Double
+ - java.lang.Byte
+ - java.lang.Character
+ - java.lang.Boolean
+
+It should be noted that OpenEJB does not restrict you to just these data
+types and allows for anything convertible from a String to be injected
+provided there is a java.beans.PropertyEditor installed to handle the type
+you want. Additionally, a plain properties file packed in your META-INF
+directory can be used to supply the injected values instead of using the
+ejb-jar.xml. See the [Custom Injection](custom-injection.html)
+ example for details.
+
+_The source for this example is the "injection-of-env-entry" directory
+located in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+<a name="Injectionofenv-entryExample-TheCode"></a>
+# The Code
+
+<a name="Injectionofenv-entryExample-AnnotatedBeanClass"></a>
+## Annotated Bean Class
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/main/java/org/superbiz/injection/InvoiceBean.java|lang=java}
+
+The use of the *@Resource* annotation isn't limited to setters. For
+example, this annotation could have been used on the corresponding *field*
+like so:
+
+
+ @Resource
+ private int maxLineItems;
+
+
+<a name="Injectionofenv-entryExample-ejb-jar.xml"></a>
+## ejb-jar.xml
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/main/resources/META-INF/ejb-jar.xml|lang=xml}
+
+<a name="Injectionofenv-entryExample-TestCase"></a>
+# Test Case
+
+{snippet:id=code|url=openejb3/examples/injection-of-env-entry/src/test/java/org/superbiz/injection/InvoiceBeanTest.java|lang=java}
+
+<a name="Injectionofenv-entryExample-Runningit"></a>
+# Running it
+
+Running the example is fairly simple. In the "injection-of-env-entry"
+directory of the [examples zip](openejb:download.html)
+, just run:
+
+{quote}
+$ mvn clean install
+{quote}
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.injection.PurchaseOrderBeanTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry
+ 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/injection-of-env-entry/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+ INFO - Configuring Service(id=Default Stateful Container, type=Container,
+provider-id=Default Stateful Container)
+ INFO - Auto-creating a container for bean InvoiceBean:
+Container(type=STATEFUL, id=Default Stateful Container)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes
+ INFO - Jndi(name=InvoiceBeanRemote) --> Ejb(deployment-id=InvoiceBean)
+ INFO - Jndi(name=PurchaseOrderBeanRemote) -->
+Ejb(deployment-id=PurchaseOrderBean)
+ INFO - Created Ejb(deployment-id=InvoiceBean, ejb-name=InvoiceBean,
+container=Default Stateful Container)
+ INFO - Created Ejb(deployment-id=PurchaseOrderBean,
+ejb-name=PurchaseOrderBean, container=Default Stateful Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/injection-of-env-entry/target/classes)
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.331 sec
+ Running org.superbiz.injection.InvoiceBeanTest
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.068 sec
+
+ Results :
+
+ Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
+
+
Added: openejb/site/trunk/content/injection-of-other-ejbs-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/injection-of-other-ejbs-example.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/injection-of-other-ejbs-example.cwiki (added)
+++ openejb/site/trunk/content/injection-of-other-ejbs-example.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,113 @@
+h1. Overview
+
+This example shows how to use the *@EJB* annotation in a bean class to refer to other beans.
+
+This functionality is often referred as dependency injection, and has been introduced in Java EE 5.
+
+In this particular example, we will create two session stateless beans:
+
+ - DataStore session bean
+ - DataReader session bean
+
+The DataReader bean uses the DataStore to retrieve some informations, and we will see how we can, inside the DataReader bean, get a reference to the DataStore bean using the @EJB annotation, thus avoiding the use of the JNDI API.
+
+_The source for this example is the "injection-of-ejbs" directory located in the [openejb-examples.zip|OPENEJB:Download] available on the download page._
+
+h1. The Code
+
+In this example we develop two simple session stateless beans (DataReader and DataStore), and show how we can use the @EJB annotation in one of these beans to get the reference to the other session bean
+
+h2. DataStore session bean
+
+h3. Bean
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreImpl.java|lang=java}
+
+h3. Local business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreLocal.java|lang=java}
+
+h3. Remote business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreRemote.java|lang=java}
+
+h2. DataReader session bean
+
+h3. Bean
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataReaderImpl.java|lang=java}
+
+Note the usage of the *@EJB* annotation on the DataStoreRemote and DataStoreLocal fields. This is the minimum required for EJB ref resolution. If you have two beans that implement the same business interfaces, you'll want to the *beanName* attribute as follows:
+{code}
+@EJB(beanName = "DataStoreImpl")
+private DataStoreRemote dataStoreRemote;
+
+@EJB(beanName = "DataStoreImpl")
+private DataStoreLocal dataStoreLocal;
+{code}
+
+h3. Local business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataReaderLocal.java|lang=java}
+
+(The remote business interface is not shown for the sake of brevity).
+
+{tip:title=@EJB annotation}
+Several components in Java EE can use the @EJB annotation, such as:
+ * Servlets
+ * ServletContextListeners
+ * Servlet Filters
+ * JSF managed beans
+ * EJB interceptors
+ * JAX-WS service endpoints
+{tip}
+
+h1. Writing a unit test for the example
+
+Writing an unit test for this example is quite simple. We need just to write a setup method to create and initialize the InitialContext, and then write our test methods
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/test/java/org/superbiz/injection/EjbDependencyTest.java|lang=java}
+
+h1. Running
+
+Running the example is fairly simple. In the "injection-of-ejbs" directory of the [examples zip|OPENEJB:Download], just run:
+
+{quote}
+$ mvn clean install
+{quote}
+
+Which should create output like the following.
+
+{noformat}
+-------------------------------------------------------
+ T E S T S
+-------------------------------------------------------
+Running org.superbiz.injection.EjbDependencyTest
+Apache OpenEJB 3.0 build: 20080408-04:13
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs
+INFO - openejb.base = /Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs
+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/injection-of-ejbs/target/classes
+INFO - Configuring app: /Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container)
+INFO - Auto-creating a container for bean DataReaderImpl: Container(type=STATELESS, id=Default Stateless Container)
+INFO - Loaded Module: /Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+INFO - Assembling app: /Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+INFO - Jndi(name=DataReaderImplLocal) --> Ejb(deployment-id=DataReaderImpl)
+INFO - Jndi(name=DataReaderImplRemote) --> Ejb(deployment-id=DataReaderImpl)
+INFO - Jndi(name=DataStoreImplLocal) --> Ejb(deployment-id=DataStoreImpl)
+INFO - Jndi(name=DataStoreImplRemote) --> Ejb(deployment-id=DataStoreImpl)
+INFO - Created Ejb(deployment-id=DataReaderImpl, ejb-name=DataReaderImpl, container=Default Stateless Container)
+INFO - Created Ejb(deployment-id=DataStoreImpl, ejb-name=DataStoreImpl, container=Default Stateless Container)
+INFO - Deployed Application(path=/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes)
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.705 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
+
Propchange: openejb/site/trunk/content/injection-of-other-ejbs-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/injection-of-other-ejbs-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/injection-of-other-ejbs-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/injection-of-other-ejbs-example.mdtext (added)
+++ openejb/site/trunk/content/injection-of-other-ejbs-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,156 @@
+Title: Injection of other EJBs Example
+<a name="InjectionofotherEJBsExample-Overview"></a>
+# Overview
+
+This example shows how to use the *@EJB* annotation in a bean class to
+refer to other beans.
+
+This functionality is often referred as dependency injection, and has been
+introduced in Java EE 5.
+
+In this particular example, we will create two session stateless beans:
+
+ - DataStore session bean
+ - DataReader session bean
+
+The DataReader bean uses the DataStore to retrieve some informations, and
+we will see how we can, inside the DataReader bean, get a reference to the
+DataStore bean using the @EJB annotation, thus avoiding the use of the JNDI
+API.
+
+_The source for this example is the "injection-of-ejbs" directory located
+in the [openejb-examples.zip](openejb:download.html)
+ available on the download page._
+
+<a name="InjectionofotherEJBsExample-TheCode"></a>
+# The Code
+
+In this example we develop two simple session stateless beans (DataReader
+and DataStore), and show how we can use the @EJB annotation in one of these
+beans to get the reference to the other session bean
+
+<a name="InjectionofotherEJBsExample-DataStoresessionbean"></a>
+## DataStore session bean
+
+<a name="InjectionofotherEJBsExample-Bean"></a>
+### Bean
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreImpl.java|lang=java}
+
+<a name="InjectionofotherEJBsExample-Localbusinessinterface"></a>
+### Local business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreLocal.java|lang=java}
+
+<a name="InjectionofotherEJBsExample-Remotebusinessinterface"></a>
+### Remote business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataStoreRemote.java|lang=java}
+
+<a name="InjectionofotherEJBsExample-DataReadersessionbean"></a>
+## DataReader session bean
+
+<a name="InjectionofotherEJBsExample-Bean"></a>
+### Bean
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataReaderImpl.java|lang=java}
+
+Note the usage of the *@EJB* annotation on the DataStoreRemote and
+DataStoreLocal fields. This is the minimum required for EJB ref
+resolution. If you have two beans that implement the same business
+interfaces, you'll want to the *beanName* attribute as follows:
+
+ @EJB(beanName = "DataStoreImpl")
+ private DataStoreRemote dataStoreRemote;
+
+ @EJB(beanName = "DataStoreImpl")
+ private DataStoreLocal dataStoreLocal;
+
+
+<a name="InjectionofotherEJBsExample-Localbusinessinterface"></a>
+### Local business interface
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/main/java/org/superbiz/injection/DataReaderLocal.java|lang=java}
+
+(The remote business interface is not shown for the sake of brevity).
+
+{tip:title=@EJB annotation}
+Several components in Java EE can use the @EJB annotation, such as:
+ * Servlets
+ * ServletContextListeners
+ * Servlet Filters
+ * JSF managed beans
+ * EJB interceptors
+ * JAX-WS service endpoints
+{tip}
+
+<a name="InjectionofotherEJBsExample-Writingaunittestfortheexample"></a>
+# Writing a unit test for the example
+
+Writing an unit test for this example is quite simple. We need just to
+write a setup method to create and initialize the InitialContext, and then
+write our test methods
+
+{snippet:id=code|url=openejb3/examples/injection-of-ejbs/src/test/java/org/superbiz/injection/EjbDependencyTest.java|lang=java}
+
+<a name="InjectionofotherEJBsExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "injection-of-ejbs" directory
+of the [examples zip](openejb:download.html)
+, just run:
+
+{quote}
+$ mvn clean install
+{quote}
+
+Which should create output like the following.
+
+
+ -------------------------------------------------------
+ T E S T S
+ -------------------------------------------------------
+ Running org.superbiz.injection.EjbDependencyTest
+ Apache OpenEJB 3.0 build: 20080408-04:13
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs
+ 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/injection-of-ejbs/target/classes
+ INFO - Configuring app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+ INFO - Configuring Service(id=Default Stateless Container, type=Container,
+provider-id=Default Stateless Container)
+ INFO - Auto-creating a container for bean DataReaderImpl:
+Container(type=STATELESS, id=Default Stateless Container)
+ INFO - Loaded Module:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+ INFO - Assembling app:
+/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes
+ INFO - Jndi(name=DataReaderImplLocal) --> Ejb(deployment-id=DataReaderImpl)
+ INFO - Jndi(name=DataReaderImplRemote) -->
+Ejb(deployment-id=DataReaderImpl)
+ INFO - Jndi(name=DataStoreImplLocal) --> Ejb(deployment-id=DataStoreImpl)
+ INFO - Jndi(name=DataStoreImplRemote) --> Ejb(deployment-id=DataStoreImpl)
+ INFO - Created Ejb(deployment-id=DataReaderImpl, ejb-name=DataReaderImpl,
+container=Default Stateless Container)
+ INFO - Created Ejb(deployment-id=DataStoreImpl, ejb-name=DataStoreImpl,
+container=Default Stateless Container)
+ INFO - Deployed
+Application(path=/Users/dblevins/work/openejb-3.0/examples/injection-of-ejbs/target/classes)
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.705 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
+
Added: openejb/site/trunk/content/interceptor-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/interceptor-example.cwiki?rev=1144778&view=auto
==============================================================================
(empty)
Propchange: openejb/site/trunk/content/interceptor-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/interceptor-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/interceptor-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/interceptor-example.mdtext (added)
+++ openejb/site/trunk/content/interceptor-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1 @@
+Title: Interceptor Example
Added: openejb/site/trunk/content/introduction-to-the-command-line-tools.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/introduction-to-the-command-line-tools.cwiki?rev=1144778&view=auto
==============================================================================
(empty)
Propchange: openejb/site/trunk/content/introduction-to-the-command-line-tools.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/introduction-to-the-command-line-tools.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/introduction-to-the-command-line-tools.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/introduction-to-the-command-line-tools.mdtext (added)
+++ openejb/site/trunk/content/introduction-to-the-command-line-tools.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1 @@
+Title: Introduction to the command line tools
Added: openejb/site/trunk/content/java-ee-refs.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/java-ee-refs.cwiki?rev=1144778&view=auto
==============================================================================
(empty)
Propchange: openejb/site/trunk/content/java-ee-refs.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/java-ee-refs.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/java-ee-refs.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/java-ee-refs.mdtext (added)
+++ openejb/site/trunk/content/java-ee-refs.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1 @@
+Title: Java EE Refs
Added: openejb/site/trunk/content/javaagent-with-maven-surefire.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/javaagent-with-maven-surefire.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/javaagent-with-maven-surefire.cwiki (added)
+++ openejb/site/trunk/content/javaagent-with-maven-surefire.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,47 @@
+h2. Maven2
+
+In maven2 you can enable the javaagent for your tests by adding this to your pom.xml file:
+
+{code:xml}
+<build>
+ <plugins>
+ <!-- this configures the surefire plugin to run your tests with the javaagent enabled -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <forkMode>pertest</forkMode>
+ <argLine>-javaagent:${basedir}/target/openejb-javaagent-3.0.jar</argLine>
+ <workingDirectory>${basedir}/target</workingDirectory>
+ </configuration>
+ </plugin>
+
+ <!-- this tells maven to copy the openejb-javaagent jar into your target/ directory -->
+ <!-- where surefire can see it -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-javaagent</artifactId>
+ <version>3.0</version>
+ <outputDirectory>${project.build.directory}</outputDirectory>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+</build>
+{code}
\ No newline at end of file
Propchange: openejb/site/trunk/content/javaagent-with-maven-surefire.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/javaagent-with-maven-surefire.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/javaagent-with-maven-surefire.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/javaagent-with-maven-surefire.mdtext (added)
+++ openejb/site/trunk/content/javaagent-with-maven-surefire.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,54 @@
+Title: JavaAgent with Maven Surefire
+<a name="JavaAgentwithMavenSurefire-Maven2"></a>
+## Maven2
+
+In maven2 you can enable the javaagent for your tests by adding this to
+your pom.xml file:
+
+
+ <build>
+ <plugins>
+ <!-- this configures the surefire plugin to run your tests with the
+javaagent enabled -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <forkMode>pertest</forkMode>
+
+<argLine>-javaagent:${basedir}/target/openejb-javaagent-3.0.jar</argLine>
+ <workingDirectory>${basedir}/target</workingDirectory>
+ </configuration>
+ </plugin>
+
+ <!-- this tells maven to copy the openejb-javaagent jar into your
+target/ directory -->
+ <!-- where surefire can see it -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-javaagent</artifactId>
+ <version>3.0</version>
+
+<outputDirectory>${project.build.directory}</outputDirectory>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+ </build>
+
Added: openejb/site/trunk/content/javaagent.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/javaagent.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/javaagent.cwiki (added)
+++ openejb/site/trunk/content/javaagent.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,58 @@
+h1. Adding a JavaAgent
+
+Adding a java agent is done via a vm parameter as follows:
+
+{panel}
+java -javaagent:openejb-javaagent-3.0-beta-2.jar _\[other params...]_
+{panel}
+
+{note:title=Need the JavaAgent?}
+The java agent is only required if using OpenJPA as your persistence provider or if using CMP.
+{note}
+h2. Maven2
+
+In maven2 you can enable the javaagent for your tests by adding this to your pom.xml file:
+
+{code:xml}
+<build>
+ <plugins>
+ <!-- this configures the surefire plugin to run your tests with the javaagent enabled -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <forkMode>pertest</forkMode>
+ <argLine>-javaagent:${basedir}/target/openejb-javaagent-3.0-beta-2.jar</argLine>
+ <workingDirectory>${basedir}/target</workingDirectory>
+ </configuration>
+ </plugin>
+
+ <!-- this tells maven to copy the openejb-javaagent jar into your target/ directory -->
+ <!-- where surefire can see it -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-javaagent</artifactId>
+ <version>3.0-beta-2</version>
+ <outputDirectory>${project.build.directory}</outputDirectory>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+</build>
+{code}
\ No newline at end of file
Propchange: openejb/site/trunk/content/javaagent.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/javaagent.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/javaagent.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/javaagent.mdtext (added)
+++ openejb/site/trunk/content/javaagent.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,68 @@
+Title: JavaAgent
+<a name="JavaAgent-AddingaJavaAgent"></a>
+# Adding a JavaAgent
+
+Adding a java agent is done via a vm parameter as follows:
+
+{panel}
+java -javaagent:openejb-javaagent-3.0-beta-2.jar _\[other params...](other-params....html)
+_
+{panel}
+
+{note:title=Need the JavaAgent?}
+The java agent is only required if using OpenJPA as your persistence
+provider or if using CMP.
+{note}
+<a name="JavaAgent-Maven2"></a>
+## Maven2
+
+In maven2 you can enable the javaagent for your tests by adding this to
+your pom.xml file:
+
+
+ <build>
+ <plugins>
+ <!-- this configures the surefire plugin to run your tests with the
+javaagent enabled -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <forkMode>pertest</forkMode>
+
+<argLine>-javaagent:${basedir}/target/openejb-javaagent-3.0-beta-2.jar</argLine>
+ <workingDirectory>${basedir}/target</workingDirectory>
+ </configuration>
+ </plugin>
+
+ <!-- this tells maven to copy the openejb-javaagent jar into your
+target/ directory -->
+ <!-- where surefire can see it -->
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-javaagent</artifactId>
+ <version>3.0-beta-2</version>
+
+<outputDirectory>${project.build.directory}</outputDirectory>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+
+ </plugins>
+ </build>
+
Added: openejb/site/trunk/content/jms-resources-and-mdb-container.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jms-resources-and-mdb-container.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jms-resources-and-mdb-container.cwiki (added)
+++ openejb/site/trunk/content/jms-resources-and-mdb-container.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,62 @@
+h1. External ActiveMQ Broker
+
+{code:xml|title=openejb.xml}
+<openejb>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+ # Do not start the embedded ActiveMQ broker
+ BrokerXmlConfig
+ ServerUrl tcp://someHostName:61616
+ </Resource>
+
+ <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">
+ ResourceAdapter MyJmsResourceAdapter
+ </Resource>
+
+ <Container id="MyJmsMdbContainer" ctype="MESSAGE">
+ ResourceAdapter MyJmsResourceAdapter
+ </Container>
+
+ <Resource id="FooQueue" type="javax.jms.Queue"/>
+ <Resource id="BarTopic" type="javax.jms.Topic"/>
+</openejb>
+{code}
+
+The {{ServerUrl}} would be changed to point to the host and port of the ActiveMQ process. The various URL formats that ActiveMQ supports also work, such as 'failover:'.
+
+The same can be done via properties in an embedded configuration, via the {{conf/system.properties}} file or on the command line via {{-D}} flags.
+
+{code}
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, LocalInitialContextFactory.class.getName());
+
+p.put("MyJmsResourceAdapter", "new://Resource?type=ActiveMQResourceAdapter");
+p.put("MyJmsResourceAdapter.ServerUrl", "tcp://someHostName:61616");
+// Do not start the ActiveMQ broker
+p.put("MyJmsResourceAdapter.BrokerXmlConfig", "");
+
+p.put("MyJmsConnectionFactory", "new://Resource?type=javax.jms.ConnectionFactory");
+p.put("MyJmsConnectionFactory.ResourceAdapter", "MyJmsResourceAdapter");
+
+p.put("MyJmsMdbContainer", "new://Container?type=MESSAGE");
+p.put("MyJmsMdbContainer.ResourceAdapter", "MyJmsResourceAdapter");
+
+p.put("FooQueue", "new://Resource?type=javax.jms.Queue");
+p.put("BarTopic", "new://Resource?type=javax.jms.Topic");
+
+InitialContext context = new InitialContext(p);
+{code}
+
+
+From anywhere in the same VM as the EJB Container you could lookup the above resources like so:
+
+{code}
+javax.jms.ConnectionFactory cf = (ConnectionFactory)
+ context.lookup("openejb:Resource/MyJmsConnectionFactory");
+
+javax.jms.Queue queue = (Queue) context.lookup("openejb:Resource/FooQueue");
+javax.jms.Topic topic = (Topic) context.lookup("openejb:Resource/BarTopic");
+{code}
+
+h1. Internal ActiveMQ Broker
+
+_TODO_
Propchange: openejb/site/trunk/content/jms-resources-and-mdb-container.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/jms-resources-and-mdb-container.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jms-resources-and-mdb-container.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jms-resources-and-mdb-container.mdtext (added)
+++ openejb/site/trunk/content/jms-resources-and-mdb-container.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,74 @@
+Title: JMS Resources and MDB Container
+<a name="JMSResourcesandMDBContainer-ExternalActiveMQBroker"></a>
+# External ActiveMQ Broker
+
+{code:xml|title=openejb.xml}
+<openejb>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+1. Do not start the embedded ActiveMQ broker
+ BrokerXmlConfig
+ ServerUrl tcp://someHostName:61616
+ </Resource>
+
+ <Resource id="MyJmsConnectionFactory"
+type="javax.jms.ConnectionFactory">
+ ResourceAdapter MyJmsResourceAdapter
+ </Resource>
+
+ <Container id="MyJmsMdbContainer" ctype="MESSAGE">
+ ResourceAdapter MyJmsResourceAdapter
+ </Container>
+
+ <Resource id="FooQueue" type="javax.jms.Queue"/>
+ <Resource id="BarTopic" type="javax.jms.Topic"/>
+</openejb>
+
+
+ The {{ServerUrl}} would be changed to point to the host and port of the
+ActiveMQ process. The various URL formats that ActiveMQ supports also
+work, such as 'failover:'.
+
+ The same can be done via properties in an embedded configuration, via the
+{{conf/system.properties}} file or on the command line via {{-D}} flags.
+
+
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY,
+LocalInitialContextFactory.class.getName());
+
+p.put("MyJmsResourceAdapter",
+"new://Resource?type=ActiveMQResourceAdapter");
+p.put("MyJmsResourceAdapter.ServerUrl", "tcp://someHostName:61616");
+// Do not start the ActiveMQ broker
+p.put("MyJmsResourceAdapter.BrokerXmlConfig", "");
+
+p.put("MyJmsConnectionFactory",
+"new://Resource?type=javax.jms.ConnectionFactory");
+p.put("MyJmsConnectionFactory.ResourceAdapter", "MyJmsResourceAdapter");
+
+p.put("MyJmsMdbContainer", "new://Container?type=MESSAGE");
+p.put("MyJmsMdbContainer.ResourceAdapter", "MyJmsResourceAdapter");
+
+p.put("FooQueue", "new://Resource?type=javax.jms.Queue");
+p.put("BarTopic", "new://Resource?type=javax.jms.Topic");
+
+InitialContext context = new InitialContext(p);
+
+
+
+ From anywhere in the same VM as the EJB Container you could lookup the
+above resources like so:
+
+
+javax.jms.ConnectionFactory cf = (ConnectionFactory)
+ context.lookup("openejb:Resource/MyJmsConnectionFactory");
+
+javax.jms.Queue queue = (Queue)
+context.lookup("openejb:Resource/FooQueue");
+javax.jms.Topic topic = (Topic)
+context.lookup("openejb:Resource/BarTopic");
+
+
+ h1. Internal ActiveMQ Broker
+
+ _TODO_
Added: openejb/site/trunk/content/jndi-names.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jndi-names.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jndi-names.cwiki (added)
+++ openejb/site/trunk/content/jndi-names.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,278 @@
+h1. What's My Bean's JNDI Name?
+There are two things to keep in mind before you start reading:
+# OpenEJB provides a default JNDI name to your EJB.
+# You can customize the JNDI name.
+
+h2.Default JNDI name
+The default JNDI name is in the following format:
+{code}
+{deploymentId}{interfaceType.annotationName}
+{code}
+Lets try and understand the above format. Both *deploymentId* and *interfaceType.annotationName* are pre-defined variables. There are other pre-defined variables available which you could use to customize the JNDI name format.
+
+h1. JNDI Name Formatting
+{excerpt}
+The *openejb.jndiname.format* property allows you to supply a template for the global JNDI names of all your EJBs. With it, you have complete control over the structure of the JNDI layout can institute a design pattern just right for your client apps. See the [Service Locator] doc for clever ways to use the JNDI name formatting functionality in client code.
+
+ || variable || description ||
+ | moduleId | Typically the name of the ejb-jar file or the <ejb-jar id=""> id value if specified |
+ | ejbType | STATEFUL, STATELESS, BMP_ENTITY, CMP_ENTITY, or MESSAGE_DRIVEN |
+ | ejbClass | for a class named _org.acme.superfun.WidgetBean_ results in *org.acme.superfun.WidgetBean* |
+ | ejbClass.simpleName | for a class named _org.acme.superfun.WidgetBean_ results in *WidgetBean* |
+ | ejbClass.packageName | for a class named _org.acme.superfun.WidgetBean_ results in *org.acme.superfun* |
+ | ejbName | The ejb-name as specified in xml or via the 'name' attribute in an @Stateful, @Stateless, or @MessageDriven annotation |
+ | deploymentId | The unique system id for the ejb. Typically the ejbName unless specified in the openejb-jar.xml or via changing the openejb.deploymentId.format |
+ | interfaceType | see interfaceType.annotationName |
+ | interfaceType.annotationName | Following the EJB 3 annotations @RemoteHome, @LocalHome, @Remote and @Local
+- *RemoteHome* _(EJB 2 EJBHome)_
+- *LocalHome* _(EJB 2 EJBLocalHome)_
+- *Remote* _(EJB 3 Business Remote)_
+- *Local* _(EJB 3 Business Local)_
+- *Endpoint* _(EJB webservice endpoint)_
+|
+ | interfaceType.annotationNameLC | This is the same as interfaceType.annotationName, but all in lower case.
+|
+
+ | interfaceType.xmlName | Following the ejb-jar.xml descriptor elements <home>, <local-home>, <business-remote>, <business-local>, and <service-endpoint>:
+- *home* _(EJB 2 EJBHome)_
+- *local-home* _(EJB 2 EJBLocalHome)_
+- *business-remote* _(EJB 3 Business Remote)_
+- *business-local* _(EJB 3 Business Local)_
+- *service-endpoint* _(EJB webservice endpoint)_
+ |
+ | interfaceType.xmlNameCc | Camel-case version of interfaceType.xmlName:
+- *Home* _(EJB 2 EJBHome)_
+- *LocalHome* _(EJB 2 EJBLocalHome)_
+- *BusinessRemote* _(EJB 3 Business Remote)_
+- *BusinessLocal* _(EJB 3 Business Local)_
+- *ServiceEndpoint* _(EJB webservice endpoint)_ |
+ | interfaceType.openejbLegacyName | Following the OpenEJB 1.0 hard-coded format:
+- _(empty string)_ _(EJB 2 EJBHome)_
+- *Local* _(EJB 2 EJBLocalHome)_
+- *BusinessRemote* _(EJB 3 Business Remote)_
+- *BusinessLocal* _(EJB 3 Business Local)_
+- *ServiceEndpoint* _(EJB webservice endpoint)_ |
+ | interfaceClass | - _(business)_ for a class named _org.acme.superfun.WidgetRemote_ results in *org.acme.superfun.WidgetRemote*
+ - _(home)_ for a class named _org.acme.superfun.WidgetHome_ results in *org.acme.superfun.WidgetHome*
+|
+ | interfaceClass.simpleName | - _(business)_ for a class named _org.acme.superfun.WidgetRemote_ results in *WidgetRemote*
+- _(home)_ for a class named _org.acme.superfun.WidgetHome_ results in *WidgetHome* |
+ | interfaceClass.packageName | for a class named _org.acme.superfun.WidgetRemote_ results in *org.acme.superfun* |
+{excerpt}
+
+h1. Setting the JNDI name
+
+It's possible to set the desired jndi name format for the whole server level, an ejb-jar, an ejb, an ejb's "local" interface (local/remote/local-home/home), and for an individual interface the ejb implements. More specific jndi name formats act as an override to any more general formats. The most specific format dictates the jndi name that will be used for any given interface of an ejb. It's possible to specify a general format for your server, override it at an ejb level and override that further for a specific interface of that ejb.
+
+h2. Via System property
+
+The jndi name format can be set on a server level via a _system property_, for example:
+
+{panel:border=dotted}
+$ ./bin/openejb start "-Dopenejb.jndiname.format=\{ejbName}/\{interfaceClass}"
+{panel}
+
+As usual, other ways of specifying system properties are via the conf/system.properties file in a standalone server, or via the InitialContext properties when embedded.
+
+h2. Via properties in the openejb-jar.xml
+
+It's possible to set the openejb.jndiname.format for an ejb-jar jar in a META-INF/openejb-jar.xml file as follows:
+
+{code:xml}
+<openejb-jar>
+ <properties>
+ openejb.deploymentId.format = {ejbName}
+ openejb.jndiname.format = {deploymentId}{interfaceType.annotationName}
+ </properties>
+</openejb-jar>
+{code}
+
+h2. Via the <jndi> tag for a specific ejb
+
+The following sets the name specifically for the interface org.superbiz.Foo.
+
+{code:xml}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo" interface="org.superbiz.Foo"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+Or more generally...
+
+{code:xml}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo" interface="Remote"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+Or more generally still...
+
+{code:xml}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+The 'name' attribute can still use templates if it likes, such as:
+
+{code:xml}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="ejb/{interfaceClass.simpleName}" interface="org.superbiz.Foo"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+h3. Multiple <jndi> tags
+
+Multiple <jndi> tags are allowed making it possible for you to be as specific as you need about the jndi name of each interface or each logical group of iterfaces (Local, Remote, LocalHome, RemoteHome).
+
+Given an ejb, FooBean, with the following interfaces:
+ - business-local: org.superbiz.LocalOne
+ - business-local: org.superbiz.LocalTwo
+ - business-remote: org.superbiz.RemoteOne
+ - business-remote: org.superbiz.RemoteTwo
+ - home: org.superbiz.FooHome
+ - local-home: org.superbiz.FooLocalHome
+
+The following four examples would yield the same jndi names. The intention with these examples is to show the various ways you can isolate specific interfaces or types of interfaces to gain more specific control on how they are named.
+
+{code:xml|title=#1}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="LocalOne" interface="org.superbiz.LocalOne"/>
+ <jndi name="LocalTwo" interface="org.superbiz.LocalTwo"/>
+ <jndi name="RemoteOne" interface="org.superbiz.RemoteOne"/>
+ <jndi name="RemoteTwo" interface="org.superbiz.RemoteTwo"/>
+ <jndi name="FooHome" interface="org.superbiz.FooHome"/>
+ <jndi name="FooLocalHome" interface="org.superbiz.FooLocalHome"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+{code:xml|title=#2}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to LocalOne and LocalTwo -->
+ <jndi name="{interfaceClass.simpleName}" interface="Local"/>
+
+ <!-- applies to RemoteOne and RemoteTwo -->
+ <jndi name="{interfaceClass.simpleName}" interface="Remote"/>
+
+ <!-- applies to FooHome -->
+ <jndi name="{interfaceClass.simpleName}" interface="RemoteHome"/>
+
+ <!-- applies to FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}" interface="LocalHome"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+{code:xml|title=#3}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to RemoteOne, RemoteTwo, FooHome, and FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}"/>
+
+ <!-- these two would count as an override on the above format -->
+ <jndi name="LocalOne" interface="org.superbiz.LocalOne"/>
+ <jndi name="LocalTwo" interface="org.superbiz.LocalTwo"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+{code:xml|title=#4}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to LocalOne, LocalTwo, RemoteOne, RemoteTwo, FooHome, and FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}"/>
+ </ejb-deployment>
+</openejb-jar>
+{code}
+
+
+
+h1. Changing the Default Setting
+
+*You are responsible for ensuring the names don't conflict.*
+
+h3. Conservative settings
+
+A very conservative setting such as "_\{deploymentId}/\{interfaceClass}_" would guarantee that each and every single interface is bound to JNDI. If your bean had a legacy EJBObject interface, three business remote interfaces, and two business local interfaces, this pattern would result in *six* proxies bound into JNDI.
+
+Similarly conservative settings would be:
+ - _\{deploymentId}/\{interfaceClass.simpleName}_
+ - _\{moduleId}/\{ejbName}/\{interfaceClass}_
+ - _\{ejbName}/\{interfaceClass}_
+ - _\{moduleId}/\{ejbClass}/\{interfaceClass}_
+ - _\{ejbClass}/\{interfaceClass}_
+ - _\{ejbClass}/\{interfaceClass.simpleName}_
+ - _\{ejbClass.simpleName}/\{interfaceClass.simpleName}_
+ - _\{interfaceClass}/\{ejbName}_
+
+Bordeline optimistic:
+ - _\{moduleId}/\{interfaceClass}_
+ - _\{interfaceClass}_
+
+The above two settings would work if you the interface wasn't shared by other beans.
+
+h3. Pragmatic settings
+
+A more middle ground setting such as "_\{deploymentId}\{interfaceType.annotationName}_" would guarantee that at least one proxy of each interface type is bound to JNDI. If your bean had a legacy EJBObject interface, three business remote interfaces, and two business local interfaces, this pattern would result in *three* proxies bound into JNDI: one proxy dedicated to your EJBObject interface; one proxy implementing all three business remote interfaces; one proxy implementing the two business local interfaces.
+
+Similarly pragmatic settings would be:
+ - _\{moduleId}/\{ejbClass}/\{interfaceType.annotationName}_
+ - _\{ejbClass}/\{interfaceType.xmlName}_
+ - _\{ejbClass.simpleName}/\{interfaceType.xmlNameCc}_
+ - _\{interfaceType}/\{ejbName}_
+ - _\{interfaceType}/\{ejbClass}_
+
+h3. Optimistic settings
+
+A very optimistic setting such as "_\{deploymentId}_" would guarantee only one proxy for the bean will be bound to JNDI. This would be fine if you knew you only had one type of interface in your beans. For example, only business remote interfaces, or only business local interfaces, or only an EJBObject interface, or only an EJBLocalObject interface.
+
+If a bean in the app did have more than one interface type, one business local and one business remote for example, by default OpenEJB will reject the app when it detects that it cannot bind the second interface. This strict behavior can be disabled by setting the *openejb.jndiname.failoncollision* system property to _false_. When this property is set to false, we will simply log an error that the second proxy cannot be bound to JNDI, tell you which ejb is using that name, and continue loading your app.
+
+Similarly optimistic settings would be:
+ - _\{ejbName}_
+ - _\{ejbClass}_
+ - _\{ejbClass.simpleName}_
+ - _\{moduleId}/\{ejbClass.simpleName}_
+ - _\{moduleId}/\{ejbName}_
+
+h1. Advanced Details on EJB 3.0 Business Proxies (the simple part)
+
+If you implement your business interfaces, your life is simple as your proxies will also implement your business interfaces of the same type. Meaning any proxy OpenEJB creates for a business local interface will also implement your other business local interfaces. Similarly, any proxy OpenEJB creates for a business remote interface will also implement your other business remote interfaces.
+
+h1. Advanced Details on EJB 3.0 Business Proxies (the complicated part)
+
+{info:Who should read?}
+Read this section of either of these two apply to you:
+ - You do not implement your business interfaces in your bean class
+ - One or more of your business remote interfaces extend from javax.rmi.Remote
+
+If neither of these two items describe your apps, then there is no need to read further. Go have fun.
+{info}
+h3. Not implementing business interfaces
+
+If you do not implement your business interfaces it may not be possible for us to implement all your business interfaces in a single interface. Conflicts in the throws clauses and the return values can occur as detailed [here|OPENEJB:Multiple Business Interface Hazzards]. When creating a proxy for an interface we will detect and remove any other business interfaces that would conflict with the main interface.
+
+h3. Business interfaces extending javax.rmi.Remote
+
+Per spec rules many runtime exceptions (container or connection related) are thrown from javax.rmi.Remote proxies as java.rmi.RemoteException which is not a runtime exception and must be throwable via the proxy as a checked exception. The issue is that conflicting throws clauses are actually removed for two interfaces sharing the same method signature. For example two methods such as these:
+ - InterfaceA: void doIt() throws Foo;
+ - InterfaceB: void doIt() throws RemoteException;
+
+can be implemented by trimming out the conflicting throws clauses as follows:
+ - Implementation: void doIt(){}
+
+This is fine for a bean class as it does not need to throw the RMI required javax.rmi.RemoteException. However if we create a proxy from these two interfaces it will also wind up with a 'doIt(){}' method that cannot throw javax.rmi.RemoteException. This is very bad as the container does need to throw RemoteException to any business interfaces extending java.rmi.Remote for any container related issues or connection issues. If the container attempts to throw a RemoteException from the proxies 'doIt(){}' method, it will result in an UndeclaredThrowableException thrown by the VM.
+
+The only way to guarantee the proxy has the 'doIt() throws RemoteException {}' method of InterfaceB is to cut out InterfaceA when we create the proxy dedicated to InterfaceB.
+{excerpt}
Propchange: openejb/site/trunk/content/jndi-names.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/jndi-names.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jndi-names.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jndi-names.mdtext (added)
+++ openejb/site/trunk/content/jndi-names.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,395 @@
+Title: JNDI Names
+<a name="JNDINames-What'sMyBean'sJNDIName?"></a>
+# What's My Bean's JNDI Name?
+There are two things to keep in mind before you start reading:
+1. OpenEJB provides a default JNDI name to your EJB.
+1. You can customize the JNDI name.
+
+<a name="JNDINames-DefaultJNDIname"></a>
+## Default JNDI name
+The default JNDI name is in the following format:
+
+ {deploymentId}{interfaceType.annotationName}
+
+Lets try and understand the above format. Both *deploymentId* and
+*interfaceType.annotationName* are pre-defined variables. There are other
+pre-defined variables available which you could use to customize the JNDI
+name format.
+
+<a name="JNDINames-JNDINameFormatting"></a>
+# JNDI Name Formatting
+{excerpt}
+The *openejb.jndiname.format* property allows you to supply a template for
+the global JNDI names of all your EJBs. With it, you have complete control
+over the structure of the JNDI layout can institute a design pattern just
+right for your client apps. See the [Service Locator](service-locator.html)
+ doc for clever ways to use the JNDI name formatting functionality in
+client code.
+
+ || variable || description ||
+ | moduleId | Typically the name of the ejb-jar file or the <ejb-jar
+id=""> id value if specified |
+ | ejbType | STATEFUL, STATELESS, BMP_ENTITY, CMP_ENTITY, or
+MESSAGE_DRIVEN |
+ | ejbClass | for a class named _org.acme.superfun.WidgetBean_ results in
+*org.acme.superfun.WidgetBean* |
+ | ejbClass.simpleName | for a class named _org.acme.superfun.WidgetBean_
+results in *WidgetBean* |
+ | ejbClass.packageName | for a class named _org.acme.superfun.WidgetBean_
+results in *org.acme.superfun* |
+ | ejbName | The ejb-name as specified in xml or via the 'name' attribute
+in an @Stateful, @Stateless, or @MessageDriven annotation |
+ | deploymentId | The unique system id for the ejb. Typically the ejbName
+unless specified in the openejb-jar.xml or via changing the
+openejb.deploymentId.format |
+ | interfaceType | see interfaceType.annotationName |
+ | interfaceType.annotationName | Following the EJB 3 annotations
+@RemoteHome, @LocalHome, @Remote and @Local
+- *RemoteHome* _(EJB 2 EJBHome)_
+- *LocalHome* _(EJB 2 EJBLocalHome)_
+- *Remote* _(EJB 3 Business Remote)_
+- *Local* _(EJB 3 Business Local)_
+- *Endpoint* _(EJB webservice endpoint)_
+<table>
+<tr></tr>
+ | interfaceType.annotationNameLC | This is the same as
+interfaceType.annotationName, but all in lower case.
+<tr></tr>
+</table>
+
+ | interfaceType.xmlName | Following the ejb-jar.xml descriptor elements
+<home>, <local-home>, <business-remote>, <business-local>, and
+<service-endpoint>:
+- *home* _(EJB 2 EJBHome)_
+- *local-home* _(EJB 2 EJBLocalHome)_
+- *business-remote* _(EJB 3 Business Remote)_
+- *business-local* _(EJB 3 Business Local)_
+- *service-endpoint* _(EJB webservice endpoint)_
+ |
+ | interfaceType.xmlNameCc | Camel-case version of interfaceType.xmlName:
+- *Home* _(EJB 2 EJBHome)_
+- *LocalHome* _(EJB 2 EJBLocalHome)_
+- *BusinessRemote* _(EJB 3 Business Remote)_
+- *BusinessLocal* _(EJB 3 Business Local)_
+- *ServiceEndpoint* _(EJB webservice endpoint)_ |
+ | interfaceType.openejbLegacyName | Following the OpenEJB 1.0 hard-coded
+format:
+- _(empty string)_ _(EJB 2 EJBHome)_
+- *Local* _(EJB 2 EJBLocalHome)_
+- *BusinessRemote* _(EJB 3 Business Remote)_
+- *BusinessLocal* _(EJB 3 Business Local)_
+- *ServiceEndpoint* _(EJB webservice endpoint)_ |
+ | interfaceClass | - _(business)_ for a class named
+_org.acme.superfun.WidgetRemote_ results in
+*org.acme.superfun.WidgetRemote*
+ - _(home)_ for a class named _org.acme.superfun.WidgetHome_ results in
+*org.acme.superfun.WidgetHome*
+<table>
+<tr></tr>
+ | interfaceClass.simpleName | - _(business)_ for a class named
+_org.acme.superfun.WidgetRemote_ results in *WidgetRemote*
+- _(home)_ for a class named _org.acme.superfun.WidgetHome_ results in
+*WidgetHome* |
+ | interfaceClass.packageName | for a class named
+_org.acme.superfun.WidgetRemote_ results in *org.acme.superfun* |
+{excerpt}
+</table>
+
+<a name="JNDINames-SettingtheJNDIname"></a>
+# Setting the JNDI name
+
+It's possible to set the desired jndi name format for the whole server
+level, an ejb-jar, an ejb, an ejb's "local" interface
+(local/remote/local-home/home), and for an individual interface the ejb
+implements. More specific jndi name formats act as an override to any more
+general formats. The most specific format dictates the jndi name that will
+be used for any given interface of an ejb. It's possible to specify a
+general format for your server, override it at an ejb level and override
+that further for a specific interface of that ejb.
+
+<a name="JNDINames-ViaSystemproperty"></a>
+## Via System property
+
+The jndi name format can be set on a server level via a _system property_,
+for example:
+
+{panel:border=dotted}
+$ ./bin/openejb start
+"-Dopenejb.jndiname.format=\{ejbName}/\{interfaceClass}"
+{panel}
+
+As usual, other ways of specifying system properties are via the
+conf/system.properties file in a standalone server, or via the
+InitialContext properties when embedded.
+
+<a name="JNDINames-Viapropertiesintheopenejb-jar.xml"></a>
+## Via properties in the openejb-jar.xml
+
+It's possible to set the openejb.jndiname.format for an ejb-jar jar in a
+META-INF/openejb-jar.xml file as follows:
+
+
+ <openejb-jar>
+ <properties>
+ openejb.deploymentId.format = {ejbName}
+ openejb.jndiname.format = {deploymentId}{interfaceType.annotationName}
+ </properties>
+ </openejb-jar>
+
+
+<a name="JNDINames-Viathe<jndi>tagforaspecificejb"></a>
+## Via the <jndi> tag for a specific ejb
+
+The following sets the name specifically for the interface
+org.superbiz.Foo.
+
+
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo" interface="org.superbiz.Foo"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+Or more generally...
+
+
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo" interface="Remote"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+Or more generally still...
+
+
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="foo"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+The 'name' attribute can still use templates if it likes, such as:
+
+
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="ejb/{interfaceClass.simpleName}"
+interface="org.superbiz.Foo"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+<a name="JNDINames-Multiple<jndi>tags"></a>
+### Multiple <jndi> tags
+
+Multiple <jndi> tags are allowed making it possible for you to be as
+specific as you need about the jndi name of each interface or each logical
+group of iterfaces (Local, Remote, LocalHome, RemoteHome).
+
+Given an ejb, FooBean, with the following interfaces:
+ - business-local: org.superbiz.LocalOne
+ - business-local: org.superbiz.LocalTwo
+ - business-remote: org.superbiz.RemoteOne
+ - business-remote: org.superbiz.RemoteTwo
+ - home: org.superbiz.FooHome
+ - local-home: org.superbiz.FooLocalHome
+
+The following four examples would yield the same jndi names. The intention
+with these examples is to show the various ways you can isolate specific
+interfaces or types of interfaces to gain more specific control on how they
+are named.
+
+{code:xml|title=#1}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <jndi name="LocalOne" interface="org.superbiz.LocalOne"/>
+ <jndi name="LocalTwo" interface="org.superbiz.LocalTwo"/>
+ <jndi name="RemoteOne" interface="org.superbiz.RemoteOne"/>
+ <jndi name="RemoteTwo" interface="org.superbiz.RemoteTwo"/>
+ <jndi name="FooHome" interface="org.superbiz.FooHome"/>
+ <jndi name="FooLocalHome" interface="org.superbiz.FooLocalHome"/>
+ </ejb-deployment>
+</openejb-jar>
+
+
+ {code:xml|title=#2}
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to LocalOne and LocalTwo -->
+ <jndi name="{interfaceClass.simpleName}" interface="Local"/>
+
+ <!-- applies to RemoteOne and RemoteTwo -->
+ <jndi name="{interfaceClass.simpleName}" interface="Remote"/>
+
+ <!-- applies to FooHome -->
+ <jndi name="{interfaceClass.simpleName}" interface="RemoteHome"/>
+
+ <!-- applies to FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}" interface="LocalHome"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+{code:xml|title=#3}
+<openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to RemoteOne, RemoteTwo, FooHome, and FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}"/>
+
+ <!-- these two would count as an override on the above format -->
+ <jndi name="LocalOne" interface="org.superbiz.LocalOne"/>
+ <jndi name="LocalTwo" interface="org.superbiz.LocalTwo"/>
+ </ejb-deployment>
+</openejb-jar>
+
+
+ {code:xml|title=#4}
+ <openejb-jar>
+ <ejb-deployment ejb-name="FooBean">
+ <!-- applies to LocalOne, LocalTwo, RemoteOne, RemoteTwo, FooHome, and
+FooLocalHome -->
+ <jndi name="{interfaceClass.simpleName}"/>
+ </ejb-deployment>
+ </openejb-jar>
+
+
+
+
+<a name="JNDINames-ChangingtheDefaultSetting"></a>
+# Changing the Default Setting
+
+*You are responsible for ensuring the names don't conflict.*
+
+<a name="JNDINames-Conservativesettings"></a>
+### Conservative settings
+
+A very conservative setting such as "_\{deploymentId}/\{interfaceClass}_"
+would guarantee that each and every single interface is bound to JNDI. If
+your bean had a legacy EJBObject interface, three business remote
+interfaces, and two business local interfaces, this pattern would result in
+*six* proxies bound into JNDI.
+
+Similarly conservative settings would be:
+ - _\{deploymentId}/\{interfaceClass.simpleName}_
+ - _\{moduleId}/\{ejbName}/\{interfaceClass}_
+ - _\{ejbName}/\{interfaceClass}_
+ - _\{moduleId}/\{ejbClass}/\{interfaceClass}_
+ - _\{ejbClass}/\{interfaceClass}_
+ - _\{ejbClass}/\{interfaceClass.simpleName}_
+ - _\{ejbClass.simpleName}/\{interfaceClass.simpleName}_
+ - _\{interfaceClass}/\{ejbName}_
+
+Bordeline optimistic:
+ - _\{moduleId}/\{interfaceClass}_
+ - _\{interfaceClass}_
+
+The above two settings would work if you the interface wasn't shared by
+other beans.
+
+<a name="JNDINames-Pragmaticsettings"></a>
+### Pragmatic settings
+
+A more middle ground setting such as
+"_\{deploymentId}\{interfaceType.annotationName}_" would guarantee that at
+least one proxy of each interface type is bound to JNDI. If your bean had
+a legacy EJBObject interface, three business remote interfaces, and two
+business local interfaces, this pattern would result in *three* proxies
+bound into JNDI: one proxy dedicated to your EJBObject interface; one proxy
+implementing all three business remote interfaces; one proxy implementing
+the two business local interfaces.
+
+Similarly pragmatic settings would be:
+ - _\{moduleId}/\{ejbClass}/\{interfaceType.annotationName}_
+ - _\{ejbClass}/\{interfaceType.xmlName}_
+ - _\{ejbClass.simpleName}/\{interfaceType.xmlNameCc}_
+ - _\{interfaceType}/\{ejbName}_
+ - _\{interfaceType}/\{ejbClass}_
+
+<a name="JNDINames-Optimisticsettings"></a>
+### Optimistic settings
+
+A very optimistic setting such as "_\{deploymentId}_" would guarantee only
+one proxy for the bean will be bound to JNDI. This would be fine if you
+knew you only had one type of interface in your beans. For example, only
+business remote interfaces, or only business local interfaces, or only an
+EJBObject interface, or only an EJBLocalObject interface.
+
+If a bean in the app did have more than one interface type, one business
+local and one business remote for example, by default OpenEJB will reject
+the app when it detects that it cannot bind the second interface. This
+strict behavior can be disabled by setting the
+*openejb.jndiname.failoncollision* system property to _false_. When this
+property is set to false, we will simply log an error that the second proxy
+cannot be bound to JNDI, tell you which ejb is using that name, and
+continue loading your app.
+
+Similarly optimistic settings would be:
+ - _\{ejbName}_
+ - _\{ejbClass}_
+ - _\{ejbClass.simpleName}_
+ - _\{moduleId}/\{ejbClass.simpleName}_
+ - _\{moduleId}/\{ejbName}_
+
+<a name="JNDINames-AdvancedDetailsonEJB3.0BusinessProxies(thesimplepart)"></a>
+# Advanced Details on EJB 3.0 Business Proxies (the simple part)
+
+If you implement your business interfaces, your life is simple as your
+proxies will also implement your business interfaces of the same type.
+Meaning any proxy OpenEJB creates for a business local interface will also
+implement your other business local interfaces. Similarly, any proxy
+OpenEJB creates for a business remote interface will also implement your
+other business remote interfaces.
+
+<a name="JNDINames-AdvancedDetailsonEJB3.0BusinessProxies(thecomplicatedpart)"></a>
+# Advanced Details on EJB 3.0 Business Proxies (the complicated part)
+
+{info:Who should read?}
+Read this section of either of these two apply to you:
+ - You do not implement your business interfaces in your bean class
+ - One or more of your business remote interfaces extend from
+javax.rmi.Remote
+
+If neither of these two items describe your apps, then there is no need to
+read further. Go have fun.
+{info}
+<a name="JNDINames-Notimplementingbusinessinterfaces"></a>
+### Not implementing business interfaces
+
+If you do not implement your business interfaces it may not be possible for
+us to implement all your business interfaces in a single interface.
+Conflicts in the throws clauses and the return values can occur as detailed [here](openejb:multiple-business-interface-hazzards.html)
+. When creating a proxy for an interface we will detect and remove any
+other business interfaces that would conflict with the main interface.
+
+<a name="JNDINames-Businessinterfacesextendingjavax.rmi.Remote"></a>
+### Business interfaces extending javax.rmi.Remote
+
+Per spec rules many runtime exceptions (container or connection related)
+are thrown from javax.rmi.Remote proxies as java.rmi.RemoteException which
+is not a runtime exception and must be throwable via the proxy as a checked
+exception. The issue is that conflicting throws clauses are actually
+removed for two interfaces sharing the same method signature. For example
+two methods such as these:
+ - InterfaceA: void doIt() throws Foo;
+ - InterfaceB: void doIt() throws RemoteException;
+
+can be implemented by trimming out the conflicting throws clauses as
+follows:
+ - Implementation: void doIt(){}
+
+This is fine for a bean class as it does not need to throw the RMI required
+javax.rmi.RemoteException. However if we create a proxy from these two
+interfaces it will also wind up with a 'doIt(){}' method that cannot throw
+javax.rmi.RemoteException. This is very bad as the container does need to
+throw RemoteException to any business interfaces extending java.rmi.Remote
+for any container related issues or connection issues. If the container
+attempts to throw a RemoteException from the proxies 'doIt(){}' method, it
+will result in an UndeclaredThrowableException thrown by the VM.
+
+The only way to guarantee the proxy has the 'doIt() throws RemoteException
+{}' method of InterfaceB is to cut out InterfaceA when we create the proxy
+dedicated to InterfaceB.
+{excerpt}
Added: openejb/site/trunk/content/jpa-concepts.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jpa-concepts.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jpa-concepts.cwiki (added)
+++ openejb/site/trunk/content/jpa-concepts.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,142 @@
+h1. JPA 101
+
+If there's one thing you have to understand to successfully use JPA (Java Persistence API) it's the concept of a *Cache*. Almost everything boils down to the Cache at one point or another. Unfortunately the Cache is an internal thing and not exposed via the JPA API classes, so it not easy to touch or feel from a coding perspective.
+
+Here's a quick cheat sheet of the JPA world:
+
+ - A *Cache* is a *copy of data*, copy meaning pulled from but living outside the database.
+ - *Flushing* a Cache is the act of putting modified data back into the database.
+ - A *PersistenceContext* is essentially a Cache. It also tends to have it's own non-shared database connection.
+ - An *EntityManager* represents a PersistenceContext (and therefore a Cache)
+ - An *EntityManagerFactory* creates an EntityManager (and therefore a PersistenceContext/Cache)
+
+
+ - With <persistence-unit transaction-type="*RESOURCE_LOCAL*"> *you* are responsible for EntityManager (PersistenceContext/Cache) creating and tracking...
+ -- You *must* use the *EntityManagerFactory* to get an EntityManager
+ -- The resulting *EntityManager* instance *is* a PersistenceContext/Cache
+ -- An *EntityManagerFactory* can be injected via the *@PersistenceUnit* annotation only (not @PersistenceContext)
+ -- You are *not* allowed to use @PersistenceContext to refer to a unit of type RESOURCE_LOCAL
+ -- You *must* use the *EntityTransaction* API to begin/commit around *every* call to your EntityManger
+ -- Calling entityManagerFactory.createEntityManager() twice results in *two* separate EntityManager instances and therefor *two* separate PersistenceContexts/Caches.
+ -- It is *almost never* a good idea to have more than one *instance* of an EntityManager in use (don't create a second one unless you've destroyed the first)
+
+
+ - With <persistence-unit transaction-type="*TRANSACTION*"> the *container* will do EntityManager (PersistenceContext/Cache) creating and tracking...
+ -- You *cannot* use the *EntityManagerFactory* to get an EntityManager
+ -- You can only get an *EntityManager* supplied by the *container*
+ -- An *EntityManager* can be injected via the *@PersistenceContext* annotation only (not @PersistenceUnit)
+ -- You are *not* allowed to use @PersistenceUnit to refer to a unit of type TRANSACTION
+ -- The *EntityManager* given by the container is a *reference* to the PersistenceContext/Cache associated with a JTA Transaction.
+ -- If no JTA transaction is in progress, the EntityManager *cannot be used* because there is no PersistenceContext/Cache.
+ -- Everyone with an EntityManager reference to the *same unit* in the *same transaction* will automatically have a reference to the *same PersistenceContext/Cache*
+ -- The PersistenceContext/Cache is *flushed* and cleared at JTA *commit* time
+
+h1. Cache == PersistenceContext
+
+The concept of a database cache is an extremely important concept to be aware of. Without a copy of the data in memory (i.e. a cache) when you call account.getBalance() the persistence provider would have to go read the value from the database. Calling account.getBalance() several times would cause several trips to the database. This would obviously be a big waste of resources. The other side of having a cache is that when you call account.setBalance(5000) it also doesn't hit the database (usually). When the cache is "flushed" the data in it is sent to the database via as many SQL updates, inserts and deletes as are required. That is the basics of java persistence of any kind all wrapped in a nutshell. If you can understand that, you're good to go in nearly any persistence technology java has to offer.
+
+Complications can arise when there is more than one PersistenceContext/Cache relating the same data in the same transaction. In any given transaction you want exactly one PersistenceContext/Cache for a given set of data. Using a TRANSACTION unit with an EntityManager created by the container will always guarantee that this is the case. With a RESOURCE_LOCAL unit and an EntityManagerFactory you should create and use exactly one EntityManager instance in your transaction to ensure there is only one active PersistenceContext/Cache for the given set of data active against the current transaction.
+
+h1. Caches and Detaching
+
+Detaching is the concept of a persistent object *leaving* the PersistenceContext/Cache. Leaving means that any updates made to the object are *not* reflected in the PersistenceContext/Cache. An object will become Detached if it somehow *lives longer* or is *used outside* the scope of the PersistenceContext/Cache.
+
+For a TRANSACTION unit, the PersistenceContext/Cache will live as long as the transaction does. When a transaction completes (commits or rollsback) all objects that were in the PersistenceContext/Cache are Detached. You can still use them, but they are no longer associated with a PersistenceContext/Cache and modifications on them will *not* be reflected in a PersistenceContext/Cache and therefore not the database either.
+
+Serializing objects that are currently in a PersistenceContext/Cache will also cause them to Detach.
+
+In some cases objects or collections of objects that become Detached may not have all the data you need. This can be because of lazy loading. With lazy loading, data isn't pulled from the database and into the PersistenceContext/Cache until it is requested in code. In many cases the Collections of persistent objects returned from an javax.persistence.Query.getResultList() call are completely empty until you iterate over them. A side effect of this is that if the Collection becomes Detached before it's been fully read it will be permanently empty and of no use and calling methods on the Detached Collection can cause strange errors and exceptions to be thrown. If you wish to Detach a Collection of persistent objects it is always a good idea to iterate over the Collection at least once.
+
+You *cannot* call EntityManager.persist() or EntityManager.remove() on a Detached object.
+
+Calling EntityManager.merge() will re-attach a Detached object.
+
+h1. Valid RESOURCE_LOCAL Unit usage
+
+Servlets and EJBs can use RESOURCE_LOCAL persistence units through the EntityManagerFactory as follows:
+
+{code:xml=persistence.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <!-- Tutorial "unit" -->
+ <persistence-unit name="Tutorial" transaction-type="RESOURCE_LOCAL">
+ <non-jta-data-source>myNonJtaDataSource</non-jta-data-source>
+ <class>org.superbiz.jpa.Account</class>
+ </persistence-unit>
+
+</persistence>
+{code}
+
+{code}
+import javax.persistence.EntityManagerFactory;
+import javax.persistence.EntityManager;
+import javax.persistence.EntityTransaction;
+import javax.persistence.PersistenceUnit;
+
+public class MyEjbOrServlet ... {
+
+ @PersistenceUnit(unitName="Tutorial")
+ private EntityManagerFactory factory;
+
+ // Proper exception handling left out for simplicity
+ public void ejbMethodOrServletServiceMethod() throws Exception {
+ EntityManager entityManager = factory.createEntityManager();
+
+ EntityTransaction entityTransaction = entityManager.getTransaction();
+
+ entityTransaction.begin();
+
+ Account account = entityManager.find(Account.class, 12345);
+
+ account.setBalance(5000);
+
+ entityTransaction.commit();
+ }
+
+ ...
+}
+{code}
+
+h1. Valid TRANSACTION Unit usage
+
+EJBs can use TRANSACTION persistence units through the EntityManager as follows:
+
+{code:xml=persistence.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <!-- Tutorial "unit" -->
+ <persistence-unit name="Tutorial" transaction-type="TRANSACTION">
+ <jta-data-source>myJtaDataSource</jta-data-source>
+ <non-jta-data-source>myNonJtaDataSource</non-jta-data-source>
+ <class>org.superbiz.jpa.Account</class>
+ </persistence-unit>
+
+</persistence>
+{code}
+
+{code}
+import javax.ejb.Stateless;
+import javax.ejb.TransactionAttribute;
+import javax.ejb.TransactionAttributeType;
+import javax.persistence.EntityManager;
+import javax.persistence.PersistenceContext;
+
+@Stateless
+public class MyEjb implements MyEjbInterface {
+
+ @PersistenceContext(unitName = "Tutorial")
+ private EntityManager entityManager;
+
+ // Proper exception handling left out for simplicity
+ @TransactionAttribute(TransactionAttributeType.REQUIRED)
+ public void ejbMethod() throws Exception {
+
+ Account account = entityManager.find(Account.class, 12345);
+
+ account.setBalance(5000);
+
+ }
+}
+{code}
\ No newline at end of file
Propchange: openejb/site/trunk/content/jpa-concepts.cwiki
------------------------------------------------------------------------------
svn:eol-style = native