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:33 UTC
[18/20] tomee git commit: Docs old and new
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/admin/file-layout.adoc
----------------------------------------------------------------------
diff --git a/docs/admin/file-layout.adoc b/docs/admin/file-layout.adoc
new file mode 100755
index 0000000..433fea3
--- /dev/null
+++ b/docs/admin/file-layout.adoc
@@ -0,0 +1,144 @@
+= Directory Structure
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+ifndef::backend-pdf[]
+
+[#filetree.col-md-4]
+[
+ {
+ label: 'apps',
+ description: 'A common but optional folder containing the applications (war, ear, jar). Note: this folder needs to be activated in tomee.xml for instance and is not there by default.',
+ children: [
+ {label:'module1.jar',description:'An ejbmodule'},
+ {label:'myapp',description:'An exploded war or ear'},
+ {label:'anotherapp.war',description:'A war'},
+ {label:'anotherapp',description:'By default TomEE will explode the war next to the .war file, this is customizable.'},
+ {label:'anotherapp2.ear',description:'An ear'},
+ {label:'anotherapp2',description:'By default TomEE will explode the ear next to the .ear file, this is customizable.'}
+ ]
+ },
+ {
+ label: 'bin',
+ description: 'The executable and boot related files',
+ children: [
+ {label:'bootstrap.jar',description:'The jar allowing Tomcat to start'},
+ {label:'catalina.bat',description:'The windows main Tomcat script'},
+ {label:'catalina.bat.original',description:'The original catalina.bat from Tomcat. TomEE customizes it.'},
+ {label:'catalina.sh',description:'The UNIx main Tomcat script'},
+ {label:'catalina.sh.original',description:'The original catalina.sh from Tomcat. TomEE customizes it.'},
+ {label:'catalina-tasks.xml',description:'Some Ant tasks Tomcat provides to work with JMX'},
+ {label:'commons-daemon.jar',description:'When setting up TomEE as a service you need this jar.'},
+ {label:'commons-daemon-native.tar.gz',description:'The native needed by commons-daemon'},
+ {label:'configtest.bat',description:'A windows script to validate the server.xml'},
+ {label:'configtest.sh',description:'A UNIx script to validate the server.xml'},
+ {label:'daemon.sh',description:'A script which can be used as init.d script'},
+ {label:'digest.bat',description:'A windows script to compute a digest'},
+ {label:'digest.sh',description:'A UNIx script to compute a digest'},
+ {label:'service.bat',description:'The windows service script'},
+ {label:'service.install.as.admin.bat',description:'Install TomEE as a service on windows'},
+ {label:'service.readme.txt',description:'The explanations on how to setup TomEE as a windows service'},
+ {label:'service.remove.as.admin.bat',description:'Uninstall TomEE service on windows'},
+ {label:'setclasspath.bat',description:'The script called by catalina.bat to initialize Tomcat classpath'},
+ {label:'setclasspath.sh',description:'The script called by catalina.bat to initialize TomEE classpath'},
+ {label:'setenv.sh',description:'A UNIx user script (optional) where you can specify some JVM options like CATALINA_OPTS environment variable'},
+ {label:'setenv.bat',description:'A windows user script (optional) where you can specify some JVM options like CATALINA_OPTS environment variable'},
+ {label:'shutdown.bat',description:'Stop the server on windows, it is commonly used with -force and a timeout as options'},
+ {label:'shutdown.sh',description:'Stop the server on UNIx, it is commonly used with -force and a timeout as options'},
+ {label:'startup.bat',description:'Start (and forget) TomEE on windows'},
+ {label:'startup.sh',description:'Start (and forget) TomEE on UNIx'},
+ {label:'tomcat-juli.jar',description:'The Tomcat Java Util Logging extensions which allow for instance to configure the logging per application'},
+ {label:'tomcat-native.tar.gz',description:'The Tomcat native used by some connectors'},
+ {label:'TomEE....exe',description:'TomEE windows executables when setup as a service for amd64 architectures'},
+ {label:'tomee.bat',description:'TomEE utility script for windows, allows to compute ciphers for instance'},
+ {label:'tomee.sh',description:'TomEE utility script for UNIx, allows to compute ciphers for instance'},
+ {label:'tool-wrapper.bat',description:'Windows script calling Tomcat Tool utility. It executes a command line with Tomcat classloader.'},
+ {label:'tool-wrapper.sh',description:'UNIx script calling Tomcat Tool utility. It executes a command line with Tomcat classloader.'},
+ {label:'version.bat',description:'Print Tomcat version (for windows)'},
+ {label:'version.sh',description:'Print Tomcat version (for UNIx)'}
+ ]
+ },
+ {
+ label: 'conf',
+ description: 'Folder containing the configuration of TomEE',
+ children: [
+ {label:'Catalina',description:'A folder where Tomcat can copy web application configuration (typically context.xml can be overriden from there)'},
+ {label:'catalina.policy',description:'The server security policy rules'},
+ {label:'catalina.properties',description:'The server boot configuration (classloader etc...)'},
+ {label:'conf.d',description:'A TomEE folder where services can pick configuration'},
+ {label:'context.xml',description:'The default context.xml configuration'},
+ {label:'logging.properties',description:'The logging configuration for the server and applications (overridable)'},
+ {label:'server.xml',description:'The server configuration (Host, Context, Valves, ...)'},
+ {label:'server.xml.original',description:'The original server.xml, TomEE updates it to add its lifecycle manager.'},
+ {label:'system.properties',description:'TomEE global configuration'},
+ {label:'tomcat-users.xml',description:'The default location where tomcat stores users.'},
+ {label:'tomcat-users.xml.original',description:'The Tomcat tomcat-users.xml (TomEE add comments)'},
+ {label:'tomcat-users.xsd',description:'The XSD for tomcat-users.xml'},
+ {label:'tomee.xml',description:'The TomEE configuration file, syntax is hybrid between XML and Properties and it is fully replaceable with system.properties but users generally prefer this file.'},
+ {label:'web.xml',description:'The default web.xml'}
+ ]
+ },
+ {
+ label: 'lib',
+ description: 'Folder containing TomEE binaries',
+ children: [
+ {label:'*.jar',description:'Tomcat + TomEE libraries'}
+ ]
+ },
+ {
+ label: 'logs',
+ description: 'Default location of log files',
+ children: [
+ {label:'catalina.$day.log',description:'By default container logs go there'},
+ {label:'xxx.2016-03-16.log',description:'By default application xxx logs go there (when using servlet API)'},
+ {label:'localhost.$day.log',description:'By default host related logs go there'},
+ {label:'localhost_access_log.$day.txt',description:'By default access logs (request the container processed) go there'}
+ ]
+ },
+ {
+ label: 'temp',
+ description: 'Java temporary directory is redirected by default to this folder',
+ children: [
+ {label:'OpenEJB-dejlzdbhjzbfrzeofrh',description:'A temporary file TomEE can create (suffix depends the startup) to check the instance'}
+ ]
+ },
+ {
+ label: 'webapps',
+ description: 'Folder containing the web applications',
+ children: [
+ {label:'myapp',description:'An exploded war'},
+ {label:'anotherapp.war',description:'A war'},
+ {label:'anotherapp',description:'By default TomEE will explode the war next to the .war file, this is customizable.'}
+ ]
+ },
+ {
+ label: 'work',
+ description: 'Folder where Tomcat and TomEE can work',
+ children: [
+ {
+ label:'Catalina',description:'By default Tomcat Engine is called Catalina. This folder matches engine name.',
+ children: [
+ {
+ label:'localhost',description:'A folder by host by engine to seggregate data of each ones',
+ children: [
+ {
+ label:'myapp',description:'An application deployed on the previous level host',
+ children: [
+ { label:'org.apache.jsp.index_jsp.java',description:'The generated JSP source (index.jsp there)' },
+ { label:'org.apache.jsp.index_jsp.class',description:'The compiled JSP binary' }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
+
+[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
+Click on a tree node or open a folder to see the detail there.
+
+endif::[]
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/admin/index.adoc
----------------------------------------------------------------------
diff --git a/docs/admin/index.adoc b/docs/admin/index.adoc
new file mode 100755
index 0000000..9c10d63
--- /dev/null
+++ b/docs/admin/index.adoc
@@ -0,0 +1,7 @@
+= Administrator
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+Click link:../docs.html[here] to find the documentation for administrators.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/.DS_Store
----------------------------------------------------------------------
diff --git a/docs/advanced/.DS_Store b/docs/advanced/.DS_Store
new file mode 100644
index 0000000..2718e5f
Binary files /dev/null and b/docs/advanced/.DS_Store differ
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/applicationcomposer/index.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/applicationcomposer/index.adoc b/docs/advanced/applicationcomposer/index.adoc
new file mode 100755
index 0000000..50390cc
--- /dev/null
+++ b/docs/advanced/applicationcomposer/index.adoc
@@ -0,0 +1,76 @@
+= ApplicationComposer with JBatch
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+ApplicationComposer can be a way to run a JBatch not needing any HTTP connector.
+
+Here is an example making batch integration easy - note you can extract the generic part in a library very easily:
+
+TIP: if you didn't check yet BatchEE provides some standalone utilities for JBatch but the idea of this page can be reused for a lot of applications.
+
+[source,java]
+----
+// helper class reusable for any batch
+abstract class BatchApplication {
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("YYYYMMddHHmmss");
+
+ protected Report runBatch(final String batchName, final Properties config) {
+ final JobOperator operator = BatchRuntime.getJobOperator();
+ final long id = operator.start(batchName, config);
+ Batches.waitForEnd(operator, id);
+ return new Report(operator.getJobExecution(id), operator.getParameters(id));
+ }
+
+ @Module // we enforce BatchEE to be initialized as an EJB context to get JNDI for JTA init, needed for TomEE 1
+ public EjbModule ensureBatchEESetupIsDoneInTheRightContext() {
+ final EjbJar ejbJar = new EjbJar().enterpriseBean(new SingletonBean(BatchEEBeanManagerInitializer.class));
+
+ final Beans beans = new Beans();
+ beans.addManagedClass(BatchEEBeanManagerInitializer.Init.class);
+
+ final EjbModule ejbModule = new EjbModule(ejbJar);
+ ejbModule.setModuleId("batchee-shared-components");
+ ejbModule.setBeans(beans);
+ return ejbModule;
+ }
+
+ public static class Report {
+ private final JobExecution execution;
+ private final Properties properties;
+
+ public Report(final JobExecution execution, final Properties properties) {
+ this.execution = execution;
+ this.properties = properties;
+ }
+
+ public JobExecution getExecution() {
+ return execution;
+ }
+
+ public Properties getProperties() {
+ return properties;
+ }
+ }
+}
+
+@Classes(cdi = true, value = { MyFilter.class, MoveFile.class, InputFile.class, MyReader.class, LoggingListener.class })
+public class MyBatch extends BatchApplication {
+ private final Properties config;
+
+ public Mybatch(final String[] args) { // main args
+ this.config = new Properties() {{ // create the batch config
+ setProperty("input-directory", args[0]);
+ }};
+ }
+
+ public Report execute(final String inputDirectory) {
+ return runBatch("sunstone", config);
+ }
+
+ public static void main(final String[] args) throws Exception {
+ ApplicationComposers.run(MyBatch.class, args);
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/client/jndi.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/client/jndi.adoc b/docs/advanced/client/jndi.adoc
new file mode 100644
index 0000000..a6e461a
--- /dev/null
+++ b/docs/advanced/client/jndi.adoc
@@ -0,0 +1,116 @@
+== Java Naming and Directory Interface (JNDI)
+:jbake-date: 2016-10-14
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE has several JNDI client intended for multiple usages.
+
+== Default one
+
+In a standalone instance you generally don't need (or want) to specify anything
+to do a lookup. Doing so you will inherit from the contextual environment:
+
+[source,java]
+----
+final Context ctx = new InitialContext();
+ctx.lookup("java:....");
+----
+
+== LocalInitialContextFactory
+
+This is the legacy context factory used by OpenEJB. It is still useful to fallback
+on the "default" one in embedded mode where sometimes classloaders or libraries can mess
+up the automatic conextual context.
+
+Usage:
+
+[source,java]
+----
+Properties properties = new Properties();
+properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory");
+final Context ctx = new InitialContext(properties);
+ctx.lookup("java:....");
+----
+
+This context factory supports few more options when *you boot the container* creating a context:
+
+|===
+| Name | Description
+| openejb.embedded.remotable | true/false: starts embedded services
+| Context.SECURITY_PRINCIPAL/Context.SECURITY_CREDENTIALS | the *global* security identity for the whole container
+|===
+
+IMPORTANT: `Context.SECURITY_*` shouldn't be used for runtime lookups with `LocalInitialContextFactory`, it would leak a security identity and make the runtime no more thread safe.
+This factory was deprecated starting with 7.0.2 in favor of `org.apache.openejb.core.OpenEJBInitialContextFactory`.
+
+== OpenEJBInitialContextFactory
+
+This factory allows you to access local EJB and container resources.
+
+[source,java]
+----
+Properties properties = new Properties();
+properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.OpenEJBInitialContextFactory");
+final Context ctx = new InitialContext(properties);
+ctx.lookup("java:....");
+----
+
+== RemoteInitialContextFactory
+
+Intended to be used to contact a remote server, the `org.apache.openejb.client.RemoteInitialContextFactory` relies on the provider url
+to contact a tomee instance:
+
+[source,java]
+----
+Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory");
+p.put(Context.PROVIDER_URL, "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201");
+
+final InitialContext remoteContext = new InitialContext(p);
+ctx.lookup("java:....");
+----
+
+Contrarly to local one, the remote factory supports `Context.SECURITY_*` options in a thread safe manner and you can do lookups at runtime using them.
+
+See link:../../admin/cluster/index.html[Cluster] page for more details on the options.
+
+=== Security
+
+The context configuration can take additional configuration to handle EJB security:
+
+[source]
+----
+p.put("openejb.authentication.realmName", "my-realm"); // optional
+p.put(Context.SECURITY_PRINCIPAL, "alfred");
+p.put(Context.SECURITY_CREDENTIALS, "bat");
+----
+
+The realm will be used by JAAS to get the right LoginModules and principal/credentials to
+do the actual authentication.
+
+==== HTTP case
+
+Often HTTP layer is secured and in this case you need to authenticate before the EJBd (remote EJB TomEE protocol) layer.
+Thanks to TomEE/Tomcat integration login there will propagate to the EJBd context.
+
+This can be done passing the token you need to set as `Authorization` header in the `PROVIDER_URL`:
+
+[source]
+----
+// tomee/openejb principal/credentials
+p.put(Context.PROVIDER_URL, "http://localhost:8080/tomee/ejb?authorization=Basic%20dG9tZWU6b3BlbmVqYg==");
+----
+
+The token passed as `authorization` query parameter is the header value URL encoded. It can
+be any token like a basic one, a custom one, an OAuth2 one (in this case you need to renew it programmatically
+and change your client instance when renewing) etc...
+
+TIP: basic being very common there is a shortcut with two alternate query parameter replacing `authorization` one: `basic.password` and `basic.username`.
+
+Finally if you don't use `Authorization` header you can change the used header setting `authorizationHeader` query parameter.
+
+NOTE: `authorization`, `authorizationHeader`, `basic.username`, and `basic.password` are removed
+from the URL before opening the connection and therefore not logged in the remote server access log since version 7.0.3.
+
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/index.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/index.adoc b/docs/advanced/index.adoc
new file mode 100755
index 0000000..7928b61
--- /dev/null
+++ b/docs/advanced/index.adoc
@@ -0,0 +1,7 @@
+= Advanced
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+Click link:../docs.html[here] to find advanced documentation.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/jms/jms-configuration.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/jms/jms-configuration.adoc b/docs/advanced/jms/jms-configuration.adoc
new file mode 100644
index 0000000..701b1dd
--- /dev/null
+++ b/docs/advanced/jms/jms-configuration.adoc
@@ -0,0 +1,67 @@
+= Why is my ActiveMQ/JMS MDB not scaling as expected?
+:jbake-date: 2017-02-22
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+==== Why my ActiveMQ/JMS MDB is not scaling as expected?
+
+There are multiple configurations points to ensure you scale as much as you want.
+
+Here some common configuration to validate (note that when possible the sample value is the default):
+
+- The resource adapter thread pool ("worker threads" or `WorkManager`) limits the number of max work threads:
+
+[source,xml]
+----
+<Resource id="my resource adapter" ....>
+ # using -1 will make the server using cached threads (unbounded)
+ # min recommanded: maxSessions + 1 (for connect())
+ threadPoolSize = 30
+</Resource>
+----
+
+- Then the MDB container itself has a upper bound through `InstanceLimit` which controls the max MDB instance count:
+
+[source,xml]
+----
+<Container id="my mdb container" type="MESSAGE">
+ # -1 will disable it
+ # min recommanded = maxSessions
+ InstanceLimit = 10
+</Container>
+----
+
+- ActiveMQ `maxSessions` controls how many sessions a MDB can use:
+
+[source,java]
+----
+@MessageDriven(activationConfig = {
+ @javax.ejb.ActivationConfigProperty(propertyName = "maxSessions", propertyValue = "1"),
+ @javax.ejb.ActivationConfigProperty(propertyName = "destination", propertyValue = "target-queue")
+})
+public static class MyMdb implements MessageListener {
+ @Override
+ public void onMessage(final Message message) {
+ // ...
+ }
+}
+----
+
+- The ConnectionFactory has also an instance pool through geronimo-connector logic, configuration
+ can make the behavior changing but this is controlled through pool related variables (the pool and resource properties are merged in the definition):
+
+[source,xml]
+----
+<Resource id="my connection factory" type="ConnectionFactory">
+ # recommanded to be aligned on maxSessions
+ PoolMaxSize = 10
+ # for 100% MDB (no client) you can evaluate to turn it off/false, for client it can still be useful depending what you do
+ Pooling = true
+</Resource>
+----
+
+==== Slow Message Consumption
+
+If you find you have a slow consumption of messages there are several options to have a look (activemq website explains it very well)
+but one very impacting option can be the prefetch size.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/setup/index.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/setup/index.adoc b/docs/advanced/setup/index.adoc
new file mode 100755
index 0000000..4fe684d
--- /dev/null
+++ b/docs/advanced/setup/index.adoc
@@ -0,0 +1,142 @@
+= How to Setup TomEE in production
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+
+
+You can use TomEE as described on link:../../admin/directory-structure.html[Directory Structure] page but in production it is better to
+split TomEE and application binaries and configuration.
+
+Idea is to have this kind of layout (the root is the one you prefer):
+
+ifndef::backend-pdf[]
+
+[#filetree.col-md-4]
+[{
+ label: '/some/path',
+ description: 'any location on your file system',
+ children: [
+ {
+ label: 'tomee',
+ description: 'all tomee binaries will be there, note: you often do the same for the JVM versions you have',
+ children: [
+ {
+ label: 'tomee-1.7.1',
+ description: 'a particular tomee version (just unzip it there)',
+ children: [
+ { label: 'bin', description: 'the startup binaries/scripts' },
+ { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' },
+ { label: 'lib', description: 'the binaries' }
+ ]
+ },
+ {
+ label: 'tomee-1.7.2',
+ description: 'a particular tomee version (just unzip it there)',
+ children: [
+ { label: 'bin', description: 'the startup binaries/scripts' },
+ { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' },
+ { label: 'lib', description: 'the binaries' }
+ ]
+ },
+ {
+ label: 'tomee-7.0.0-M3',
+ description: 'a particular tomee version (just unzip it there)',
+ children: [
+ { label: 'bin', description: 'the startup binaries/scripts' },
+ { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' },
+ { label: 'lib', description: 'the binaries' }
+ ]
+ }
+ ]
+ },
+ {
+ label: 'applications',
+ description: 'all applications',
+ children: [
+ {
+ label: 'application1',
+ description: 'any application instance (ie configuration + binaries)',
+ children: [
+ { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' },
+ { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' },
+ { label: 'lib', description: 'some additional binaries like JDBC drivers' },
+ { label: 'logs', description: 'instances logs location' },
+ { label: 'work', description: 'dedicated work directory' },
+ { label: 'temp', description: 'instance temporary folder' },
+ { label: 'webapps', description: 'instance webapp folder' }
+ ]
+ },
+ {
+ label: 'application2',
+ description: 'any application instance (ie configuration + binaries)',
+ children: [
+ { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' },
+ { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' },
+ { label: 'lib', description: 'some additional binaries like JDBC drivers' },
+ { label: 'logs', description: 'instances logs location' },
+ { label: 'work', description: 'dedicated work directory' },
+ { label: 'temp', description: 'instance temporary folder' },
+ { label: 'webapps', description: 'instance webapp folder' }
+ ]
+ }
+ ]
+ }
+ ]
+}]
+
+
+[#filetreedetail.col-md-8.bs-callout.bs-callout-primary]
+Click on a tree node or open a folder to see the detail there.
+
+[.clearfix]
+
+
+endif::[]
+
+=== Instance scripts
+
+The idea for instances (applications) scripts is to simply delegate to tomcat ones but customizing the JVM and TomEE versions.
+
+Customizing the version (and locations) is done in `bin/setenv.sh` of instances.
+
+Here are an example for the common scripts (of course you can write helper version like restart etc).
+
+==== setenv.sh
+
+[source,bash]
+----
+#! /bin/sh
+
+# which java
+export JAVA_HOME="/some/path/java/jdk-8u60"
+# which tomee
+export CATALINA_HOME="/some/path/tomee/tomee-7.0.0-M3"
+# where is the application - to let tomcat/tomee finds the configuration
+export CATALINA_BASE="/some/path/application1/"
+# to let tomee be able to kill the instance if shutdown doesn't work (see shutdown script)
+export CATALINA_PID="/some/path/application1/work/tomee.pid"
+----
+
+==== startup
+
+[source,bash]
+----
+#! /bin/bash
+
+proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
+source "$proc_script_base/bin/setenv.sh"
+nohup "$CATALINA_HOME/bin/startup.sh" "$@" > $proc_script_base/logs/nohup.log &
+----
+
+==== shutdown
+
+[source,bash]
+----
+#! /bin/bash
+
+proc_script_base="`cd $(dirname $0) && cd .. && pwd`"
+source "$proc_script_base/bin/setenv.sh"
+# we support parameters like timeout and force, typically we would call it this way: ./shutdown 1200 -force
+"$CATALINA_HOME/bin/shutdown.sh" "$@"
+----
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/shading/index.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/shading/index.adoc b/docs/advanced/shading/index.adoc
new file mode 100755
index 0000000..fc4b18a
--- /dev/null
+++ b/docs/advanced/shading/index.adoc
@@ -0,0 +1,276 @@
+= Fat / Uber jars - Using the Shade Plugin
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+Shading the container and the application has some challenges like merging correctly resources (`META-INF/services/` typically).
+
+Here is a maven shade plugin configuration working for most cases:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-shade-plugin</artifactId>
+ <version>2.3</version>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>shade</goal>
+ </goals>
+ <configuration>
+ <dependencyReducedPomLocation>${project.build.directory}/reduced-pom.xml</dependencyReducedPomLocation>
+ <transformers>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+ <mainClass>org.apache.tomee.embedded.FatApp</mainClass>
+ </transformer>
+ <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
+ <resource>META-INF/cxf/bus-extensions.txt</resource>
+ </transformer>
+ <transformer implementation="org.apache.openwebbeans.maven.shade.OpenWebBeansPropertiesTransformer" />
+ </transformers>
+ <filters>
+ <filter> <!-- we don't want JSF to be activated -->
+ <artifact>*:*</artifact>
+ <excludes>
+ <exclude>META-INF/faces-config.xml</exclude>
+ </excludes>
+ </filter>
+ </filters>
+ </configuration>
+ </execution>
+ </executions>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.openwebbeans</groupId>
+ <artifactId>openwebbeans-maven</artifactId>
+ <version>1.7.0/version>
+ </dependency>
+ </dependencies>
+</plugin>
+----
+
+NOTE: see link:../tomee-embedded/index.html[TomEE Embedded] page for more information about tomee embedded options.
+
+IMPORTANT: this shade uses TomEE Embedded but you can do the same with an link:../applicationcomposer/index.html[Application Composer] application.
+
+TIP: if you have `META-INF/web-fragment.xml` in your application you will need to merge them in a single one in the shade. Note that tomcat provides one
+which can be skipped in this operation since it is there only as a marker for jasper detection.
+
+Then just build the jar:
+
+[source,bash]
+----
+mvn clean package
+----
+
+And you can run it:
+
+[source,bash]
+----
+java -jar myapp-1.0-SNAPSHOT.jar
+----
+
+== Fat Jars with Gradle
+
+With gradle you can rely on either jar plugin, fatjar plugin or shadowjar plugin. Last one is likely the closer to maven shade plugin
+so that's the one used for next sample:
+
+[source,groovy]
+----
+// run $ gradle clean shadowJar
+import org.apache.openwebbeans.gradle.shadow.OpenWebBeansPropertiesTransformer
+
+buildscript {
+ repositories {
+ mavenLocal()
+ jcenter()
+ }
+ dependencies {
+ classpath 'com.github.jengelman.gradle.plugins:shadow:1.2.3'
+ classpath 'org.apache.openwebbeans:openwebbeans-gradle:1.7.0'
+ }
+}
+
+apply plugin: 'com.github.johnrengelman.shadow'
+
+group 'org.apache.tomee.demo.gradle'
+version '1.0-SNAPSHOT'
+
+apply plugin: 'idea'
+apply plugin: 'java'
+
+sourceCompatibility = 1.8
+
+repositories {
+ mavenLocal()
+ mavenCentral()
+}
+
+dependencies {
+ compileOnly 'org.projectlombok:lombok:1.16.10'
+ compile 'org.apache.tomee:tomee-embedded:7.0.2-SNAPSHOT'
+}
+
+// customize exclusions depending your app
+
+// first the not used dependencies like JSF, JAXWS, JMS ones
+def excludedDependenciesGroups = [
+ // gradle is buggy with poms, scope provided and optional I think
+ 'com.google.code.findbugs',
+ 'com.google.guava',
+ 'javax.annotation',
+ 'javax.ws.rs',
+ 'net.sf.ehcache',
+ 'org.apache.httpcomponents',
+ 'org.ow2.asm',
+ // tomee jaxws, jms, etc...
+ 'commons-codec',
+ 'com.sun.xml.messaging.saaj',
+ 'joda-time',
+ 'junit',
+ 'net.shibboleth.utilities',
+ 'org.apache.activemq',
+ 'org.apache.activemq.protobuf',
+ 'org.apache.myfaces.core',
+ 'org.apache.neethi',
+ 'org.apache.santuario',
+ 'org.apache.ws.xmlschema',
+ 'org.apache.wss4j',
+ 'org.bouncycastle',
+ 'org.cryptacular',
+ 'org.fusesource.hawtbuf',
+ 'org.jasypt',
+ 'org.jvnet.mimepull',
+ 'org.opensaml',
+ 'wsdl4j',
+ 'xml-resolver'
+]
+
+// then cxf+tomee specific dependencies so we need to be more precise than the group
+// to not exclude everything
+def excludedDependenciesArtifacts = [
+ 'cxf-rt-bindings-soap',
+ 'cxf-rt-bindings-xml',
+ 'cxf-rt-databinding-jaxb',
+ 'cxf-rt-frontend-jaxws',
+ 'cxf-rt-frontend-simple',
+ 'cxf-rt-security-saml',
+ 'cxf-rt-ws-addr',
+ 'cxf-rt-wsdl',
+ 'cxf-rt-ws-policy',
+ 'cxf-rt-ws-security',
+ 'openejb-cxf',
+ 'openejb-webservices',
+ 'tomee-webservices',
+ 'geronimo-connector',
+ 'geronimo-javamail_1.4_mail'
+]
+shadowJar {
+ classifier = 'bundle'
+
+ // merge SPI descriptors
+ mergeServiceFiles()
+ append 'META-INF/cxf/bus-extensions.txt'
+ transform(OpenWebBeansPropertiesTransformer.class)
+
+ // switch off JSF + JMS + JAXWS
+ exclude 'META-INF/faces-config.xml'
+ dependencies {
+ exclude(dependency {
+ excludedDependenciesGroups.contains(it.moduleGroup) ||
+ excludedDependenciesArtifacts.contains(it.moduleName)
+ })
+ }
+
+ // ensure we define the expected Main (if you wrap tomee main use your own class)
+ manifest {
+ attributes 'Main-Class': 'org.apache.tomee.embedded.FatApp'
+ }
+}
+----
+
+Then run:
+
+[source]
+----
+gradle clean build shadowJar
+----
+
+and you'll get `build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar` ready to run with:
+
+[source]
+----
+java -jar build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar --as-war --simple-log=true
+----
+
+== Fat Wars
+
+Fat Wars are executable wars. Note they can be fancy for demos but they have the drawback to put the server in web resources
+at packaging time (to ensure the war is actually an executable jar) so adding a filter preventing these files to be read
+can be needed if you don't already use a web technology doing it (a servlet bound to /*).
+
+Here how to do a fat war:
+
+[source,xml]
+----
+<properties>
+ <!-- can be uber (for all), jaxrs, jaxws for lighter ones -->
+ <tomee.flavor>uber</tomee.flavor>
+</properties>
+
+<dependencies>
+ <!-- ...your dependencies as usual... -->
+ <dependency>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>tomee-embedded</artifactId>
+ <classifier>${tomee.flavor}</classifier>
+ <version>7.0.0</version>
+ <scope>provided</scope>
+ </dependency>
+</dependencies>
+
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-war-plugin</artifactId>
+ <version>2.6</version>
+ <configuration>
+ <failOnMissingWebXml>false</failOnMissingWebXml>
+ <archive>
+ <manifest>
+ <mainClass>org.apache.tomee.embedded.Main</mainClass>
+ </manifest>
+ </archive>
+ <dependentWarExcludes />
+ <overlays>
+ <overlay>
+ <groupId>org.apache.tomee</groupId>
+ <artifactId>tomee-embedded</artifactId>
+ <classifier>${tomee.flavor}</classifier>
+ <type>jar</type>
+ <excludes />
+ </overlay>
+ </overlays>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>
+----
+
+Then just build the war:
+
+[source,bash]
+----
+mvn clean package
+----
+
+And you can run it:
+
+[source,bash]
+----
+java -jar myapp-1.0-SNAPSHOT.war
+----
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/advanced/tomee-embedded/index.adoc
----------------------------------------------------------------------
diff --git a/docs/advanced/tomee-embedded/index.adoc b/docs/advanced/tomee-embedded/index.adoc
new file mode 100755
index 0000000..8664ade
--- /dev/null
+++ b/docs/advanced/tomee-embedded/index.adoc
@@ -0,0 +1,223 @@
+= TomEE Embedded
+:jbake-date: 2016-03-16
+:jbake-type: page
+:jbake-status: published
+:jbake-tomeepdf:
+
+TomEE Embedded is based on Tomcat embedded and starts a real TomEE in the launching JVM. It is also
+able to deploy the classpath as a webapp and to use either `META-INF/resources` or a folder as web resources.
+
+Here is a basic programmatic usage based on `org.apache.tomee.embedded.Container` class:
+
+[source,java]
+----
+try (final Container container = new Container(new Configuration()).deployClasspathAsWebApp()) {
+ System.out.println("Started on http://localhost:" + container.getConfiguration().getHttpPort());
+
+ // do something or wait until the end of the application
+}
+----
+
+All EE features are then accessible directly in the same JVM.
+
+== TomEE Embedded Configuration
+
+The default configuration allows to start tomee without issue but you can desire to customize some of them.
+
+[.table.table-bordered,options="header"]
+|===
+| Name | Default | Description
+|httpPort | 8080| http port
+|stopPort | 8005| shutdown port
+|host |localhost| host
+|dir|-|where to create a file hierarchy for tomee (conf, temp, ...)
+|serverXml|-|which server.xml to use
+|keepServerXmlAsThis|false|don't adjust ports/host from the configuration and keep the ones in server.xml
+|properties|-|container properties
+|quickSession | true|use Random instead of SecureRandom (for dev)
+|skipHttp|false|don't use the http connector
+|httpsPort | 8443|https potr
+|ssl|false| activate https
+|withEjbRemote|false|use EJBd
+|keystoreFile|-|https keystore location
+|keystorePass|-|https keystore password
+|keystoreType |JKS|https keystore type
+|clientAuth|-|https client auth
+|keyAlias|-|https alias
+|sslProtocol|-|SSL protocol for https connector
+|webXml|-|default web.xml to use
+|loginConfig|-|which LoginConfig to use, relies on `org.apache.tomee.embedded.LoginConfigBuilder` to create it
+|securityConstraints|-|add some security constraints, use `org.apache.tomee.embedded.SecurityConstaintBuilder` to build them
+|realm|-|which realm to use (useful to switch to `JAASRealm` for instance) without modifying the application
+|deployOpenEjbApp|false|should internal openejb application be delpoyed
+|users|-|a map of user/password
+|roles|-|a map of role/users
+|tempDir|${java.io.tmpdir}/tomee-embedded_${timestamp}|tomcat needs a docBase, in case you don't provide one one will be created there
+|webResourceCached |true|should web resources be cached by tomcat (set false in frontend dev)
+|configuration-location|-|location (classpath or file) to a .properties to configure the server
+[pre-task|-|Runnable or org.apache.tomee.embedded.LifecycleTask implementations to execute before the container starts
+|classes-filter|-|implementation of a custom xbean Filter to ignore not desired classes during scanning
+|basic|-|set /* under BASIC authentication for the realm "Security", authentication role being "*"
+|===
+
+Note: passing to `Container` constructor a `Configuration` it will start the container automatically but using `setup(Configuration)`
+to initialize the configuration you will need to call `start()`.
+
+You can also pass through the properties `connector.xxx` and `connector.attributes.xxx` to customize connector(s)
+configuration directly.
+
+== Standalone applications or TomEE Embedded provided main(String[])
+
+Deploying an application in a server is very nice cause the application is generally small and it allows to update the
+container without touching the application (typically insanely important in case of security issues for instance).
+
+However sometimes you don't have the choice so TomEE Embedded provides a built-in `main(String[])`. Here are its options:
+
+NOTE: this is still a TomEE so all system properties work (for instance to create a resource).
+
+[.table.table-bordered,options="header"]
+|===
+|Name|Default|Description
+|--path|-|location of application(s) to deploy
+|--context|-|Context name for applications (same order than paths)
+|-p or --port|8080|http port
+|-s or --shutdown|8005|shutdown port
+|-d or --directory|./.apache-tomee|tomee work directory
+|-c or --as-war|-|deploy classpath as a war
+|-b or --doc-base|-|where web resources are for classpath deployment
+|--renaming|-|for fat war only, is renaming of the context supported
+|--serverxml|-|the server.xml location
+|--tomeexml|-|the server.xml location
+|--property|-|a list of container properties (values follow the format x=y)
+|===
+
+Note that since 7.0.0 TomEE provides 3 flavors (qualifier) of tomee-embedded as fat jars:
+
+- uber (where we put all request features by users, this is likely the most complete and the biggest)
+- jaxrs: webprofile minus JSF
+- jaxws: webprofile plus JAX-WS
+
+These different uber jars are interesting in mainly 2 cases:
+
+- you do a war shade (it avoids to list a bunch of dependencies but still get a customized version)
+- you run your application using `--path` option
+
+NOTE: if you already do a custom shade/fatjar this is not really impacting since you can depend on `tomee-embedded` and exclude/include what you want.
+
+== FatApp a shortcut main
+
+`FatApp` main (same package as tomee embedded `Main`) just wraps the default main ensuring:
+
+- ̀`--as-war` is used
+- ̀`--single-classloader` is used
+- `--configuration-location=tomee-embedded.properties` is set if `tomee-embedded.properties` is found in the classpath
+
+== configuration-location
+
+`--configuration-location` option allows to simplify the configuration of tomee embedded through properties.
+
+Here are the recognized entries (they match the configuration, see org.apache.tomee.embedded.Configuration for the detail):
+
+|===
+|Name|
+|http|
+|https|
+|stop|
+|host|
+|dir|
+|serverXml|
+|keepServerXmlAsThis|
+|quickSession|
+|skipHttp|
+|ssl|
+|http2|
+|webResourceCached|
+|withEjbRemote|
+|deployOpenEjbApp|
+|keystoreFile|
+|keystorePass|
+|keystoreType|
+|clientAuth|
+|keyAlias|
+|sslProtocol|
+|webXml|
+|tempDir|
+|classesFilter|
+|conf|
+|properties.x (set container properties x with the associated value)|
+|users.x (for default in memory realm add the user x with its password - the value)|
+|roles.x (for default in memory realm add the role x with its comma separated users - the value)|
+|connector.x (set the property x on the connector)|
+|realm=fullyqualifiedname,realm.prop=xxx (define a custom realm with its configuration)|
+|login=,login.prop=xxx (define a org.apache.tomee.embedded.LoginConfigBuilder == define a LoginConfig)|
+|securityConstraint=,securityConstraint.prop=xxx (define a org.apache.tomee.embedded.SecurityConstaintBuilder == define webapp security)|
+|configurationCustomizer.alias=,configurationCustomizer.alias.class=class,configurationCustomizer.alias.prop=xxx (define a ConfigurationCustomizer)|
+|===
+
+Here is a sample to add BASIC security on `/api/*`:
+
+[source]
+----
+# security configuration
+securityConstraint =
+securityConstraint.authConstraint = true
+securityConstraint.authRole = **
+securityConstraint.collection = api:/api/*
+
+login =
+login.realmName = app
+login.authMethod = BASIC
+
+realm = org.apache.catalina.realm.JAASRealm
+realm.appName = app
+
+properties.java.security.auth.login.config = configuration/login.jaas
+----
+
+And here a configuration to exclude jackson packages from scanning and use log4j2 as main logger (needs it as dependency):
+
+[source]
+----
+properties.openejb.log.factory = log4j2
+properties.openejb.container.additional.include = com.fasterxml.jackson,org.apache.logging.log4j
+----
+
+== Application Runner
+
+SInce TomEE 7.0.2, TomEE provide a light ApplicationComposer integration for TomEE Embedded (all features are not yet supported but the main ones are):
+`org.apache.tomee.embedded.TomEEEmbeddedApplicationRunner`. It relies on the definition of an `@Application`:
+
+[source,java]
+----
+@Application
+@Classes(context = "app")
+@ContainerProperties(@ContainerProperties.Property(name = "t", value = "set"))
+@TomEEEmbeddedApplicationRunner.LifecycleTasks(MyTask.class) // can start a ftp/sftp/elasticsearch/mongo/... server before tomee
+@TomEEEmbeddedApplicationRunner.Configurers(SetMyProperty.class)
+public class TheApp {
+ @RandomPort("http")
+ private int port;
+
+ @RandomPort("http")
+ private URL base;
+
+ @org.apache.openejb.testing.Configuration
+ public Properties add() {
+ return new PropertiesBuilder().p("programmatic", "property").build();
+ }
+
+ @PostConstruct
+ public void appStarted() {
+ // ...
+ }
+}
+----
+
+Then just start it with:
+
+[source,java]
+----
+TomEEEmbeddedApplicationRunner.run(TheApp.class, "some arg1", "other arg");
+----
+
+TIP: `@Classes(values)` and `@Jars` are supported too which can avoid a huge scanning if you run with a lot of not CDI dependencies which would boost the startup of your application.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/alternate-descriptors.mdtext
----------------------------------------------------------------------
diff --git a/docs/alternate-descriptors.mdtext b/docs/alternate-descriptors.mdtext
new file mode 100644
index 0000000..f55dfc9
--- /dev/null
+++ b/docs/alternate-descriptors.mdtext
@@ -0,0 +1,114 @@
+Title: Alternate Descriptors
+As of OpenEJB 3.1.1, you have the ability to specify an alternate set of
+deployment descriptors to use for a given environment. This is focused
+mostly on testing where it is often desirable to use a slightly different
+configuration for a set of tests or even a specific test.
+
+# When nothing else does the trick
+
+Note that this approach was added as a catch-all for when one of the
+simpler overriding techniques will not work. For the common case of
+needing to tweak your persistence.xml, see the [Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html)
+ page for a simpler approach.
+
+For many reasons it is very inconvenient to have to maintain two sets of
+descriptors, one for production and one for testing. We aggressively add
+features based on user feedback and questions. If you are looking for a
+way to solve a problem without duplicating entire descriptors, please let
+us know. You should never have to go the long way to do something simple.
+
+<a name="AlternateDescriptors-openejb.altdd.prefix"></a>
+# openejb.altdd.prefix
+
+To use this functionality, just set the new "openejb.altdd.prefix" system
+property or `InitialContext` property to something like "_test_", then any
+descriptors in your META-INF/ directory that start with "_test._" will
+override the regular descriptor. So for example with an app like this:
+
+ - META-INF/ejb-jar.xml
+ - META-INF/*test*.ejb-jar.xml
+ - META-INF/persistence.xml
+ - META-INF/*test*.env-entry.properties
+
+Just initialize your test case like so:
+
+
+ Properties properties = new Properties();
+ properties.setProperty(Context.INITIAL_CONTEXT_FACTORY,
+ "org.apache.openejb.client.LocalInitialContextFactory");
+ properties.setProperty("openejb.altdd.prefix", "test");
+
+ InitialContext initialContext = new InitialContext(properties);
+
+
+The logical result will be the prefixed file replacing the non-prefixed
+file as the active descriptor:
+
+ - META-INF/ejb-jar.xml -> *test*.ejb-jar.xml
+ - META-INF/persistence.xml
+ - META-INF/env-entry.properties -> *test*.env-entry.properties
+
+This will work in any environment in which OpenEJB works (embedded,
+standalone, tomcat, geronimo, etc.).
+
+Note that there does *not* have to be an equivalent non-prefixed version of
+the file. In the example above, only a "test.env-entry.properties" file
+exists and there is no equivalent plain "env-entry.properties" file. This
+prefixing works for any deployment descriptor in the META-INF/ directory or
+WEB-INF/ directory. The prefix does not have to be "test" and could be
+anything you choose. You can also have as many prefixed files as you need
+and could even go as far as to have one prefix per individual test.
+
+<a name="AlternateDescriptors-Morethanoneprefix"></a>
+# More than one prefix
+
+It is possible to have several prefixes, specified in order of preference,
+so that it is possible to avoid duplicating descriptors that are used in
+more than one "profile". For example, the "foo" test case uses the same
+"env-entries.properties" file as the "bar" test case, but both have their
+own ejb-jar.xml files:
+
+ - META-INF/ejb-jar.xml
+ - META-INF/test.ejb-jar.xml
+ - META-INF/footest.ejb-jar.xml
+ - META-INF/bartest.ejb-jar.xml
+ - META-INF/persistence.xml
+ - META-INF/test.env-entry.properties
+
+The "foo" test case could set the _openejb.altdd.prefix_ as follows:
+
+
+ //...
+ properties.setProperty("openejb.altdd.prefix", "footest, test");
+
+ InitialContext initialContext = new InitialContext(properties);
+
+
+Resulting the following logical view of the app:
+
+ - META-INF/ejb-jar.xml -> *footest*.ejb-jar.xml
+ - META-INF/persistence.xml
+ - META-INF/env-entry.properties -> test.env-entry.properties
+
+And the "bar" test case could set the _openejb.altdd.prefix_ as follows:
+
+
+ //...
+ properties.setProperty("openejb.altdd.prefix", "footest, test");
+
+ InitialContext initialContext = new InitialContext(properties);
+
+
+Resulting the following logical view of the app:
+
+ - META-INF/ejb-jar.xml -> *bartest*.ejb-jar.xml
+ - META-INF/persistence.xml
+ - META-INF/env-entry.properties -> test.env-entry.properties
+
+In both scenarios the same env-entry.properties file
+(test.env-entry.properties) is shared.
+
+Note that there is a "test.ejb-jar.xml" file that is present, however in
+both cases it is not used as the order of preference in the list is "left
+to right" meaning most preferred first.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/annotations,-xml-and-defaults.mdtext
----------------------------------------------------------------------
diff --git a/docs/annotations,-xml-and-defaults.mdtext b/docs/annotations,-xml-and-defaults.mdtext
new file mode 100644
index 0000000..a7d1fe1
--- /dev/null
+++ b/docs/annotations,-xml-and-defaults.mdtext
@@ -0,0 +1,565 @@
+Title: Annotations, XML and Defaults
+
+
+
+<div id="PageContent">
+ <p>The following is a list of all annotations and their attributes, the xml tags that correspond to them (for overriding), and what the default values are when left unspecified.</p>
+
+<div >
+<table ><tbody>
+<tr>
+<th > Annotation </th>
+<th > xml element(s) </th>
+<th > default value </th>
+</tr>
+<tr>
+<td "> @Stateless </td>
+<td "><ul>
+ <li><session></li>
+ <li><ejb-class></li>
+ <li><session-type>Stateless</session-type></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <ejb-name> </td>
+<td "> The simple name of the bean class. For <em>org.acme.superfun.WidgetBean</em> the ejb-name will be <b>WidgetBean</b> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>description</li>
+</ul>
+</td>
+<td "> <description> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>mappedName</li>
+</ul>
+</td>
+<td "> <mapped-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @Stateful </td>
+<td "><ul>
+ <li><session></li>
+ <li><ejb-class></li>
+ <li><session-type>Stateful</session-type></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <ejb-name> </td>
+<td "> The simple name of the bean class. For <em>org.acme.superfun.WidgetBean</em> the ejb-name will be <b>WidgetBean</b> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>description</li>
+</ul>
+</td>
+<td "> <description> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>mappedName</li>
+</ul>
+</td>
+<td "> <mapped-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @MessageDriven </td>
+<td "><ul>
+ <li><message-driven></li>
+ <li><ejb-class></li>
+ <li><session-type>Stateful</session-type></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <ejb-name> </td>
+<td "> The simple name of the bean class. For <em>org.acme.superfun.WidgetBean</em> the ejb-name will be <b>WidgetBean</b> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>description</li>
+</ul>
+</td>
+<td "> <description> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>mappedName</li>
+</ul>
+</td>
+<td "> <mapped-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>messageListenerInterface</li>
+</ul>
+</td>
+<td "> <messaging-type> </td>
+<td "> The interface the bean class implements. When relying upon the default is illegal for the bean to implement more than one interface </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>activationConfig[]</li>
+</ul>
+</td>
+<td "> <activation-config> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @ActivationConfigProperty </td>
+<td "> <activation-config-property> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>propertyName</li>
+</ul>
+</td>
+<td "> <activation-config-property-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>propertyValue</li>
+</ul>
+</td>
+<td "> <activation-config-property-value> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @RemoteHome </td>
+<td "><ul>
+ <li><home></li>
+ <li><remote></li>
+</ul>
+</td>
+<td "> The home is inspected to determine the value of <remote></td>
+</tr>
+<tr>
+<td "> @LocalHome </td>
+<td "><ul>
+ <li><local-home></li>
+ <li><local></li>
+</ul>
+</td>
+<td "> The local-home is inspected to determine the value of <local> </td>
+</tr>
+<tr>
+<td "> @TransactionManagement </td>
+<td "> <transaction-type> </td>
+<td "> TransactionManagementType.CONTAINER (xml value "Container") </td>
+</tr>
+<tr>
+<td "> @TransactionAttribute </td>
+<td "><ul>
+ <li><container-transaction></li>
+ <li><transaction-attribute></li>
+</ul>
+</td>
+<td "> All method default to TransactionAttributeType.REQUIRED (xml value "Required") </td>
+</tr>
+<tr>
+<td "> @RolesAllowed </td>
+<td "><ul>
+ <li><method-permission></li>
+ <li><role-name></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PermitAll </td>
+<td "><ul>
+ <li><method-permission></li>
+ <li><unchecked></li>
+</ul>
+</td>
+<td "> All methods default to unchecked </td>
+</tr>
+<tr>
+<td "> @DenyAll </td>
+<td "> <exclude-list> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @RunAs </td>
+<td "><ul>
+ <li><security-identity></li>
+ <li><run-as></li>
+ <li><role-name></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @DeclareRoles </td>
+<td "> <security-role-ref> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @Interceptors </td>
+<td "><ul>
+ <li><interceptor></li>
+ <li><interceptor-binding></li>
+ <li><interceptor-class></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @ExcludeDefaultInterceptors </td>
+<td "><ul>
+ <li><interceptor-binding></li>
+ <li><exclude-default-interceptors></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @ExcludeClassInterceptors </td>
+<td "><ul>
+ <li><interceptor-binding></li>
+ <li><exclude-class-interceptors></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @AroundInvoke </td>
+<td "> <around-invoke> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PostConstruct </td>
+<td "> <post-construct> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PreDestroy </td>
+<td "> <pre-destroy> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PrePassivate </td>
+<td "> <pre-passivate> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PostActivate </td>
+<td "> <post-activate> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @Init </td>
+<td "> <init-method> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @Remove </td>
+<td "> <remove-method> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>retainIfException</li>
+</ul>
+</td>
+<td "> <retain-if-exception> </td>
+<td "> false </td>
+</tr>
+<tr>
+<td "> @Timeout </td>
+<td "> <timeout-method> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @ApplicationException </td>
+<td "><ul>
+ <li><application-exception></li>
+ <li><exception-class></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>rollback</li>
+</ul>
+</td>
+<td "> <rollback> </td>
+<td "> false </td>
+</tr>
+<tr>
+<td "> @EJB </td>
+<td "><ul>
+ <li><ejb-ref></li>
+ <li><ejb-local-ref></li>
+ <li><injection-target></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "><ul>
+ <li><ejb-ref-name></li>
+</ul>
+</td>
+<td "><ul>
+ <li>on class: illegal to leave undefined</li>
+ <li>on field: {className}/{fieldName} as in <b>org.superbiz.Widget/myEjb</b></li>
+ <li>on setter: {className}/{propertyName} as in setMyEjb() defaults to <b>org.superbiz.Widget/myEjb</b></li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>beanInterface</li>
+</ul>
+</td>
+<td "><ul>
+ <li><home></li>
+ <li><local-home></li>
+ <li><remote></li>
+ <li><local></li>
+</ul>
+</td>
+<td "><ul>
+ <li>on class: illegal to leave undefined</li>
+ <li>on field: the data type of the field</li>
+ <li>on setter: the data type of the first method param</li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>beanName</li>
+</ul>
+</td>
+<td "> <ejb-link> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>description</li>
+</ul>
+</td>
+<td "> <description> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>mappedName</li>
+</ul>
+</td>
+<td "> <mapped-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @Resource </td>
+<td "><ul>
+ <li><env-entry></li>
+ <li><resource-ref></li>
+ <li><resource-env-ref></li>
+ <li><injection-target></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "><ul>
+ <li><env-entry-name></li>
+ <li><res-ref-name></li>
+ <li><resource-env-ref-name></li>
+</ul>
+</td>
+<td "><ul>
+ <li>on class: illegal to leave undefined</li>
+ <li>on field: {className}/{fieldName} as in <b>org.superbiz.Widget/myDataSource</b></li>
+ <li>on setter: {className}/{propertyName} as in setMyDataSource() defaults to <b>org.superbiz.Widget/myDataSource</b></li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>type</li>
+</ul>
+</td>
+<td "><ul>
+ <li><env-entry-type></li>
+ <li><res-type></li>
+ <li><resource-env-ref-type></li>
+</ul>
+</td>
+<td "><ul>
+ <li>on class: illegal to leave undefined</li>
+ <li>on field: the data type of the field</li>
+ <li>on setter: the data type of the first method param</li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>description</li>
+</ul>
+</td>
+<td "> <description> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>mappedName</li>
+</ul>
+</td>
+<td "> <mapped-name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>shareable</li>
+</ul>
+</td>
+<td "> <res-sharing-scope> </td>
+<td "> true (xml value "Shareable") </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>authenticationType</li>
+</ul>
+</td>
+<td "> <res-auth> </td>
+<td "> AuthenticationType.CONTAINER (xml value "Container") </td>
+</tr>
+<tr>
+<td "> @PersistenceUnit </td>
+<td "><ul>
+ <li><persistence-unit-ref></li>
+ <li><injection-target></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <persistence-unit-ref-name> </td>
+<td ">on class: illegal to leave undefined
+<ul>
+ <li>on field: {className}/{fieldName} as in <b>org.superbiz.Widget/myUnit</b></li>
+ <li>on setter: {className}/{propertyName} as in setMyUnit() defaults to <b>org.superbiz.Widget/myUnit</b></li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>unitName</li>
+</ul>
+</td>
+<td "> <persistence-unit-name> </td>
+<td "> vendor specific </td>
+</tr>
+<tr>
+<td "> @PersistenceContext </td>
+<td "><ul>
+ <li><persistence-context-ref></li>
+ <li><injection-target></li>
+</ul>
+</td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <persistence-context-ref-name> </td>
+<td ">on class: illegal to leave undefined
+<ul>
+ <li>on field: {className}/{fieldName} as in <b>org.superbiz.Widget/myContext</b></li>
+ <li>on setter: {className}/{propertyName} as in setMyContext() defaults to <b>org.superbiz.Widget/myContext</b></li>
+</ul>
+</td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>unitName</li>
+</ul>
+</td>
+<td "> <persistence-unit-name> </td>
+<td "> vendor specific </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>type</li>
+</ul>
+</td>
+<td "> <persistence-context-type> </td>
+<td "> PersistenceContextType.TRANSACTION (xml value "Transaction") </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>properties[]</li>
+</ul>
+</td>
+<td "> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "> @PersistenceProperty </td>
+<td "> <persistence-property> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>name</li>
+</ul>
+</td>
+<td "> <name> </td>
+<td "> </td>
+</tr>
+<tr>
+<td "><ul type="square" class="alternate">
+ <li>value</li>
+</ul>
+</td>
+<td "> <value> </td>
+<td "> </td>
+</tr>
+</tbody></table>
+</div>
+
+ </div>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/app-clients-and-jndi.mdtext
----------------------------------------------------------------------
diff --git a/docs/app-clients-and-jndi.mdtext b/docs/app-clients-and-jndi.mdtext
new file mode 100644
index 0000000..c3beda6
--- /dev/null
+++ b/docs/app-clients-and-jndi.mdtext
@@ -0,0 +1,69 @@
+Title: App Clients and JNDI
+There are some slight differences between the way OpenEJB does app clients
+and the way Geronimo does app clients
+
+
+Neither uses the names created via the openejb.jndiname.format. So
+changing that will (should) have no affect. The idea is that users
+should be able to set it to be whatever they want it to be and that should
+not break the App Client code. The openejb.jndiname.format is
+specifically for "plain" clients and allows them to get the names as they
+want them.
+
+Internally, we bind each EJB proxy under essentially a hardcoded and
+predictable format and then again using the user supplied format. So
+there are at minimum two JNDI trees with every EJB proxy. It used to
+be two at least. Now we have quite a few because of Java EE 6 global
+JNDI and the support we added for @LocalClient and allowing the same
+interface to be used as both @Local and @Remote.
+
+Basically we have:
+
+* openejb/Deployment/<hardcoded internal format>
+* openejb/local/<strategy format>
+* openejb/remote/<strategy format>
+
+The 'openejb/Deployment' section is the non-changing fully qualified name
+for use internally and by app clients.
+
+The 'openejb/remote' section is for "pretty" names looked up via plain
+clients using the RemoteInitialContextFactory. The protocol can tell
+the difference between app clients and plain clients and knows which area
+to look in.
+
+The 'openejb/local' section is for "pretty" names looked up via the
+LocalInitialContextFactory.
+
+The "pretty" names are defined by the openejb.jndiname.format and since the
+user has control of that formatting it's possible that not all proxies can
+be bound. Say the bean has both a local and remote interface and the
+user has just "\{deploymentId\}" or "\{ejbName\}" as the format.
+ Hence those bind calls use the "optional" set of binding methods.
+
+The format of the internal names bound into openejb/Deployment is
+guaranteed to be unique. It's not pretty to look at obviously, but
+every possible proxy will be bound there guaranteed. For binding into
+'openejb/Deployment' we don't use the "optional" set of binding methods.
+ If something can't be bound it's a deployment issue.
+
+The home interface is bound, but with the name of the corresponding
+business interface rather than the home interface.
+
+To be a little bit more clear - Both OpenEJB and Geronimo build their
+own JNDI trees for the App Client. Geronimo prefers to have its own
+JNDI tree for the App Client as there are other things in it that are not
+EJB related. Either way the OpenEJB EJBd protocol can carry the "id"
+of the App Client and both Geronimo and OpenEJB rely on that.
+
+In Geronimo App Clients the id is set to "Deployments" and that tells
+OpenEJB not to look in the "openejb/remote" section of JNDI as it normally
+would. It will instead use the "openejb/Deployments" section of JNDI
+were the names follow a predictable and unchanging format.
+
+In OpenEJB App Clients the id is set to the name of the App Client and we
+instead look in "openejb/client/<id>/" where names are formatted by the
+user via the application-client.xml.
+
+When calls are made from client to server and the App Client module id is
+not present, we look in openejb/remote/ where names are formatted using the
+openejb.jndi.format
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-composer/advanced.md
----------------------------------------------------------------------
diff --git a/docs/application-composer/advanced.md b/docs/application-composer/advanced.md
new file mode 100644
index 0000000..15c643d
--- /dev/null
+++ b/docs/application-composer/advanced.md
@@ -0,0 +1,90 @@
+# Application Composer Advanced
+
+[Getting Started](getting-started.html) page gives you already a lot of inputs but you caneven go further.
+
+## @Descriptors
+
+You can reuse existing file descriptors using `@Descriptors`. The name is the file name
+and the path either a classpath path or a file path:
+
+ // runner if needed etc...
+ @Descriptors(@Descriptor(name = "persistence.xml", path = "META-INF/persistence.xml"))
+ public class MyTest {
+ //...
+ }
+
+Note: this can be put in a `@Module` method as well.
+
+## Services
+
+If you want to test a JAXRS or JAXWS service you need to activate these services.
+
+To do so just add the needed dependency and use `@EnableServices`:
+
+ // runner if needed etc...
+ @EnableService("jaxrs") // jaxws supported as well
+ public class MyTest {
+ //...
+ }
+
+## Random port
+
+Services like JAXRS and JAXWS relies on HTTP. Often it is nice to have a random port
+to be able to deploy multiple tests/projects on the same CI platform at the same time.
+
+To shortcut all the needed logic you can use `@RandomPort`. It is simply an injection giving
+you either the port (`int`) or the root context (`URL`):
+
+ // runner, services if needed etc...
+ public class MyTest {
+ @RandomPort("http")
+ private int port;
+ }
+
+Note: you can generate this way multiple ports. The value is the name of the service it will apply on (being said http
+is an alias for httpejbd which is our embedded http layer).
+
+## Nice logs
+
+`@SimpleLog` annotation allows you to have one liner logs
+
+## @JaxrsProvider
+
+`@JaxrsProvider` allows you to specify on a `@Module` method the list of JAXRS provider you want to use.
+
+## Dependencies without hacky code
+
+`@Jars` allows you to add dependencies (scanned) to your application automatically (like CDI libraries):
+
+ @Module
+ @Classes(cdi = true, value = { C1.class, C2.class, E1.class })
+ @Jars("deltaspike-")
+ public WebApp app() {
+ return new WebApp();
+ }
+
+## @Default
+
+`@Default` automatically adds in the application `target/classes` as binaries and `src/main/webapp` as resources for maven projects.
+
+## @CdiExtensions
+
+This annotation allows you to control which extensions are activated during the test.
+
+## @AppResource
+
+This annotation allows injection of few particular test resources like:
+
+* the test `AppModule` (application meta)
+* the test `Context` (JNDI)
+* the test `ApplicationComposers` (underlying runner)
+* `ContextProvider`: allow to mock JAXRS contexts
+
+## @MockInjector
+
+Allows to mock EJB injections. It decorates a dedicated method returning an instance (or Class) implementing `FallbackPropertyInjector`.
+
+## @WebResource
+
+Allow for web application to add folders containing web resources.
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-composer/getting-started.md
----------------------------------------------------------------------
diff --git a/docs/application-composer/getting-started.md b/docs/application-composer/getting-started.md
new file mode 100644
index 0000000..13ab248
--- /dev/null
+++ b/docs/application-composer/getting-started.md
@@ -0,0 +1,188 @@
+# Application Composer Getting Started
+
+ApplicationComposer API is mainly contained in `org.apache.openejb.testing` package
+(historically, today we would have called the package `org.apache.tomee.applicationcomposer`).
+
+## Dependencies
+
+To start using ApplicationComposer you need to add some dependencies.
+
+The minimum required one is `openejb-core`:
+
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-core</artifactId>
+ <version>${openejb.version></version>
+ </dependency>
+
+If you need JAXRS services you'll add (or replace thanks to transitivity of maven) `openejb-cxf-rs`:
+
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-cxf-rs</artifactId>
+ <version>${openejb.version></version>
+ </dependency>
+
+If you need JAXWS services you'll add (or replace thanks to transitivity of maven) `openejb-cxf`:
+
+ <dependency>
+ <groupId>org.apache.openejb</groupId>
+ <artifactId>openejb-cxf</artifactId>
+ <version>${openejb.version></version>
+ </dependency>
+
+etc...
+
+## ApplicationComposer Components
+
+### @Module
+
+An ApplicationComposer needs at minimum a module (the application you need to deploy).
+
+To do so you have two cases:
+
+* before TomEE 2.x: you can only write method(s) decorated with `@Module`
+* since TomEE 2.x: you can skip it and use `@Classes` directly on the ApplicationComposer class as a shortcut for:
+
+ @Module
+ public WebApp app() {
+ return new WebApp();
+ }
+
+The expected returned type of these methods are in `org.apache.openejb.jee` package:
+
+* `Application`: entry point to create an ear
+* `WebApp`: a web application
+* `EjbJar`: an ejb module
+* `EnterpriseBean` children: a simple EJB
+* `Persistence`: a persistence module with multiple units
+* `PersistenceUnit`: a simple unit (automatically wrapped in a `Persistence`)
+* `Connector`: a JCA connector module
+* `Beans`: a CDI module,
+* `Class[]` or `Class`: a set of classes scanned to discover annotations
+
+Note that for easiness `@Classes` was added to be able to describe a module and some scanned classes. For instance the
+following snippet will create a web application with classes C1, C2 as CDI beans and E1 as an EJB automatically:
+
+ @Module
+ @Classes(cdi = true, value = { C1.class, C2.class, E1.class })
+ public WebApp app() {
+ return new WebApp();
+ }
+
+### @Configuration
+
+Often you need to customize a bit the container or at least create some resources like test databases.
+To do so you can create a method returning `Properties` which will be the container properties.
+
+Note: to simplify writing properties you can use `PropertiesBuilder` util class which is just a fluent API
+to write properties.
+
+In these properties you can reuse OpenEJB/TomEE property syntax for resources.
+
+Here is a sample:
+
+ @Configuration
+ public Properties configuration() {
+ return new PropertiesBuilder()
+ .p("db", "new://Resource?type=DataSource")
+ .p("db.JdbcUrld", "jdbc:hsqldb:mem:test")
+ .build();
+ }
+
+Since TomEE 2.x you can also put properties on ApplicationComposer class using `@ContainerProperties` API:
+
+ @ContainerProperties({
+ @ContainerProperties.Property(name = "db", value = "new://Resource?type=DataSource"),
+ @ContainerProperties.Property(name = "db.JdbcUrl", value = "jdbc:hsqldb:mem:test")
+ })
+ public class MyAppComposer() {
+ // ...
+ }
+
+### @Component
+
+Sometimes you need to customize a container component. The most common use case is the security service
+to mock a little bit authorization if you don't care in your test.
+
+To do so just write a method decorated with `@Component` returning the instance you desire.
+
+Components in TomEE are stored in a container Map and the key needs to be a `Class`. This one is deduced from the returned
+type of the `@Component` method:
+
+ @Component
+ public SecurityService mockSecurity() {
+ return new MySecurityService();
+ }
+
+## How to run it?
+
+### JUnit
+
+If you use JUnit you have mainly 2 solutions to run you "model" using the ApplicationComposer:
+
+* using `ApplicationComposer` runner:
+
+ @RunWith(ApplicationComposer.class)
+ public class MyTest {
+ // ...
+ }
+
+* using `ApplicationComposerRule` rule:
+
+ public class MyTest {
+ @Rule // or @ClassRule if you want the container/application lifecycle be bound to the class and not test methods
+ public final ApplicationComposerRule rule = new ApplicationComposerRule(this);
+ }
+
+Tip: since TomEE 2.x ApplicationComposerRule is decomposed in 2 rules if you need: `ContainerRule` and `DeployApplication`.
+Using JUnit `RuleChain` you can chain them to get the samebehavior as `ApplicationComposerRule` or better deploy
+multiple ApplicationComposer models and controlling their deployment ordering (to mock a remote service for instance).
+
+Finally just write `@Test` method using test class injections as if the test class was a managed bean!
+
+### TestNG
+
+TestNG integration is quite simple today and mainly `ApplicationComposerListener` class you can configure
+as a listener to get ApplicationComposer features.
+
+Finally just write TestNG `@Test` method using test class injections as if the test class was a managed bean!
+
+### Standalone
+
+Since TomEE 2.x you can also use `ApplicationComposers` to directly run you ApplicationComposer model
+as a standalone application:
+
+ public class MyApp {
+ public static void main(String[] args) {
+ ApplicationComposers.run(MyApp.class, args);
+ }
+
+ // @Module, @Configuration etc...
+ }
+
+Tip: if `MyApp` has `@PostConstruct` methods they will be respected and if `MyApp` has a constructor taking an array
+of String it will be instantiated getting the second parameter as argument (ie you can propagate your main parameter
+to your model to modify your application depending it!)
+
+## JUnit Sample
+
+ @Classes(cdi = true, value = { MyService.class, MyOtherService.class })
+ @ContainerProperties(@ContainerProperties.Property(name = "myDb", value = "new://Resource?type=DataSource"))
+ @RunWith(ApplicationComposer.class)
+ public class MyTest {
+ @Resource(name = "myDb")
+ private DataSource ds;
+
+ @Inject
+ private MyService service;
+
+ @Test
+ public void myTest() {
+ // do test using injections
+ }
+ }
+
+## Going further
+
+If you want to learn more about ApplicationComposer see [Advanced](advanced.html) page.
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-composer/history.md
----------------------------------------------------------------------
diff --git a/docs/application-composer/history.md b/docs/application-composer/history.md
new file mode 100644
index 0000000..3deb828
--- /dev/null
+++ b/docs/application-composer/history.md
@@ -0,0 +1,38 @@
+# Application Composer History
+
+ApplicationComposer can look like a long story but following it you'll realize it is finally quite natural.
+
+## Internal tool
+
+TomEE (former OpenEJB) is an Application Server. One of the most important task writing an Application Server
+is to ensure the implemented features do what is expected. However it is hard to write N test applications, in N modules
+to ensure it works smoothly. In particular when you want to test a small part of the whole server.
+
+So you immediately think to mocking what is not needed. It works but has a big pitfall: test is often a noop or hide
+a lot of issues.
+
+So the idea came to be able to shortcut the part we don't care much about runtime: the application packaging.
+
+Here what is the ApplicationComposer: an (originally test) API to create a EE application programmatically.
+
+## Designs
+
+ApplicationComposer design was aligned on this simple need. An ApplicationComposer "test" (browsing other pages you'll see
+it is much more than test today) is composed of mainly 2 parts:
+
+* modules: methods describing a module of an application. It can be a persistence.xml, an ejb-jar.xml, a web.xml...but all programmatically.
+* configuration: container configuration allowing to interact with container (creating resources for instance)
+
+## Test but not only
+
+ApplicationComposer was originally a JUnit only runner but was pretty quickly extended to TestNG too and
+today you can even use it to write `main(String[])` - even in a shade!
+
+API was greatly simplified and it allows you pretty easily to deploy with a simple shade a JAXRS/JAXWS/JMS service!
+
+## Going further
+
+If you want to go further you can browse:
+
+* [Getting Started](getting-started.html)
+* [Advanced](advanced.html)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-composer/index.md
----------------------------------------------------------------------
diff --git a/docs/application-composer/index.md b/docs/application-composer/index.md
new file mode 100644
index 0000000..1823808
--- /dev/null
+++ b/docs/application-composer/index.md
@@ -0,0 +1,18 @@
+# Application Composer
+
+Here is the subdomain dedicated to the Application Composer.
+
+If you don't know at all what ApplicationComposer means, [History](history.html) page
+will explain you where does it come from and what it can be used to today.
+
+If you are already familiar with ApplicationComposer concept and are just looking for a sample,
+[Getting Started](getting-started.html) is designed for you.
+
+Finally if you already use ApplicationComposer and just desire to go further, [Advanced](advanced.html)
+page is the one you need to look!
+
+Children:
+
+* [History](history.html)
+* [Getting Started](getting-started.html)
+* [Advanced](advanced.html)
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-deployment-solutions.mdtext
----------------------------------------------------------------------
diff --git a/docs/application-deployment-solutions.mdtext b/docs/application-deployment-solutions.mdtext
new file mode 100644
index 0000000..3f21d0b
--- /dev/null
+++ b/docs/application-deployment-solutions.mdtext
@@ -0,0 +1,75 @@
+Title: Deploying An Application To TomEE Or OpenEJB
+
+# Deploying An Application To TomEE Or OpenEJB
+## How to deploy my application under TomEE
+### Description
+
+This aims to be more dynamic in the way you deploy your applications.
+It is clearly cloud oriented.
+
+### Webapp and TomEE deployment
+
+Webapp can be deployed as Tomcat does. Simply put it in webapps folder
+(or the one you configured) and start TomEE.
+
+### TomEE specific deployment
+
+By default TomEE deploys applications (ear, war, jar) contained in $CATALINA_BASE/apps
+directory at start up.
+
+### Deployer
+
+OpenEJB provides a Deployer EJB to do this task. It can be used
+in your own software looking up remotely the "openejb/DeployerBusinessRemote" EJB.
+Its interface is "org.apache.openejb.assembler.Deployer".
+The needed dependency is org.apache.openejb:openejb-core.
+
+Once you got your deployer simply invoke the "deploy" method. Give it the location
+of your application (can be a file, http, https, maven location depending on
+the way you configured your container, for more information
+have a look to TomEE provisionning).
+
+Note: the "undeploy" method exists too and take the same path.
+
+The Deployer is the base of all other solutions
+
+### Maven plugin
+
+[org.apache.openejb:tomee-maven-plugin](maven/index.html) can be used to deploy/undeploy your application. Once this plugin is added to your pom you have access to the following configuration:
+
+* tomeeHttpPort
+* tomeeHost
+
+Then simply run
+
+ mvn tomee:deploy <path>
+
+or
+
+ mvn tomee:undeploy <path>
+
+#### The Deployer through TomEE Webapp
+
+When you start TomEE you can locally access the TomEE webapps (http://host:ip/tomee/).
+
+Then simply go to JNDI tree, select the deployer in the tree, then click on "invoke this ejb",
+select the deploy (or undeploy) method, fill the path and click on "invoke".
+
+#### Cloud idea
+
+If you want to cloudify your application, you'll get a configuration database (or any
+other storage system ;)).
+
+So it means it is easy for you to get a host and a port...so it is easy
+to deploy on all your server using the deployer: simply use the maven provisioning
+then run the deployer on all your nodes and that's all!
+
+
+### Doing it with camel?
+
+If you are using a route to deploy/undeploy your applications
+you can have a look to the proposed camel-openejb component:
+
+* base code: http://svn.apache.org/repos/asf/tomee/sandbox/camel/camel-openejb/
+* proposed to be added to camel: https://issues.apache.org/jira/browse/CAMEL-4935
+
http://git-wip-us.apache.org/repos/asf/tomee/blob/f779264f/docs/application-discovery-via-the-classpath.mdtext
----------------------------------------------------------------------
diff --git a/docs/application-discovery-via-the-classpath.mdtext b/docs/application-discovery-via-the-classpath.mdtext
new file mode 100644
index 0000000..bb818a9
--- /dev/null
+++ b/docs/application-discovery-via-the-classpath.mdtext
@@ -0,0 +1,91 @@
+Title: Application discovery via the classpath
+This document details the various ways to get OpenEJB to detect
+applications you would like deployed while in an embedded mode.
+
+<a name="Applicationdiscoveryviatheclasspath-Emptyejb-jar.xmlapproach(recommended)"></a>
+# Empty ejb-jar.xml approach (recommended)
+
+Simplify the issue of searching for annotated applications by adding an
+ejb-jar.xml like this to your app:
+
+ <ejb-jar/>
+
+
+OpenEJB will find the app in the classpath and deploy it along with any
+annotated beans it may contain.
+
+The ejb-jar.xml can contain more than just "<ejb-jar/>" as usual.
+
+This is the recommended approach for people using OpenEJB for unit testing
+as it allows OpenEJB to find your application in the classpath without the
+need for you to specify any path information which tends to complicate
+builds.
+
+# Including/Excluding paths (advanced)
+
+If you do not like the idea of having the ejb-jar.xml in your app or an
+openejb.xml, we can search the classpath for annotated beans (@Stateless,
+@Stateful, @MessageDriven) and load them automatically just as if they
+contained an ejb-jar.xml.
+
+This form of searching, however, is very expensive as it involves iterating
+over every path in the classpath and reading in each class definition
+contained thereunder and checking it for annotations.
+
+This approach can only be made faster by helping us trim down or pinpoint
+the paths we should search via the *openejb.deployments.classpath.include*
+property which can be specified as a _system property_ or a property passed
+into the _InitialContext_.
+
+The value of this property is a regular expression and therefore can be
+absolute or relative. For example the path
+"/Users/dblevins/work/swizzle/swizzle-stream/target/classes" which contains
+the class files of an application you wish to test could be included in any
+of the following values to the "openejb.deployments.classpath.include"
+property:
+
+* "file:///Users/dblevins/work/swizzle/swizzle-stream/target/classes/" _(an absolute path)_
+* "file:///Users/dblevins/work/swizzle/.*" _(relative)_
+* ".\*swizzle-stream.\*" _(very relative)_
+* ".\*(swizzle-stream|swizzle-jira|acme-rocket-app).\*" _(including several paths)_
+* ".\*(swizzle-stream^|swizzle-jira^|acme-rocket-app).\*" _(including several paths with Win specific escapes)_
+
+Note the filtering is done on URLs in the classpath, so forward slashes
+should always be used even on OSs using backslash ("\").
+
+There are also the *openejb.deployments.classpath.exclude* and *openejb.exclude-include.order*
+properties if you wish to work in the opposite direction or change the processing order.
+The default values for the properties are as follows:
+
+ openejb.exclude-include.order=include-exclude //Defines the processing order
+ openejb.deployments.classpath.include="" //Include nothing
+ openejb.deployments.classpath.exclude=".*" //Exclude everything
+
+The exclude and the include are applied separately and the results of each
+are combined together to create the list of paths OpenEJB will scrape for
+annotations.
+
+ *Note:* by default these settings will only affect which jars OpenEJB will
+ scan for annotated components when no descriptor is found. If you would
+ like to use these settings to also filter out jars that do contain
+ descriptors, set the *openejb.deployments.classpath.filter.descriptors*
+ property to _true_. The default is _false_.
+
+# Troubleshooting
+
+If the include/exclude is not being processed as you expect first try
+reversing the order to *openejb.exclude-include.order*=exclude-include
+There are a number internal filters that may result in an unexpected exclusion.
+
+If you're having trouble determining if the META-INF/ejb-jar.xml file for
+your ejb module is in the classpath, a little debug code like this in your
+test setup will help you see what OpenEJB sees (which may be nothing):
+
+
+ Enumeration<URL> ejbJars =
+ this.getClass().getClassLoader().getResources("META-INF/ejb-jar.xml");
+ while (ejbJars.hasMoreElements()) {
+ URL url = ejbJars.nextElement();
+ System.out.println("app = " + url);
+ }
+