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 2018/12/02 02:20:50 UTC
[23/30] tomee git commit: Rename *.mdtext files to *.md
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/jndi-names.md
----------------------------------------------------------------------
diff --git a/docs/jndi-names.md b/docs/jndi-names.md
new file mode 100644
index 0000000..caec21c
--- /dev/null
+++ b/docs/jndi-names.md
@@ -0,0 +1,372 @@
+index-group=Unrevised
+type=page
+status=published
+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.
+2 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
+
+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.
+<table class="mdtable">
+<tr><td>variable</td><td> description</td></tr>
+<tr><td>moduleId</td><td> Typically the name of the ejb-jar file<br> or the <ejb-jar id=""> id value if specified</td></tr>
+<tr><td>ejbType</td><td> STATEFUL, STATELESS, BMP_ENTITY, CMP_ENTITY, or MESSAGE_DRIVEN</td></tr>
+<tr><td>ejbClass</td><td> for a class named org.acme.superfun.WidgetBean results in org.acme.superfun.WidgetBean</td></tr>
+<tr><td>ejbClass.simpleName</td><td> for a class named org.acme.superfun.WidgetBean results in WidgetBean</td></tr>
+<tr><td>ejbClass.packageName</td><td> for a class named org.acme.superfun.WidgetBean results in org.acme.superfun</td></tr>
+<tr><td>ejbName</td><td> The ejb-name as specified in xml or via the 'name' attribute in an @Stateful, @Stateless, or @MessageDriven annotation</td></tr>
+<tr><td>deploymentId</td><td> The unique system id for the ejb. Typically the ejbName unless specified in the openejb-jar.xml or via changing the openejb.deploymentId.format</td></tr>
+<tr><td>interfaceType</td><td> see interfaceType.annotationName</td></tr>
+<tr><td>interfaceType.annotationName</td><td> 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)</td></tr>
+<tr><td>interfaceType.annotationNameLC</td><td> This is the same as interfaceType.annotationName, but all in lower case.</td></tr>
+<tr><td>interfaceType.xmlName</td><td> 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)</td></tr>
+<tr><td>interfaceType.xmlNameCc</td><td> 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)</td></tr>
+<tr><td>interfaceType.openejbLegacyName</td><td>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)</td></tr>
+<tr><td>interfaceClass</td><td>
+(business) for a class named org.acme.superfun.WidgetRemote results in org.acme.superfun.WidgetRemote<br>
+(home) for a class named org.acme.superfun.WidgetHome results in org.acme.superfun.WidgetHome</td></tr>
+<tr><td>interfaceClass.simpleName</td><td>
+(business) for a class named org.acme.superfun.WidgetRemote results in WidgetRemote
+(home) for a class named org.acme.superfun.WidgetHome results in WidgetHome</td></tr>
+<tr><td>interfaceClass.packageName</td><td> for a class named org.acme.superfun.WidgetRemote results in org.acme.superfun</td></tr>
+</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:
+
+
+ $ ./bin/openejb start
+ -Dopenejb.jndiname.format=\{ejbName}/\{interfaceClass}"
+
+
+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.
+
+ <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>
+
+Or
+
+ <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>
+
+Or
+
+ <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>
+
+or
+
+ <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.
+<pre>
+ - {deploymentId}/{interfaceClass.simpleName}
+ - {moduleId}/{ejbName}/{interfaceClass}
+ - {ejbName}/{interfaceClass}
+ - {moduleId}/{ejbClass}/{interfaceClass}
+ - {ejbClass}/{interfaceClass}
+ - {ejbClass}/{interfaceClass.simpleName}
+ - {ejbClass.simpleName}/{interfaceClass.simpleName}
+ - {interfaceClass}/{ejbName}
+</pre>
+Bordeline optimistic:
+<pre>
+ - {moduleId}/{interfaceClass}
+ - {interfaceClass}
+</pre>
+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
+<pre>
+ - {moduleId}/{ejbClass}/{interfaceType.annotationName}
+ - {ejbClass}/{interfaceType.xmlName}
+ - {ejbClass.simpleName}/{interfaceType.xmlNameCc}
+ - {interfaceType}/{ejbName}
+ - {interfaceType}/{ejbClass}
+</pre>
+<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:
+<pre>
+ - {ejbName}
+ - {ejbClass}
+ - {ejbClass.simpleName}
+ - {moduleId}/{ejbClass.simpleName}
+ - {moduleId}/{ejbName}
+</pre>
+<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)
+
+*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.
+
+<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](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.
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/jpa-concepts.md
----------------------------------------------------------------------
diff --git a/docs/jpa-concepts.md b/docs/jpa-concepts.md
new file mode 100644
index 0000000..942d0fb
--- /dev/null
+++ b/docs/jpa-concepts.md
@@ -0,0 +1,220 @@
+index-group=Unrevised
+type=page
+status=published
+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)
+
+Comparing `RESOURCE_LOCAL` and `JTA` persistence contexts
+
+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="**JTA**"> 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 JTA
+- 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 JTA 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 JTA 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:
+
+ <?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>
+
+And referenced as follows
+
+ 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();
+ }
+
+ ...
+ }
+
+
+# Valid JTA Unit usage
+
+EJBs can use JTA persistence units through the EntityManager as
+follows:
+
+ <?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="JTA">
+ <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>
+
+And referenced as follows
+
+ 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);
+
+ }
+ }
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/jpa-usage.md
----------------------------------------------------------------------
diff --git a/docs/jpa-usage.md b/docs/jpa-usage.md
new file mode 100644
index 0000000..6b7cb54
--- /dev/null
+++ b/docs/jpa-usage.md
@@ -0,0 +1,52 @@
+index-group=Unrevised
+type=page
+status=published
+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)
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/local-client-injection.md
----------------------------------------------------------------------
diff --git a/docs/local-client-injection.md b/docs/local-client-injection.md
new file mode 100644
index 0000000..7a56f56
--- /dev/null
+++ b/docs/local-client-injection.md
@@ -0,0 +1,87 @@
+index-group=Unrevised
+type=page
+status=published
+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 [Collapsed EAR](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
+
+`openejb.tempclassloader.skip=annotations`
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/local-server.md
----------------------------------------------------------------------
diff --git a/docs/local-server.md b/docs/local-server.md
new file mode 100644
index 0000000..55f45c1
--- /dev/null
+++ b/docs/local-server.md
@@ -0,0 +1,61 @@
+index-group=Unrevised
+type=page
+status=published
+title=Local Server
+~~~~~~
+!http://www.openejb.org/images/diagram-local-server.gif|valign=top,
+align=right, hspace=15!
+<a name="LocalServer-AccessingEJBsLocally"></a>
+# Accessing EJBs Locally
+
+When OpenEJB embedded in your app, server, IDE, or JUnit, you can use what
+we call the Local Server and avoid the network overhead and enjoy an easy
+way to embedd OpenEJB. Instead of putting the app in the server, put the
+server in the app!
+
+<a name="LocalServer-Saywhat?!Alocalserver?"></a>
+# Say what?! A local server?
+
+Yes, you read correctly. OpenEJB can be embedded and treated as your very
+own personal EJB container.
+
+If they can have Local and Remote EJB's, why not Local and Remote EJB
+Servers too?
+
+Haven't you ever wanted EJBs without the heavy? I mean you need the "heavy"
+eventually, but not while you're developing. Well, there's the advantage of
+an EJB implementation that was designed with a very clean and well defined
+server-container contract, you can cut the server part out completely!
+
+So, if you wish to access ejbs locally and not in client/server mode, you
+can do so by embedding OpenEJB as a library and accessing ejbs through
+OpenEJB's built-in IntraVM (Local) Server. Why would someone want to do
+this?
+* Your application is a server or other middleware
+* You want to write an app that can be both stand alone *and* distributed
+* To test your EJBs with JUnit and don't want to start/stop servers and
+other nonsense
+* Imagine the power from being able to use your IDE debugger to step from
+your Client all the way into your EJB and back with no remote debugging
+voodoo.
+
+In this case, your application, test suite, IDE, or client accesses beans
+as you would from any other EJB Server. The EJB Server just happens to be
+running in the same virtual machine as your application. This EJB Server is
+thusly called the IntraVM Server, and, for all intense purposes, your
+application an IntraVM Client.
+
+There are some interesting differences though. The IntraVM Server isn't a
+heavyweight server as one normally associates with EJB. It doesn't open
+connections, launch threads for processing requests, introduce complex
+classloading heirarchies, or any of those "heavy" kind of things. All it
+does is dish out proxies to your app that can be used to shoot calls right
+into the EJB Container. Very light, very fast, very easy for testing,
+debugging, developing, etc.
+
+<a name="LocalServer-Embedding"></a>
+# Embedding
+
+!http://www.openejb.org/images/diagram-local-server.gif|valign=top,
+align=right, hspace=15!
+{include:OPENEJBx30:Embedding}
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/lookup-of-other-ejbs-example.md
----------------------------------------------------------------------
diff --git a/docs/lookup-of-other-ejbs-example.md b/docs/lookup-of-other-ejbs-example.md
new file mode 100644
index 0000000..d4cd99d
--- /dev/null
+++ b/docs/lookup-of-other-ejbs-example.md
@@ -0,0 +1,149 @@
+index-group=Unrevised
+type=page
+status=published
+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:
+
+> $ mvn clean install
+
+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://tomee.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
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/managedcontainer-config.md
----------------------------------------------------------------------
diff --git a/docs/managedcontainer-config.md b/docs/managedcontainer-config.md
new file mode 100644
index 0000000..1d95e4f
--- /dev/null
+++ b/docs/managedcontainer-config.md
@@ -0,0 +1,26 @@
+index-group=Unrevised
+type=page
+status=published
+title=ManagedContainer Configuration
+~~~~~~
+
+
+A ManagedContainer can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional.
+
+ <Container id="myManagedContainer" type="MANAGED">
+ </Container>
+
+Alternatively, a ManagedContainer can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext`
+
+ myManagedContainer = new://Container?type=MANAGED
+
+Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared ManagedContainer a warning will be logged. If a ManagedContainer is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple ManagedContainer declarations are allowed.
+# Supported Properties
+<table class="mdtable">
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</table>
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/manual-installation.md
----------------------------------------------------------------------
diff --git a/docs/manual-installation.md b/docs/manual-installation.md
new file mode 100644
index 0000000..b00fe81
--- /dev/null
+++ b/docs/manual-installation.md
@@ -0,0 +1,224 @@
+index-group=Unrevised
+type=page
+status=published
+title=Manual Installation
+~~~~~~
+
+# 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 [download page](http://tomee.apache.org/downloads.html)
+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
+
+##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 [download page](http://tomee.apache.org/downloads.html)
+
+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
+
+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
+
+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.
+
+<pre><code>
+ 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$
+
+</code></pre>
+
+<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.
+
+
+ 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.
+
+ apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-loader-*.jar lib/openejb-loader.jar
+
+
+Add the following `<Listener
+className="org.apache.openejb.loader.OpenEJBListener" />` to your conf/server.xml file to load the OpenEJB listener:
+
+The snippet is shown below
+
+ <!-- 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">
+ <!-- OpenEJB plugin for tomcat -->
+ <Listener
+ className="org.apache.openejb.loader.OpenEJBListener" />
+
+ <!--APR library loader. Documentation at /docs/apr.html -->
+ <Listener
+ className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
+
+<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.
+
+<pre><code>
+
+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.
+
+apache-tomcat-6.0.14$ cp webapps/openejb/tomcat/annotations-api.jar
+lib/annotations-api.jar
+
+</code></pre>
+
+<a name="ManualInstallation-{anchor:javaagent}AddOpenEJBjavaagenttoTomcatstartup"></a>
+## 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.
+
+<pre><code>
+
+ 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.
+
+ apache-tomcat-6.0.14$ cp webapps/openejb/lib/openejb-javaagent-*.jar lib/openejb-javaagent.jar
+
+</code></pre>
+
+Simply, add the snippet marked below in
+bin/catalina.bat (Windows) or bin/catalina.sh (Unix) file to enable the
+OpenEJB javaagent:
+
+ 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
+
+ # Start of Snippet to add
+ 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
+ # End of Snippet to add
+
+
+ rem ----- Execute The Requested Command
+ ---------------------------------------
+ echo Using CATALINA_BASE: %CATALINA_BASE%
+ echo Using CATALINA_HOME: %CATALINA_HOME%
+
+
+
+ # 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
+
+ #Start of Snippet to add
+ 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
+ #End of Snippet to add
+
+
+
+##Note:
+ The example above is an excerpt from the middle of the
+bin/catalina.sh file. Search for the this section and add the snippet shown
http://git-wip-us.apache.org/repos/asf/tomee/blob/b93bd755/docs/maven.md
----------------------------------------------------------------------
diff --git a/docs/maven.md b/docs/maven.md
new file mode 100644
index 0000000..a68c7a9
--- /dev/null
+++ b/docs/maven.md
@@ -0,0 +1,42 @@
+index-group=Unrevised
+type=page
+status=published
+~~~~~~
+# Maven Information
+
+This page is intended to provide an insight into basic [Maven](http://maven.apache.org/) usage for users that are not all that familiar with [Maven](http://maven.apache.org/) projects.
+It is by no means a tutorial and is designed to be more of a *quickstart* to get you up and running.
+
+You can find a really good [Maven](http://maven.apache.org/) tutorial here: [http://books.sonatype.com/mvnex-book/reference/public-book.html](http://books.sonatype.com/mvnex-book/reference/public-book.html)
+
+It is assumed that:
+
+ - You have downloaded and installed [Maven](http://maven.apache.org/) and that you can run **mvn --version** from any command prompt (or console).
+ - You have downloaded and installed [Subversion](http://subversion.apache.org/) and that you can run **svn --version** from any command prompt or console.
+
+It is also assumed you have downloaded one of the following:
+
+ - One of the example projects from [http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples]()
+ - The entire project source from [http://svn.apache.org/repos/asf/tomee/tomee/trunk](http://svn.apache.org/repos/asf/tomee/tomee/trunk)
+
+Use [Subversion](http://subversion.apache.org/) to checkout the example sources from a console like so:
+
+ svn co http://svn.apache.org/repos/asf/tomee/tomee/trunk/examples/[example]
+
+Or that you may of course also be using your own project pom.xml
+
+If you want to use the latest snapshot locate the *<repositories>* section in your pom.xml and ensure the following repository exists:
+
+ <repositories>
+ <repository>
+ <id>apache-m2-snapshot</id>
+ <name>Apache M2 Snapshot Repository</name>
+ <url>http://repository.apache.org/snapshots/</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
\ No newline at end of file