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/11/30 23:04:27 UTC
[12/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/jms-resources-and-mdb-container.mdtext
----------------------------------------------------------------------
diff --git a/docs/jms-resources-and-mdb-container.mdtext b/docs/jms-resources-and-mdb-container.mdtext
new file mode 100644
index 0000000..91d305a
--- /dev/null
+++ b/docs/jms-resources-and-mdb-container.mdtext
@@ -0,0 +1,279 @@
+Title: JMS Resources and MDB Container
+
+# External ActiveMQ Broker
+
+ <tomee>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+ # Do not start the embedded ActiveMQ broker
+ BrokerXmlConfig =
+ ServerUrl = tcp://someHostName:61616
+ </Resource>
+
+ <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Resource>
+
+ <Container id="MyJmsMdbContainer" ctype="MESSAGE">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Container>
+
+ <Resource id="FooQueue" type="javax.jms.Queue"/>
+ <Resource id="BarTopic" type="javax.jms.Topic"/>
+ </tomee>
+
+
+The `ServerUrl` would be changed to point to the host and port of the
+ActiveMQ process. The various URL formats that ActiveMQ supports also
+work, such as 'failover:'.
+
+# Internal ActiveMQ Broker
+
+ <tomee>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+ BrokerXmlConfig = broker:(tcp://someHostName:61616)
+ ServerUrl = tcp://someHostName:61616
+ </Resource>
+
+ <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Resource>
+
+ <Container id="MyJmsMdbContainer" ctype="MESSAGE">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Container>
+
+ <Resource id="FooQueue" type="javax.jms.Queue"/>
+ <Resource id="BarTopic" type="javax.jms.Topic"/>
+ </tomee>
+
+The `BrokerXmlConfig` tells ActiveMQ to start on the tcp host/port `someHostName` and `61616`
+
+## Internal ActiveMQ Broker with JDBC Persistence
+
+Adding the `DataSource` property to your `ActiveMQResourceAdapter` config will automatically setup JDBC Persistence using the
+`org.apache.activemq.store.jdbc.JDBCPersistenceAdapter`
+
+ <tomee>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+ BrokerXmlConfig = broker:(tcp://someHostName:61616)
+ ServerUrl = tcp://someHostName:61616
+ DataSource = MyDataSource
+ </Resource>
+
+ <Resource id="MyDataSource" type="javax.sql.DataSource">
+ JdbcDriver = org.hsqldb.jdbcDriver.
+ JdbcUrl = jdbc:hsqldb:file:data/hsqldb/hsqldb.
+ UserName = sa
+ Password = foo
+ </Resource>
+ </tomee>
+
+
+
+## Internal ActiveMQ Broker with activemq.xml
+
+The [activemq.xml](activemq.xml) file format requires a number of Spring dependencies, and is therefore not included in the distribution by default. This is purley due to the fact that this ActiveMQ file format is parsed using Spring libraries and this is beyond our control. However, the advantage is opening up the door to the huge number of configuration options available found here: [http://activemq.apache.org/xml-configuration.html](http://activemq.apache.org/xml-configuration.html).
+
+This support can be enabled by adding the right libraries and creating an [`[tomee]/conf/activemq.xml`](activemq.xml) file (Click the link for a basic example).
+
+Add the following jars to the `tomee/lib/` directory:
+
+- [spring-beans-3.2.9.RELEASE.jar](http://repo1.maven.org/maven2/org/springframework/spring-beans/3.2.9.RELEASE/spring-beans-3.2.9.RELEASE.jar)
+- [spring-context-3.2.9.RELEASE.jar](http://repo1.maven.org/maven2/org/springframework/spring-context/3.2.9.RELEASE/spring-context-3.2.9.RELEASE.jar)
+- [spring-core-3.2.9.RELEASE.jar](http://repo1.maven.org/maven2/org/springframework/spring-core/3.2.9.RELEASE/spring-core-3.2.9.RELEASE.jar)
+- [spring-web-3.2.9.RELEASE.jar](http://repo1.maven.org/maven2/org/springframework/spring-web/3.2.9.RELEASE/spring-web-3.2.9.RELEASE.jar)
+- [xbean-spring-3.9.jar](http://repo1.maven.org/maven2/org/apache/xbean/xbean-spring/3.2.9.RELEASE/xbean-spring-3.9.jar)
+
+Later versions should work, but have not been tested.
+
+Create an [activemq.xml file](activemq.xml) a in `[tomee]/conf/activemq.xml`.
+
+Then use the `xbean:file:` url prefix in the `BrokerXmlConfig` as shown belog.
+
+
+ <tomee>
+ <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">
+ BrokerXmlConfig = xbean:file:conf/activemq.xml
+ ServerUrl = tcp://someHostName:61616
+ </Resource>
+
+ <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Resource>
+
+ <Container id="MyJmsMdbContainer" ctype="MESSAGE">
+ ResourceAdapter = MyJmsResourceAdapter
+ </Container>
+
+ <Resource id="FooQueue" type="javax.jms.Queue"/>
+ <Resource id="BarTopic" type="javax.jms.Topic"/>
+ </tomee>
+
+Finally, restart the server.
+
+
+# Configuration via System properties
+
+The same can be done via properties in an embedded configuration, via the
+`conf/system.properties` file or on the command line via `-D` flags.
+
+
+ Properties p = new Properties();
+ p.put(Context.INITIAL_CONTEXT_FACTORY, LocalInitialContextFactory.class.getName());
+
+ p.put("MyJmsResourceAdapter", "new://Resource?type=ActiveMQResourceAdapter");
+ p.put("MyJmsResourceAdapter.ServerUrl", "tcp://someHostName:61616");
+ p.put("MyJmsResourceAdapter.BrokerXmlConfig", "");
+
+ p.put("MyJmsConnectionFactory", "new://Resource?type=javax.jms.ConnectionFactory");
+ p.put("MyJmsConnectionFactory.ResourceAdapter", "MyJmsResourceAdapter");
+
+ p.put("MyJmsMdbContainer", "new://Container?type=MESSAGE");
+ p.put("MyJmsMdbContainer.ResourceAdapter", "MyJmsResourceAdapter");
+
+ p.put("FooQueue", "new://Resource?type=javax.jms.Queue");
+ p.put("BarTopic", "new://Resource?type=javax.jms.Topic");
+
+ InitialContext context = new InitialContext(p);
+
+# Global lookup of JMS Resources
+
+From anywhere in the same VM as the EJB Container you could lookup the
+above resources like so:
+
+ javax.jms.ConnectionFactory cf = (ConnectionFactory)
+ context.lookup("openejb:Resource/MyJmsConnectionFactory");
+
+ javax.jms.Queue queue = (Queue) context.lookup("openejb:Resource/FooQueue");
+ javax.jms.Topic topic = (Topic) context.lookup("openejb:Resource/BarTopic");
+
+# MDB ActivationConfig
+
+
+Here, the value for `destination` is the physical name of the desired destination. The value for
+`destinationType` is the class name that defines the type of destination. It should be `javax.jms.Queue` or `javax.jms.Topic`.
+
+The Activation Spec properties that can be configured are:
+
+<TABLE><TBODY>
+<TR>
+<TH> Property Name </TH>
+<TH> Required </TH>
+<TH> Default Value </TH>
+<TH> Description </TH>
+</TR>
+<TR>
+<TD> acknowledgeMode </TD>
+<TD> no </TD>
+<TD> Auto-acknowledge </TD>
+<TD> The JMS Acknowledgement mode to use. Valid values are: Auto-acknowledge or Dups-ok-acknowledge </TD>
+</TR>
+<TR>
+<TD> clientId </TD>
+<TD> no </TD>
+<TD> set in resource adapter </TD>
+<TD> The JMS Client ID to use (only really required for durable topics) </TD>
+</TR>
+<TR>
+<TD> destinationType </TD>
+<TD> yes </TD>
+<TD> null </TD>
+<TD> The type of destination; a queue or topic </TD>
+</TR>
+<TR>
+<TD> destination </TD>
+<TD> yes </TD>
+<TD> null </TD>
+<TD> The destination name (queue or topic name) </TD>
+</TR>
+<TR>
+<TD> enableBatch </TD>
+<TD> no </TD>
+<TD> false </TD>
+<TD> Used to enable transaction batching for increased performance </TD>
+</TR>
+<TR>
+<TD> maxMessagesPerBatch </TD>
+<TD> no </TD>
+<TD> 10 </TD>
+<TD> The number of messages per transaction batch </TD>
+</TR>
+<TR>
+<TD> maxMessagesPerSessions </TD>
+<TD> no </TD>
+<TD> 10 </TD>
+<TD> This is actually the prefetch size for the subscription. (Yes, badly named). </TD>
+</TR>
+<TR>
+<TD> maxSessions </TD>
+<TD> no </TD>
+<TD> 10 </TD>
+<TD> The maximum number of concurrent sessions to use </TD>
+</TR>
+<TR>
+<TD> messageSelector </TD>
+<TD> no </TD>
+<TD> null </TD>
+<TD>Message Selector</A> to use on the subscription to perform content based routing filtering the messages </TD>
+</TR>
+<TR>
+<TD> noLocal </TD>
+<TD> no </TD>
+<TD> false </TD>
+<TD> Only required for topic subscriptions; indicates if locally published messages should be included in the subscription or not </TD>
+</TR>
+<TR>
+<TD> password </TD>
+<TD> no </TD>
+<TD> set in resource adapter </TD>
+<TD> The password for the JMS connection </TD>
+</TR>
+<TR>
+<TD> subscriptionDurability </TD>
+<TD> no </TD>
+<TD> NonDurable </TD>
+<TD> Whether or not a durable (topic) subscription is required. Valid values are: Durable or NonDurable </TD>
+</TR>
+<TR>
+<TD> subscriptionName </TD>
+<TD> no </TD>
+<TD> null </TD>
+<TD> The name of the durable subscriber. Only used for durable topics and combined with the clientID to uniquely identify the durable topic subscription </TD>
+</TR>
+<TR>
+<TD> userName </TD>
+<TD> no </TD>
+<TD> set in resource adapter </TD>
+<TD> The user for the JMS connection </TD>
+</TR>
+<TR>
+<TD> useRAManagedTransaction </TD>
+<TD> no </TD>
+<TD> false </TD>
+<TD> Typically, a resource adapter delivers messages to an endpoint which is managed by a container. Normally, this container likes to be the one that wants to control the transaction that the inbound message is being delivered on. But sometimes, you want to deliver to a simpler container system that will not be controlling the inbound transaction. In these cases, if you set useRAManagedTransaction to true, the resource adapter will commit the transaction if no exception was generated from the MessageListener and rollback if an exception is thrown. </TD>
+</TR>
+<TR>
+<TD> initialRedeliveryDelay </TD>
+<TD> no </TD>
+<TD> 1000 </TD>
+<TD> The delay before redeliveries start. Also configurable on the ResourceAdapter </TD>
+</TR>
+<TR>
+<TD> maximumRedeliveries </TD>
+<TD> no </TD>
+<TD> 5 </TD>
+<TD> The maximum number of redeliveries or -1 for no maximum. Also configurable on the ResourceAdapter </TD>
+</TR>
+<TR>
+<TD> redeliveryBackOffMultiplier </TD>
+<TD> no </TD>
+<TD> 5 </TD>
+<TD> The multiplier to use if exponential back off is enabled. Also configurable on the ResourceAdapter </TD>
+</TR>
+<TR>
+<TD> redeliveryUseExponentialBackOff </TD>
+<TD> no </TD>
+<TD> false </TD>
+<TD> To enable exponential backoff. Also configurable on the ResourceAdapter </TD>
+</TR>
+</TBODY></TABLE>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/jmsconnectionfactory-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/jmsconnectionfactory-config.mdtext b/docs/jmsconnectionfactory-config.mdtext
new file mode 100644
index 0000000..16591ca
--- /dev/null
+++ b/docs/jmsconnectionfactory-config.mdtext
@@ -0,0 +1,85 @@
+Title: JmsConnectionFactory Configuration
+
+
+A JmsConnectionFactory 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.
+
+ <Resource id="myJmsConnectionFactory" type="javax.jms.ConnectionFactory">
+ connectionMaxIdleTime = 15 Minutes
+ connectionMaxWaitTime = 5 seconds
+ poolMaxSize = 10
+ poolMinSize = 0
+ resourceAdapter = Default JMS Resource Adapter
+ transactionSupport = xa
+ </Resource>
+
+Alternatively, a JmsConnectionFactory 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`
+
+ myJmsConnectionFactory = new://Resource?type=javax.jms.ConnectionFactory
+ myJmsConnectionFactory.connectionMaxIdleTime = 15 Minutes
+ myJmsConnectionFactory.connectionMaxWaitTime = 5 seconds
+ myJmsConnectionFactory.poolMaxSize = 10
+ myJmsConnectionFactory.poolMinSize = 0
+ myJmsConnectionFactory.resourceAdapter = Default JMS Resource Adapter
+ myJmsConnectionFactory.transactionSupport = xa
+
+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 JmsConnectionFactory a warning will be logged. If a JmsConnectionFactory is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple JmsConnectionFactory declarations are allowed.
+# Supported Properties
+<table>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+<tr>
+ <td>connectionMaxIdleTime</td>
+ <td><a href="configuring-durations.html">time</a></td>
+ <td>15 Minutes</td>
+ <td>
+Maximum amount of time a connection can be idle before being reclaimed
+</td>
+</tr>
+<tr>
+ <td>connectionMaxWaitTime</td>
+ <td><a href="configuring-durations.html">time</a></td>
+ <td>5 seconds</td>
+ <td>
+Maximum amount of time to wait for a connection
+</td>
+</tr>
+<tr>
+ <td>poolMaxSize</td>
+ <td>int</td>
+ <td>10</td>
+ <td>
+Maximum number of physical connection to the ActiveMQ broker
+</td>
+</tr>
+<tr>
+ <td>poolMinSize</td>
+ <td>int</td>
+ <td>0</td>
+ <td>
+Minimum number of physical connection to the ActiveMQ broker
+</td>
+</tr>
+<tr>
+ <td>resourceAdapter</td>
+ <td>String</td>
+ <td>Default JMS Resource Adapter</td>
+ <td>
+
+</td>
+</tr>
+<tr>
+ <td>transactionSupport</td>
+ <td>String</td>
+ <td>xa</td>
+ <td>
+Specifies if the connection is enrolled in global transaction
+allowed values: xa, local or none
+</td>
+</tr>
+</table>
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/jndi-names.mdtext
----------------------------------------------------------------------
diff --git a/docs/jndi-names.mdtext b/docs/jndi-names.mdtext
new file mode 100644
index 0000000..1da61af
--- /dev/null
+++ b/docs/jndi-names.mdtext
@@ -0,0 +1,368 @@
+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>
+<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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/jpa-concepts.mdtext
----------------------------------------------------------------------
diff --git a/docs/jpa-concepts.mdtext b/docs/jpa-concepts.mdtext
new file mode 100644
index 0000000..0afb88c
--- /dev/null
+++ b/docs/jpa-concepts.mdtext
@@ -0,0 +1,217 @@
+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/f779264f/docs/jpa-usage.mdtext
----------------------------------------------------------------------
diff --git a/docs/jpa-usage.mdtext b/docs/jpa-usage.mdtext
new file mode 100644
index 0000000..6a5cf39
--- /dev/null
+++ b/docs/jpa-usage.mdtext
@@ -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)
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/local-client-injection.mdtext
----------------------------------------------------------------------
diff --git a/docs/local-client-injection.mdtext b/docs/local-client-injection.mdtext
new file mode 100644
index 0000000..4387fd9
--- /dev/null
+++ b/docs/local-client-injection.mdtext
@@ -0,0 +1,85 @@
+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/f779264f/docs/local-server.mdtext
----------------------------------------------------------------------
diff --git a/docs/local-server.mdtext b/docs/local-server.mdtext
new file mode 100644
index 0000000..acacb2c
--- /dev/null
+++ b/docs/local-server.mdtext
@@ -0,0 +1,57 @@
+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/f779264f/docs/lookup-of-other-ejbs-example.mdtext
----------------------------------------------------------------------
diff --git a/docs/lookup-of-other-ejbs-example.mdtext b/docs/lookup-of-other-ejbs-example.mdtext
new file mode 100644
index 0000000..5681e06
--- /dev/null
+++ b/docs/lookup-of-other-ejbs-example.mdtext
@@ -0,0 +1,147 @@
+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/f779264f/docs/managedcontainer-config.mdtext
----------------------------------------------------------------------
diff --git a/docs/managedcontainer-config.mdtext b/docs/managedcontainer-config.mdtext
new file mode 100644
index 0000000..5c32014
--- /dev/null
+++ b/docs/managedcontainer-config.mdtext
@@ -0,0 +1,24 @@
+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>
+<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/f779264f/docs/manual-installation.mdtext
----------------------------------------------------------------------
diff --git a/docs/manual-installation.mdtext b/docs/manual-installation.mdtext
new file mode 100644
index 0000000..d24e01d
--- /dev/null
+++ b/docs/manual-installation.mdtext
@@ -0,0 +1,223 @@
+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/f779264f/docs/maven.mdtext
----------------------------------------------------------------------
diff --git a/docs/maven.mdtext b/docs/maven.mdtext
new file mode 100644
index 0000000..41eb91c
--- /dev/null
+++ b/docs/maven.mdtext
@@ -0,0 +1,38 @@
+# 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