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:29 UTC
[14/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/testing/arquillian/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/testing/arquillian/index.adoc b/docs/developer/testing/arquillian/index.adoc
new file mode 100755
index 0000000..16f0538
--- /dev/null
+++ b/docs/developer/testing/arquillian/index.adoc
@@ -0,0 +1,421 @@
+= TomEE and Arquillian
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE has several arquillian adapter flavors:
+
+- openejb-embedded: a plain embedded OpenEJB supporting most of EE features
+- tomee-embedded: a full TomEE running in the same JVM
+- tomee-remote: a standard TomEE running in its own process as in production
+- tomee-webapp (not recommanded): an adapter starting from a Tomcat and installing tomee-webapp
+
+=== Embedded or Remote?
+
+Big advantage of embedded adapters is to be able to debug as usual. However it has few drawbacks which can make you
+rething this choice:
+
+- JVM resources are available where it will likely not be the case in war mode (src/main/resources typically)
+- You can mix server and client side features when writing a test
+- Classloading is a bit different by design and less isolated (test dependencies) so you can get runtime surprises when really deploying
+
+To summarize: the choice is the trade off you choose between easiness and reality of the simulation.
+
+TIP: in TomEE build we build the same tests against all tomee adapters in the same build/module, this means you can use embedded adapter in dev
+and activate remote tomee too (not only cause then if there is a failure you don't know if you missed it locally or if it is due
+to the switch of adapter) on your continuous integration platform.
+
+NOTE: all configurations have defaults
+
+=== OpenEJB Embedded
+
+==== Coordinates
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>arquillian-openejb-embedded</artifactId>
+ <version>${tomee7.version}
+</dependency>
+----
+
+==== arquillian.xml
+
+|===
+|Name|Description
+|properties|container properties, as in conf/system.properties (not in xml format)
+|preloadClasses|some class to load (ie enforce static block initialization)
+|startDefaultScopes|should CDI default scopes be started (includes @RequestScoped)
+|singleDeploymentByArchiveName |names of archives (or true for all) to dploy a single time
+|===
+
+Sample:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<arquillian
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
+ <container qualifier="openejb" default="true">
+ <configuration>
+ <property name="properties">
+ # used to not have a single DataSource and be able to test the resource resolution
+ db1 = new://Resource?type=DataSource
+ db1.JdbcUrl = jdbc:hsqldb:mem:db1
+
+ # will preload both classes, simple comma separated qualified names work too
+ openejb.arquillian.predeploy-archives = org.company.openejb.arquillian.openejb.archive.[SimpleArchive|SimpleArchive2]
+ </property>
+ </configuration>
+ </container>
+</arquillian>
+----
+
+=== TomEE Embedded
+
+==== Coordinates
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>arquillian-tomee-embedded</artifactId>
+ <version>${tomee7.version}
+</dependency>
+----
+
+==== Configuration
+
+|===
+|Name|Description
+| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort)
+| httpsPort | the HTTPS port
+| httpPort | the HTTP port
+| stopPort | the shutdown port
+| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs)
+| appWorkingDir | where to dump applications (`@Deployment`)
+| host | which host to use
+| stopHost | which port to use to shutdown TomEE (port on Server configuration)
+| stopCommand | which command to use to shutdown TomEE
+| serverXml | where is the provided server.xml
+| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used
+| preloadClasses | which classes to initialize during container startup
+| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy)
+| unsafeEjbd | should EJB allow all classes
+| unpackWars | unpackWARs value in server.xml
+| properties | container properties
+| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner
+| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set
+| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key
+| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key
+|ssl| should https be activated
+|withEjbRemote| should EJBd remote be activated
+|keystoreFile | if ssl is set to true the keystore location
+|keystorePass | if ssl is set to true the keystore password
+|keystoreType | if ssl is set to true the keystore type
+|clientAuth |should SSL connector use clientAuth
+|keyAlias | if ssl is set to true the key to use
+|sslProtocol | if ssl is set to true the protocol to use
+|users |a map of users (properties syntax)
+|roles |user roles (properties syntax)
+|webResourcesCached |should resources be cached or not (`DefaultServlet` caching)
+|===
+
+
+Sample:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<arquillian
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://jboss.org/schema/arquillian
+ http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
+ <container qualifier="tomee" default="true">
+ <configuration>
+ <property name="serverXml">conf/server.xml</property>
+
+ <!-- port = -1 means random -->
+ <property name="httpPort">-1</property>
+ <property name="stopPort">-1</property>
+
+ <!-- ssl -->
+ <property name="httpsPort">-1</property>
+ <property name="ssl">false</property>
+ <property name="keystoreFile">keystore-path</property>
+ <property name="keystorePass">changeit</property>
+ <property name="keystoreType">JKS</property>
+ <property name="clientAuth">false</property>
+ <property name="keyAlias">alias</property>
+ <property name="sslProtocol">protocol</property>
+
+ <!-- where to create TomEE files -->
+ <property name="dir">target/tomee-embedded</property>
+
+ <!-- where to dump on disk applications to deploy -->
+ <property name="appWorkingDir">target/working-dir</property>
+
+ <!-- optional - limit the port allowed when random -->
+ <property name="portRange">20001-30000</property>
+
+ <!-- container config -->
+ <property name="properties">
+ # same as embedded case
+ </property>
+
+ <!-- Deployer config -->
+ <property name="deployerProperties">
+ # openejb.deployer.binaries.use=true
+ # openejb.deployer.forced.appId=[name]
+ # openejb.deployer.save-deployments=false
+ </property>
+ </configuration>
+ </container>
+</arquillian>
+----
+
+=== TomEE Remote
+
+IMPORTANT: if a server is already started on host:port then it will be used instead of starting the configured TomEE type.
+
+To use a custom instance with arquillian ensure to have ejbd and tomee webapp activated. A way is to have in `conf/system.properties` these entries:
+
+[source]
+----
+tomee.remote.support=true
+openejb.system.apps=true
+
+# you can customize it depending the security level you need on the instance
+tomee.serialization.class.whitelist =
+tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process
+----
+
+For really remote instances (= not on localhost) you need the `deployerProperties` of previous snippet too:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<arquillian
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://jboss.org/schema/arquillian
+ http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
+ <container qualifier="tomee" default="true">
+ <configuration>
+ <!-- ... -->
+ <property name="deployerProperties">
+ openejb.deployer.binaries.use=true
+ openejb.deployer.save-deployments=false
+ </property>
+ </configuration>
+ </container>
+</arquillian>
+----
+
+==== Coordinates
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>arquillian-tomee-remote</artifactId>
+ <version>${tomee7.version}
+</dependency>
+----
+
+==== Configuration
+
+|===
+|Name|Description
+| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort)
+| httpsPort | the HTTPS port
+| httpPort | the HTTP port
+| stopPort | the shutdown port
+| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs)
+| appWorkingDir | where to dump applications (`@Deployment`)
+| host | which host to use
+| stopHost | which port to use to shutdown TomEE (port on Server configuration)
+| stopCommand | which command to use to shutdown TomEE
+| serverXml | where is the provided server.xml
+| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used
+| preloadClasses | which classes to initialize during container startup
+| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy)
+| unsafeEjbd | should EJB allow all classes
+| unpackWars | unpackWARs value in server.xml
+| properties | container properties
+| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner
+| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set
+| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key
+| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key
+|groupId|the maven groupId of the TomEE (or not) artifact
+|artifactId|the maven artifactId of the TomEE (or not) artifact
+|version |the maven version of the TomEE (or not) artifact
+|classifier |the maven classifier of the TomEE (or not) artifact
+|type |the maven type of the TomEE (or not) artifact (should be zip)
+|removeUnusedWebapps |should default webapps (ROOT, manager, ...) be removed
+|ajpPort |the ajp port if used
+|conf |a folder to synchronize with TomEE conf folder
+|bin |a folder to synchronize with TomEE bin folder
+|lib |a folder to synchronize with TomEE lib folder
+|endorsed |a folder to synchronize with TomEE endorsed folder
+|javaagent |a list (flat format) of javaagent to add when launching tomee, can use maven coordinates if prefixed with `mvn:`
+|additionalLibs |a list (flat format) of library to add to TomEE libraries, can use paths of maven coordinates when prefixed with `mvn:`
+|cleanOnStartUp |should TomEE folder be deleted on startup if exists
+|debug |should the container run in debug mode (`-Dopenejb.server.debug=true` activates it without touching the configuration)
+|debugPort |if activated which port to use to debug
+|catalina_opts |equivalent to `CATALINA_OPTS` environment variable
+|simple_log |should logs be inline
+|deployerProperties |deployer properties, useful when not deploying on an instance managed by the build (remote instance typically)
+|===
+
+
+Sample:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<arquillian
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://jboss.org/schema/arquillian
+ http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
+ <container qualifier="tomee" default="true">
+ <configuration>
+ <property name="serverXml">conf/server.xml</property>
+
+ <!-- tomee zip to use -->
+ <property name="groupId">org.apache.tomee</property>
+ <property name="artifactId">apache-tomee</property>
+ <property name="version">LATEST</property>
+ <property name="type">zip</property>
+
+ <!-- tomee provided files, ignored by default -->
+ <property name="bin">src/test/tomee/bin</property>
+ <property name="conf">src/test/tomee/conf</property>
+ <property name="lib">src/test/tomee/lib</property>
+
+ <!--
+ remote debugging,
+ -Dopenejb.server.debug can activate it too
+ -->
+ <property name="debug">false</property>
+ <property name="debugPort">5005</property>
+
+ <!-- nice one line logging -->
+ <property name="simpleLog">true</property>
+
+ <!-- jvm config -->
+ <property name="catalina_opts">-XX:-UseParallelGC</property>
+
+ <!-- remove if exist -->
+ <property name="cleanOnStartUp">true</property>
+
+ <!-- remove default webapps -->
+ <property name="removeunusedWebapps">true</property>
+
+ <!-- port = -1 means random -->
+ <property name="httpPort">-1</property>
+ <property name="stopPort">-1</property>
+
+ <!-- where to create TomEE -->
+ <property name="dir">target/apache-tomee</property>
+
+ <!-- where to dump on disk applications to deploy -->
+ <property name="appWorkingDir">target/working-dir</property>
+
+ <!-- optional - limit the port allowed when random -->
+ <property name="portRange">20001-30000</property>
+
+ <!-- container config -->
+ <property name="properties">
+ # same as embedded case
+ </property>
+
+ <!-- we monitor the test with sirona -->
+ <property name="javaagent">
+ mvn:org.apache.sirona:sirona-javaagent:0.2-incubating:jar:shaded
+ </property>
+
+ <!-- Deployer config -->
+ <property name="deployerProperties">
+ # openejb.deployer.binaries.use=true
+ # openejb.deployer.forced.appId=[name]
+ # openejb.deployer.save-deployments=false
+ </property>
+
+ </configuration>
+ </container>
+</arquillian>
+----
+
+=== Multiple instances
+
+With arquillian you can create cluster or isolated instances. Here is a sample `arquillian.xml`:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://jboss.org/schema/arquillian
+ http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
+ <group qualifier="tomee-cluster">
+ <container qualifier="tomee-1">
+ <configuration>
+ <property name="httpPort">-1</property>
+ <property name="stopPort">-1</property>
+ <property name="ajpPort">-1</property>
+ <property name="dir">target/tomee1</property>
+ <property name="appWorkingDir">target/wd1</property>
+ </configuration>
+ </container>
+ <container qualifier="tomee-2">
+ <configuration>
+ <property name="httpPort">-1</property>
+ <property name="stopPort">-1</property>
+ <property name="ajpPort">-1</property>
+ <property name="dir">target/tomee2</property>
+ <property name="appWorkingDir">target/wd2</property>
+ </configuration>
+ </container>
+ </group>
+</arquillian>
+----
+
+Then in your test just specify the container you are testing against:
+
+[source,java]
+----
+@RunWith(Arquillian.class)
+public class MultipleTomEETest {
+ @Deployment(name = "war1", testable = false)
+ @TargetsContainer("tomee-1")
+ public static WebArchive war1() {
+ return /* ... */;
+ }
+
+ @Deployment(name = "war2", testable = false)
+ @TargetsContainer("tomee-2")
+ public static WebArchive war2() {
+ return /* ... */;
+ }
+
+ @Test
+ @OperateOnDeployment("war1")
+ public void testRunningInDep1(
+ @ArquillianResource URL url) {
+ // test on tomee 1, url is contextual
+ }
+
+ @Test
+ @OperateOnDeployment("war2")
+ public void testRunningInDep1(
+ @ArquillianResource URL url) {
+ // test on tomee 1, url is contextual
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/testing/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/testing/index.adoc b/docs/developer/testing/index.adoc
new file mode 100755
index 0000000..8b277e6
--- /dev/null
+++ b/docs/developer/testing/index.adoc
@@ -0,0 +1,9 @@
+= Unit Testing
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+- link:applicationcomposer/index.html[ApplicationComposer]: Lightweight tests
+- link:arquillian/index.html[Arquillian]: The standard for EE tests
+- link:other/index.html[Going futher]: OpenEJB JUnit, TomEE Embedded...
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/testing/other/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/testing/other/index.adoc b/docs/developer/testing/other/index.adoc
new file mode 100755
index 0000000..b1d41b1
--- /dev/null
+++ b/docs/developer/testing/other/index.adoc
@@ -0,0 +1,134 @@
+= Other Testing Techniques
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+=== EJBContainer
+
+The `EJBContainer` API is a JavaEE API enriched by some OpenEJB features to make the testing easier.
+
+It starts a container (embedded for case we are interested in) scanning the classpath. This operation can be
+slow and if you go with this solution maybe think to start it only once for all tests.
+
+==== Sample
+
+[source,java]
+----
+import org.junit.After;
+import org.junit.AfterClass;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import javax.ejb.embeddable.EJBContainer;
+import javax.inject.Inject;
+import javax.naming.NamingException;
+
+import static org.junit.Assert.assertTrue;
+
+public class ATest {
+ @Inject
+ private MyCDIBean aBean;
+
+ @PersistenceContext
+ private EntityManager em;
+
+ @Resource
+ private DataSource ds;
+
+ @BeforeClass
+ public static void start() throws NamingException {
+ container = EJBContainer.createEJBContainer();
+ }
+
+ @AfterClass
+ public static void shutdown() {
+ if (container != null) {
+ container.close();
+ }
+ }
+
+ @Before
+ public void inject() throws NamingException {
+ container.getContext().bind("inject", this);
+ }
+
+ @After
+ public void reset() throws NamingException {
+ container.getContext().unbind("inject");
+ }
+
+ @Test
+ public void aTest() {
+ // ...
+ }
+}
+----
+
+It will use `createEJBContainer()` method to start the container and application, and `close()` to shutdown it.
+
+OpenEJB provides the `bind("inject")` hack to be able to get injection in the test class.
+
+=== OpenEJB JUnit
+
+`openejb-junit` is another artifact providing some facilities for testing.
+
+==== EJBContainer Rule
+
+[source,java]
+----
+@Properties({
+ @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"),
+ @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*openejb-junit.*")
+})
+public class TestEJBContainerDefaultConfig {
+ @Rule
+ public final EJBContainerRule containerRule = new EJBContainerRule(this);
+
+ @org.apache.openejb.junit.jee.resources.TestResource
+ private Context ctx;
+
+ @org.apache.openejb.junit.jee.resources.TestResource
+ private java.util.Properties props;
+
+ @org.apache.openejb.junit.jee.resources.TestResource
+ private EJBContainer container;
+
+
+ @Test
+ public void configIsHere() {
+ // ...
+ }
+}
+
+----
+
+TIP: there is the equivalent runner: `@RunWith(EJBContainerRunner.class)`
+
+==== InjectRule: injections for EJBContainerRule
+
+[source,java]
+----
+@Properties({
+ @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"),
+ @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*myjar.*")
+})
+public class TestEJBContainerRule {
+ @ClassRule
+ public static final EJBContainerRule CONTAINER_RULE = new EJBContainerRule();
+
+ @Rule
+ public final InjectRule injectRule = new InjectRule(this, CONTAINER_RULE);
+
+ @EJB
+ private BasicEjbLocal ejb;
+
+ @Test
+ public void aTest() {
+ // ...
+ }
+}
+----
+
+TIP: an alternative in `openejb-core` is to use `org.apache.openejb.Injector.inject(instance)`
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/gradle-plugins.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/gradle-plugins.adoc b/docs/developer/tools/gradle-plugins.adoc
new file mode 100755
index 0000000..fe43434
--- /dev/null
+++ b/docs/developer/tools/gradle-plugins.adoc
@@ -0,0 +1,50 @@
+= TomEE Gradle Plugin
+:jbake-date: 2016-05-31
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE provides a gradle plugin for tomee-embedded "à la Jetty".
+
+[source,java]
+----
+buildscript {
+ repositories {
+ mavenCentral()
+ }
+
+ dependencies {
+ classpath 'org.apache.tomee.gradle:tomee-embedded:7.0.0'
+ }
+}
+
+apply plugin: 'org.apache.tomee.tomee-embedded'
+
+// ...
+----
+
+Then just start tomee with:
+
+[source]
+----
+gradle tomee-embedded -i
+----
+
+== Configuration
+
+All the configuration is optional.
+
+[source,java]
+----
+// plugin setup
+def tomeeEmbedded = extensions.getByName('tomee-embedded')
+tomeeEmbedded.tomeeVersion = 'other version'
+tomeeEmbedded.skipDefaultRepository = true // don't use central to retrieve tomee
+
+// container dependencies
+def tomeeEmbeddedDeps = configurations.getByName('tomee-embedded')
+// add dependencies you need to this configuration
+----
+
+tomee-embedded task has several more advanced configuration like tomee properties, modules to deploy etc...
+Its configuration is pretty close to link:maven/embedded.html[Embedded Maven Plugin].
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/index.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/index.adoc b/docs/developer/tools/index.adoc
new file mode 100755
index 0000000..235f774
--- /dev/null
+++ b/docs/developer/tools/index.adoc
@@ -0,0 +1,8 @@
+= Build Tools and Plugins
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+- link:maven-plugins.html[Maven Plugins]
+- link:gradle-plugins.html[Gradle Plugin]
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/maven-plugins.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/maven-plugins.adoc b/docs/developer/tools/maven-plugins.adoc
new file mode 100755
index 0000000..3f335d2
--- /dev/null
+++ b/docs/developer/tools/maven-plugins.adoc
@@ -0,0 +1,12 @@
+= TomEE Maven Plugins
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE provides several maven plugins:
+
+- one for a link:maven/tomee.html[standalone TomEE]
+- one for link:maven/embedded.html[TomEE embedded]
+- one for link:maven/applicationcomposer.html[application composer] based applications
+- Note: there is one for `EJBContainer` but this one is easily replaced by one of the previous in general
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/maven/applicationcomposer.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/maven/applicationcomposer.adoc b/docs/developer/tools/maven/applicationcomposer.adoc
new file mode 100755
index 0000000..8694c37
--- /dev/null
+++ b/docs/developer/tools/maven/applicationcomposer.adoc
@@ -0,0 +1,47 @@
+= Application Composer Maven Plugin
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+This plugin has two goal:
+
+- `applicationcomposer:run`: to start the application from mvn command line
+- `applicationcomposer:zip`: to package a zip with dependencies and start scripts
+
+IMPORTANT: the dependencies are retrieved with `MavenProject.getArtifacts()` which means you artifacts should be a `war`
+- maven doesn't populate it with a `jar` - and the compile phase - at least - should be passed to ensure it is populated.
+
+=== Run goal configuration
+
+[source]
+----
+mvn process-classes applicationcomposer:run -DskipTests
+----
+
+[.table.table-bordered,options="header"]
+|===
+| Name | Default | Description
+| args | - | a list of application arguments
+|application|-|application qualified name
+|binaries|${project.build.outputDirectory}|where is your module code (target/classes)
+|mavenLog|true|force to use maven logging in openejb
+|===
+
+=== Zip goal configuration
+
+[source]
+----
+mvn process-classes applicationcomposer:zip -DskipTests
+----
+
+[.table.table-bordered,options="header"]
+|===
+| Name | Default | Description
+|workDir|${project.build.directory}/${project.build.finalName}-applicationcomposer| where the container can "work" and create temp files
+|zip|${project.build.directory}/${project.build.finalName}-applicationcomposer.zip| where to create the zip
+|attach|true|attach the created artifact
+|classifier|-|artifact classifier if needed
+|application|-|application qualified name
+|binaries|${project.build.outputDirectory}|where is your module code (target/classes)
+|===
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/maven/embedded.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/maven/embedded.adoc b/docs/developer/tools/maven/embedded.adoc
new file mode 100755
index 0000000..6e27054
--- /dev/null
+++ b/docs/developer/tools/maven/embedded.adoc
@@ -0,0 +1,53 @@
+= TomEE Embedded Maven Plugin
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE Embedded Maven plugin has a single goal: `tomee-embedded:run`.
+
+=== Configuration
+
+[.table.table-bordered,options="header"]
+|===
+| Name | Default | Description
+| warFile | ${project.build.directory}/${project.build.finalName} | where is the binary
+| httpPort | 8080 | HTTP port
+| httpsPort | 8443 | HTTPS port
+| ajpPort | 8009 | AJP port
+| stopPort | 8005 | shutdown port
+| host | localhost | the server host
+| dir | ${project.build.directory}/apache-tomee-embedded | the work directory
+| keystoreFile | - | the keystore file for the HTTPS connector
+| keystorePass | - | the keystore password for the HTTPS connector
+| keystoreType | JKS | the keystore type for the HTTPS connector
+| clientAuth | - | should HTTPS use client authentication
+| keyAlias | - | the key to use for HTTPS
+| sslProtocol | - | the protocol to use for SSL/HTTPS
+| serverXml | - | a custom server.xml
+| ssl | false | is HTTPS active
+| withEjbRemote |false | is EJBd active
+| quickSession | true | is sessions using Random instead of SecureRandom to generate id (faster but less secure, good for dev purposes)
+| skipHttp | false | don't activate HTTP connector (allow to have only HTTPS for instance)
+| classpathAsWar | false | deploy the classpath instead of the binary/war
+| useProjectClasspath | true | in previous case use the project classpath and not plugin one
+| webResourceCached | true | should web resources be cached
+| modules | ${project.build.outputDirectory} | list of module to add to the classpath of the application
+| docBase | ${project.basedir}/src/main/webapp | where is the docBase in classpath deployment mode (where are web resources)
+| context | - | which context to use for the main artifact/deployment
+| containerProperties | - | map of container properties
+| mavenLog | true | should the plugin use maven logger instead of JUL
+| keepServerXmlAsThis | false | don't apply port/host configuration to the server.xml if provided
+| users | - | map of user/password
+| roles | - | map of role/users
+| forceJspDevelopment | true | ensure JSP are in development mode (updated)
+| applications | - | list of applications to deploy
+| applicationScopes | - | scope of the artifact to take into account for the classpath (ignore PROVIDED for instance)
+| skipCurrentProject | - | don't deploy current project but only configured applications
+| applicationCopyFolder | - | a folder containing applications
+| workDir | - | tomee embedded work dir
+| inlinedServerXml | - | server.xml content directly in the pom
+| inlinedTomEEXml | - | tomee.xml content directly in the pom
+| liveReload | - | livereload configuration if activated. This is an object containing these options: {watchedFolder: 'src/main/webapp', path: '/', port: 35729}
+| withLiveReload | false | activate livereload for web resources
+|===
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/developer/tools/maven/tomee.adoc
----------------------------------------------------------------------
diff --git a/docs/developer/tools/maven/tomee.adoc b/docs/developer/tools/maven/tomee.adoc
new file mode 100755
index 0000000..e4f5896
--- /dev/null
+++ b/docs/developer/tools/maven/tomee.adoc
@@ -0,0 +1,183 @@
+= TomEE Maven Plugin
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE Maven Plugin is a set of goals for the development and to prepare to go in production:
+
+- `tomee:build`
+- `tomee:exec`
+- `tomee:configtest`
+- `tomee:debug`
+- `tomee:deploy`
+- `tomee:exec`
+- `tomee:list`
+- `tomee:run`
+- `tomee:start`
+- `tomee:stop`
+- `tomee:undeploy`
+
+=== Run
+
+The most commonly used goal, it allows to start a tomee with applications. Here is its configuration:
+
+[.table.table-bordered,options="header"]
+|===
+|Name|Default|Description
+
+|synchronization|-|a synchronization (see after the table)
+|synchronizations|-|list of synchronizations
+|reloadOnUpdate|-|should the application be redeployed when a synchronization is triggered
+
+|skipCurrentProject|false|should current project not be considered as a deployable even if its packaging is compatible (war typically)
+|tomeeVersion|auto, plugin one|which version of TomEE to use
+|tomeeGroupId|org.apache.tomee|TomEE artifact groupId
+|tomeeArtifactId|apache-tomee|TomEE artifact artifactId
+|tomeeType|zip| the type of the TomEE artifact , only zip supported at the moment
+|tomeeClassifier|webprofile|which flavor of TomEE to use (classifier)
+|tomeeShutdownPort|read from server.xml|the shutdown port
+|tomeeShutdownAttempts|60|how many times to wait for startup/shutdown (waits 1s in between)
+|tomeeShutdownCommand|SHUTDOWN|the shutdown command
+|tomeeAjpPort|read from the pom|the AJP port if needed
+|tomeeHttpsPort|read from the pom|the HTTPS port if needed
+|args|-|command line arguments (system properties, javaagent, JVM options ...)
+|debug|-|start and wait for a remote debugger to connect
+|debugPort|5005|used when debug to change the default port
+|simpleLog|false|use one line logs
+|extractWars|false|explode wars before starting
+|stripWarVersion|true|remove the version from the war name
+|stripVersion|false|remove the version from the artifact name whatever it is (even jar)
+|webappResources|${project.basedir}/src/main/webapp|where web resources are
+|webappClasses and classes|${project.build.outputDirectory}|where artifact binaries are
+|catalinaBase|${project.build.directory}/apache-tomee|where to create the tomee instance
+|context|-|name of the current artifact (rename the war from the maven name to this one)
+|webappDir|webapps|path to webapps folder from tomee.base
+|appDir|apps|path to apps folder from tomee.base
+|libDir|lib|where is lib folder
+|mainDir|${project.basedir}/src/main|used in openejb mode to change default config of conf/lib/bin folders to openejb instead of tomee
+|config|${project.basedir}/src/main/tomee/conf|a conf folder synchronized with TomEE one
+|bin|${project.basedir}/src/main/tomee/bin|a bin folder synchronized with TomEE one
+|lib|${project.basedir}/src/main/tomee/lib|a lib folder synchronized with TomEE one
+|systemVariables|-|a map of system properties
+|classpaths|-|a list of additional entries for the startup classpath
+|customizers|-|a list of customizers
+|jsCustomizers|-|a list of js customizers (js scripts)
+|groovyCustomizers|-|a list of groovy customizers (groovy scripts)
+|webappDefaultConfig|false|auto config war oriented
+|quickSession|true|session generation will use `Random` instead of `SecureRandom` (for dev)
+|forceReloadable|false|ensure TomEE supports reloading/redeployment
+|forceJspDevelopment|true|JSP will be auto-recompiled on changes
+|libs|-|dependencies to add in lib, see after this table for advanced usage
+|endorsedLibs|-|dependencies to add in endorsed, see after this table for advanced usage
+|javaagents|-|javaagents to add on the JVM, supports maven coordinates
+|persistJavaagents|false|should javaagent be saved or just use for this plugin run
+|webapps|-|additional applicatinos to deploy
+|warFile|${project.build.directory}/${project.build.finalName}.${project.packaging}|the war to deploy
+|workWarFile|${project.build.directory}/${project.build.finalName}"|the exploded war to deploy
+|removeDefaultWebapps|true| should default webapps (ROOT, docs, ...) be deleted
+|deployOpenEjbApplication|false|should openejb internal application be deployed
+|removeTomeeWebapp|true|should tomee webapp (with EJBd adapter) be deployed
+|tomeeAlreadyInstalled|false|skip all the setup configuration
+|ejbRemote|true|should EJBd be activated
+|checkStarted|false|should the plugin check the server is up (useful when used with `pre-integration` phase
+|useConsole|true|wait for the end of the execution reading inputs from the console (like `quit` command)
+|useOpenEJB|false|use openejb-standalone instead of tomee
+|inlinedServerXml|-|a server.xml content in pom.xml directly
+|inlinedTomEEXml|-|a tomee.xml content in pom.xml directly
+|overrideOnUnzip|true|if when unzipping tomee a file is already there should it be overriden
+|skipRootFolderOnUnzip|true|ignore root folder of the zip
+|keystore|-|path to keystore for HTTPS connector
+|===
+
+
+Synchronization are blocks defining a source and target folder and both are synchronized. It typically copy
+`src/main/webapp` resources in `target/apache-tomee/webapps/myapp/`.
+
+
+==== Customizers
+
+Customizers are java classes loadable by the plugin and with a main or implementing `Runnable` and taking optionally
+as constructor parameter a `File` representing `tomee.base` or no arguments.
+
+They are executed when creating the TomEE instance.
+
+There are two scripting flavors of that: js and groovy. Both will have some contextual variables:
+
+- catalinaBase: tomee base path
+- resolver: a maven resolver to get a dependency using maven. For instance: `resolver.resolve('group', 'artfact', 'version', 'type')`
+
+==== Dependencies (libs)
+
+The format can be:
+
+- a maven dependency:
+
+[source]
+----
+groupId:artifactId:version
+----
+
+- a zip dependency and extracted in lib folder:
+
+[source]
+----
+unzip:groupId:artifactId:version
+----
+
+- a matching prefix to remove:
+
+[source]
+----
+remove:prefix
+----
+
+==== Example
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.tomee.maven</groupId>
+ <artifactId>tomee-maven-plugin</artifactId>
+ <version>${tomee7.version}</version>
+ <configuration>
+ <tomeeClassifier>plus</tomeeClassifier>
+ <debug>false</debug>
+ <debugPort>5005</debugPort>
+ <args>-Dfoo=bar</args>
+ <config>${project.basedir}/src/test/tomee/conf</config>
+ <libs>
+ <lib>mysql:mysql-connector-java:5.1.20</lib>
+ </libs>
+ <webapps>
+ <webapp>org.superbiz:myapp:4.3?name=ROOT</webapp>
+ <webapp>org.superbiz:api:1.1</webapp>
+ </webapps>
+ <apps>
+ <app>org.superbiz:mybugapp:3.2:ear</app>
+ </apps>
+ <libs>
+ <lib>mysql:mysql-connector-java:5.1.21</lib>
+ <lib>unzip:org.superbiz:hibernate-bundle:4.1.0.Final:zip</lib>
+ <lib>remove:openjpa-</lib>
+ </libs>
+ </configuration>
+</plugin>
+----
+
+=== Build
+
+Excepted synchronization, build plugin inherit from `run` Mojo its configuration. It just adds the following:
+
+[.table.table-bordered,options="header"]
+|===
+|Name|Default|Description
+|formats|-|map of configuration, keys are format (zip, tar.gz) and value the target location
+|zip|true|create a zip from the configured instance
+|attach|true|attach created artifacts
+|skipArchiveRootFolder|false|don't add a root folder in the zip
+|===
+
+=== Tomcat like goals
+
+`configtest`, `start` and `stop` just execute these commands on the server (like on `catalina.sh`).
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/docs.adoc
----------------------------------------------------------------------
diff --git a/docs/docs.adoc b/docs/docs.adoc
new file mode 100644
index 0000000..5507038
--- /dev/null
+++ b/docs/docs.adoc
@@ -0,0 +1,26 @@
+= TomEE Documentation
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+=== Administration
+- link:admin/configuration/index.html[Server Configuration]
+- link:admin/directory-structure.html[Directory Structure]
+- link:admin/cluster/index.html[Clustering and High Availability (HA)]
+
+=== Developers
+- link:developer/ide/index.html[IDEs - Eclipse, Intellij Idea and Netbeans]
+- link:developer/testing/index.html[Unit Testing - Arquillian, OpenEJB JUnit, TomEE Embedded and ApplicationComposer]
+- link:developer/tools/index.html[Build Tools and Plugins]
+- link:developer/migration/tomee-1-to-7.html[Migrating From TomEE 1.x to 7.x]
+- link:developer/json/index.html[TomEE and Apache Johnzon - JAX-RS JSON Provider]
+- link:developer/configuration/cxf.html[Apache CXF Configuration - JAX-RS (RESTful Services) and JAX-WS (Web Services)]
+- link:developer/classloading/index.html[Understanding the TomEE ClassLoader]
+
+=== Advanced
+- link:advanced/applicationcomposer/index.html[`ApplicationComposer` with JBatch]
+- link:advanced/setup/index.html[How to Setup TomEE in Production]
+- link:advanced/shading/index.html[Fat / Uber Jar Deployment using the Maven Shade Plugin]
+- link:advanced/client/jndi.html[Java Naming and Directory Interface (JNDI)]
+- link:advanced/jms/jms-configuration.html[Why is my ActiveMQ/JMS MDB not scaling as expected?]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/documentation.mdtext
----------------------------------------------------------------------
diff --git a/docs/documentation.mdtext b/docs/documentation.mdtext
new file mode 100644
index 0000000..b0f4238
--- /dev/null
+++ b/docs/documentation.mdtext
@@ -0,0 +1,102 @@
+Title: Documentation
+
+See also the [examples page](examples-trunk/index.html) for downloadable, executable and code-focused view of Java EE and TomEE.
+You can also find us on IRC freenode.org #openejb and #tomee
+
+{row
+
+{span-one-third
+###IDE
+[Get started with Intellij](tomee-and-intellij.html), [Debugging in Intellij](contrib/debug/debug-intellij.html)
+[Get started with Eclipse (WTP)](tomee-and-eclipse.html)
+[Get started with Eclipse (m2e-Webby)](getting-started-with-eclipse-and-webby.html)
+[Get started with Netbeans](tomee-and-netbeans.html)
+
+###General Informations
+[Comparison: OpenEJB, TomEE, TomEE+](comparison.html)
+[TomEE Directory structure](tomee-directory-structure.html)
+[Deploying in TomEE](deploying-in-tomee.html)
+[The 'tomee' webapp](tomee-webapp.html)
+[TomEE Reference Card](refcard/refcard.html)
+[ApplicationComposer](application-composer/index.html)
+}
+{span-one-third
+###Configuration
+[System Properties](system-properties.html)
+[Deployments](deployments.html)
+[Configuring Resources](Configuring-in-tomee.html)
+[Configuring DataSources](configuring-datasources.html)
+[Containers and Resources](containers-and-resources.html)
+[JMS Resources and MDB Container](jms-resources-and-mdb-container.html)
+[Configuring JavaMail](configuring-javamail.html)
+[TomEE Security](tomee-and-security.html)
+[Security How To](security.html)
+[EJB Clients](clients.html)
+[EJB over SSL](ejb-over-ssl.html)
+[JNDI Names](jndi-names.html)
+[Changing JMS implementations](changing-jms-implementations.html)
+[Changing JPA to Hibernate](tomee-and-hibernate.html)
+}
+{span-one-third
+###Testing Techniques
+[Application discovery via the classpath](application-discovery-via-the-classpath.html)
+[Embedded Configuration](embedded-configuration.html)
+[Configuring DataSources in Tests](configuring-datasources-in-tests.html)
+[Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html)
+[Configuring Containers in Tests](configuring-containers-in-tests.html)
+[Configuring Logging in Tests](configuring-logging-in-tests.html)
+[Alternate Descriptors](alternate-descriptors.html)
+[Unit Testing Transactions](unit-testing-transactions.html)
+[TestCase with TestBean inner-class](testcase-with-testbean-inner-class.html)
+[TestCase Injection (@LocalClient)](local-client-injection.html)
+}
+}
+{row
+
+{span-one-third
+###Discovery and Failover
+[Overview](ejb-failover.html)
+[Multicast Discovery (UDP)](multicast-discovery.html)
+[Multipulse Discovery (UDP)](multipulse-discovery.html)
+[Multipoint Discovery (TCP)](multipoint-discovery.html)
+[Multipoint Considerations](multipoint-considerations.html)
+[Multipoint Recommendations](multipoint-recommendations.html)
+[Logging Events](failover-logging.html)
+}
+{span-one-third
+
+###OpenEJB Standalone Server
+[Understanding the Directory Layout](understanding-the-directory-layout.html)
+[Startup](startup.html)
+[Deploy Tool](deploy-tool.html)
+[Properties Tool](properties-tool.html)
+}
+{span-one-third
+###Spring
+[Spring and OpenEJB 3.0](spring-and-openejb-3.0.html)
+[Spring and OpenEJB 3.1 and later](spring.html)
+[Spring, EJB and JPA example](spring-ejb-and-jpa.html)
+}
+}
+{row
+
+{span-one-third
+###Arquillian
+[Arquillian Primer - What you need to know](arquillian-getting-started.html)
+[Using the TomEE Arquillian adapters](arquillian-available-adapters.html)
+}
+{span-one-third
+###TomEE Maven Plugin
+[Getting started](tomee-mp-getting-started.html)
+[tomee-maven-plugin reference documentation](maven/index.html)
+[tomee-embedded-maven-plugin reference documentation](tomee-embedded-maven-plugin.html)
+[TomEE simple webapp archetype documentation](tomee-mp-getting-started.html)
+}
+{span-one-third
+###Tips and Tricks
+[Install TomEE using the drop-in WAR](installation-drop-in-war.html)
+[Global Concurrency Management](tip-concurrency.html)
+[WebLogic Lookup](tip-weblogic.html)
+[Jersey Client](tip-jersey-client.html)
+}
+}
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/documentation.old.mdtext
----------------------------------------------------------------------
diff --git a/docs/documentation.old.mdtext b/docs/documentation.old.mdtext
new file mode 100644
index 0000000..b0f4238
--- /dev/null
+++ b/docs/documentation.old.mdtext
@@ -0,0 +1,102 @@
+Title: Documentation
+
+See also the [examples page](examples-trunk/index.html) for downloadable, executable and code-focused view of Java EE and TomEE.
+You can also find us on IRC freenode.org #openejb and #tomee
+
+{row
+
+{span-one-third
+###IDE
+[Get started with Intellij](tomee-and-intellij.html), [Debugging in Intellij](contrib/debug/debug-intellij.html)
+[Get started with Eclipse (WTP)](tomee-and-eclipse.html)
+[Get started with Eclipse (m2e-Webby)](getting-started-with-eclipse-and-webby.html)
+[Get started with Netbeans](tomee-and-netbeans.html)
+
+###General Informations
+[Comparison: OpenEJB, TomEE, TomEE+](comparison.html)
+[TomEE Directory structure](tomee-directory-structure.html)
+[Deploying in TomEE](deploying-in-tomee.html)
+[The 'tomee' webapp](tomee-webapp.html)
+[TomEE Reference Card](refcard/refcard.html)
+[ApplicationComposer](application-composer/index.html)
+}
+{span-one-third
+###Configuration
+[System Properties](system-properties.html)
+[Deployments](deployments.html)
+[Configuring Resources](Configuring-in-tomee.html)
+[Configuring DataSources](configuring-datasources.html)
+[Containers and Resources](containers-and-resources.html)
+[JMS Resources and MDB Container](jms-resources-and-mdb-container.html)
+[Configuring JavaMail](configuring-javamail.html)
+[TomEE Security](tomee-and-security.html)
+[Security How To](security.html)
+[EJB Clients](clients.html)
+[EJB over SSL](ejb-over-ssl.html)
+[JNDI Names](jndi-names.html)
+[Changing JMS implementations](changing-jms-implementations.html)
+[Changing JPA to Hibernate](tomee-and-hibernate.html)
+}
+{span-one-third
+###Testing Techniques
+[Application discovery via the classpath](application-discovery-via-the-classpath.html)
+[Embedded Configuration](embedded-configuration.html)
+[Configuring DataSources in Tests](configuring-datasources-in-tests.html)
+[Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html)
+[Configuring Containers in Tests](configuring-containers-in-tests.html)
+[Configuring Logging in Tests](configuring-logging-in-tests.html)
+[Alternate Descriptors](alternate-descriptors.html)
+[Unit Testing Transactions](unit-testing-transactions.html)
+[TestCase with TestBean inner-class](testcase-with-testbean-inner-class.html)
+[TestCase Injection (@LocalClient)](local-client-injection.html)
+}
+}
+{row
+
+{span-one-third
+###Discovery and Failover
+[Overview](ejb-failover.html)
+[Multicast Discovery (UDP)](multicast-discovery.html)
+[Multipulse Discovery (UDP)](multipulse-discovery.html)
+[Multipoint Discovery (TCP)](multipoint-discovery.html)
+[Multipoint Considerations](multipoint-considerations.html)
+[Multipoint Recommendations](multipoint-recommendations.html)
+[Logging Events](failover-logging.html)
+}
+{span-one-third
+
+###OpenEJB Standalone Server
+[Understanding the Directory Layout](understanding-the-directory-layout.html)
+[Startup](startup.html)
+[Deploy Tool](deploy-tool.html)
+[Properties Tool](properties-tool.html)
+}
+{span-one-third
+###Spring
+[Spring and OpenEJB 3.0](spring-and-openejb-3.0.html)
+[Spring and OpenEJB 3.1 and later](spring.html)
+[Spring, EJB and JPA example](spring-ejb-and-jpa.html)
+}
+}
+{row
+
+{span-one-third
+###Arquillian
+[Arquillian Primer - What you need to know](arquillian-getting-started.html)
+[Using the TomEE Arquillian adapters](arquillian-available-adapters.html)
+}
+{span-one-third
+###TomEE Maven Plugin
+[Getting started](tomee-mp-getting-started.html)
+[tomee-maven-plugin reference documentation](maven/index.html)
+[tomee-embedded-maven-plugin reference documentation](tomee-embedded-maven-plugin.html)
+[TomEE simple webapp archetype documentation](tomee-mp-getting-started.html)
+}
+{span-one-third
+###Tips and Tricks
+[Install TomEE using the drop-in WAR](installation-drop-in-war.html)
+[Global Concurrency Management](tip-concurrency.html)
+[WebLogic Lookup](tip-weblogic.html)
+[Jersey Client](tip-jersey-client.html)
+}
+}
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/dynamic-datasource.mdtext
----------------------------------------------------------------------
diff --git a/docs/dynamic-datasource.mdtext b/docs/dynamic-datasource.mdtext
new file mode 100644
index 0000000..1b23333
--- /dev/null
+++ b/docs/dynamic-datasource.mdtext
@@ -0,0 +1,216 @@
+Title: Dynamic Datasource
+<a name="DynamicDatasource-OpenEJBdynamicdatasource"></a>
+# OpenEJB dynamic datasource
+
+<a name="DynamicDatasource-Goal"></a>
+## Goal
+
+The openejb dynamic datasource api aims to allow to use multiple data
+sources as one.
+
+It can be useful for technical reasons (load balancing for example) or
+functionnal reasons (filtering, aggregation, enriching...).
+
+<a name="DynamicDatasource-TheAPI"></a>
+## The API
+
+The interface Router (*org.apache.openejb.resource.jdbc.Router*) have
+only one method to get the datasource to use:
+
+ Router.getDataSource()
+
+The *org.apache.openejb.resource.jdbc.RoutedDataSource* wraps a classical
+data source. It has to be used to declare your datasource.
+
+You can implement all the policy you want in your Router implementation.
+
+A class called *org.apache.openejb.resource.jdbc.AbstractRouter* is
+available to ease router development.
+
+<a name="DynamicDatasource-Knownlimitation(s)"></a>
+## Known limitation(s)
+
+You have to use the same kind of databases (same version, same
+configuration...).
+
+All database have to be created when you use the router. The way to do it
+automatically can depend of your JPA provider.
+
+<a name="DynamicDatasource-OpenJPA"></a>
+### OpenJPA
+
+OpenJPA initializes its database when the entitymanager is called for the
+first time so you need to initialize all your proxied datasource before
+using the other one. It can be done using an Init EJB doing a find() on
+each proxied datasource.
+
+<a name="DynamicDatasource-Hibernate"></a>
+### Hibernate
+
+Hibernate initializes the database when it starts so if you declare a
+persistence unit by database all databases will be initialized at the start
+up.
+
+<a name="DynamicDatasource-Example"></a>
+## Example
+
+<a name="DynamicDatasource-Thestory(theunittestexample)"></a>
+### The story (the unit test example)
+
+You want to use only one datasource in the code but you have a criteria to
+set to choose the real database to use between three.
+
+So in your code you want something like:
+
+ public class RoutedEJBBean {
+ @PersistenceContext(unitName = "router")
+ private EntityManager em;
+
+ // this router is not automatic, we
+ // need it to select the database to use
+ @Resource(name = "My Router")
+ private DeterminedRouter router;
+
+ public void persist(int id, String name, String clientDatasource) {
+ router.setDataSource(clientDatasource);
+ em.persist(new Person(id, name));
+ }
+ }
+
+
+<a name="DynamicDatasource-Therouterimplementation"></a>
+## The router implementation
+
+The router will simply manage a map to store proxied datasources and a
+field to store the datasource used in the current thread (ThreadLocal).
+
+ public class DeterminedRouter implements Router {
+ private String dataSourceNames; // used to store configuration (openejb.xml)
+ private String defaultDataSourceName; // defautl data source name
+ private Map<String, DataSource> dataSources = null; // proxied data sources
+ private ThreadLocal<DataSource> currentDataSource = new ThreadLocal<DataSource>(); // the datasource to use or null
+
+ /**
+ * @param datasourceList datasource resource name, separator is a space
+ */
+ public void setDataSourceNames(String datasourceList) {
+ dataSourceNames = datasourceList;
+ }
+
+ /**
+ * lookup datasource in openejb resources
+ */
+ private void init() { // looking up datasources declared as proxied
+ dataSources = new ConcurrentHashMap<String, DataSource>();
+ for (String ds : dataSourceNames.split(" ")) {
+ ContainerSystem containerSystem = SystemInstance.get().getComponent(ContainerSystem.class);
+
+ Object o = null;
+ Context ctx = containerSystem.getJNDIContext();
+ try {
+ o = ctx.lookup("openejb:Resource/" + ds);
+ if (o instanceof DataSource) {
+ dataSources.put(ds, (DataSource) o);
+ }
+ } catch (NamingException ignore) {
+ }
+ }
+ }
+
+ /**
+ * @return the user selected data source if it is set
+ * or the default one
+ * @throws IllegalArgumentException if the data source is not found
+ */
+ public DataSource getDataSource() {
+ // lazy init of routed datasources
+ if (dataSources == null) {
+ init();
+ }
+
+ // if no datasource is selected use the default one
+ if (currentDataSource.get() == null) {
+ if (dataSources.containsKey(defaultDataSourceName)) {
+ return dataSources.get(defaultDataSourceName);
+
+ } else {
+ throw new IllegalArgumentException("you have to specify at least one datasource");
+ }
+ }
+
+ // the developper set the datasource to use
+ return currentDataSource.get();
+ }
+
+ /**
+ *
+ * @param datasourceName data source name
+ */
+ public void setDataSource(String datasourceName) {
+ if (dataSources == null) {
+ init();
+ }
+ if (!dataSources.containsKey(datasourceName)) {
+ throw new IllegalArgumentException("data source called " + datasourceName + " can't be found.");
+ }
+ DataSource ds = dataSources.get(datasourceName);
+ currentDataSource.set(ds);
+ }
+
+ public void setDefaultDataSourceName(String name) {
+ this.defaultDataSourceName = name;
+ }
+ }
+
+
+<a name="DynamicDatasource-Creationoftheserviceproviderfortherouter"></a>
+## Creation of the service provider for the router
+
+To be able to use your router add a file called service-jar.xml under
+META-INF/<package>. For example META-INF/org.router.
+
+This file will contain something like:
+
+ <ServiceJar>
+ <ServiceProvider id="DeterminedRouter" service="Resource"
+ type="org.apache.openejb.resource.jdbc.Router" class-name="implementation class">
+ Param defaultValue
+ ParamWithNoDefaultValue
+ </ServiceProvider>
+ </ServiceJar>
+
+## openejb.xml
+
+In the openejb.xml file, you have to declare your dynamic database and in
+our example it needs the proxied datasources too:
+
+ <Resource id="router" type="<your implementation>" provider="<your provider>">
+ Param value
+ </Resource>
+
+ <Resource id="route db" type="DataSource" provider="RoutedDataSource">
+ Router router
+ </Resource>
+
+ <!–- real databases – for our example -->
+ <Resource id="db1" type="DataSource">
+ JdbcDriver org.hsqldb.jdbcDriver
+ JdbcUrl jdbc:hsqldb:mem:db1
+ UserName sa
+ Password
+ JtaManaged true
+ </Resource>
+ <Resource id="db2" type="DataSource">
+ JdbcDriver org.hsqldb.jdbcDriver
+ JdbcUrl jdbc:hsqldb:mem:db2
+ UserName sa
+ Password
+ JtaManaged true
+ </Resource>
+ <Resource id="db3" type="DataSource">
+ JdbcDriver org.hsqldb.jdbcDriver
+ JdbcUrl jdbc:hsqldb:mem:db3
+ UserName sa
+ Password
+ JtaManaged true
+ </Resource>
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/eclipse-plugin.mdtext
----------------------------------------------------------------------
diff --git a/docs/eclipse-plugin.mdtext b/docs/eclipse-plugin.mdtext
new file mode 100644
index 0000000..fb2386d
--- /dev/null
+++ b/docs/eclipse-plugin.mdtext
@@ -0,0 +1,38 @@
+Title: Eclipse Plugin
+<a name="EclipsePlugin-Whatisit?"></a>
+# What is it?
+
+The *OpenEJB Eclipse Plugin* will be a suite of tools made available via
+Eclipse to make EJB development with OpenEJB easier. The initial offering
+will probably provide basic functionality by taking advantage of [WebTools](http://www.eclipse.org/webtools)
+ to allow for OpenEJB to be an available container/runtime within Eclipse.
+This means full debugging and Eclipse project integration. From there, the
+sky is the limit so feel free to suggest features on the [OpenEJB Dev list|Mailing Lists#MailingLists-DeveloperMailingList]
+.
+
+<a name="EclipsePlugin-Howtogetinvolved?"></a>
+# How to get involved?
+
+Just the same as getting involved with any part of OpenEJB -- send a mail
+to the [OpenEJB Dev list](mailing-lists#mailinglists-developermailinglist.html)
+ and say "Hi!" We're a very relaxed group so no need to be perfect or
+overly prepared. Just dive right in, we're always happy to have more.
+
+<a name="EclipsePlugin-WheredoIgetit?"></a>
+# Where do I get it?
+
+The initiative is just launching, but you can grab what we have right here
+and start hacking.
+
+ http://svn.apache.org/repos/asf/tomee/openejb-eclipse-plugin/trunk/
+
+<a name="EclipsePlugin-WhatdoIneedtohelp?"></a>
+# What do I need to help?
+
+ [Eclipse](http://www.eclipse.org)
+ [Eclipse Web Tools](http://www.eclipse.org/webtools)
+
+<a name="EclipsePlugin-Resources"></a>
+# Resources
+
+ [EclipseCon Presentation for Extending WTP](http://eclipsezilla.eclipsecon.org/show_bug.cgi?id=3581)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-failover.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-failover.mdtext b/docs/ejb-failover.mdtext
new file mode 100644
index 0000000..924f869
--- /dev/null
+++ b/docs/ejb-failover.mdtext
@@ -0,0 +1,88 @@
+Title: EJB Client/Server Failover
+
+OpenEJB supports stateless failover. Specifically, the ability for an EJB
+client to failover from one server to the next if a request cannot be
+completed. No application state information is communicated between the
+servers, so this functionality should be used only with applications that
+are inherently stateless. A common term for this sort of setup is a server
+farm.
+
+The basic design assumption is that all servers in the same group have the
+same applications deployed and are capable of doing the same job. Servers
+can be brought online and offline while clients are running. As members
+join/leave this information is sent to the client as part of normal EJB
+request/response communication so active clients always have the most
+current information on servers that can process their request should
+communication with a particular server fail.
+
+# Client Behavior
+
+On each request to the server, the client will send the version number
+associated with the list of servers in the cluster it is aware of.
+Initially this version will be zero and the list will be empty. Only when
+the server sees the client has an old list will the server send the updated
+list. This is an important distinction as the list is not transmitted back
+and forth on every request, only on change. If the membership of the
+cluster is stable there is essentially no clustering overhead to the
+protocol -- 8 byte overhead to each request and 1 byte on each response --
+so you will *not* see an exponential slowdown in response times the more
+members are added to the cluster. This new list takes affect for all
+proxies that share the same connection.
+
+When a server shuts down, more connections are refused, existing
+connections not in mid-request are closed, any remaining connections are
+closed immediately after completion of the request in progress and clients
+can failover gracefully to the next server in the list. If a server
+crashes requests are retried on the next server in the list (or depending
+on the `ConnectionStrategy`). This failover pattern is followed until there
+are no more servers in the list at which point the client attempts a final
+multicast search (if it was created with a `PROVIDER_URL` starting with
+`multicast://`) before abandoning the request and throwing an exception to
+the caller.
+
+By default, the failover is ordered but random selection is supported. The
+multicast discovery aspect of the client adds a nice randomness to the
+selection of the first server.
+
+# Discovery
+
+Each discoverable service has a URI which is broadcast as a heartbeat to
+other servers in the cluster. This URI advertises the service's type, its
+cluster group, and its location in the format of 'group:type:location'.
+Say for example "cluster1:ejb:ejbd://thehost:4201". The URI is sent out
+repeatedly in a pulse and its presence on the network indicates its
+availability and its absence indicates the service is no longer available.
+
+The sending of this pulse (the heartbeat) can be done via UDP or TCP:
+multicast and "multipoint" respectively. More on that in the following
+section. The rate at which the heartbeat is pulsed to the network can be
+specified via the 'heart_rate' property. The default is 500 milliseconds.
+This rate is also used when listening for services on the network. If a
+service goes missing for the duration of 'heart_rate' multiplied by
+'max_missed_heartbeats', then the service is considered dead.
+
+The 'group' property, cluster1 in the example, is used to dissect the
+servers on the network into smaller logical clusters. A given server will
+broadcast all it's services with the group prefixed in the URI, as well it
+will ignore any services it sees broadcast if they do not share the same
+group name.
+
+#Details
+
+Multicast
+
+ - [Multicast UDP Discovery](multicast-discovery.html)
+ - [Multipulse UDP Discovery](multipulse-discovery.html)
+
+Multipoint
+
+ - [Multipoint TCP Discovery](multipoint-discovery.html)
+ - [Considerations](multipoint-considerations.html)
+ - [Recommendations](multipoint-recommendations.html)
+
+Logging
+
+ - [Failover Logging Events](failover-logging.html)
+
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-local-ref.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-local-ref.mdtext b/docs/ejb-local-ref.mdtext
new file mode 100644
index 0000000..986cb78
--- /dev/null
+++ b/docs/ejb-local-ref.mdtext
@@ -0,0 +1,49 @@
+Title: ejb-local-ref
+<a name="ejb-local-ref-Viaannotation"></a>
+# Via annotation
+
+Usable by EJB, Interceptor, Servlet, Filter, or Listener
+
+ package org.superbiz.refs;
+
+ import javax.ejb.EJB;
+ import javax.ejb.Stateless;
+ import javax.naming.InitialContext;
+
+ @Stateless
+ @EJB(name = "myFooEjb", beanInterface = FooLocal.class)
+ public class MyEjbLocalRefBean implements MyBeanInterface {
+
+ @EJB
+ private BarLocal myBarEjb;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarEjb == null) throw new NullPointerException("myBarEjb not injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ FooLocal fooLocal = (FooLocal) context.lookup("java:comp/env/myFooEjb");
+ BarLocal barLocal = (BarLocal) context.lookup("java:comp/env/org.superbiz.refs.MyEjbLocalRefBean/myBarEjb");
+ }
+ }
+
+
+<a name="ejb-local-ref-Viaxml"></a>
+# Via xml
+
+The above @EJB annotation usage is 100% equivalent to the following xml.
+
+ <ejb-local-ref>
+ <ejb-ref-name>myFooEjb</ejb-ref-name>
+ <local>org.superbiz.refs.FooLocal</local>
+ </ejb-local-ref>
+
+ <ejb-local-ref>
+ <ejb-ref-name>org.superbiz.refs.MyEjbLocalRefBean/myBarEjb</ejb-ref-name>
+ <local>org.superbiz.refs.BarLocal</local>
+ <injection-target>
+ <injection-target-class>org.superbiz.refs.MyEjbLocalRefBean</injection-target-class>
+ <injection-target-name>myBarEjb</injection-target-name>
+ </injection-target>
+ </ejb-local-ref>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-over-ssl.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-over-ssl.mdtext b/docs/ejb-over-ssl.mdtext
new file mode 100644
index 0000000..8dd5cb9
--- /dev/null
+++ b/docs/ejb-over-ssl.mdtext
@@ -0,0 +1,96 @@
+Title: EJB over SSL
+
+It is possible to setup client/server requests over SSL. EJB requests from a remote client can happen two different ways:
+
+ - **https** for when an EJB is running in TomEE
+ - **ejbds** for when an EJB is running in OpenEJB Standalone
+
+Note, TomEE can be setup to support **ejbds**.
+
+# https
+
+First, you'll need to setup Tomcat (TomEE) with SSL as described here:
+
+ [http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html](http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html)
+
+Once that is done and the `tomee` webapp can be accessed with `https`, an EJB client can invoke over `https` using the following
+`InitialContext` setup:
+
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "https://127.0.0.1:8443/tomee/ejb");
+ // user and pass optional
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+If you setup Tomcat (TomEE) to use the APR (Apache Portable Runitme) implementation of SSL on the server side, and you have connection issues like connection reset, you'll have to set 'https.protocols' system property.
+'https.protocols' property must be set according to the SSLProtocol parameter of the HTTPS connector configuration :
+
+[http://tomcat.apache.org/tomcat-7.0-doc/config/http.html][1]
+
+You can also have a look a this :
+
+[http://docs.oracle.com/javase/1.4.2/docs/guide/plugin/developer_guide/faq/troubleshooting.html][2]
+
+# ejbds
+
+The SSL version of the `ejbd` protocol is called `ejbds` and is enabled and setup in OpenEJB Standalone by default.
+
+Its configuration `conf/ejbds.properties` looks like this:
+
+ server = org.apache.openejb.server.ejbd.EjbServer
+ bind = 127.0.0.1
+ port = 4203
+ disabled = false
+ threads = 200
+ backlog = 200
+ secure = true
+ discovery = ejb:ejbds://{bind}:{port}
+
+To access this service from a remote client, the `InitialContext` would be setup like the following:
+
+ Properties p = new Properties();
+ p.put("java.naming.factory.initial", "org.apache.openejb.client.RemoteInitialContextFactory");
+ p.put("java.naming.provider.url", "ejbd://localhost:4201");
+ // user and pass optional
+ p.put("java.naming.security.principal", "myuser");
+ p.put("java.naming.security.credentials", "mypass");
+
+ InitialContext ctx = new InitialContext(p);
+
+ MyBean myBean = (MyBean) ctx.lookup("MyBeanRemote");
+
+## Changing the Cipher Suite
+[This is a pending feature](https://issues.apache.org/jira/browse/OPENEJB-1856)
+By default, the ejbds protocol connects with SSL_DH_anon_WITH_RC4_128_MD5. That means your connection is encrypted and the integrity of the transmission is verified. However, this only protects your from eavesdroppers, it offers absolutely zero protection from Man in the Middle attacks. This sort of attack could be pulled off without your knowledge and the attacker has the ability to intercept, monitor, and even modify your messages. If the attacker could control a router on your connection path, this attack could be trivially pulled off with nothing more but the OpenEJB server and client.
+
+To secure your connections against this sort of attack, your client can cryptographically prove it's talking to the correct server before sending any data. To do this, simply select one or more secure cipher suites that your J2SE provider supports from [this listing](http://docs.oracle.com/cd/E19728-01/820-2550/cipher_suites.html).
+
+You must now instruct the client and server to use that suite.
+
+On the server:
+
+ server = org.apache.openejb.server.ejbd.EjbServer
+ bind = 127.0.0.1
+ port = 4203
+ disabled = false
+ threads = 200
+ backlog = 200
+ secure = true
+ enabledCipherSuites = TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA
+ discovery = ejb:ejbds://{bind}:{port}
+
+On the client, you must supply a property:
+
+ -Dopenejb.client.enabledCipherSuites=TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA
+
+The final piece is to make sure your server has available a private certificate that the the client can trust. This can be certificate from an authority or a self signed certificate. The javax.net.ssl.trustStore and javax.net.ssl.keyStore JVM properties [are used to set this up.](http://fusesource.com/docs/broker/5.3/security/SSL-SysProps.html)
+
+
+ [1]: http://tomcat.apache.org/tomcat-7.0-doc/config/http.html
+ [2]: http://docs.oracle.com/javase/1.4.2/docs/guide/plugin/developer_guide/faq/troubleshooting.html
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-ref.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-ref.mdtext b/docs/ejb-ref.mdtext
new file mode 100644
index 0000000..01b9c3b
--- /dev/null
+++ b/docs/ejb-ref.mdtext
@@ -0,0 +1,47 @@
+Title: ejb-ref
+<a name="ejb-ref-Viaannotation"></a>
+# Via annotation
+
+ package org.superbiz.refs;
+
+ import javax.ejb.EJB;
+ import javax.ejb.Stateless;
+ import javax.naming.InitialContext;
+
+ @Stateless
+ @EJB(name = "myFooEjb", beanInterface = FooRemote.class)
+ public class MyEjbRemoteRefBean implements MyBeanInterface {
+
+ @EJB
+ private BarRemote myBarEjb;
+
+ public void someBusinessMethod() throws Exception {
+ if (myBarEjb == null) throw new NullPointerException("myBarEjb not injected");
+
+ // Both can be looked up from JNDI as well
+ InitialContext context = new InitialContext();
+ FooRemote fooRemote = (FooRemote) context.lookup("java:comp/env/myFooEjb");
+ BarRemote barRemote = (BarRemote) context.lookup("java:comp/env/org.superbiz.refs.MyEjbRemoteRefBean/myBarEjb");
+ }
+ }
+
+
+<a name="ejb-ref-Viaxml"></a>
+# Via xml
+
+The above @EJB annotation usage is 100% equivalent to the following xml.
+
+ <ejb-ref>
+ <ejb-ref-name>myFooEjb</ejb-ref-name>
+ <remote>org.superbiz.refs.FooRemote</remote>
+ </ejb-ref>
+ <ejb-ref>
+
+ <ejb-ref-name>org.superbiz.refs.MyEjbRemoteRefBean/myBarEjb</ejb-ref-name>
+ <remote>org.superbiz.refs.BarRemote</remote>
+ <injection-target>
+ <injection-target-class>org.superbiz.refs.MyEjbRemoteRefBean</injection-target-class>
+ <injection-target-name>myBarEjb</injection-target-name>
+ </injection-target>
+ </ejb-ref>
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-refs.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-refs.mdtext b/docs/ejb-refs.mdtext
new file mode 100644
index 0000000..c60c634
--- /dev/null
+++ b/docs/ejb-refs.mdtext
@@ -0,0 +1,174 @@
+Title: EJB Refs
+
+TomEE complains it doesn't know the container type, so I added type="javax.naming.InitialContext" and it worked (mostly).
+<a name="EJBRefs-Referencingabeaninanotherjar(withannotations)"></a>
+## Referencing a bean in another jar (with annotations)
+
+When using annotations to reference a bean from another ejb in your ear you
+have to supplement the @EJB reference with a small chunk of xml in the
+ejb-jar.xml of the referring bean.
+
+So in ejb app A colorsApp.jar you have this bean:
+
+
+ package com.foo.colors;
+
+ import javax.ejb.Stateless;
+
+ @Stateless
+ public class OrangeBean implements OrangeRemote {
+ }
+
+
+Then in ejb app B shapesApp.jar you have this bean with a reference to
+OrangeRemote:
+
+
+ package com.foo.shapes;
+
+ import javax.ejb.Stateless;
+ import com.foo.colors.OrangeRemote;
+
+ @Stateless
+ public class SquareBean implements SquareRemote {
+ @EJB OrangeRemote orangeRemote;
+ }
+
+
+To hook this reference up you need to override this ref and add more info
+in the ejb-jar.xml of shapesApp.jar as follows:
+
+
+ <ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+ </ejb-jar>
+
+
+<a name="EJBRefs-Referencingabeaninanotherjar(xmlonly,noannotations)"></a>
+## Referencing a bean in another jar (xml only, no annotations)
+
+The same basic approach applies and dependency injection is still possible,
+however more information must be described in the xml.
+
+
+In ejb app A colorsApp.jar you have this bean:
+
+
+ package com.foo.colors;
+
+ import javax.ejb.Stateless;
+
+ @Stateless
+ public class OrangeBean implements OrangeRemote {
+ }
+
+
+Then in ejb app B shapesApp.jar -- note there is no @EJB annotation:
+
+
+ package com.foo.shapes;
+
+ import javax.ejb.Stateless;
+ import com.foo.colors.OrangeRemote;
+
+ @Stateless
+ public class SquareBean implements SquareRemote {
+ OrangeRemote orangeRemote;
+ }
+
+
+Here's how you would hook this reference up, injection and all, with just
+xml. The following would be added to the ejb-jar.xml of shapesApp.jar:
+
+
+ <ejb-jar>
+ <enterprise-beans>
+
+ <session>
+ <ejb-name>SquareBean</ejb-name>
+ <ejb-ref>
+ <ejb-ref-name>com.foo.shapes.SquareBean/orangeRemote</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <remote>com.foo.colors.OrangeRemote</remote>
+ <ejb-link>colorsApp.jar#OrangeBean</ejb-link>
+ <injection-target>
+ <injection-target-class>com.foo.shapes.SquareBean</injection-target-class>
+ <injection-target-name>orangeRemote</injection-target-name>
+ </injection-target>
+ </ejb-ref>
+ </session>
+
+ </enterprise-beans>
+ </ejb-jar>
+
+
+Note that the value of <ejb-ref-name> could actually be anything and the
+above example would still work as there is no annotation that needs to
+match the <ejb-ref-name> and no one will likely be looking up the EJB as
+it's injected.
+
+# Referencing a bean in another server
+
+As of OpenEJB 4.0.0-beta-3, server to server references work.
+
+First we need to configure and name the InitialContext that will be used to satisfy the lookup to the other server.
+
+In this example we are calling our InitialContext `shoe` for fun.
+
+ <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+ <openejb>
+
+ <JndiProvider id="shoe" type="javax.naming.InitialContext">
+ java.naming.provider.url = ejbd://localhost:4201
+ java.naming.factory.initial = org.apache.openejb.client.RemoteInitialContextFactory
+ </JndiProvider>
+
+ </openejb>
+
+Declaring the `@EJB` reference is then done using a `mappedName` that references the named `InitialContext`
+
+ public class BlueBean implements BlueRemote {
+
+ @EJB(mappedName = "jndi:ext://shoe/OrangeBeanRemote")
+ private OrangeRemote orangeRemote;
+
+ public void hasOrangeRemote() {
+ Assert.assertNotNull("orangeRemote is null", orangeRemote);
+ assertEquals("olleh", orangeRemote.echo("hello"));
+ }
+ }
+
+Specifically, the `mappedName` syntax is as follows:
+
+ - jndi:ext://`<contextId>`/`<jndiName>`
+
+
+## Referencing a bean in "many" servers
+
+Note the above also works with the various forms of failover that TomEE supports.
+
+If say, there are two servers that have the `OrangeBeanRemote` bean, you could expand the `<JndiProvider>` delcaration like so:
+
+ <JndiProvider id="shoe" type="javax.naming.InitialContext">
+ java.naming.provider.url = failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201
+ java.naming.factory.initial = org.apache.openejb.client.RemoteInitialContextFactory
+ </JndiProvider>
+
+In the event that the `ejbd://192.168.1.20:4201` server cannot be contacted, the second server will be tried.
+
+This sort of arangement can also happen dynamicall against a list of servers that continuously grows and shrinks. The server list is maintained behind
+the scenes using server discovery logic that can function on either UDP or TCP. See these docs for more details on Failover and Discovery:
+
+ - [Multicast Discovery (UDP)](multicast-discovery.html)
+ - [Multipulse Discovery (TCP)](multipulse-discovery.html)
+ - [Multipoint Discovery (TCP)](multipoint-discovery.html)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/ejb-request-logging.mdtext
----------------------------------------------------------------------
diff --git a/docs/ejb-request-logging.mdtext b/docs/ejb-request-logging.mdtext
new file mode 100644
index 0000000..76e8695
--- /dev/null
+++ b/docs/ejb-request-logging.mdtext
@@ -0,0 +1,94 @@
+Title: EJB Request Logging
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Both client-side and server-side request logging is supported and includes various invocation times aimed at helping to identify where time
+is going in a request.
+
+## Client-side
+
+On the client requests/responses are logged on java.util.logging `FINEST` level in category `OpenEJB.client`. The code is similar to the following:
+
+ final long time = System.nanoTime() - start;
+ final String message = String.format("Invocation %sns - %s - Request(%s) - Response(%s)", time, conn.getURI(), req, res);
+ logger.log(Level.FINEST, message);
+
+Note that the check to see if FINEST is enabled is cached for performance reasons, so it must be set at VM startup.
+
+## Server-side
+
+On the server requests/responses are logged in java.util.logging `FINE` in category`"OpenEJB.server.remote.ejb`. The code for that
+is similar to this:
+
+ logger.fine("EJB REQUEST: " + req + " -- RESPONSE: " + res);
+
+## Request times
+
+Three times are tracked per request and logged in the above statements as part of the formatting of the EJB Response. They're best understood in reverse:
+
+ - **Container time** -- this is the raw time of invoking the bean including its
+interceptors and any transaction begin/commit time. This time is effectively "business logic".
+ - **Server time** -- this timer starts the (nano)second the request is seen by the server and
+ the (nano)second the response is actually written. The serverTime minus the containerTime will
+effectively show you how long serialization and deserialization is taking pre request.
+ - **Client time** -- entire begin to end including attempting to contact the server and fully reading the response. The clientTime minus the serverTime will show network latency for the most part.
+
+The container time and server time are written in the EJB response and visible to the client. The client will log all three times, the server will log the first two. All log statements are on a single line.
+
+## Bean-time and JMX Statistics
+
+The above information applies purely to remote EJB calls made over a network. Calls on `@Remote` or `@Local` interfaces between two components in the same server are not logged.
+
+However, **all** EJB invocations to business methods *or* callbacks like `@PostConstruct` are tracked for statistical analysis.
+By default a floating window of 2000 samples are kept. The time tracked is purely **bean time** which includes
+interceptors, decorators and the bean itself, but does not include other container services like transactions or security.
+
+This information is available in JMX. A sample JMX ObjectName for a `CounterBean` will look like this:
+
+ openejb.management:J2EEServer=openejb,J2EEApplication=null,EJBModule=StatsModule,StatelessSessionBean=CounterBean,j2eeType=Invocations,name=CounterBean
+
+All beans have the following MBean attributes, listed here in shorthand:
+
+ * javax.management.MBeanAttributeInfo[description=, name=InvocationCount, type=long, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=InvocationTime, type=long, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=MonitoredMethods, type=long, read-only, descriptor={}]
+ * javax.management.MBeanOperationInfo[description=, name=FilterAttributes, returnType=void, signature=[javax.management.MBeanParameterInfo[description="", name=excludeRegex, type=java.lang.String, descriptor={}], javax.management.MBeanParameterInfo[description="", name=includeRegex, type=java.lang.String, descriptor={}]], impact=unknown, descriptor={}]
+
+Then for every method there will be these attributes and operations:
+
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Count, type=long, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().GeometricMean, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Kurtosis, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Max, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Mean, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Min, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile01, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile10, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile25, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile50, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile75, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile90, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Percentile99, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().SampleSize, type=int, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Skewness, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().StandardDeviation, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Sum, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Sumsq, type=double, read-only, descriptor={}]
+ * javax.management.MBeanAttributeInfo[description=, name=someMethod().Variance, type=double, read-only, descriptor={}]
+ * javax.management.MBeanOperationInfo[description=, name=someMethod().setSampleSize, returnType=void, signature=[javax.management.MBeanParameterInfo[description=, name=p1, type=int, descriptor={}]], impact=unknown, descriptor={}]
+ * javax.management.MBeanOperationInfo[description=, name=someMethod().sortedValues, returnType=[D, signature=[], impact=unknown, descriptor={}]
+ * javax.management.MBeanOperationInfo[description=, name=someMethod().values, returnType=[D, signature=[], impact=unknown, descriptor={}]