TOMEE-2316 Convert Markdown files to Asciidoc in the docs folder - 1
Project: http://git-wip-us.apache.org/repos/asf/tomee/repo Commit: http://git-wip-us.apache.org/repos/asf/tomee/commit/3e87b477 Tree: http://git-wip-us.apache.org/repos/asf/tomee/tree/3e87b477 Diff: http://git-wip-us.apache.org/repos/asf/tomee/diff/3e87b477 Branch: refs/heads/master Commit: 3e87b477837a6bab15c0b008eda2fbee6edb35dd Parents: 388460f Author: Carlos Chacin <[email protected]> Authored: Wed Dec 5 22:07:17 2018 -0800 Committer: Carlos Chacin <[email protected]> Committed: Wed Dec 5 22:08:35 2018 -0800 ---------------------------------------------------------------------- docs/Configuring-in-tomee.adoc | 47 ++ docs/Configuring-in-tomee.md | 45 -- docs/activemqresourceadapter-config.adoc | 88 +++ docs/activemqresourceadapter-config.md | 69 --- docs/admin/cluster/index.adoc | 1 + docs/advanced/client/jndi.adoc | 1 + docs/alternate-descriptors.adoc | 121 ++++ docs/alternate-descriptors.md | 117 ---- docs/annotations,-xml-and-defaults.adoc | 20 + docs/annotations,-xml-and-defaults.md | 569 ------------------- docs/app-clients-and-jndi.adoc | 74 +++ docs/app-clients-and-jndi.md | 73 --- docs/application-composer/advanced.adoc | 107 ++++ docs/application-composer/advanced.md | 90 --- docs/application-composer/getting-started.adoc | 225 ++++++++ docs/application-composer/getting-started.md | 188 ------ docs/application-composer/history.adoc | 48 ++ docs/application-composer/history.md | 38 -- docs/application-composer/index.adoc | 20 + docs/application-composer/index.md | 18 - docs/application-deployment-solutions.adoc | 90 +++ docs/application-deployment-solutions.md | 78 --- ...application-discovery-via-the-classpath.adoc | 107 ++++ docs/application-discovery-via-the-classpath.md | 94 --- docs/application-resources.adoc | 362 ++++++++++++ docs/application-resources.md | 250 -------- docs/arquillian-available-adapters.adoc | 311 ++++++++++ docs/arquillian-available-adapters.md | 264 --------- docs/arquillian-getting-started.adoc | 41 ++ docs/arquillian-getting-started.md | 24 - 30 files changed, 1663 insertions(+), 1917 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/Configuring-in-tomee.adoc ---------------------------------------------------------------------- diff --git a/docs/Configuring-in-tomee.adoc b/docs/Configuring-in-tomee.adoc new file mode 100644 index 0000000..bc26314 --- /dev/null +++ b/docs/Configuring-in-tomee.adoc @@ -0,0 +1,47 @@ +# Apache TomEE configuration +:index-group: Configuration +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +NOTE: 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. + +###Configuring Resources: + +* Drivers are dropped into tomeeDir/lib +* Resources are configured in tomeeDir/conf/tomee.xml. + +* The configurations take a very simple (XML+Property-file) syntax. +* Tag names match annotation names + +For example, + +.... +@Resource DataSource moviesDatabase +.... + +is injected with the following resource: + +.... +<Resource id="moviesDatabase" type="DataSource"> +JdbcDriver org.hsqldb.jdbcDriver +JdbcUrl jdbc:mysql:localhost:3306/moviesdb +UserName sa +Password secret +JtaManaged true +</Resource> +.... + +For more on how to configure, read through +link:/configuring-datasources.html[configuring-datasources], +link:containers-and-resources.html[containers-and-resources] docs. http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/Configuring-in-tomee.md ---------------------------------------------------------------------- diff --git a/docs/Configuring-in-tomee.md b/docs/Configuring-in-tomee.md deleted file mode 100644 index 0c798eb..0000000 --- a/docs/Configuring-in-tomee.md +++ /dev/null @@ -1,45 +0,0 @@ -index-group=Configuration -type=page -status=published -title=Apache TomEE configuration -~~~~~~ -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. - -###Configuring Resources: - -* Drivers are dropped into tomeeDir/lib -* Resources are configured in tomeeDir/conf/tomee.xml. -* The configurations take a very simple (XML+Property-file) syntax. -* Tag names match annotation names - -For example, - - @Resource DataSource moviesDatabase - -is injected with the following resource: - - - <Resource id="moviesDatabase" type="DataSource"> - JdbcDriver org.hsqldb.jdbcDriver - JdbcUrl jdbc:mysql:localhost:3306/moviesdb - UserName sa - Password secret - JtaManaged true - </Resource> - -For more on how to configure, read through [configuring-datasources](/configuring-datasources.html), [containers-and-resources](containers-and-resources.html) docs. http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/activemqresourceadapter-config.adoc ---------------------------------------------------------------------- diff --git a/docs/activemqresourceadapter-config.adoc b/docs/activemqresourceadapter-config.adoc new file mode 100644 index 0000000..1402427 --- /dev/null +++ b/docs/activemqresourceadapter-config.adoc @@ -0,0 +1,88 @@ +# ActiveMQResourceAdapter Configuration +:index-group: ActiveMQ +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +A ActiveMQResourceAdapter can be declared via xml in the +`<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file +using a declaration like the following. All properties in the element +body are optional. + +.... +<Resource id="myActiveMQResourceAdapter" type="ActiveMQResourceAdapter"> + brokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false + dataSource = Default Unmanaged JDBC Database + serverUrl = vm://localhost?waitForStart=20000&async=true + startupTimeout = 10 seconds +</Resource> +.... + +Alternatively, a ActiveMQResourceAdapter can be declared via properties +in the `<tomee-home>/conf/system.properties` file or via Java +VirtualMachine `-D` properties. The properties can also be used when +embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or +`InitialContext` + +.... +myActiveMQResourceAdapter = new://Resource?type=ActiveMQResourceAdapter +myActiveMQResourceAdapter.brokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false +myActiveMQResourceAdapter.dataSource = Default Unmanaged JDBC Database +myActiveMQResourceAdapter.serverUrl = vm://localhost?waitForStart=20000&async=true +myActiveMQResourceAdapter.startupTimeout = 10 seconds +.... + +Properties and xml can be mixed. Properties will override the xml +allowing for easy configuration change without the need for $\{} style +variable substitution. Properties are not case sensitive. If a property +is specified that is not supported by the declared +ActiveMQResourceAdapter a warning will be logged. If a +ActiveMQResourceAdapter is needed by the application and one is not +declared, TomEE will create one dynamically using default settings. +Multiple ActiveMQResourceAdapter declarations are allowed. + +== Supported Properties + +Property + +Type + +Default + +Description + +brokerXmlConfig + +String + +broker:(tcp://localhost:61616)?useJmx=false + +Broker configuration URI as defined by ActiveMQ see +http://activemq.apache.org/broker-configuration-uri.html BrokerXmlConfig +xbean:file:conf/activemq.xml - Requires xbean-spring.jar and +dependencies + +dataSource + +String + +Default Unmanaged JDBC Database + +DataSource for persistence messages + +serverUrl + +java.net.URI + +vm://localhost?waitForStart=20000&async=true + +Broker address + +startupTimeout + +time + +10 seconds + +How long to wait for broker startup http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/activemqresourceadapter-config.md ---------------------------------------------------------------------- diff --git a/docs/activemqresourceadapter-config.md b/docs/activemqresourceadapter-config.md deleted file mode 100644 index d709310..0000000 --- a/docs/activemqresourceadapter-config.md +++ /dev/null @@ -1,69 +0,0 @@ -index-group=ActiveMQ -type=page -status=published -title=ActiveMQResourceAdapter Configuration -~~~~~~ - - -A ActiveMQResourceAdapter can be declared via xml in the `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file using a declaration like the following. All properties in the element body are optional. - - <Resource id="myActiveMQResourceAdapter" type="ActiveMQResourceAdapter"> - brokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false - dataSource = Default Unmanaged JDBC Database - serverUrl = vm://localhost?waitForStart=20000&async=true - startupTimeout = 10 seconds - </Resource> - -Alternatively, a ActiveMQResourceAdapter can be declared via properties in the `<tomee-home>/conf/system.properties` file or via Java VirtualMachine `-D` properties. The properties can also be used when embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or `InitialContext` - - myActiveMQResourceAdapter = new://Resource?type=ActiveMQResourceAdapter - myActiveMQResourceAdapter.brokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false - myActiveMQResourceAdapter.dataSource = Default Unmanaged JDBC Database - myActiveMQResourceAdapter.serverUrl = vm://localhost?waitForStart=20000&async=true - myActiveMQResourceAdapter.startupTimeout = 10 seconds - -Properties and xml can be mixed. Properties will override the xml allowing for easy configuration change without the need for ${} style variable substitution. Properties are not case sensitive. If a property is specified that is not supported by the declared ActiveMQResourceAdapter a warning will be logged. If a ActiveMQResourceAdapter is needed by the application and one is not declared, TomEE will create one dynamically using default settings. Multiple ActiveMQResourceAdapter declarations are allowed. - -## Supported Properties -<table class="mdtable"> -<tr> -<th>Property</th> -<th>Type</th> -<th>Default</th> -<th>Description</th> -</tr> -<tr> - <td>brokerXmlConfig</td> - <td>String</td> - <td>broker:(tcp://localhost:61616)?useJmx=false</td> - <td> -Broker configuration URI as defined by ActiveMQ -see http://activemq.apache.org/broker-configuration-uri.html -BrokerXmlConfig xbean:file:conf/activemq.xml - Requires xbean-spring.jar and dependencies -</td> -</tr> -<tr> - <td>dataSource</td> - <td>String</td> - <td>Default Unmanaged JDBC Database</td> - <td> -DataSource for persistence messages -</td> -</tr> -<tr> - <td>serverUrl</td> - <td>java.net.URI</td> - <td>vm://localhost?waitForStart=20000&async=true</td> - <td> -Broker address -</td> -</tr> -<tr> - <td>startupTimeout</td> - <td><a href="configuring-durations.html">time</a></td> - <td>10 seconds</td> - <td> -How long to wait for broker startup -</td> -</tr> -</table> http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/admin/cluster/index.adoc ---------------------------------------------------------------------- diff --git a/docs/admin/cluster/index.adoc b/docs/admin/cluster/index.adoc index 9893c8f..a7cc4a7 100644 --- a/docs/admin/cluster/index.adoc +++ b/docs/admin/cluster/index.adoc @@ -1,3 +1,4 @@ +:jbake-date: 2018-12-05 :jbake-type: page :jbake-status: published :jbake-title: Clustering and High Availability (HA) http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/advanced/client/jndi.adoc ---------------------------------------------------------------------- diff --git a/docs/advanced/client/jndi.adoc b/docs/advanced/client/jndi.adoc index 5f2e55b..3097e69 100644 --- a/docs/advanced/client/jndi.adoc +++ b/docs/advanced/client/jndi.adoc @@ -1,4 +1,5 @@ :jbake-title: Java Naming and Directory Interface (JNDI) +:jbake-date: 2018-12-05 :jbake-type: page :jbake-status: published http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/alternate-descriptors.adoc ---------------------------------------------------------------------- diff --git a/docs/alternate-descriptors.adoc b/docs/alternate-descriptors.adoc new file mode 100644 index 0000000..8818a72 --- /dev/null +++ b/docs/alternate-descriptors.adoc @@ -0,0 +1,121 @@ +# Alternate Descriptors +:index-group: Testing Techniques +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +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 +link:configuring-persistenceunits-in-tests.html[Configuring +PersistenceUnits in Tests] 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. + +# 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. + +# 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/3e87b477/docs/alternate-descriptors.md ---------------------------------------------------------------------- diff --git a/docs/alternate-descriptors.md b/docs/alternate-descriptors.md deleted file mode 100644 index 1eb52fe..0000000 --- a/docs/alternate-descriptors.md +++ /dev/null @@ -1,117 +0,0 @@ -index-group=Testing Techniques -type=page -status=published -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/3e87b477/docs/annotations,-xml-and-defaults.adoc ---------------------------------------------------------------------- diff --git a/docs/annotations,-xml-and-defaults.adoc b/docs/annotations,-xml-and-defaults.adoc new file mode 100644 index 0000000..8849c9d --- /dev/null +++ b/docs/annotations,-xml-and-defaults.adoc @@ -0,0 +1,20 @@ +# Annotations, XML and Defaults +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +.... + <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> +.... + +Annotation + +xml element(s) + +default value + +.... + </div> +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/annotations,-xml-and-defaults.md ---------------------------------------------------------------------- diff --git a/docs/annotations,-xml-and-defaults.md b/docs/annotations,-xml-and-defaults.md deleted file mode 100644 index bd41890..0000000 --- a/docs/annotations,-xml-and-defaults.md +++ /dev/null @@ -1,569 +0,0 @@ -index-group=Unrevised -type=page -status=published -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 class="mdtable"> <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> http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/app-clients-and-jndi.adoc ---------------------------------------------------------------------- diff --git a/docs/app-clients-and-jndi.adoc b/docs/app-clients-and-jndi.adoc new file mode 100644 index 0000000..dee6ebb --- /dev/null +++ b/docs/app-clients-and-jndi.adoc @@ -0,0 +1,74 @@ +# App Clients and JNDI +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +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//" 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/3e87b477/docs/app-clients-and-jndi.md ---------------------------------------------------------------------- diff --git a/docs/app-clients-and-jndi.md b/docs/app-clients-and-jndi.md deleted file mode 100644 index b6faaaa..0000000 --- a/docs/app-clients-and-jndi.md +++ /dev/null @@ -1,73 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/3e87b477/docs/application-composer/advanced.adoc ---------------------------------------------------------------------- diff --git a/docs/application-composer/advanced.adoc b/docs/application-composer/advanced.adoc new file mode 100644 index 0000000..1ce9b66 --- /dev/null +++ b/docs/application-composer/advanced.adoc @@ -0,0 +1,107 @@ +== Application Composer Advanced + +link:getting-started.html[Getting Started] 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/3e87b477/docs/application-composer/advanced.md ---------------------------------------------------------------------- diff --git a/docs/application-composer/advanced.md b/docs/application-composer/advanced.md deleted file mode 100644 index 15c643d..0000000 --- a/docs/application-composer/advanced.md +++ /dev/null @@ -1,90 +0,0 @@ -# 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/3e87b477/docs/application-composer/getting-started.adoc ---------------------------------------------------------------------- diff --git a/docs/application-composer/getting-started.adoc b/docs/application-composer/getting-started.adoc new file mode 100644 index 0000000..9465c97 --- /dev/null +++ b/docs/application-composer/getting-started.adoc @@ -0,0 +1,225 @@ +== 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 +link:advanced.html[Advanced] page. http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-composer/getting-started.md ---------------------------------------------------------------------- diff --git a/docs/application-composer/getting-started.md b/docs/application-composer/getting-started.md deleted file mode 100644 index 13ab248..0000000 --- a/docs/application-composer/getting-started.md +++ /dev/null @@ -1,188 +0,0 @@ -# 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/3e87b477/docs/application-composer/history.adoc ---------------------------------------------------------------------- diff --git a/docs/application-composer/history.adoc b/docs/application-composer/history.adoc new file mode 100644 index 0000000..d33eb23 --- /dev/null +++ b/docs/application-composer/history.adoc @@ -0,0 +1,48 @@ +== 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: + +* link:getting-started.html[Getting Started] +* link:advanced.html[Advanced] http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-composer/history.md ---------------------------------------------------------------------- diff --git a/docs/application-composer/history.md b/docs/application-composer/history.md deleted file mode 100644 index 3deb828..0000000 --- a/docs/application-composer/history.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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/3e87b477/docs/application-composer/index.adoc ---------------------------------------------------------------------- diff --git a/docs/application-composer/index.adoc b/docs/application-composer/index.adoc new file mode 100644 index 0000000..1eea036 --- /dev/null +++ b/docs/application-composer/index.adoc @@ -0,0 +1,20 @@ +== Application Composer + +Here is the subdomain dedicated to the Application Composer. + +If you don't know at all what ApplicationComposer means, +link:history.html[History] 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, link:getting-started.html[Getting Started] is +designed for you. + +Finally if you already use ApplicationComposer and just desire to go +further, link:advanced.html[Advanced] page is the one you need to look! + +Children: + +* link:history.html[History] +* link:getting-started.html[Getting Started] +* link:advanced.html[Advanced] http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-composer/index.md ---------------------------------------------------------------------- diff --git a/docs/application-composer/index.md b/docs/application-composer/index.md deleted file mode 100644 index 1823808..0000000 --- a/docs/application-composer/index.md +++ /dev/null @@ -1,18 +0,0 @@ -# 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/3e87b477/docs/application-deployment-solutions.adoc ---------------------------------------------------------------------- diff --git a/docs/application-deployment-solutions.adoc b/docs/application-deployment-solutions.adoc new file mode 100644 index 0000000..68a06f8 --- /dev/null +++ b/docs/application-deployment-solutions.adoc @@ -0,0 +1,90 @@ +# Deploying An Application To TomEE Or OpenEJB +:index-group: Unrevised +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + + +== 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 + +link:maven/index.html[org.apache.openejb:tomee-maven-plugin] 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/3e87b477/docs/application-deployment-solutions.md ---------------------------------------------------------------------- diff --git a/docs/application-deployment-solutions.md b/docs/application-deployment-solutions.md deleted file mode 100644 index 6912c65..0000000 --- a/docs/application-deployment-solutions.md +++ /dev/null @@ -1,78 +0,0 @@ -index-group=Unrevised -type=page -status=published -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/3e87b477/docs/application-discovery-via-the-classpath.adoc ---------------------------------------------------------------------- diff --git a/docs/application-discovery-via-the-classpath.adoc b/docs/application-discovery-via-the-classpath.adoc new file mode 100644 index 0000000..8984c24 --- /dev/null +++ b/docs/application-discovery-via-the-classpath.adoc @@ -0,0 +1,107 @@ +# Application discovery via the classpath +:index-group: Testing Techniques +:jbake-date: 2018-12-05 +:jbake-type: page +:jbake-status: published + +This document +details the various ways to get OpenEJB to detect applications you would +like deployed while in an embedded mode. + +# 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 "" 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); +} +.... http://git-wip-us.apache.org/repos/asf/tomee/blob/3e87b477/docs/application-discovery-via-the-classpath.md ---------------------------------------------------------------------- diff --git a/docs/application-discovery-via-the-classpath.md b/docs/application-discovery-via-the-classpath.md deleted file mode 100644 index 3754479..0000000 --- a/docs/application-discovery-via-the-classpath.md +++ /dev/null @@ -1,94 +0,0 @@ -index-group=Testing Techniques -type=page -status=published -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); - }
