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 [8/13] - /openejb/site/trunk/content/
Added: openejb/site/trunk/content/jpa-concepts.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jpa-concepts.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jpa-concepts.mdtext (added)
+++ openejb/site/trunk/content/jpa-concepts.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,218 @@
+Title: JPA Concepts
+<a name="JPAConcepts-JPA101"></a>
+# 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
+
+<a name="JPAConcepts-Cache==PersistenceContext"></a>
+# 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.
+
+<a name="JPAConcepts-CachesandDetaching"></a>
+# 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.
+
+<a name="JPAConcepts-ValidRESOURCE_LOCALUnitusage"></a>
+# 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>
+
+
+
+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();
+ }
+
+ ...
+}
+
+
+ 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>
+
+
+
+ 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);
+
+ }
+ }
+
Added: openejb/site/trunk/content/jpa-usage.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jpa-usage.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jpa-usage.cwiki (added)
+++ openejb/site/trunk/content/jpa-usage.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,23 @@
+h1. Things to watch out for
+
+h2. Critical: Always set jta-data-source and non-jta-data-source
+
+Always set the value of jta-data-source and non-jta-data-source in your persistence.xml file. Regardless if targeting your EntityManager usage for transaction-type="RESOURCE_LOCAL" or transaction-type="TRANSACTION", it's very difficult to guarantee one or the other will be the only one needed. Often times the JPA Provider itself will require both internally to do various optimizations or other special features.
+
+* The *jta-data-source* should always have it's OpenEJB-specific '*JtaManaged*' property set to '*true*' (this is the default)
+* The *non-jta-data-source* should always have it's OpenEJB-specific '*JtaManaged*' property set to '*false*'.
+
+See [Containers and Resources] for how to configure 'JtaManaged' and a full list of <Resource> properties for DataSources.
+
+h2. Be detach aware
+
+A warning for any new JPA user is by default all objects will detach at the end of a transaction. People typically discover this when the go to remove or update an object they fetched previously and get an exception like "You cannot perform operation delete on detached object".
+
+All ejb methods start a transaction unless a) you [configure them otherwise|Transaction Annotations], or b) the caller already has a transaction in progress when it calls the bean. If you're in a test case or a servlet, it's most likely B that is biting you. You're asking an ejb for some persistent objects, it uses the EntityManager in the scope of the transaction started around it's method and returns some persistent objects, by the time you get them the transaction has completed and now the objects are detached.
+
+h3. Solutions
+ # Call EntityManager.merge(..) inside the bean code to reattach your object.
+ # Use PersistenceContextType.EXTENDED as in '@PersistenceContext(unitName = "movie-unit", type = PersistenceContextType.EXTENDED)' for EntityManager refs instead of the default of PersistenceContextType.TRANSACTION.
+ # If testing, use a technique to execute transactions in your test code. That's described here in [Unit testing transactions]
+
+
Propchange: openejb/site/trunk/content/jpa-usage.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/jpa-usage.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/jpa-usage.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/jpa-usage.mdtext (added)
+++ openejb/site/trunk/content/jpa-usage.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,50 @@
+Title: JPA Usage
+<a name="JPAUsage-Thingstowatchoutfor"></a>
+# Things to watch out for
+
+<a name="JPAUsage-Critical:Alwayssetjta-data-sourceandnon-jta-data-source"></a>
+## Critical: Always set jta-data-source and non-jta-data-source
+
+Always set the value of jta-data-source and non-jta-data-source in your
+persistence.xml file. Regardless if targeting your EntityManager usage for
+transaction-type="RESOURCE_LOCAL" or transaction-type="TRANSACTION", it's
+very difficult to guarantee one or the other will be the only one needed.
+Often times the JPA Provider itself will require both internally to do
+various optimizations or other special features.
+
+* The *jta-data-source* should always have it's OpenEJB-specific
+'*JtaManaged*' property set to '*true*' (this is the default)
+* The *non-jta-data-source* should always have it's OpenEJB-specific
+'*JtaManaged*' property set to '*false*'.
+
+See [Containers and Resources](containers-and-resources.html)
+ for how to configure 'JtaManaged' and a full list of <Resource> properties
+for DataSources.
+
+<a name="JPAUsage-Bedetachaware"></a>
+## Be detach aware
+
+A warning for any new JPA user is by default all objects will detach at the
+end of a transaction. People typically discover this when the go to remove
+or update an object they fetched previously and get an exception like "You
+cannot perform operation delete on detached object".
+
+All ejb methods start a transaction unless a) you [configure them otherwise](transaction-annotations.html)
+, or b) the caller already has a transaction in progress when it calls the
+bean. If you're in a test case or a servlet, it's most likely B that is
+biting you. You're asking an ejb for some persistent objects, it uses the
+EntityManager in the scope of the transaction started around it's method
+and returns some persistent objects, by the time you get them the
+transaction has completed and now the objects are detached.
+
+<a name="JPAUsage-Solutions"></a>
+### Solutions
+1. Call EntityManager.merge(..) inside the bean code to reattach your
+object.
+1. Use PersistenceContextType.EXTENDED as in '@PersistenceContext(unitName
+= "movie-unit", type = PersistenceContextType.EXTENDED)' for EntityManager
+refs instead of the default of PersistenceContextType.TRANSACTION.
+1. If testing, use a technique to execute transactions in your test code.
+That's described here in [Unit testing transactions](unit-testing-transactions.html)
+
+
Added: openejb/site/trunk/content/local-client-injection.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/local-client-injection.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/local-client-injection.cwiki (added)
+++ openejb/site/trunk/content/local-client-injection.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,56 @@
+{note:title=OpenEJB 3.1.1 or later required}
+
+The *@LocalClient* annotation (org.apache.openejb.api.LocalClient) is an innovation that crosses concepts of an Java EE Application Client with a plain Java SE client. This particular annotation is focused on clients of an Embeddable EJB container, i.e. local clients. There is another annotation in development called @RemoteClient that will be focused on remote clients; clients running outside the vm the container runs.
+
+Any clients annotated with @LocalClient will be scanned at deployment time for usage of injection-related annotations. The references in the @LocalClient will be processed with the application just as if the class was a Java EE Application Client module, but with a few slight differences:
+
+ # Declaring field/method injection points as 'static' is not required
+ # References to EntityManagers via @PersistenceContext are allowed
+ # References to local business interfaces via @EJB is allowed
+ # References to UserTransaction via @Resource is allowed
+
+As well since this is not a heavyweight Java EE Application Client, you are not required to use any special packaging or command-line parameters to run the client. Your client can be a Unit Test or any plain java code that needs to pull objects from the Embedded EJB container. Classes with @LocalClient can be placed in a Client module or an EJB module. A given module may have as many classes annotated with @LocalClient as it wishes.
+
+h1. Injection
+
+The injection occurs via acquiring a LocalInitialContext via the LocalInitialContextFactory and calling _bind("inject", instance)_ passing in the instantiated local client object:
+
+{code}
+@LocalClient
+public class MoviesTest extends TestCase {
+
+ @EJB
+ private Movies movies;
+
+ @Resource
+ private UserTransaction userTransaction;
+
+ @PersistenceContext
+ private EntityManager entityManager;
+
+ public void setUp() throws Exception {
+ Properties p = new Properties();
+ p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");
+ InitialContext initialContext = new InitialContext(p);
+ initialContext.bind("inject", this);
+ }
+
+ //... other test methods
+}
+{code}
+
+h1. Discovery
+
+All EJB modules are scanned for @LocalClient classes, even if those EJB Modules are inside .war files as with the [OPENEJB:Collapsed EAR]. As well any modules that contain a META-INF/application-client.xml file will be scanned for @LocalClient classes.
+
+If you see the following error message and are absolutely sure the module containing your @LocalClient class is being properly identified as an EJB module or a Client module, than it is possible you are seeing some classloading issues.
+
+{panel}
+javax.naming.NamingException: Unable to find injection meta-data for org.superbiz.MyClient. Ensure that class was annotated with @org.apache.openejb.api.LocalClient and was successfully discovered and deployed.
+{panel}
+
+If you encounter this try setting this openejb-specific boot flag so that annotations will be treated specially and always loaded by the parent classloader
+
+{quote}openejb.tempclassloader.skip=annotations{quote}
+
+
Propchange: openejb/site/trunk/content/local-client-injection.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/local-client-injection.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/local-client-injection.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/local-client-injection.mdtext (added)
+++ openejb/site/trunk/content/local-client-injection.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,86 @@
+Title: Local Client Injection
+{note:title=OpenEJB 3.1.1 or later required}
+
+The *@LocalClient* annotation (org.apache.openejb.api.LocalClient) is an
+innovation that crosses concepts of an Java EE Application Client with a
+plain Java SE client. This particular annotation is focused on clients of
+an Embeddable EJB container, i.e. local clients. There is another
+annotation in development called @RemoteClient that will be focused on
+remote clients; clients running outside the vm the container runs.
+
+Any clients annotated with @LocalClient will be scanned at deployment time
+for usage of injection-related annotations. The references in the
+@LocalClient will be processed with the application just as if the class
+was a Java EE Application Client module, but with a few slight differences:
+
+1. Declaring field/method injection points as 'static' is not required
+1. References to EntityManagers via @PersistenceContext are allowed
+1. References to local business interfaces via @EJB is allowed
+1. References to UserTransaction via @Resource is allowed
+
+As well since this is not a heavyweight Java EE Application Client, you are
+not required to use any special packaging or command-line parameters to run
+the client. Your client can be a Unit Test or any plain java code that
+needs to pull objects from the Embedded EJB container. Classes with
+@LocalClient can be placed in a Client module or an EJB module. A given
+module may have as many classes annotated with @LocalClient as it wishes.
+
+<a name="LocalClientInjection-Injection"></a>
+# Injection
+
+The injection occurs via acquiring a LocalInitialContext via the
+LocalInitialContextFactory and calling _bind("inject", instance)_ passing
+in the instantiated local client object:
+
+
+ @LocalClient
+ public class MoviesTest extends TestCase {
+
+ @EJB
+ private Movies movies;
+
+ @Resource
+ private UserTransaction userTransaction;
+
+ @PersistenceContext
+ private EntityManager entityManager;
+
+ public void setUp() throws Exception {
+ Properties p = new Properties();
+ p.put(Context.INITIAL_CONTEXT_FACTORY,
+"org.apache.openejb.client.LocalInitialContextFactory");
+ InitialContext initialContext = new InitialContext(p);
+ initialContext.bind("inject", this);
+ }
+
+ //... other test methods
+ }
+
+
+<a name="LocalClientInjection-Discovery"></a>
+# Discovery
+
+All EJB modules are scanned for @LocalClient classes, even if those EJB
+Modules are inside .war files as with the [OPENEJB:Collapsed EAR](openejb:collapsed-ear.html)
+. As well any modules that contain a META-INF/application-client.xml file
+will be scanned for @LocalClient classes.
+
+If you see the following error message and are absolutely sure the module
+containing your @LocalClient class is being properly identified as an EJB
+module or a Client module, than it is possible you are seeing some
+classloading issues.
+
+{panel}
+javax.naming.NamingException: Unable to find injection meta-data for
+org.superbiz.MyClient. Ensure that class was annotated with
+@org.apache.openejb.api.LocalClient and was successfully discovered and
+deployed.
+{panel}
+
+If you encounter this try setting this openejb-specific boot flag so that
+annotations will be treated specially and always loaded by the parent
+classloader
+
+{quote}openejb.tempclassloader.skip=annotations{quote}
+
+
Added: openejb/site/trunk/content/lookup-of-other-ejbs-example.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/lookup-of-other-ejbs-example.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/lookup-of-other-ejbs-example.cwiki (added)
+++ openejb/site/trunk/content/lookup-of-other-ejbs-example.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,93 @@
+h1. Overview
+
+This example shows how to configure JNDI to lookup other EJBs using either the *@EJB* annotation or the *ejb-jar.xml* deployment descriptor.
+
+There are a couple interesting aspects in this example intended to flush out some of the more confusing, and perhaps frustrating, aspects of referring to EJBs.
+
+ - beans themselves do not have JNDI names (this was only recently added in Java EE 6)
+
+This is the most frustrating and hard to accept. Java EE 5 does not have a global namespace and therefore there is no *singular* name for your EJB. It does not matter what you do to your EJB, there is no standard way to "give" the bean a name that can be used by the application globally.
+
+ - each EJB owns its own private {{java:comp/env}} namespace ({{java:comp/env}} is not global and cannot be treated that way)
+ - names do not magically appear in {{java:comp/env}}, they must be explicitly added.
+ - to get a reference to bean {{B}} in the {{java:comp/env}} namespace of bean {{A}}, bean {{A}} must declare a reference to bean {{B}}.
+
+You read this right. If you have 10 EJBs and all of them want to refer to bean {{B}}, then you must declare bean {{B}} as a reference 10 times (once for each of the 10 beans). There is no standard way in Java EE 5 to do this just once for all beans. In Java EE 6 there is a "{{java:global}}" namespace, a "{{java:app}}" namespace, and a "{{java:module}}" namespace where names can be defined with the desired scope. Java EE 5 has only {{java:comp}}.
+
+There are two things which make this even more confusing:
+
+ - Servlets have always defined {{java:comp/env}} differently. In a webapp, the {{java:comp/env}} namespace is shared by all servlets. This is essentially equivalent to the {{java:module}} namespace in Java EE 6. Understand there is a conflict in definition here and that for EJBs, {{java:comp}} is scoped at the component (the EJB itself) not the module as with webapps.
+ - All vendors have some proprietary concept of global JNDI. So you may be able to lookup "{{java:/MyBean}}" or "{{MyBeanLocal}}", but these are vendor-specific and non-portable.
+
+As well this example shows some other interesting aspects of referring to EJBs:
+
+ - Two beans may use the same business interfaces, the interface alone does not necessarily identify the exact bean
+ - circular references are possible
+
+To illustrate all of this, we have two simple @Stateless beans, {{RedBean}} and {{BlueBean}}. Both implement the same business local interface, {{Friend}}. Both {{RedBean}} and {{BlueBean}} define {{java:comp/env/myFriend}} differently which is allowed as {{java:comp}} is a namespace that is private to each bean and not visible to other beans -- so the names do not have to match.
+
+
+h1. The Code
+
+Here we show the code for {{RedBean}} and {{BlueBean}} and their shared business local interface {{Friend}}.
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/RedBean.java|lang=java}
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/BlueBean.java|lang=java}
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/Friend.java|lang=java}
+
+The key items in the above are the following:
+ - {{@EJB}} has been used at the *class level* to declare {{myFriend}} in the {{java:comp/env}} namespace of each EJB
+ - because both beans share the *same interface*, {{Friend}}, we need to add *{{beanName}}* to the {{@EJB}} usage to specify the exact EJB we want
+ - for {{BlueBean}} the {{java:comp/env/myFriend}} name has been configured to point to {{RedBean}}
+ - for {{RedBean}} the {{java:comp/env/myFriend}} name has been configured to point to {{BlueBean}}
+
+h2. Alternative to annotations
+
+If there is a desire to not use annotations, the above annotation usage is equivalent to the following ejb-jar.xml
+{snippet:url=openejb3/examples/lookup-of-ejbs-with-descriptor/src/main/resources/META-INF/ejb-jar.xml|lang=xml}
+
+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/lookup-of-ejbs/src/test/java/org/superbiz/ejblookup/EjbDependencyTest.java|lang=java}
+
+h1. Running
+
+Running the example is fairly simple. In the "lookup-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.ejblookup.EjbDependencyTest
+Apache OpenEJB 3.1.5-SNAPSHOT build: 20101129-09:51
+http://openejb.apache.org/
+INFO - openejb.home = /Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs
+INFO - openejb.base = /Users/dblevins/work/openejb-3.1.x/examples/lookup-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 - Found EjbModule in classpath: /Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs/target/classes
+INFO - Beginning load: /Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs/target/classes
+INFO - Configuring enterprise application: classpath.ear
+INFO - Configuring Service(id=Default Stateless Container, type=Container, provider-id=Default Stateless Container)
+INFO - Auto-creating a container for bean BlueBean: Container(type=STATELESS, id=Default Stateless Container)
+INFO - Enterprise application "classpath.ear" loaded.
+INFO - Assembling app: classpath.ear
+INFO - Jndi(name=BlueBeanLocal) --> Ejb(deployment-id=BlueBean)
+INFO - Jndi(name=RedBeanLocal) --> Ejb(deployment-id=RedBean)
+INFO - Created Ejb(deployment-id=RedBean, ejb-name=RedBean, container=Default Stateless Container)
+INFO - Created Ejb(deployment-id=BlueBean, ejb-name=BlueBean, container=Default Stateless Container)
+INFO - Deployed Application(path=classpath.ear)
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.244 sec
+
+Results :
+
+Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+{noformat}
+
Propchange: openejb/site/trunk/content/lookup-of-other-ejbs-example.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/lookup-of-other-ejbs-example.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/lookup-of-other-ejbs-example.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/lookup-of-other-ejbs-example.mdtext (added)
+++ openejb/site/trunk/content/lookup-of-other-ejbs-example.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,149 @@
+Title: Lookup of other EJBs Example
+<a name="LookupofotherEJBsExample-Overview"></a>
+# Overview
+
+This example shows how to configure JNDI to lookup other EJBs using either
+the *@EJB* annotation or the *ejb-jar.xml* deployment descriptor.
+
+There are a couple interesting aspects in this example intended to flush
+out some of the more confusing, and perhaps frustrating, aspects of
+referring to EJBs.
+
+ - beans themselves do not have JNDI names (this was only recently added in
+Java EE 6)
+
+This is the most frustrating and hard to accept. Java EE 5 does not have a
+global namespace and therefore there is no *singular* name for your EJB.
+It does not matter what you do to your EJB, there is no standard way to
+"give" the bean a name that can be used by the application globally.
+
+ - each EJB owns its own private *java:comp/env* namespace
+(*java:comp/env* is not global and cannot be treated that way)
+ - names do not magically appear in *java:comp/env*, they must be
+explicitly added.
+ - to get a reference to bean *B* in the *java:comp/env* namespace of
+bean *A*, bean *A* must declare a reference to bean *B*.
+
+You read this right. If you have 10 EJBs and all of them want to refer to
+bean *B*, then you must declare bean *B* as a reference 10 times (once
+for each of the 10 beans). There is no standard way in Java EE 5 to do
+this just once for all beans. In Java EE 6 there is a "*java:global*"
+namespace, a "*java:app*" namespace, and a "*java:module*" namespace
+where names can be defined with the desired scope. Java EE 5 has only
+*java:comp*.
+
+There are two things which make this even more confusing:
+
+ - Servlets have always defined *java:comp/env* differently. In a
+webapp, the *java:comp/env* namespace is shared by all servlets. This is
+essentially equivalent to the *java:module* namespace in Java EE 6.
+Understand there is a conflict in definition here and that for EJBs,
+*java:comp* is scoped at the component (the EJB itself) not the module as
+with webapps.
+ - All vendors have some proprietary concept of global JNDI. So you may be
+able to lookup "*java:/MyBean*" or "*MyBeanLocal*", but these are
+vendor-specific and non-portable.
+
+As well this example shows some other interesting aspects of referring to
+EJBs:
+
+ - Two beans may use the same business interfaces, the interface alone does
+not necessarily identify the exact bean
+ - circular references are possible
+
+To illustrate all of this, we have two simple @Stateless beans, *RedBean*
+and *BlueBean*. Both implement the same business local interface,
+*Friend*. Both *RedBean* and *BlueBean* define
+*java:comp/env/myFriend* differently which is allowed as *java:comp* is
+a namespace that is private to each bean and not visible to other beans --
+so the names do not have to match.
+
+
+<a name="LookupofotherEJBsExample-TheCode"></a>
+# The Code
+
+Here we show the code for *RedBean* and *BlueBean* and their shared
+business local interface *Friend*.
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/RedBean.java|lang=java}
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/BlueBean.java|lang=java}
+{snippet:id=code|url=openejb3/examples/lookup-of-ejbs/src/main/java/org/superbiz/ejblookup/Friend.java|lang=java}
+
+The key items in the above are the following:
+ - *@EJB* has been used at the *class level* to declare *myFriend* in
+the *java:comp/env* namespace of each EJB
+ - because both beans share the *same interface*, *Friend*, we need to
+add **beanName** to the *@EJB* usage to specify the exact EJB we want
+ - for *BlueBean* the *java:comp/env/myFriend* name has been configured
+to point to *RedBean*
+ - for *RedBean* the *java:comp/env/myFriend* name has been configured
+to point to *BlueBean*
+
+<a name="LookupofotherEJBsExample-Alternativetoannotations"></a>
+## Alternative to annotations
+
+If there is a desire to not use annotations, the above annotation usage is
+equivalent to the following ejb-jar.xml
+{snippet:url=openejb3/examples/lookup-of-ejbs-with-descriptor/src/main/resources/META-INF/ejb-jar.xml|lang=xml}
+
+<a name="LookupofotherEJBsExample-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/lookup-of-ejbs/src/test/java/org/superbiz/ejblookup/EjbDependencyTest.java|lang=java}
+
+<a name="LookupofotherEJBsExample-Running"></a>
+# Running
+
+Running the example is fairly simple. In the "lookup-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.ejblookup.EjbDependencyTest
+ Apache OpenEJB 3.1.5-SNAPSHOT build: 20101129-09:51
+ http://openejb.apache.org/
+ INFO - openejb.home =
+/Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs
+ INFO - openejb.base =
+/Users/dblevins/work/openejb-3.1.x/examples/lookup-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 - Found EjbModule in classpath:
+/Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs/target/classes
+ INFO - Beginning load:
+/Users/dblevins/work/openejb-3.1.x/examples/lookup-of-ejbs/target/classes
+ INFO - Configuring enterprise application: classpath.ear
+ INFO - Configuring Service(id=Default Stateless Container, type=Container,
+provider-id=Default Stateless Container)
+ INFO - Auto-creating a container for bean BlueBean:
+Container(type=STATELESS, id=Default Stateless Container)
+ INFO - Enterprise application "classpath.ear" loaded.
+ INFO - Assembling app: classpath.ear
+ INFO - Jndi(name=BlueBeanLocal) --> Ejb(deployment-id=BlueBean)
+ INFO - Jndi(name=RedBeanLocal) --> Ejb(deployment-id=RedBean)
+ INFO - Created Ejb(deployment-id=RedBean, ejb-name=RedBean,
+container=Default Stateless Container)
+ INFO - Created Ejb(deployment-id=BlueBean, ejb-name=BlueBean,
+container=Default Stateless Container)
+ INFO - Deployed Application(path=classpath.ear)
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.244 sec
+
+ Results :
+
+ Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
+
+
Added: openejb/site/trunk/content/manual-installation.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/manual-installation.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/manual-installation.cwiki (added)
+++ openejb/site/trunk/content/manual-installation.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,192 @@
+{composition-setup}
+{composition-setup}
+h1. Overview
+
+The manual installation process is significantly harder then the [automatic installation|Tomcat] which we normally recommend. In this installation process you will do the following:
+
+# Install openejb.war
+## Download openejb.war from the [OpenEJB download page|http://people.apache.org/~dain/openejb-temp]
+## Make webapps/openejb directory
+## Change to new webapps/openejb directory
+## Unpack the openejb.war file in the new directory
+# Add the OpenEJB listener the conf/server.xml file
+# Update the non-compliant Tomcat annotations-api.jar
+# Add the OpenEJB JavaAgent to the bin/catalina.bat or bin/catalina.bat script
+
+h1. {anchor:install-openejb}Install openejb.war
+
+Once Tomcat has been [installed|Tomcat Installation], the OpenEJB plugin for Tomcat can be installed. The war can be obtained from the [OpenEJB download page|http://people.apache.org/~dain/openejb-temp]. The commands in this example are executed from within the Tomcat installation directory.
+
+h2. Unpack OpenEJB Tomcat plugin in Tomcat webapps directory
+
+{warning:title=Be Careful}This is the most error prone step. A web application does not contain a root directory, so if you unpack it in the wrong directory, it is difficult to undo. Please, follow this step closely, and most importantly *make sure you execute the unpack command from within the new webapps/openejb directory*.{warning}
+
+Due to the structure of war files, you must create a new directory for OpenEJB, change to the new directory and execute the unpack command from within the new directory. If you get this wrong, it is difficult to undo, so follow the steps closely.
+
+{deck:id=unpack tomcat}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>mkdir webapps\openejb
+
+C:\apache-tomcat-6.0.14>cd webapps\openejb
+
+C:\apache-tomcat-6.0.14\webapps\openejb>jar -xvf \openejb.war
+ created: WEB-INF/
+ created: WEB-INF/classes/
+ created: WEB-INF/classes/org/
+ created: WEB-INF/classes/org/apache/
+ created: WEB-INF/classes/org/apache/openejb/
+...snip...
+
+C:\apache-tomcat-6.0.14\webapps\openejb>dir
+ Volume in drive C has no label.
+ Volume Serial Number is 0000-0000
+
+ Directory of C:\apache-tomcat-6.0.14\webapps\openejb
+
+09/21/2007 10:19 AM <DIR> .
+09/21/2007 10:19 AM <DIR> ..
+09/21/2007 10:19 AM 1,000 index.html
+09/21/2007 10:19 AM <DIR> lib
+09/21/2007 10:19 AM 11,358 LICENSE
+09/21/2007 10:19 AM <DIR> META-INF
+09/21/2007 10:19 AM 11,649 NOTICE
+09/21/2007 10:19 AM 1,018 openejb.xml
+09/21/2007 10:19 AM 1,886 README.txt
+09/21/2007 10:19 AM <DIR> tomcat
+09/21/2007 10:19 AM <DIR> WEB-INF
+ 5 File(s) 26,911 bytes
+ 6 Dir(s) 4,633,796,608 bytes free
+
+C:\apache-tomcat-6.0.14\webapps\openejb>cd ..\..
+
+C:\apache-tomcat-6.0.14>
+{noformat}{card}
+{card:label=Unix}{noformat:nopanel=true}
+apache-tomcat-6.0.14$ mkdir webapps/openejb
+
+apache-tomcat-6.0.14$ cd webapps/openejb/
+
+apache-tomcat-6.0.14/webapps/openejb$ jar -xvf path/to/openejb.war
+ created: WEB-INF/
+ created: WEB-INF/classes/
+ created: WEB-INF/classes/org/
+ created: WEB-INF/classes/org/apache/
+ created: WEB-INF/classes/org/apache/openejb/
+...snip...
+
+apache-tomcat-6.0.14/webapps/openejb$ ls
+LICENSE META-INF/ NOTICE README.txt WEB-INF/ index.html lib/ openejb.xml tomcat/
+
+apache-tomcat-6.0.14/webapps/openejb$ cd ../..
+
+apache-tomcat-6.0.14$
+{noformat}{card}
+{deck}
+
+h2. Add the OpenEJB listener to Tomcat
+
+All Tomcat listener classes must be available in the Tomcat common class loader, so the openejb-loader jar must be copied into the Tomcat lib directory.
+
+{deck:id=copy openejb loader}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy webapps\openejb\lib\openejb-loader-3.0.0-SNAPSHOT.jar lib\openejb-loader.jar
+ 1 file(s) copied.
+{noformat}{card}
+{card:label=Unix}{noformat:nopanel=true}
+apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar lib/openejb-loader.jar
+{noformat}{card}
+{deck}
+
+Add the following {highlight}highlighted lines{highlight} to your conf/server.xml file to load the OpenEJB listener:
+
+{panel:title=conf/server.xml}
+<!-- Note: A "Server" is not itself a "Container", so you may not
+ define subcomponents such as "Valves" at this level.
+ Documentation at /docs/config/server.html
+ -->
+<Server port="8005" shutdown="SHUTDOWN">
+ {highlight}<!-- OpenEJB plugin for tomcat -->{highlight}
+ {highlight}<Listener className="org.apache.openejb.loader.OpenEJBListener" />{highlight}
+
+ <!--APR library loader. Documentation at /docs/apr.html -->
+ <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
+...snip...
+{panel}
+
+h2. Update the Tomcat annotations-api.jar file
+
+Tomcat contains an old non-compliant version of the javax.annotation classes and these invalid classes must be updated so OpenEJB can process annotations. Simply, replace the annotations-api.jar in the Tomcat lib directory with the updated annotations-api.jar in the OpenEJB war.
+
+{deck:id=update annotations-api.jar}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy webapps\openejb\tomcat\annotations-api.jar lib\annotations-api.jar
+Overwrite lib\annotations-api.jar? (Yes/No/All): y
+ 1 file(s) copied.
+{noformat}{card}
+{card:label=Unix}{noformat:nopanel=true}
+apache-tomcat-6.0.14$ cp webapps/openejb/tomcat/annotations-api.jar lib/annotations-api.jar
+{noformat}{card}
+{deck}
+
+h2. {anchor:javaagent} Add OpenEJB javaagent to Tomcat startup
+
+OpenJPA, the Java Persistence implementation used by OpenEJB, currently must enhanced persistence classes to function properly, and this requires the installation of a javaagent into the Tomcat startup process.
+
+First, copy the OpenEJB JavaAgent jar into the lib directory.
+
+{deck:id=unpack tomcat}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy webapps\openejb\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar lib\openejb-javaagent.jar
+ 1 file(s) copied.
+{noformat}{card}
+{card:label=Unix}{noformat:nopanel=true}
+apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-javaagent-*.jar lib/openejb-javaagent.jar
+{noformat}{card}
+{deck}
+
+Simply, add the following {highlight}highlighted lines{highlight} to the bin/catalina.bat (Windows) or bin/catalina.sh (Unix) file to enable the OpenEJB javaagent:
+
+{deck:id=update script}
+{card:label=Windows}
+{panel:title=bin/catalina.bat}
+...snip...
+if not exist "%CATALINA_BASE%\conf\logging.properties" goto noJuli
+set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties"
+:noJuli
+
+{highlight}rem Add OpenEJB javaagent
+if not exist "%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar" goto noOpenEJBJavaagent
+set JAVA_OPTS="-javaagent:%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar" %JAVA_OPTS%
+:noOpenEJBJavaagent{highlight}
+
+rem ----- Execute The Requested Command ---------------------------------------
+
+echo Using CATALINA_BASE: %CATALINA_BASE%
+echo Using CATALINA_HOME: %CATALINA_HOME%
+...snip...
+{panel}
+{card}
+{card:label=Unix}
+{panel:title=bin/catalina.sh}
+...snip...
+\# Set juli LogManager if it is present
+if [OPENEJB: -r "$CATALINA_BASE"/conf/logging.properties ]; then
+ JAVA_OPTS="$JAVA_OPTS "-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager" "-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
+fi
+
+{highlight}\# Add OpenEJB javaagent
+if [OPENEJB: -r "$CATALINA_BASE"/webapps/lib/openejb-javaagent.jar ]; then
+ JAVA_OPTS=""-javaagent:$CATALINA_BASE/lib/openejb-javaagent.jar" $JAVA_OPTS"
+fi{highlight}
+
+\# ----- Execute The Requested Command -----------------------------------------
+
+\# Bugzilla 37848: only output this if we have a TTY
+if [OPENEJB: $have_tty -eq 1 ]; then
+ echo "Using CATALINA_BASE: $CATALINA_BASE"
+...snip...
+{panel}
+{card}
+{deck}
+
+*NOTE:* The example above is an excerpt from the middle of the bin/catalina.sh file. Search for "Execute" in the file to locate the correct position in the file to add the new lines.
\ No newline at end of file
Propchange: openejb/site/trunk/content/manual-installation.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/manual-installation.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/manual-installation.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/manual-installation.mdtext (added)
+++ openejb/site/trunk/content/manual-installation.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,250 @@
+Title: Manual Installation
+{composition-setup}
+{composition-setup}
+<a name="ManualInstallation-Overview"></a>
+# Overview
+
+The manual installation process is significantly harder then the [automatic installation](tomcat.html)
+ which we normally recommend. In this installation process you will do the
+following:
+
+1. Install openejb.war
+1. # Download openejb.war from the [OpenEJB download page](http://people.apache.org/~dain/openejb-temp)
+1. # Make webapps/openejb directory
+1. # Change to new webapps/openejb directory
+1. # Unpack the openejb.war file in the new directory
+1. Add the OpenEJB listener the conf/server.xml file
+1. Update the non-compliant Tomcat annotations-api.jar
+1. Add the OpenEJB JavaAgent to the bin/catalina.bat or bin/catalina.bat
+script
+
+<a name="ManualInstallation-{anchor:install-openejb}Installopenejb.war"></a>
+# {anchor:install-openejb}Install openejb.war
+
+Once Tomcat has been [installed](tomcat-installation.html)
+, the OpenEJB plugin for Tomcat can be installed. The war can be obtained
+from the [OpenEJB download page|http://people.apache.org/~dain/openejb-temp]
+. The commands in this example are executed from within the Tomcat
+installation directory.
+
+<a name="ManualInstallation-UnpackOpenEJBTomcatplugininTomcatwebappsdirectory"></a>
+## Unpack OpenEJB Tomcat plugin in Tomcat webapps directory
+
+{warning:title=Be Careful}This is the most error prone step. A web
+application does not contain a root directory, so if you unpack it in the
+wrong directory, it is difficult to undo. Please, follow this step
+closely, and most importantly *make sure you execute the unpack command
+from within the new webapps/openejb directory*.{warning}
+
+Due to the structure of war files, you must create a new directory for
+OpenEJB, change to the new directory and execute the unpack command from
+within the new directory. If you get this wrong, it is difficult to undo,
+so follow the steps closely.
+
+{deck:id=unpack tomcat}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>mkdir webapps\openejb
+
+C:\apache-tomcat-6.0.14>cd webapps\openejb
+
+C:\apache-tomcat-6.0.14\webapps\openejb>jar -xvf \openejb.war
+ created: WEB-INF/
+ created: WEB-INF/classes/
+ created: WEB-INF/classes/org/
+ created: WEB-INF/classes/org/apache/
+ created: WEB-INF/classes/org/apache/openejb/
+...snip...
+
+C:\apache-tomcat-6.0.14\webapps\openejb>dir
+ Volume in drive C has no label.
+ Volume Serial Number is 0000-0000
+
+ Directory of C:\apache-tomcat-6.0.14\webapps\openejb
+
+09/21/2007 10:19 AM <DIR> .
+09/21/2007 10:19 AM <DIR> ..
+09/21/2007 10:19 AM 1,000 index.html
+09/21/2007 10:19 AM <DIR> lib
+09/21/2007 10:19 AM 11,358 LICENSE
+09/21/2007 10:19 AM <DIR> META-INF
+09/21/2007 10:19 AM 11,649 NOTICE
+09/21/2007 10:19 AM 1,018 openejb.xml
+09/21/2007 10:19 AM 1,886 README.txt
+09/21/2007 10:19 AM <DIR> tomcat
+09/21/2007 10:19 AM <DIR> WEB-INF
+ 5 File(s) 26,911 bytes
+ 6 Dir(s) 4,633,796,608 bytes free
+
+C:\apache-tomcat-6.0.14\webapps\openejb>cd ..\..
+
+C:\apache-tomcat-6.0.14>
+
+ {card:label=Unix}{noformat:nopanel=true}
+ apache-tomcat-6.0.14$ mkdir webapps/openejb
+
+ apache-tomcat-6.0.14$ cd webapps/openejb/
+
+ apache-tomcat-6.0.14/webapps/openejb$ jar -xvf path/to/openejb.war
+ created: WEB-INF/
+ created: WEB-INF/classes/
+ created: WEB-INF/classes/org/
+ created: WEB-INF/classes/org/apache/
+ created: WEB-INF/classes/org/apache/openejb/
+ ...snip...
+
+ apache-tomcat-6.0.14/webapps/openejb$ ls
+ LICENSE META-INF/ NOTICE README.txt WEB-INF/ index.html
+ lib/ openejb.xml tomcat/
+
+ apache-tomcat-6.0.14/webapps/openejb$ cd ../..
+
+ apache-tomcat-6.0.14$
+
+{deck}
+
+<a name="ManualInstallation-AddtheOpenEJBlistenertoTomcat"></a>
+## Add the OpenEJB listener to Tomcat
+
+All Tomcat listener classes must be available in the Tomcat common class
+loader, so the openejb-loader jar must be copied into the Tomcat lib
+directory.
+
+{deck:id=copy openejb loader}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy
+webapps\openejb\lib\openejb-loader-3.0.0-SNAPSHOT.jar
+lib\openejb-loader.jar
+ 1 file(s) copied.
+
+ {card:label=Unix}{noformat:nopanel=true}
+ apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar
+lib/openejb-loader.jar
+
+{deck}
+
+Add the following {highlight}highlighted lines{highlight} to your
+conf/server.xml file to load the OpenEJB listener:
+
+{panel:title=conf/server.xml}
+<!-- Note: A "Server" is not itself a "Container", so you may not
+ define subcomponents such as "Valves" at this
+level.
+ Documentation at /docs/config/server.html
+ -->
+<Server port="8005" shutdown="SHUTDOWN">
+ {highlight}<!-- OpenEJB plugin for tomcat -->{highlight}
+ {highlight}<Listener
+className="org.apache.openejb.loader.OpenEJBListener" />{highlight}
+
+ <!--APR library loader. Documentation at /docs/apr.html -->
+ <Listener
+className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
+...snip...
+{panel}
+
+<a name="ManualInstallation-UpdatetheTomcatannotations-api.jarfile"></a>
+## Update the Tomcat annotations-api.jar file
+
+Tomcat contains an old non-compliant version of the javax.annotation
+classes and these invalid classes must be updated so OpenEJB can process
+annotations. Simply, replace the annotations-api.jar in the Tomcat lib
+directory with the updated annotations-api.jar in the OpenEJB war.
+
+{deck:id=update annotations-api.jar}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy webapps\openejb\tomcat\annotations-api.jar
+lib\annotations-api.jar
+Overwrite lib\annotations-api.jar? (Yes/No/All): y
+ 1 file(s) copied.
+
+ {card:label=Unix}{noformat:nopanel=true}
+ apache-tomcat-6.0.14$ cp webapps/openejb/tomcat/annotations-api.jar
+lib/annotations-api.jar
+
+{deck}
+
+<a name="ManualInstallation-{anchor:javaagent}AddOpenEJBjavaagenttoTomcatstartup"></a>
+## {anchor:javaagent} Add OpenEJB javaagent to Tomcat startup
+
+OpenJPA, the Java Persistence implementation used by OpenEJB, currently
+must enhanced persistence classes to function properly, and this requires
+the installation of a javaagent into the Tomcat startup process.
+
+First, copy the OpenEJB JavaAgent jar into the lib directory.
+
+{deck:id=unpack tomcat}
+{card:label=Windows}{noformat:nopanel=true}
+C:\apache-tomcat-6.0.14>copy
+webapps\openejb\lib\openejb-javaagent-3.0.0-SNAPSHOT.jar
+lib\openejb-javaagent.jar
+ 1 file(s) copied.
+
+ {card:label=Unix}{noformat:nopanel=true}
+ apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-javaagent-*.jar
+lib/openejb-javaagent.jar
+
+{deck}
+
+Simply, add the following {highlight}highlighted lines{highlight} to the
+bin/catalina.bat (Windows) or bin/catalina.sh (Unix) file to enable the
+OpenEJB javaagent:
+
+{deck:id=update script}
+{card:label=Windows}
+{panel:title=bin/catalina.bat}
+...snip...
+if not exist "%CATALINA_BASE%\conf\logging.properties" goto noJuli
+set JAVA_OPTS=%JAVA_OPTS%
+-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
+-Djava.util.logging.config.file="%CATALINA_BASE%\conf\logging.properties"
+:noJuli
+
+{highlight}rem Add OpenEJB javaagent
+if not exist "%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar"
+goto noOpenEJBJavaagent
+set
+JAVA_OPTS="-javaagent:%CATALINA_BASE%\webapps\openejb\lib\openejb-javaagent.jar"
+%JAVA_OPTS%
+:noOpenEJBJavaagent{highlight}
+
+rem ----- Execute The Requested Command
+---------------------------------------
+
+echo Using CATALINA_BASE: %CATALINA_BASE%
+echo Using CATALINA_HOME: %CATALINA_HOME%
+...snip...
+{panel}
+{card}
+{card:label=Unix}
+{panel:title=bin/catalina.sh}
+...snip...
+\# Set juli LogManager if it is present
+if [OPENEJB: -r "$CATALINA_BASE"/conf/logging.properties ](openejb:--r-"$catalina_base"/conf/logging.properties-.html)
+; then
+ JAVA_OPTS="$JAVA_OPTS
+"-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager"
+"-Djava.util.logging.config.file="$CATALINA_BASE/conf/logging.properties"
+fi
+
+{highlight}\# Add OpenEJB javaagent
+if [OPENEJB: -r "$CATALINA_BASE"/webapps/lib/openejb-javaagent.jar ](openejb:--r-"$catalina_base"/webapps/lib/openejb-javaagent.jar-.html)
+; then
+ JAVA_OPTS=""-javaagent:$CATALINA_BASE/lib/openejb-javaagent.jar"
+$JAVA_OPTS"
+fi{highlight}
+
+\# ----- Execute The Requested Command
+-----------------------------------------
+
+\# Bugzilla 37848: only output this if we have a TTY
+if [OPENEJB: $have_tty -eq 1 ](openejb:-$have_tty--eq-1-.html)
+; then
+ echo "Using CATALINA_BASE: $CATALINA_BASE"
+...snip...
+{panel}
+{card}
+{deck}
+
+*NOTE:* The example above is an excerpt from the middle of the
+bin/catalina.sh file. Search for "Execute" in the file to locate the
+correct position in the file to add the new lines.
Modified: openejb/site/trunk/content/navigation.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/navigation.cwiki?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/navigation.cwiki (original)
+++ openejb/site/trunk/content/navigation.cwiki Sun Jul 10 05:36:12 2011
@@ -1,39 +1 @@
-h3. Overview
-
-- [Home|Index]
-- [News]
-- [FAQ]
-- [Download]
-- [Documentation|OPENEJBx30:Index]
-- [Examples]
-- [Lightning Demos|http://cwiki.apache.org/confluence/display/OPENEJB/Lightening+Demos]
-- [Mailing Lists]
-- [Source Code]
-- [Project Blog|http://blogs.apache.org/openejb]
-
-h3. Servers
-
-- [Local|Local Server]
-- [Remote|Remote Server]
-
-h3. Integrations
-
-- [OPENEJBx30:Tomcat]
-- [Geronimo]
-- [WebObjects]
-
-h3. Community
-
-- [Team]
-- [Articles]
-- [IRC|http://webchat.freenode.net/?channels=openejb]
-
-h3. Related Projects
-
-- [ActiveMQ|http://activemq.apache.org]
-- [OpenJPA|http://openjpa.apache.org]
-- [CXF|http://cxf.apache.org]
-
-h3. Index
- - [Site Index|Space Index]
- - [Doc Index|OPENEJBx30:Space Index]
+{include:OPENEJB:Navigation}
\ No newline at end of file
Modified: openejb/site/trunk/content/navigation.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/navigation.mdtext?rev=1144778&r1=1144777&r2=1144778&view=diff
==============================================================================
--- openejb/site/trunk/content/navigation.mdtext (original)
+++ openejb/site/trunk/content/navigation.mdtext Sun Jul 10 05:36:12 2011
@@ -1,46 +1,2 @@
Title: Navigation
-<a name="Navigation-Overview"></a>
-### Overview
-
-- [Home](index.html)
-- [News](news.html)
-- [FAQ](faq.html)
-- [Download](download.html)
-- [Documentation](openejbx30:index.html)
-- [Examples](examples.html)
-- [Lightning Demos](http://cwiki.apache.org/confluence/display/OPENEJB/Lightening+Demos)
-- [Mailing Lists](mailing-lists.html)
-- [Source Code](source-code.html)
-- [Project Blog](http://blogs.apache.org/openejb)
-
-<a name="Navigation-Servers"></a>
-### Servers
-
-- [Local](local-server.html)
-- [Remote](remote-server.html)
-
-<a name="Navigation-Integrations"></a>
-### Integrations
-
-- [OPENEJBx30:Tomcat](openejbx30:tomcat.html)
-- [Geronimo](geronimo.html)
-- [WebObjects](webobjects.html)
-
-<a name="Navigation-Community"></a>
-### Community
-
-- [Team](team.html)
-- [Articles](articles.html)
-- [IRC](http://webchat.freenode.net/?channels=openejb)
-
-<a name="Navigation-RelatedProjects"></a>
-### Related Projects
-
-- [ActiveMQ](http://activemq.apache.org)
-- [OpenJPA](http://openjpa.apache.org)
-- [CXF](http://cxf.apache.org)
-
-<a name="Navigation-Index"></a>
-### Index
- - [Site Index](space-index.html)
- - [Doc Index](openejbx30:space-index.html)
+{include:OPENEJB:Navigation}
Added: openejb/site/trunk/content/new-instructions.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/new-instructions.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/new-instructions.cwiki (added)
+++ openejb/site/trunk/content/new-instructions.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,4 @@
+{note:title=THIS PAGE WILL BE ARCHIVED AND REMOVED}
+Instructions on OpenEJB Tomcat Installation can be found at [Tomcat]
+{note}
+
Propchange: openejb/site/trunk/content/new-instructions.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/new-instructions.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/new-instructions.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/new-instructions.mdtext (added)
+++ openejb/site/trunk/content/new-instructions.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,5 @@
+Title: New Instructions
+{note:title=THIS PAGE WILL BE ARCHIVED AND REMOVED}
+Instructions on OpenEJB Tomcat Installation can be found at [Tomcat](tomcat.html)
+{note}
+
Added: openejb/site/trunk/content/online-javadocs.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/online-javadocs.cwiki?rev=1144778&view=auto
==============================================================================
(empty)
Propchange: openejb/site/trunk/content/online-javadocs.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/online-javadocs.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/online-javadocs.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/online-javadocs.mdtext (added)
+++ openejb/site/trunk/content/online-javadocs.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1 @@
+Title: Online Javadocs
Added: openejb/site/trunk/content/openejb-per-tomcat-installation.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openejb-per-tomcat-installation.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openejb-per-tomcat-installation.cwiki (added)
+++ openejb/site/trunk/content/openejb-per-tomcat-installation.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,40 @@
+{note:title=THIS PAGE WILL BE ARCHIVED AND REMOVED}
+Instructions on OpenEJB Tomcat Installation can be found at [Tomcat]
+
+{note}
+
+h1. OpenEJB per Tomcat instance
+
+Configure OpenEJB per Tomcat instance requires the following steps:\* Copy the _war/openejb-loader-1.0-SNAPSHOT.war_ into the webapps dir of a running Tomcat install
+{code:title=Under Unix}
+$ cd $OPENEJB_HOME
+$ cp war/openejb-loader-1.0-SNAPSHOT.war $CATALINA_HOME/webapps
+{code}
+or
+{code:title=Under Windows}
+c:/> cd %OPENEJB_HOME%
+%OPENEJB_HOME%> cp war/openejb-loader-1.0-SNAPSHOT.war %CATALINA_HOME%/webapps
+{code}
+* Update the openejb.home init param (inside the WEB-INF/web.xml file) to point to where OpenEJB was installed.
+
+{code:title=Under Unix}
+$ cd $CATALINA_HOME/webapps
+$ jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+...edit WEB-INF/web.xml...
+$ jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+$ rm -rf WEB-INF
+{code}
+or
+{code:title=Under Windows}
+c:/> cd %CATALINA_HOME%/webapps
+%CATALINA_HOME%/webapps> jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+...edit WEB-INF/web.xml...
+%CATALINA_HOME%/webapps> jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+%CATALINA_HOME%/webapps> rmdir /S /Q WEB-INF
+{code}
+* Create the _temp_ directory under Tomcat's home directory
+{warning}
+This is because the beans that's been successfully validated are deployed. During validation OpenEJB creates temporary files under the _temp.dir_ directory, which is overriden by Tomcat to its temp directory. Unfortunatelly, the directory doesn't exist and needs to be created manually.
+{warning}
+* Deploy your webapps that are using the beans deployed onto OpenEJB
+* Start up Tomcat and have fun with the EJBs
\ No newline at end of file
Propchange: openejb/site/trunk/content/openejb-per-tomcat-installation.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/openejb-per-tomcat-installation.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openejb-per-tomcat-installation.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openejb-per-tomcat-installation.mdtext (added)
+++ openejb/site/trunk/content/openejb-per-tomcat-installation.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,52 @@
+Title: OpenEJB per Tomcat installation
+{note:title=THIS PAGE WILL BE ARCHIVED AND REMOVED}
+Instructions on OpenEJB Tomcat Installation can be found at [Tomcat](tomcat.html)
+
+{note}
+
+<a name="OpenEJBperTomcatinstallation-OpenEJBperTomcatinstance"></a>
+# OpenEJB per Tomcat instance
+
+Configure OpenEJB per Tomcat instance requires the following steps:\* Copy
+the _war/openejb-loader-1.0-SNAPSHOT.war_ into the webapps dir of a running
+Tomcat install
+<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>Under Unix</B></DIV><DIV class="codeContent panelContent">
+ $ cd $OPENEJB_HOME
+ $ cp war/openejb-loader-1.0-SNAPSHOT.war $CATALINA_HOME/webapps
+
+or
+<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>Under Windows</B></DIV><DIV class="codeContent panelContent">
+ c:/> cd %OPENEJB_HOME%
+ %OPENEJB_HOME%> cp war/openejb-loader-1.0-SNAPSHOT.war
+%CATALINA_HOME%/webapps
+
+* Update the openejb.home init param (inside the WEB-INF/web.xml file) to
+point to where OpenEJB was installed.
+
+<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>Under Unix</B></DIV><DIV class="codeContent panelContent">
+ $ cd $CATALINA_HOME/webapps
+ $ jar -xvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+ ...edit WEB-INF/web.xml...
+ $ jar -uvf openejb-loader-1.0-SNAPSHOT.war WEB-INF/web.xml
+ $ rm -rf WEB-INF
+
+or
+<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>Under Windows</B></DIV><DIV class="codeContent panelContent">
+ c:/> cd %CATALINA_HOME%/webapps
+ %CATALINA_HOME%/webapps> jar -xvf openejb-loader-1.0-SNAPSHOT.war
+WEB-INF/web.xml
+ ...edit WEB-INF/web.xml...
+ %CATALINA_HOME%/webapps> jar -uvf openejb-loader-1.0-SNAPSHOT.war
+WEB-INF/web.xml
+ %CATALINA_HOME%/webapps> rmdir /S /Q WEB-INF
+
+* Create the _temp_ directory under Tomcat's home directory
+{warning}
+This is because the beans that's been successfully validated are deployed.
+During validation OpenEJB creates temporary files under the _temp.dir_
+directory, which is overriden by Tomcat to its temp directory.
+Unfortunatelly, the directory doesn't exist and needs to be created
+manually.
+{warning}
+* Deploy your webapps that are using the beans deployed onto OpenEJB
+* Start up Tomcat and have fun with the EJBs
Added: openejb/site/trunk/content/openejb.xml.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openejb.xml.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openejb.xml.cwiki (added)
+++ openejb/site/trunk/content/openejb.xml.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,57 @@
+h1. Overview
+
+The openejb.xml is the main configuration file for the container system and it's services such as transaction, security, and data sources.
+
+The format is a mix of xml and properties inspired by the format of the httpd configuration file. Basically:
+
+{code:xml}
+<tag id="">
+ ...properties...
+</tag>
+{code}
+
+Such as:
+
+{code:xml}
+<Resource id="MyDataSource" type="DataSource">
+ username foo
+ password bar
+</Resource>
+{code}
+
+*Note the space*. White space is a valid name/value pair separator in any java properties file (along with semi-colon). So the above is equivalent to:
+{code:xml}
+<Resource id="MyDataSource" type="DataSource">
+ username = foo
+ password = bar
+</Resource>
+{code}
+You are free to use white space, ":", or "=" for your name/value pair separator with no affect on OpenEJB.
+
+h2. Property Defaults and Overriding
+
+The openejb.xml file itself functions as an override, default values are specified via other means (service-jar.xml files in the classpath), therefore you only need to specify property values here for 2 reasons:
+# you wish to for documentation purposes
+# you need to change the default value
+
+The default openejb.xml file has most of the useful properties for each component explicitly listed with default values for documentation purposes. It is safe to delete them and be assured that no behavior will change if a smaller config file is desired.
+
+Overriding can also be done via the command line or plain Java system properties. See [System Properties] for details.
+
+h2. What properties are available?
+
+To know what properties can be overriden the './bin/openejb properties' command is very useful: see [Properties Tool]
+
+It's function is to connect to a running server and print a canonical list of all properties OpenEJB can see via the various means of configuration. When sending requests for help to the users list or jira, it is highly encouraged to send the output of this tool with your message.
+
+h2. Not configurable via openejb.xml
+
+The only thing not yet configurable via this file are ServerServices due to OpenEJB's embeddable nature and resulting long standing tradition of keeping the container system separate from the server layer. This may change someday, but untill then ServerServices are configurable via conf/<service-id>.properties files such as conf/ejbd.properties to configure the main protocol that services EJB client requests.
+
+The format those properties files is greatly adapted from the xinet.d style of configuration and even shares similar functionality and properties such as host-based authorization (HBA) via the 'only_from' property.
+
+h2. Restoring openejb.xml to the defaults
+
+To restore this file to its original default state, you can simply delete it or rename it and OpenEJB will see it's missing and unpack another openejb.xml into the conf/ directory when it starts.
+
+This is not only handy for recovering from a non-functional config, but also for upgrading as OpenEJB will not overwrite your existing configuration file should you choose to unpack an new distro over the top of an old one -- this style of upgrade is safe provided you move your old lib/ directory first.
Propchange: openejb/site/trunk/content/openejb.xml.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/openejb.xml.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openejb.xml.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openejb.xml.mdtext (added)
+++ openejb/site/trunk/content/openejb.xml.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,92 @@
+Title: openejb.xml
+<a name="openejb.xml-Overview"></a>
+# Overview
+
+The openejb.xml is the main configuration file for the container system and
+it's services such as transaction, security, and data sources.
+
+The format is a mix of xml and properties inspired by the format of the
+httpd configuration file. Basically:
+
+
+ <tag id="">
+ ...properties...
+ </tag>
+
+
+Such as:
+
+
+ <Resource id="MyDataSource" type="DataSource">
+ username foo
+ password bar
+ </Resource>
+
+
+*Note the space*. White space is a valid name/value pair separator in any
+java properties file (along with semi-colon). So the above is equivalent
+to:
+
+ <Resource id="MyDataSource" type="DataSource">
+ username = foo
+ password = bar
+ </Resource>
+
+You are free to use white space, ":", or "=" for your name/value pair
+separator with no affect on OpenEJB.
+
+<a name="openejb.xml-PropertyDefaultsandOverriding"></a>
+## Property Defaults and Overriding
+
+The openejb.xml file itself functions as an override, default values are
+specified via other means (service-jar.xml files in the classpath),
+therefore you only need to specify property values here for 2 reasons:
+1. you wish to for documentation purposes
+1. you need to change the default value
+
+The default openejb.xml file has most of the useful properties for each
+component explicitly listed with default values for documentation purposes.
+ It is safe to delete them and be assured that no behavior will change if a
+smaller config file is desired.
+
+Overriding can also be done via the command line or plain Java system
+properties. See [System Properties](system-properties.html)
+ for details.
+
+<a name="openejb.xml-Whatpropertiesareavailable?"></a>
+## What properties are available?
+
+To know what properties can be overriden the './bin/openejb properties'
+command is very useful: see [Properties Tool](properties-tool.html)
+
+It's function is to connect to a running server and print a canonical list
+of all properties OpenEJB can see via the various means of configuration.
+When sending requests for help to the users list or jira, it is highly
+encouraged to send the output of this tool with your message.
+
+<a name="openejb.xml-Notconfigurableviaopenejb.xml"></a>
+## Not configurable via openejb.xml
+
+The only thing not yet configurable via this file are ServerServices due to
+OpenEJB's embeddable nature and resulting long standing tradition of
+keeping the container system separate from the server layer. This may
+change someday, but untill then ServerServices are configurable via
+conf/<service-id>.properties files such as conf/ejbd.properties to
+configure the main protocol that services EJB client requests.
+
+The format those properties files is greatly adapted from the xinet.d style
+of configuration and even shares similar functionality and properties such
+as host-based authorization (HBA) via the 'only_from' property.
+
+<a name="openejb.xml-Restoringopenejb.xmltothedefaults"></a>
+## Restoring openejb.xml to the defaults
+
+To restore this file to its original default state, you can simply delete
+it or rename it and OpenEJB will see it's missing and unpack another
+openejb.xml into the conf/ directory when it starts.
+
+This is not only handy for recovering from a non-functional config, but
+also for upgrading as OpenEJB will not overwrite your existing
+configuration file should you choose to unpack an new distro over the top
+of an old one -- this style of upgrade is safe provided you move your old
+lib/ directory first.
Added: openejb/site/trunk/content/openjpa.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openjpa.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openjpa.cwiki (added)
+++ openejb/site/trunk/content/openjpa.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,105 @@
+OpenJPA is bundled with OpenEJB as the default persistence provider.
+
+An example of working persistence.xml for OpenJPA:
+
+{code:xml|title=persistence.xml}
+<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <persistence-unit name="movie-unit">
+ <jta-data-source>movieDatabase</jta-data-source>
+ <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source>
+ <class>org.superbiz.injection.jpa.Movie</class>
+
+ <properties>
+ <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
+ </properties>
+ </persistence-unit>
+</persistence>
+{code}
+
+Where the datasources above are configured in your openejb.xml as follows:
+
+{code:xml|title=openejb.xml}
+<Resource id="movieDatabase" type="DataSource">
+ JdbcDriver = org.hsqldb.jdbcDriver
+ JdbcUrl = jdbc:hsqldb:mem:moviedb
+</Resource>
+
+<Resource id="movieDatabaseUnmanaged" type="DataSource">
+ JdbcDriver = org.hsqldb.jdbcDriver
+ JdbcUrl = jdbc:hsqldb:mem:moviedb
+ JtaManaged = false
+</Resource>
+{code}
+
+Or in properties as follows:
+
+{code:xml|title=java.lang.System or InitialContext properties}
+p.put("movieDatabase", "new://Resource?type=DataSource");
+p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver");
+p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb");
+
+p.put("movieDatabaseUnmanaged", "new://Resource?type=DataSource");
+p.put("movieDatabaseUnmanaged.JdbcDriver", "org.hsqldb.jdbcDriver");
+p.put("movieDatabaseUnmanaged.JdbcUrl", "jdbc:hsqldb:mem:moviedb");
+p.put("movieDatabaseUnmanaged.JtaManaged", "false");
+{code}
+
+h1. Common exceptions
+
+h2. Table not found in statement
+
+Or as derby will report it "Table 'abc.xyz' doesn't exist"
+
+Someone has to create the database structure for your persistent objects. If you add the *openjpa.jdbc.SynchronizeMappings* property as shown below OpenJPA will auto-create all your tables, all your primary keys and all foreign keys exactly to match your objects.
+
+{code:xml|title=persistence.xml}
+<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <persistence-unit name="movie-unit">
+ <!-- your other stuff -->
+
+ <properties>
+ <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema(ForeignKeys=true)"/>
+ </properties>
+ </persistence-unit>
+</persistence>
+{code}
+
+h2. Auto-commit can not be set while enrolled in a transaction
+
+Pending
+
+h2. This broker is not configured to use managed transactions.
+
+h3. Setup
+Using a EXTENDED persistence context ...
+{code:title=bean code}
+@PersistenceContext(unitName = "movie-unit", type = PersistenceContextType.EXTENDED)
+EntityManager entityManager;
+{code}
+
+on a persistence unit setup as RESOURCE_LOCAL ...
+{code:xml|title=persistence.xml}
+<persistence-unit name="movie-unit" transaction-type="RESOURCE_LOCAL">
+ ...
+</persistence-unit>
+{code}
+
+inside of a transaction.
+{code:title=bean code}
+@TransactionAttribute(TransactionAttributeType.REQUIRED)
+public void addMovie(Movie movie) throws Exception {
+ entityManager.persist(movie);
+}
+{code}
+
+Note the default transaction attribute for any ejb method is REQUIRED unless explicitly set otherwise in the bean class or method in question.
+
+h3. Solutions
+
+You can either:
+ # Change your bean or it's method to use TransactionAttributeType.NOT_REQUIRED or TransactionAttributeType.NEVER which will guarantee it will not be invoked in a JTA transaction.
+ # Change your persistence.xml so the persistence-unit uses transaction-type="TRANSACTION" making it capable of participating in a JTA transaction.
+
+
Propchange: openejb/site/trunk/content/openjpa.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/openjpa.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/openjpa.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/openjpa.mdtext (added)
+++ openejb/site/trunk/content/openjpa.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,121 @@
+Title: OpenJPA
+OpenJPA is bundled with OpenEJB as the default persistence provider.
+
+An example of working persistence.xml for OpenJPA:
+
+{code:xml|title=persistence.xml}
+<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <persistence-unit name="movie-unit">
+ <jta-data-source>movieDatabase</jta-data-source>
+ <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source>
+ <class>org.superbiz.injection.jpa.Movie</class>
+
+ <properties>
+ <property name="openjpa.jdbc.SynchronizeMappings"
+value="buildSchema(ForeignKeys=true)"/>
+ </properties>
+ </persistence-unit>
+</persistence>
+
+
+ Where the datasources above are configured in your openejb.xml as follows:
+
+ {code:xml|title=openejb.xml}
+ <Resource id="movieDatabase" type="DataSource">
+ JdbcDriver = org.hsqldb.jdbcDriver
+ JdbcUrl = jdbc:hsqldb:mem:moviedb
+ </Resource>
+
+ <Resource id="movieDatabaseUnmanaged" type="DataSource">
+ JdbcDriver = org.hsqldb.jdbcDriver
+ JdbcUrl = jdbc:hsqldb:mem:moviedb
+ JtaManaged = false
+ </Resource>
+
+
+Or in properties as follows:
+
+{code:xml|title=java.lang.System or InitialContext properties}
+p.put("movieDatabase", "new://Resource?type=DataSource");
+p.put("movieDatabase.JdbcDriver", "org.hsqldb.jdbcDriver");
+p.put("movieDatabase.JdbcUrl", "jdbc:hsqldb:mem:moviedb");
+
+p.put("movieDatabaseUnmanaged", "new://Resource?type=DataSource");
+p.put("movieDatabaseUnmanaged.JdbcDriver", "org.hsqldb.jdbcDriver");
+p.put("movieDatabaseUnmanaged.JdbcUrl", "jdbc:hsqldb:mem:moviedb");
+p.put("movieDatabaseUnmanaged.JtaManaged", "false");
+
+
+ h1. Common exceptions
+
+ h2. Table not found in statement
+
+ Or as derby will report it "Table 'abc.xyz' doesn't exist"
+
+ Someone has to create the database structure for your persistent objects.
+If you add the *openjpa.jdbc.SynchronizeMappings* property as shown below
+OpenJPA will auto-create all your tables, all your primary keys and all
+foreign keys exactly to match your objects.
+
+ {code:xml|title=persistence.xml}
+ <persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+
+ <persistence-unit name="movie-unit">
+ <!-- your other stuff -->
+
+ <properties>
+ <property name="openjpa.jdbc.SynchronizeMappings"
+value="buildSchema(ForeignKeys=true)"/>
+ </properties>
+ </persistence-unit>
+ </persistence>
+
+
+<a name="OpenJPA-Auto-commitcannotbesetwhileenrolledinatransaction"></a>
+## Auto-commit can not be set while enrolled in a transaction
+
+Pending
+
+<a name="OpenJPA-Thisbrokerisnotconfiguredtousemanagedtransactions."></a>
+## This broker is not configured to use managed transactions.
+
+<a name="OpenJPA-Setup"></a>
+### Setup
+Using a EXTENDED persistence context ...
+<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>bean code</B></DIV><DIV class="codeContent panelContent">
+ @PersistenceContext(unitName = "movie-unit", type =
+PersistenceContextType.EXTENDED)
+ EntityManager entityManager;
+
+
+on a persistence unit setup as RESOURCE_LOCAL ...
+{code:xml|title=persistence.xml}
+<persistence-unit name="movie-unit" transaction-type="RESOURCE_LOCAL">
+ ...
+</persistence-unit>
+
+
+ inside of a transaction.
+ {code:title=bean code}
+ @TransactionAttribute(TransactionAttributeType.REQUIRED)
+ public void addMovie(Movie movie) throws Exception {
+ entityManager.persist(movie);
+ }
+
+
+Note the default transaction attribute for any ejb method is REQUIRED
+unless explicitly set otherwise in the bean class or method in question.
+
+<a name="OpenJPA-Solutions"></a>
+### Solutions
+
+You can either:
+1. Change your bean or it's method to use
+TransactionAttributeType.NOT_REQUIRED or TransactionAttributeType.NEVER
+which will guarantee it will not be invoked in a JTA transaction.
+1. Change your persistence.xml so the persistence-unit uses
+transaction-type="TRANSACTION" making it capable of participating in a JTA
+transaction.
+
+
Added: openejb/site/trunk/content/persistence-context.cwiki
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/persistence-context.cwiki?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/persistence-context.cwiki (added)
+++ openejb/site/trunk/content/persistence-context.cwiki Sun Jul 10 05:36:12 2011
@@ -0,0 +1,50 @@
+h1. Via annotation
+
+Both lookup and injection of an EntityManager can be configured via the @PersistenceContext annotation.
+
+{code:title=Usable by EJB, Interceptor, Servlet, Filter, or Listener}
+package org.superbiz;
+
+import javax.persistence.PersistenceContext;
+import javax.persistence.EntityManager;
+import javax.ejb.Stateless;
+import javax.naming.InitialContext;
+
+@Stateless
+@PersistenceContext(name = "myFooEntityManager", unitName = "foo-unit")
+public class MyBean implements MyInterface {
+
+ @PersistenceContext(unitName = "bar-unit")
+ private EntityManager myBarEntityManager;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarEntityManager == null) throw new NullPointerException("myBarEntityManager not injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ EntityManager fooEntityManager = (EntityManager) context.lookup("java:comp/env/myFooEntityManager");
+ EntityManager barEntityManager = (EntityManager) context.lookup("java:comp/env/org.superbiz.MyBean/myBarEntityManager");
+ }
+}
+{code}
+
+h1. Via xml
+
+The above @PersistenceContext annotation usage is 100% equivalent to the following xml.
+
+{code:xml|title=ejb-jar.xml or web.xml}
+<persistence-context-ref>
+ <persistence-context-ref-name>myFooEntityManager</persistence-context-ref-name>
+ <persistence-unit-name>foo-unit</persistence-unit-name>
+ <persistence-context-type>Transaction</persistence-context-type>
+</persistence-context-ref>
+<persistence-context-ref>
+ <persistence-context-ref-name>org.superbiz.calculator.MyBean/myBarEntityManager</persistence-context-ref-name>
+ <persistence-unit-name>bar-unit</persistence-unit-name>
+ <persistence-context-type>Transaction</persistence-context-type>
+ <injection-target>
+ <injection-target-class>org.superbiz.calculator.MyBean</injection-target-class>
+ <injection-target-name>myBarEntityManager</injection-target-name>
+ </injection-target>
+</persistence-context-ref>
+{code}
\ No newline at end of file
Propchange: openejb/site/trunk/content/persistence-context.cwiki
------------------------------------------------------------------------------
svn:eol-style = native
Added: openejb/site/trunk/content/persistence-context.mdtext
URL: http://svn.apache.org/viewvc/openejb/site/trunk/content/persistence-context.mdtext?rev=1144778&view=auto
==============================================================================
--- openejb/site/trunk/content/persistence-context.mdtext (added)
+++ openejb/site/trunk/content/persistence-context.mdtext Sun Jul 10 05:36:12 2011
@@ -0,0 +1,61 @@
+Title: persistence-context
+<a name="persistence-context-Viaannotation"></a>
+# Via annotation
+
+Both lookup and injection of an EntityManager can be configured via the
+@PersistenceContext 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;
+
+ import javax.persistence.PersistenceContext;
+ import javax.persistence.EntityManager;
+ import javax.ejb.Stateless;
+ import javax.naming.InitialContext;
+
+ @Stateless
+ @PersistenceContext(name = "myFooEntityManager", unitName = "foo-unit")
+ public class MyBean implements MyInterface {
+
+ @PersistenceContext(unitName = "bar-unit")
+ private EntityManager myBarEntityManager;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarEntityManager == null) throw new
+NullPointerException("myBarEntityManager not injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ EntityManager fooEntityManager = (EntityManager)
+context.lookup("java:comp/env/myFooEntityManager");
+ EntityManager barEntityManager = (EntityManager)
+context.lookup("java:comp/env/org.superbiz.MyBean/myBarEntityManager");
+ }
+ }
+
+
+<a name="persistence-context-Viaxml"></a>
+# Via xml
+
+The above @PersistenceContext annotation usage is 100% equivalent to the
+following xml.
+
+{code:xml|title=ejb-jar.xml or web.xml}
+<persistence-context-ref>
+
+<persistence-context-ref-name>myFooEntityManager</persistence-context-ref-name>
+ <persistence-unit-name>foo-unit</persistence-unit-name>
+ <persistence-context-type>Transaction</persistence-context-type>
+</persistence-context-ref>
+<persistence-context-ref>
+
+<persistence-context-ref-name>org.superbiz.calculator.MyBean/myBarEntityManager</persistence-context-ref-name>
+ <persistence-unit-name>bar-unit</persistence-unit-name>
+ <persistence-context-type>Transaction</persistence-context-type>
+ <injection-target>
+
+<injection-target-class>org.superbiz.calculator.MyBean</injection-target-class>
+ <injection-target-name>myBarEntityManager</injection-target-name>
+ </injection-target>
+</persistence-context-ref>
+