http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/tomee-embedded/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/tomee-embedded/index.adoc b/src/main/jbake/content/advanced/tomee-embedded/index.adoc new file mode 100755 index 0000000..8664ade --- /dev/null +++ b/src/main/jbake/content/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-site-generator/blob/972cc356/src/main/jbake/content/blog/2016/03/new-website.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/blog/2016/03/new-website.adoc b/src/main/jbake/content/blog/2016/03/new-website.adoc new file mode 100755 index 0000000..bbe331e --- /dev/null +++ b/src/main/jbake/content/blog/2016/03/new-website.adoc @@ -0,0 +1,8 @@ += New Website for Apache TomEE +:jbake-date: 2016-03-17 +:jbake-type: post +:jbake-tags: website +:jbake-status: published +:jbake-tomeepdf: + +Apache TomEE got a new website more modern and more user oriented. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/blog/2017/tomee-7.0.3-released.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/blog/2017/tomee-7.0.3-released.adoc b/src/main/jbake/content/blog/2017/tomee-7.0.3-released.adoc new file mode 100755 index 0000000..97fe733 --- /dev/null +++ b/src/main/jbake/content/blog/2017/tomee-7.0.3-released.adoc @@ -0,0 +1,106 @@ += TomEE 7.0.3 Released +:jbake-date: 2017-03-13 +:jbake-type: post +:jbake-tags: website +:jbake-status: published +:jbake-tomeepdf: + +Aapche TomEE 7.0.3 just got released. It is available as usual on central +or our download page. + +Most significant changes are linked to the dependency upgrades but several bugfixes can be interesting as well. + +The release note is the following one: + + +== Bug + + +* link::https://issues.apache.org/jira/browse/TOMEE-1874[TOMEE-1874] - Do not inject CDI if the application is being undeployed + +* link::https://issues.apache.org/jira/browse/TOMEE-1897[TOMEE-1897] - CdiResourceProvider masks critical error in InjectionException + +* link::https://issues.apache.org/jira/browse/TOMEE-1965[TOMEE-1965] - EntityManager(Factory) (and EntityManagerFactoryCallable) not serializable + +* link::https://issues.apache.org/jira/browse/TOMEE-1967[TOMEE-1967] - ObserverManager uses printStackTrace instead of logger.error + +* link::https://issues.apache.org/jira/browse/TOMEE-1969[TOMEE-1969] - Embedded maven plugin fails with java.lang.NoClassDefFoundError: org/apache/commons/beanutils/BeanUtils + +* link::https://issues.apache.org/jira/browse/TOMEE-1970[TOMEE-1970] - Configuration error can cause infinite loop + +* link::https://issues.apache.org/jira/browse/TOMEE-1972[TOMEE-1972] - dont initialize SystemInstance reading openejb.io.util.timeout + +* link::https://issues.apache.org/jira/browse/TOMEE-1975[TOMEE-1975] - authorization should be removed from the url for openejb-client + +* link::https://issues.apache.org/jira/browse/TOMEE-1982[TOMEE-1982] - @RunAs should only apply to nested calls, not the declaring bean ones + +* link::https://issues.apache.org/jira/browse/TOMEE-1983[TOMEE-1983] - NullPointerException is thrown from a consumer created by JMSContext when queue is empty + +* link::https://issues.apache.org/jira/browse/TOMEE-1992[TOMEE-1992] - JMSContext is not serializable, causing problems for Session and Transaction Scoped CDI beans + +* link::https://issues.apache.org/jira/browse/TOMEE-1993[TOMEE-1993] - When using symbolic links the @WebServlet is not processed + +* link::https://issues.apache.org/jira/browse/TOMEE-1998[TOMEE-1998] - moviefun-rest example not working with Tomee 7 + +* link::https://issues.apache.org/jira/browse/TOMEE-2007[TOMEE-2007] - CUTask (ManagedExecutorService) can lead to NPE used from an EJB + +* link::https://issues.apache.org/jira/browse/TOMEE-2009[TOMEE-2009] - openejb.jpa.auto-scan should also add @Converter classes + +* link::https://issues.apache.org/jira/browse/TOMEE-2012[TOMEE-2012] - JPA 2.1 providers not always recognized + +* link::https://issues.apache.org/jira/browse/TOMEE-2016[TOMEE-2016] - 7.0.2 (plus) Batch fails before batch starting + +* link::https://issues.apache.org/jira/browse/TOMEE-2018[TOMEE-2018] - connectionFactoryLookup and destinationLookup not supported for mdbs + + + +== Dependency upgrade + +* link::https://issues.apache.org/jira/browse/TOMEE-1966[TOMEE-1966] - tomcat 8.5.11 + +* link::https://issues.apache.org/jira/browse/TOMEE-1986[TOMEE-1986] - johnzon 1.0.0 + +* link::https://issues.apache.org/jira/browse/TOMEE-1987[TOMEE-1987] - geronimo transaction/connector 3.1.4 + +* link::https://issues.apache.org/jira/browse/TOMEE-1990[TOMEE-1990] - JCS 2.0 + +* link::https://issues.apache.org/jira/browse/TOMEE-1994[TOMEE-1994] - Outdated serp version: Entites with Java 8 features not mapped + +* link::https://issues.apache.org/jira/browse/TOMEE-1996[TOMEE-1996] - OpenJPA 2.4.2 + +* link::https://issues.apache.org/jira/browse/TOMEE-1997[TOMEE-1997] - OpenWebBeans 1.7.2 + +* link::https://issues.apache.org/jira/browse/TOMEE-2010[TOMEE-2010] - cxf 3.1.10 + +* link::https://issues.apache.org/jira/browse/TOMEE-2011[TOMEE-2011] - activemq 5.14.3 + +* link::https://issues.apache.org/jira/browse/TOMEE-2015[TOMEE-2015] - jcs 2.1 + + + +== Improvement + +* link::https://issues.apache.org/jira/browse/TOMEE-1976[TOMEE-1976] - http ejbd client doesnt throw AuthorizationException for 401 errors + +* link::https://issues.apache.org/jira/browse/TOMEE-1981[TOMEE-1981] - Allow to disable TomEEJohnzonProvider + +* link::https://issues.apache.org/jira/browse/TOMEE-2008[TOMEE-2008] - when a lot of @PersistenceContext are in the app, org.apache.openejb.assembler.classic.EntityManagerFactoryCallable#getProvider makes startup slower + + + +== New Feature + +* link::https://issues.apache.org/jira/browse/TOMEE-1980[TOMEE-1980] - basic.username and basic.password support for http ejbd client + +* link::https://issues.apache.org/jira/browse/TOMEE-1991[TOMEE-1991] - add to org.apache.tomee.jul.handler.rotating.LocalFileHandler.PatternFormatter class and method as 7th and 8th parameters + +* link::https://issues.apache.org/jira/browse/TOMEE-2005[TOMEE-2005] - support to override arquillian protocol default value of adapters + + + +== Task + +* link::https://issues.apache.org/jira/browse/TOMEE-2002[TOMEE-2002] - use ClassUnwrapper from cxf to slowly replace ClassHelper + + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/blog/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/blog/index.adoc b/src/main/jbake/content/blog/index.adoc new file mode 100755 index 0000000..f6bf015 --- /dev/null +++ b/src/main/jbake/content/blog/index.adoc @@ -0,0 +1,6 @@ += Blog +:jbake-date: 2015-04-05 +:jbake-type: blog +:jbake-tags: website +:jbake-status: published +:jbake-tomeepdf: http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/community/commercial.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/community/commercial.adoc b/src/main/jbake/content/community/commercial.adoc new file mode 100755 index 0000000..bd6c3cf --- /dev/null +++ b/src/main/jbake/content/community/commercial.adoc @@ -0,0 +1,31 @@ += Commercial Support +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +This page is dedicated to companies offering products and services around or including Apache TomEE. + +The Apache TomEE PMC does not endorse or recommend any of the products or services on this page. We love all our supporters equally. + +Want to be added to this page? See at the bottom. + +=== Tomitribe + +Tomitribe is a company created by several founding members of the Apache TomEE community with the mission of uniting businesses using TomEE with responsible and sustainable Open Source. Our goal is to support both the community and fuel the success of business that rely TomEE with a complete set of consulting, training, and commercial support. + + +=== ManageCat + +ManageCat is a cloud management and service platform for Apache Tomcat and Apache TomEE servers. Involving with a lot of Apache Java EE projects, we want to transfer not only our knowledge about Apache TomEE and also other Java EE technologies including JPA, EJB, CDI, JSF, JSTL, JTA, JMS. We will help our customers to develop and deploy their production based Java EE applications smoothly. + +=== I want to be added there + +To be listed in the Commercial Support send a link:../security/support.html[mail] to the Apache TomEE PMC with a description of your offerings and the text you would like to have added. + +==== Policy for additions +The Apache TomEE PMC does not and cannot endorse or recommend any products or services. + +All submitted information must be factual and informational in nature and not be a marketing statement. Statements that promote your products and services over other offerings on the page will not be tolerated and will be removed. Such marketing statements can be added to your own pages on your own site. + +When in doubt, email the Apache TomEE PMC list (see link:../security/support.html[Mailing Lists]) and ask. We are be happy to help. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/community/contributors.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/community/contributors.adoc b/src/main/jbake/content/community/contributors.adoc new file mode 100755 index 0000000..1a700de --- /dev/null +++ b/src/main/jbake/content/community/contributors.adoc @@ -0,0 +1,35 @@ += Wall of fame +:jbake-date: 2016-03-16 +:jbake-type: contributors +:jbake-status: published + +---- +a...@apache.org* | Alan Cabrera | https://twitter.com/maguro/profile_image?size=bigger +ammul...@apache.org* | Aaron Mulder | ../img/ammulder.png +agumbre...@tomitribe.com* +d...@iq80.com* +dblev...@apache.org* +djen...@apache.org* | David Jencks +d...@apache.org* | Daniel Stefan Haischt | https://twitter.com/uebermodean/profile_image?size=bigger +ga...@apache.org* | Jarek Gawor | https://twitter.com/jgawor/profile_image?size=bigger +gdam...@apache.org* | Gianny Damour | ../img/gdamour.jpg +genspr...@apache.org* | Lin Quan Jiang | ../img/genspring.jpg +hogst...@apache.org* | Matt Richard Hogstrom | https://twitter.com/hogstrom/profile_image?size=bigger +jgallim...@apache.org* | Jonathan Gallimore | https://twitter.com/jongallimore/profile_image?size=bigger +jgenen...@apache.org* | Jeff Genender | ../img/jgenender.jpg +jlaskow...@apache.org* | Jacek Laskowski | https://twitter.com/jaceklaskowski/profile_image?size=bigger +jlmonte...@apache.org* | Jean-Louis Monteiro | https://twitter.com/JLouisMonteiro/profile_image?size=bigger +jvan...@apache.org* +jwhitl...@apache.org* +ke...@apache.org* | Kevan Lee Miller | https://twitter.com/kevanmiller/profile_image?size=bigger +kma...@apache.org* | Karan Singh Malhi | https://twitter.com/KrnMal/profile_image?size=bigger +la...@apache.org* | Lajos Moczar +manugeo...@apache.org* | Manu George | ../img/manugeorge.jpg +mn...@apache.org* | Mohammad Nour El-Din | ../img/mnour.jpg +rickmcgu...@apache.org* | Rick McGuire | ../img/rickmcguire.jpg +rmannibu...@gmail.com* +strub...@yahoo.de* +tveron...@apache.org* +vishwana...@apache.org* | Vishwanath | https://twitter.com/stratwine/profile_image?size=bigger +xuhaih...@apache.org* | Haihong Xu | ../img/xuhaihong.jpg +---- http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/community/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/community/index.adoc b/src/main/jbake/content/community/index.adoc new file mode 100755 index 0000000..1e4fd22 --- /dev/null +++ b/src/main/jbake/content/community/index.adoc @@ -0,0 +1,30 @@ += Community +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published + +=== In code veritas est + +Want to grab TomEE source code and hack it? Nothing simpler, just go link:sources.html[there]. + +=== Contributors + +You can see our wall of fame on: link:contributors.html[TomEE Wall Of Fame]. + +=== Social Media: cause contributing is not only about coding + +Facebook, Twitter, Google+: if that speaks to you just follow this link:social.html[TomEE on Social Media]. + +=== Support + +For more information about available support for TomEE please have a look on link:../security/support.html[Support] page. + +=== Contribute the this website + +This website is a simple JBake project you can find at http://svn.apache.org/repos/asf/tomee/site/trunk/generators/site-tomee-ng/. + +For more information please have a look to http://svn.apache.org/repos/asf/tomee/site/trunk/generators/site-tomee-ng/README.adoc +and http://jbake.org/. + +To submit a change create a ticket on http://issues.apache.org/jira/browse/TOMEE and attach a diff +with the content. Then a committer will review it and redeploy the website using Apache CMS. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/community/social.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/community/social.adoc b/src/main/jbake/content/community/social.adoc new file mode 100755 index 0000000..2658ac9 --- /dev/null +++ b/src/main/jbake/content/community/social.adoc @@ -0,0 +1,17 @@ += Social +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:icons: font + +=== Facebook + +icon:facebook[size=2x] https://facebook.com/ApacheTomEE[TomEE @ Facebook] + +=== Twitter + +icon:twitter[size=2x] https://twitter.com/apachetomee[TomEE @ Twitter] + +=== Google+ + +icon:google-plus[size=2x] https://plus.google.com/communities/105208241852045684449[TomEE @ Goole+] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/community/sources.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/community/sources.adoc b/src/main/jbake/content/community/sources.adoc new file mode 100755 index 0000000..11c3de5 --- /dev/null +++ b/src/main/jbake/content/community/sources.adoc @@ -0,0 +1,63 @@ += Sources +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published + +=== Github + +TomEE is on Github at https://github.com/apache/tomee . The sources are synchronized by Apache on Github +but Pull/Requests are integrated with Apache Infrastructure which means you can just submit us a patch as +you would do on any Github project and Apache takes care of the rest of the process. + +=== Apache Git + +TomEE is using https://git-scm.com/[Git] as source content manager. + +The master sources are on https://git-wip-us.apache.org/repos/asf/tomee.git and you can clone them using the following command: + +[source] +---- +git clone https://git-wip-us.apache.org/repos/asf/tomee.git tomee-master +---- + +If you are interested in 1.7.x branch only just checkout the `tomee-1.7.x` branch: + +[source] +---- +git clone -b tomee-1.7.x https://git-wip-us.apache.org/repos/asf/tomee.git tomee-1.7.x +---- + +Master branch is the more up to date version of the codebase and currently targets TomEE 7.x branch. + +=== Building + +TomEE is a standard Maven project and to build it you just have to use the following command: + +[source] +---- +mvn clean install +---- + +TIP: you can need to tune your environment variable `MAVEN_OPTS`, a commonly use value is `-Xmx1536m -XX:PermSize=64m -XX:MaxPermSize=384m` + +NOTE: if you are interested in testing arquillian tests with all adapters of tomee you will need to activate the dedicated profile: `-Pall-adapters`. + +==== Fast build + +Here are some shortcut builds if you just want to create a specific artifact (note it skips tests but removing `-DskipTests` you will execute them): + +- TomEE zip/tar.gz: + +[source] +---- +mvn clean install -DskipTests -pl tomee/apache-tomee -am +---- + +Then TomEE archives are at `tomee/apache/tomee/target/apache-tomee-${classifier}-${version}.${extension}`. + +=== Continuous Integration + +TomEE is using Buildbot for its continuous integration. You can access main builds (Ubuntu ones) at these address: + +- https://ci.apache.org/builders/tomee-trunk-ubuntu[TomEE Master] +- https://ci.apache.org/builders/tomee-1.7.x-ubuntu[TomEE 1.7.x] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/classloading/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/classloading/index.adoc b/src/main/jbake/content/developer/classloading/index.adoc new file mode 100755 index 0000000..af1fe1f --- /dev/null +++ b/src/main/jbake/content/developer/classloading/index.adoc @@ -0,0 +1,59 @@ += TomEE ClassLoading +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE ClassLoading is directly mapped to Tomcat one. + +ifndef::backend-pdf[] + +[#filetree.col-md-3] +[ + { + label: 'JVM', + description: 'The JVM classloader launching tomcat main(String[])', + children: [ + { + label:'common.loader', + description:'Customizable in conf/catalina.properties, the common loader is the Tomcat classloader', + children: [ + { + label:'shared.loader', + description:'Optional layer where you can add libraries for the web applications not seen by Tomcat. It is generally not used and not encouraged since Tomcat 6', + children: [ + { + label:'webapp1', + description:'loader of one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar' + }, + { + label:'webapp2', + description:'loader of another one of your wars, it container WEB-INF/classes, WEB-INF/lib/*.jar' + }, + { + label:'application1', + description:'loader of another application, it can be an ear, it contains lib and ejbmodules of the ear', + children: [ + { + label:'earwebapp1', + description:'loader of one of the wars of the ear' + }, + { + label:'earwebapp2', + description:'loader of the other webapp of the ear' + } + ] + } + ] + } + ] + } + ] + } +] + +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary] +Click on the tree (JVM) on the left to see the detail there. + +endif::[] + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/configuration/cxf.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/configuration/cxf.adoc b/src/main/jbake/content/developer/configuration/cxf.adoc new file mode 100755 index 0000000..6da508b --- /dev/null +++ b/src/main/jbake/content/developer/configuration/cxf.adoc @@ -0,0 +1,94 @@ += TomEE and CXF Configuration +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE relies on Apache CXF for JAX-WS and JAX-RS, it doesn't provides all CXF modules but most comomn +ones for both specifications (JAX-RS is part of all distributions but JAX-WS is only part of plus one). + +== Configuration + +CXF API is reusable but you can also configure the interceptors through `openejb-jar.xml` (located in WEB-INF). + +If you want to configure JAX-RS you will use the prefix `cxf.jaxrs` and if you configure JAX-WS you use `cxf.jaxws` prefix. + +TIP: to configure directly the bus use `org.apache.openejb.cxf.bus.` prefix and configure it in `conf/system.properties`. + +To configure JAX-RS you need to add in `openejb-jar.xml` a `pojo-deployment`: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<openejb-jar> + <pojo-deployment class-name="jaxrs-application"> + <properties> + # here will go the config + </properties> + </pojo-deployment> +</openejb-jar> +---- + +For JAX-WS you will use a `pojo-deployment` matching the webservice class name for POJO webservices +or an `ejb-deployment` instead of a `pojo-deployment` for EJB webservices: + + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<openejb-jar> + <ejb-deployment ejb-name="MyEJBWebService"> + <properties> + # here will go the config + </properties> + </ejb-deployment> +</openejb-jar> +---- + +Then once you selected your prefix and know where to write the config just use the following entries: + +- properties: server factory properties +- features: CXF features +- in-interceptors: CXF in interceptors +- out-interceptors: CXF out interceptors +- in-fault-interceptors: CXF in interceptors for fault handling +- out-fault-interceptors: CXF out interceptors for fault handling +- databinding: server databinding +- providers (only for JAX-RS endpoint): list of JAX-RS providers +- skip-provider-scanning (only for JAX-RS): is provider scanning on or not (default true) + +For features and interceptors the rule is the same: value is a list comma separated. Each value of the list is either a qualified class name or an id of a service in resources.xml. + +Databinding is simply either a qualified name or a service id in resources.xml (located in WEB-INF). + +== Sample for JAX-WS + +To configure WSS4J on the EJB `CalculatorBean` for instance add in openejb-jar.xml: + +[source,xml] +---- +<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1";> + <ejb-deployment ejb-name="CalculatorBean"> + <properties> + cxf.jaxws.in-interceptors = wss4j + </properties> + </ejb-deployment> +</openejb-jar> +---- + +With associated resources.xml which will define precisely the `wss4j` configuration: + +[source,xml] +---- +<resources> + <Service id="wss4j" class-name="org.apache.openejb.server.cxf.config.WSS4JInInterceptorFactory" factory-name="create"> + action = UsernameToken + passwordType = PasswordText + passwordCallbackClass = org.superbiz.ws.security.PasswordCallbackHandler + </Service> +</resources> +---- + +== Sample for JAX-RS + +link:../json/index.html[JAX-RS JSON] page shows a sample dedicated to JAX-RS. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/ide/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/ide/index.adoc b/src/main/jbake/content/developer/ide/index.adoc new file mode 100755 index 0000000..2616b89 --- /dev/null +++ b/src/main/jbake/content/developer/ide/index.adoc @@ -0,0 +1,25 @@ += TomEE and IDE +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE is supported by main IDE of the marker: + +- https://eclipse.org/downloads/[Eclipse] +- https://www.jetbrains.com/idea/download/[Intellij Idea] +- https://netbeans.org/downloads/[Netbeans] + +=== Eclipse + +Be the first to write this part! + +=== Idea + +Be the first to write this part! + +=== Netbeans + +Be the first to write this part! + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/index.adoc b/src/main/jbake/content/developer/index.adoc new file mode 100755 index 0000000..181b700 --- /dev/null +++ b/src/main/jbake/content/developer/index.adoc @@ -0,0 +1,13 @@ += TomEE for Developers +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:classloading/index.html[All you need to know about TomEE classloading] +- link:ide/index.html[Eclipse, Intellij Idea, Netbeans]: TomEE in and IDE +- link:testing/index.html[TomEE and Testing] +- link:tools/index.html[TomEE and Tools] +- link:json/index.html[TomEE and JSON] +- link:configuration/cxf.html[TomEE CXF Configuration] +- link:migration/tomee-1-to-7.html[Migrating from TomEE 1 to 7] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/json/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/json/index.adoc b/src/main/jbake/content/developer/json/index.adoc new file mode 100755 index 0000000..ba39fb4 --- /dev/null +++ b/src/main/jbake/content/developer/json/index.adoc @@ -0,0 +1,206 @@ += TomEE and JSON +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +Since TomEE 7.0, TomEE comes with Apache Johnzon. +It means you can use JSON-P out of the box but also Johnzon Mapper +which is the default JAX-RS provider for JSON. + +IMPORTANT: this is a breaking change with 1.x which was using jettison. +This last one was relying on JAXB model to generate JSON which often led +to unexpected JSON tree and some unexpected escaping too. + +== Getting started with Johnzon Mapper + +http://johnzon.apache.org/ will get more informations than this quick +getting started but here are the basics of the mapping with Johnzon. + +The mapper uses a direct java to json representation. + +For instance this java bean: + +[source,java] +---- +public class MyModel { + private int id; + private String name; + + // getters/setters +} +---- + +will be mapped to: + +[source,java] +---- +{ + "id": 1234, + "name": "Johnzon doc" +} +---- + +Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations. + +=== @JohnzonIgnore + +@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the field until some version +if the mapper has a version: + +[source,java] +---- +public class MyModel { + @JohnzonIgnore + private String name; + + // getters/setters +} +---- + +Or to support name for version 3, 4, ... but ignore it for 1 and 2: + + +[source,java] +---- +public class MyModel { + @JohnzonIgnore(minVersion = 3) + private String name; + + // getters/setters +} +---- + +=== @JohnzonConverter + +Converters are used for advanced mapping between java and json. + +There are several converter types: + +1. Converter: map java to json and the opposite based on the string representation +2. Adapter: a converter not limited to String +3. ObjectConverter.Reader: to converter from json to java at low level +4. ObjectConverter.Writer: to converter from java to json at low level +4. ObjectConverter.Codec: a Reader and Writer + +The most common is to customize date format but they all take. For that simple case we often use a Converter: + +[source,java] +---- +public class LocalDateConverter implements Converter<LocalDate> { + @Override + public String toString(final LocalDate instance) { + return instance.toString(); + } + + @Override + public LocalDate fromString(final String text) { + return LocalDate.parse(text); + } +} +---- + +If you need a more advanced use case and modify the structure of the json (wrapping the value for instance) +you will likely need Reader/Writer or a Codec. + +Then once your converter developed you can either register globally on the MapperBuilder or simply decorate +the field you want to convert with @JohnzonConverter: + +[source,java] +---- +public class MyModel { + @JohnzonConverter(LocalDateConverter.class) + private LocalDate date; + + // getters/setters +} +---- + +=== @JohnzonProperty + +Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for instance). For that cases +@JohnzonProperty allows to customize the name used: + +[source,java] +---- +public class MyModel { + @JohnzonProperty("__date") + private LocalDate date; + + // getters/setters +} +---- + +=== AccessMode + +On MapperBuilder you have several AccessMode available by default but you can also create your own one. + +The default available names are: + +* field: to use fields model and ignore getters/setters +* method: use getters/setters (means if you have a getter but no setter you will serialize the property but not read it) +* strict-method (default based on Pojo convention): same as method but getters for collections are not used to write + +You can use these names with setAccessModeName(). + +=== Your own mapper + +Since johnzon is in tomee libraries you can use it yourself (if you use maven/gradle set johnzon-mapper as provided): + +[source,java] +---- +final MySuperObject object = createObject(); + +final Mapper mapper = new MapperBuilder().build(); +mapper.writeObject(object, outputStream); + +final MySuperObject otherObject = mapper.readObject(inputStream, MySuperObject.class); +---- + +== Johnzon and JAX-RS + +TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want however to customize it you need to follow this procedure: + +1. Create a WEB-INF/openejb-jar.xml: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<openejb-jar> + <pojo-deployment class-name="jaxrs-application"> + <properties> + # optional but requires to skip scanned providers if set to true + cxf.jaxrs.skip-provider-scanning = true + # list of providers we want + cxf.jaxrs.providers = johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper + </properties> + </pojo-deployment> +</openejb-jar> +---- + +2. Create a WEB-INF/resources.xml to define johnzon service which will be use to instantiate the provider + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<resources> + <Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider"> + # 1M + maxSize = 1048576 + bufferSize = 1048576 + + # ordered attributes + attributeOrder = $order + + # Additional types to ignore + ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody + </Service> + + <Service id="order" class-name="com.company.MyAttributeSorter" /> + +</resources> +---- + +Note: as you can see you mainly just need to define a service with the id johnzon (same as in openejb-jar.xml) +and you can reference other instances using $id for services and @id for resources. + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc b/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc new file mode 100644 index 0000000..5bf7153 --- /dev/null +++ b/src/main/jbake/content/developer/migration/tomee-1-to-7.adoc @@ -0,0 +1,33 @@ += Migrate from TomEE 1 to TomEE 7 +:jbake-date: 2017-06-17 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +== Breaking changes + +- Artifact coordinates changes + +GroupId changed from `org.apache.openejb` to `org.apache.tomee`. +It includes maven plugins which use now `org.apache.tomee.maven` and the `javaee-api`. + +Versions of openejb and tomee are now aligned on 7.x and you don't need to use +4.x and 1.x (or any variant) for openejb and tomee. + +- JAX-RS 2 specification refined the sorting of providers. It can have side effects for message body +readers/writers which don't define their target mediatype properly like Jackson which uses wildcard instead of +a json related mediatype. To solve it register a custom provider redefining the media type. + +Can be as easy as: + +[source,java] +---- +@Provider +@Consumes("application/json") +@Produces("application/json") +public class MyAppJsonProvider extends JacksonJsonProvider { +} +---- + +- JPA and CDI are linked now, enabling JPA to use CDI for its components but CDI can use JPA too... +to solve issues with hibernate you need to add either as system property or persistence unit `tomee.jpa.factory.lazy = true`. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc b/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc new file mode 100755 index 0000000..64b5e48 --- /dev/null +++ b/src/main/jbake/content/developer/testing/applicationcomposer/index.adoc @@ -0,0 +1,335 @@ += ApplicationComposer: The TomEE Swiss Knife +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +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: + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</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: + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</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: + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</groupId> + <artifactId>openejb-cxf</artifactId> + <version>${openejb.version></version> +</dependency> +---- + +=== 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 7.x: you can only write method(s) decorated with @Module +since TomEE 7.x: you can skip it and use @Classes directly on the ApplicationComposer class as a shortcut for: + +[source,java] +---- +@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: + +[source,java] +---- +@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: + +[source,java] +---- +@Configuration +public Properties configuration() { + return new PropertiesBuilder() + .p("db", "new://Resource?type=DataSource") + .p("db.JdbcUrld", "jdbc:hsqldb:mem:test") + .build(); +} +---- + +Since TomEE 7.x you can also put properties on ApplicationComposer class using @ContainerProperties API: + +[source,java] +---- +@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: + +[source,java] +---- +@Component +public SecurityService mockSecurity() { + return new MySecurityService(); +} +---- + +==== @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: + +[source,java] +---- +// 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: + +[source,java] +---- +// 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): + +[source,java] +---- +// 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): + +[source,java] +---- +@Module +@Classes(cdi = true, value = { C1.class, C2.class, E1.class }) +@Jars("deltaspike-") +public WebApp app() { + return new WebApp(); +} +---- + +==== @Default +@Default (openejb one not CDI one) 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. + + +=== How to run it? +==== JUnit +If you use JUnit you have mainly 2 solutions to run you "model" using the ApplicationComposer: + +using ApplicationComposer runner: + +[source,java] +---- +@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 7.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 7.x you can also use ApplicationComposers to directly run you ApplicationComposer model as a standalone application: + +[source,java] +---- +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 + +[source,java] +---- +@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 + } +} +---- + +=== Start and Deploy once + +When having a huge suite of test it can be long to start/deploy/undeploy/shutdown he container/application for each method. + +That's why `SingleApplicationComposerRunner` allows to just reuse the same instance accross several test. + +The first test will start and deploy the application and then other tests will reuse this instance until the JVM is destroyed +where the server/application will be undeployed/shutdown. + + +Here a simple usage: + +[source,java] +---- +import org.apache.openejb.testing.SingleApplicationComposerRunner; +// other imports + +@RunWith(SingleApplicationComposerRunner.class) +public class MyTest { + @Inject + private ACdiBean bean; + + @Application + private TheModel model; + + @Test + public void aTest() { + // ... + } +} +---- + +TIP: if you need a real TomEE container then you can have a look to `TomEEEmbeddedSingleRunner` which does deploys the classpath +using tomee-embedded. + +==== Configure what to deploy + +As all tests will reuse the same application the model (the class declaring the application with `@Classes`, `@Module` etc...) needs to be extracted from the test class itself. + +The application lookup uses this strategy (ordered): + +- the fully qualified name is read from the system property `tomee.application-composer.application` +- a *single* class decorated with `@Application` is looked in the jar/folder containing the test class + +If you have several "groups" you can use JUnit `@Category` to differentiate them and write one application class by category. Then +in `surefire` plugin you declare two `executions` enforcing the system property `tomee.application-composer.application` for each of them +and the associated `@Category`. + +==== Available injections + +- If the application model class uses `@RandomPort` then the test classes can get it as well +- CDI injections are supported +- `@Application` on a field allows to get the application model to get injected + +Compared to a standalone usage it misses all other EE injections (`@PersistenceContext`, `@Resource` etc... but you can inject them in the application model +and just expose them or wrap them in your tests thanks to the `@Application` field. + + +=== Going further +If you want to learn more about ApplicationComposer see link:../../../advanced/applicationcomposer/index.html[ApplicationComposer Advanced] page. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/testing/arquillian/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/arquillian/index.adoc b/src/main/jbake/content/developer/testing/arquillian/index.adoc new file mode 100755 index 0000000..16f0538 --- /dev/null +++ b/src/main/jbake/content/developer/testing/arquillian/index.adoc @@ -0,0 +1,421 @@ += TomEE and Arquillian +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE has several arquillian adapter flavors: + +- openejb-embedded: a plain embedded OpenEJB supporting most of EE features +- tomee-embedded: a full TomEE running in the same JVM +- tomee-remote: a standard TomEE running in its own process as in production +- tomee-webapp (not recommanded): an adapter starting from a Tomcat and installing tomee-webapp + +=== Embedded or Remote? + +Big advantage of embedded adapters is to be able to debug as usual. However it has few drawbacks which can make you +rething this choice: + +- JVM resources are available where it will likely not be the case in war mode (src/main/resources typically) +- You can mix server and client side features when writing a test +- Classloading is a bit different by design and less isolated (test dependencies) so you can get runtime surprises when really deploying + +To summarize: the choice is the trade off you choose between easiness and reality of the simulation. + +TIP: in TomEE build we build the same tests against all tomee adapters in the same build/module, this means you can use embedded adapter in dev +and activate remote tomee too (not only cause then if there is a failure you don't know if you missed it locally or if it is due +to the switch of adapter) on your continuous integration platform. + +NOTE: all configurations have defaults + +=== OpenEJB Embedded + +==== Coordinates + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</groupId> + <artifactId>arquillian-openejb-embedded</artifactId> + <version>${tomee7.version} +</dependency> +---- + +==== arquillian.xml + +|=== +|Name|Description +|properties|container properties, as in conf/system.properties (not in xml format) +|preloadClasses|some class to load (ie enforce static block initialization) +|startDefaultScopes|should CDI default scopes be started (includes @RequestScoped) +|singleDeploymentByArchiveName |names of archives (or true for all) to dploy a single time +|=== + +Sample: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> +<arquillian + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> + <container qualifier="openejb" default="true"> + <configuration> + <property name="properties"> + # used to not have a single DataSource and be able to test the resource resolution + db1 = new://Resource?type=DataSource + db1.JdbcUrl = jdbc:hsqldb:mem:db1 + + # will preload both classes, simple comma separated qualified names work too + openejb.arquillian.predeploy-archives = org.company.openejb.arquillian.openejb.archive.[SimpleArchive|SimpleArchive2] + </property> + </configuration> + </container> +</arquillian> +---- + +=== TomEE Embedded + +==== Coordinates + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</groupId> + <artifactId>arquillian-tomee-embedded</artifactId> + <version>${tomee7.version} +</dependency> +---- + +==== Configuration + +|=== +|Name|Description +| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) +| httpsPort | the HTTPS port +| httpPort | the HTTP port +| stopPort | the shutdown port +| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) +| appWorkingDir | where to dump applications (`@Deployment`) +| host | which host to use +| stopHost | which port to use to shutdown TomEE (port on Server configuration) +| stopCommand | which command to use to shutdown TomEE +| serverXml | where is the provided server.xml +| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used +| preloadClasses | which classes to initialize during container startup +| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) +| unsafeEjbd | should EJB allow all classes +| unpackWars | unpackWARs value in server.xml +| properties | container properties +| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner +| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set +| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key +| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key +|ssl| should https be activated +|withEjbRemote| should EJBd remote be activated +|keystoreFile | if ssl is set to true the keystore location +|keystorePass | if ssl is set to true the keystore password +|keystoreType | if ssl is set to true the keystore type +|clientAuth |should SSL connector use clientAuth +|keyAlias | if ssl is set to true the key to use +|sslProtocol | if ssl is set to true the protocol to use +|users |a map of users (properties syntax) +|roles |user roles (properties syntax) +|webResourcesCached |should resources be cached or not (`DefaultServlet` caching) +|=== + + +Sample: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<arquillian + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://jboss.org/schema/arquillian + http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> + <container qualifier="tomee" default="true"> + <configuration> + <property name="serverXml">conf/server.xml</property> + + <!-- port = -1 means random --> + <property name="httpPort">-1</property> + <property name="stopPort">-1</property> + + <!-- ssl --> + <property name="httpsPort">-1</property> + <property name="ssl">false</property> + <property name="keystoreFile">keystore-path</property> + <property name="keystorePass">changeit</property> + <property name="keystoreType">JKS</property> + <property name="clientAuth">false</property> + <property name="keyAlias">alias</property> + <property name="sslProtocol">protocol</property> + + <!-- where to create TomEE files --> + <property name="dir">target/tomee-embedded</property> + + <!-- where to dump on disk applications to deploy --> + <property name="appWorkingDir">target/working-dir</property> + + <!-- optional - limit the port allowed when random --> + <property name="portRange">20001-30000</property> + + <!-- container config --> + <property name="properties"> + # same as embedded case + </property> + + <!-- Deployer config --> + <property name="deployerProperties"> + # openejb.deployer.binaries.use=true + # openejb.deployer.forced.appId=[name] + # openejb.deployer.save-deployments=false + </property> + </configuration> + </container> +</arquillian> +---- + +=== TomEE Remote + +IMPORTANT: if a server is already started on host:port then it will be used instead of starting the configured TomEE type. + +To use a custom instance with arquillian ensure to have ejbd and tomee webapp activated. A way is to have in `conf/system.properties` these entries: + +[source] +---- +tomee.remote.support=true +openejb.system.apps=true + +# you can customize it depending the security level you need on the instance +tomee.serialization.class.whitelist = +tomee.serialization.class.blacklist = org.codehaus.groovy.runtime.,org.apache.commons.collections.functors.,org.apache.xalan,java.lang.Process +---- + +For really remote instances (= not on localhost) you need the `deployerProperties` of previous snippet too: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<arquillian + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://jboss.org/schema/arquillian + http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> + <container qualifier="tomee" default="true"> + <configuration> + <!-- ... --> + <property name="deployerProperties"> + openejb.deployer.binaries.use=true + openejb.deployer.save-deployments=false + </property> + </configuration> + </container> +</arquillian> +---- + +==== Coordinates + +[source,xml] +---- +<dependency> + <groupId>org.apache.tomee</groupId> + <artifactId>arquillian-tomee-remote</artifactId> + <version>${tomee7.version} +</dependency> +---- + +==== Configuration + +|=== +|Name|Description +| exportConfAsSystemProperty|export system properties with adapter prefix(es) (ex: httpPort will be set as tomee.httpPort) +| httpsPort | the HTTPS port +| httpPort | the HTTP port +| stopPort | the shutdown port +| dir | where to create the TomEE work dir (a fake file layout is created for Tomcat needs) +| appWorkingDir | where to dump applications (`@Deployment`) +| host | which host to use +| stopHost | which port to use to shutdown TomEE (port on Server configuration) +| stopCommand | which command to use to shutdown TomEE +| serverXml | where is the provided server.xml +| portRange | when port are set to -1 TomEE adapter will generate an available port, if specified the range will be used +| preloadClasses | which classes to initialize during container startup +| quickSession | should the session use a Random instead of SecureRandom (useful when the machine doesn't have a lot of entropy) +| unsafeEjbd | should EJB allow all classes +| unpackWars | unpackWARs value in server.xml +| properties | container properties +| webContextToUseWithEars |sometimes you can need this to adjust which context the adapter uses to find the ArquillianServletRunner +| keepServerXmlAsThis |don't replace ports etc in server.xml and use it like it has been provided when serverXml is set +| singleDumpByArchiveName | dump only once `@Deployment` archives using the name as key +| singleDeploymentByArchiveName |deploy only once `@Deployment` archives using the name as key +|groupId|the maven groupId of the TomEE (or not) artifact +|artifactId|the maven artifactId of the TomEE (or not) artifact +|version |the maven version of the TomEE (or not) artifact +|classifier |the maven classifier of the TomEE (or not) artifact +|type |the maven type of the TomEE (or not) artifact (should be zip) +|removeUnusedWebapps |should default webapps (ROOT, manager, ...) be removed +|ajpPort |the ajp port if used +|conf |a folder to synchronize with TomEE conf folder +|bin |a folder to synchronize with TomEE bin folder +|lib |a folder to synchronize with TomEE lib folder +|endorsed |a folder to synchronize with TomEE endorsed folder +|javaagent |a list (flat format) of javaagent to add when launching tomee, can use maven coordinates if prefixed with `mvn:` +|additionalLibs |a list (flat format) of library to add to TomEE libraries, can use paths of maven coordinates when prefixed with `mvn:` +|cleanOnStartUp |should TomEE folder be deleted on startup if exists +|debug |should the container run in debug mode (`-Dopenejb.server.debug=true` activates it without touching the configuration) +|debugPort |if activated which port to use to debug +|catalina_opts |equivalent to `CATALINA_OPTS` environment variable +|simple_log |should logs be inline +|deployerProperties |deployer properties, useful when not deploying on an instance managed by the build (remote instance typically) +|=== + + +Sample: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<arquillian + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://jboss.org/schema/arquillian + http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> + <container qualifier="tomee" default="true"> + <configuration> + <property name="serverXml">conf/server.xml</property> + + <!-- tomee zip to use --> + <property name="groupId">org.apache.tomee</property> + <property name="artifactId">apache-tomee</property> + <property name="version">LATEST</property> + <property name="type">zip</property> + + <!-- tomee provided files, ignored by default --> + <property name="bin">src/test/tomee/bin</property> + <property name="conf">src/test/tomee/conf</property> + <property name="lib">src/test/tomee/lib</property> + + <!-- + remote debugging, + -Dopenejb.server.debug can activate it too + --> + <property name="debug">false</property> + <property name="debugPort">5005</property> + + <!-- nice one line logging --> + <property name="simpleLog">true</property> + + <!-- jvm config --> + <property name="catalina_opts">-XX:-UseParallelGC</property> + + <!-- remove if exist --> + <property name="cleanOnStartUp">true</property> + + <!-- remove default webapps --> + <property name="removeunusedWebapps">true</property> + + <!-- port = -1 means random --> + <property name="httpPort">-1</property> + <property name="stopPort">-1</property> + + <!-- where to create TomEE --> + <property name="dir">target/apache-tomee</property> + + <!-- where to dump on disk applications to deploy --> + <property name="appWorkingDir">target/working-dir</property> + + <!-- optional - limit the port allowed when random --> + <property name="portRange">20001-30000</property> + + <!-- container config --> + <property name="properties"> + # same as embedded case + </property> + + <!-- we monitor the test with sirona --> + <property name="javaagent"> + mvn:org.apache.sirona:sirona-javaagent:0.2-incubating:jar:shaded + </property> + + <!-- Deployer config --> + <property name="deployerProperties"> + # openejb.deployer.binaries.use=true + # openejb.deployer.forced.appId=[name] + # openejb.deployer.save-deployments=false + </property> + + </configuration> + </container> +</arquillian> +---- + +=== Multiple instances + +With arquillian you can create cluster or isolated instances. Here is a sample `arquillian.xml`: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<arquillian xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + http://jboss.org/schema/arquillian + http://jboss.org/schema/arquillian/arquillian_1_0.xsd";> + <group qualifier="tomee-cluster"> + <container qualifier="tomee-1"> + <configuration> + <property name="httpPort">-1</property> + <property name="stopPort">-1</property> + <property name="ajpPort">-1</property> + <property name="dir">target/tomee1</property> + <property name="appWorkingDir">target/wd1</property> + </configuration> + </container> + <container qualifier="tomee-2"> + <configuration> + <property name="httpPort">-1</property> + <property name="stopPort">-1</property> + <property name="ajpPort">-1</property> + <property name="dir">target/tomee2</property> + <property name="appWorkingDir">target/wd2</property> + </configuration> + </container> + </group> +</arquillian> +---- + +Then in your test just specify the container you are testing against: + +[source,java] +---- +@RunWith(Arquillian.class) +public class MultipleTomEETest { + @Deployment(name = "war1", testable = false) + @TargetsContainer("tomee-1") + public static WebArchive war1() { + return /* ... */; + } + + @Deployment(name = "war2", testable = false) + @TargetsContainer("tomee-2") + public static WebArchive war2() { + return /* ... */; + } + + @Test + @OperateOnDeployment("war1") + public void testRunningInDep1( + @ArquillianResource URL url) { + // test on tomee 1, url is contextual + } + + @Test + @OperateOnDeployment("war2") + public void testRunningInDep1( + @ArquillianResource URL url) { + // test on tomee 1, url is contextual + } +} +---- http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/testing/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/index.adoc b/src/main/jbake/content/developer/testing/index.adoc new file mode 100755 index 0000000..66e562c --- /dev/null +++ b/src/main/jbake/content/developer/testing/index.adoc @@ -0,0 +1,9 @@ += TomEE and Testing +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:applicationcomposer/index.html[`ApplicationComposer`]: lightweight tests +- link:arquillian/index.html[Arquillian]: the de facto standard for EE tests +- link:other/index.html[Going futher]: OpenEJB JUnit, TomEE Embedded... http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/testing/other/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/testing/other/index.adoc b/src/main/jbake/content/developer/testing/other/index.adoc new file mode 100755 index 0000000..b1d41b1 --- /dev/null +++ b/src/main/jbake/content/developer/testing/other/index.adoc @@ -0,0 +1,134 @@ += Other Testing Techniques +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +=== EJBContainer + +The `EJBContainer` API is a JavaEE API enriched by some OpenEJB features to make the testing easier. + +It starts a container (embedded for case we are interested in) scanning the classpath. This operation can be +slow and if you go with this solution maybe think to start it only once for all tests. + +==== Sample + +[source,java] +---- +import org.junit.After; +import org.junit.AfterClass; +import org.junit.Before; +import org.junit.BeforeClass; +import org.junit.Test; + +import javax.ejb.embeddable.EJBContainer; +import javax.inject.Inject; +import javax.naming.NamingException; + +import static org.junit.Assert.assertTrue; + +public class ATest { + @Inject + private MyCDIBean aBean; + + @PersistenceContext + private EntityManager em; + + @Resource + private DataSource ds; + + @BeforeClass + public static void start() throws NamingException { + container = EJBContainer.createEJBContainer(); + } + + @AfterClass + public static void shutdown() { + if (container != null) { + container.close(); + } + } + + @Before + public void inject() throws NamingException { + container.getContext().bind("inject", this); + } + + @After + public void reset() throws NamingException { + container.getContext().unbind("inject"); + } + + @Test + public void aTest() { + // ... + } +} +---- + +It will use `createEJBContainer()` method to start the container and application, and `close()` to shutdown it. + +OpenEJB provides the `bind("inject")` hack to be able to get injection in the test class. + +=== OpenEJB JUnit + +`openejb-junit` is another artifact providing some facilities for testing. + +==== EJBContainer Rule + +[source,java] +---- +@Properties({ + @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"), + @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*openejb-junit.*") +}) +public class TestEJBContainerDefaultConfig { + @Rule + public final EJBContainerRule containerRule = new EJBContainerRule(this); + + @org.apache.openejb.junit.jee.resources.TestResource + private Context ctx; + + @org.apache.openejb.junit.jee.resources.TestResource + private java.util.Properties props; + + @org.apache.openejb.junit.jee.resources.TestResource + private EJBContainer container; + + + @Test + public void configIsHere() { + // ... + } +} + +---- + +TIP: there is the equivalent runner: `@RunWith(EJBContainerRunner.class)` + +==== InjectRule: injections for EJBContainerRule + +[source,java] +---- +@Properties({ + @Property(key = DeploymentFilterable.CLASSPATH_EXCLUDE, value = "jar:.*"), + @Property(key = DeploymentFilterable.CLASSPATH_INCLUDE, value = ".*myjar.*") +}) +public class TestEJBContainerRule { + @ClassRule + public static final EJBContainerRule CONTAINER_RULE = new EJBContainerRule(); + + @Rule + public final InjectRule injectRule = new InjectRule(this, CONTAINER_RULE); + + @EJB + private BasicEjbLocal ejb; + + @Test + public void aTest() { + // ... + } +} +---- + +TIP: an alternative in `openejb-core` is to use `org.apache.openejb.Injector.inject(instance)` http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/tools/gradle-plugins.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/gradle-plugins.adoc b/src/main/jbake/content/developer/tools/gradle-plugins.adoc new file mode 100755 index 0000000..fe43434 --- /dev/null +++ b/src/main/jbake/content/developer/tools/gradle-plugins.adoc @@ -0,0 +1,50 @@ += TomEE Gradle Plugin +:jbake-date: 2016-05-31 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE provides a gradle plugin for tomee-embedded "Ã la Jetty". + +[source,java] +---- +buildscript { + repositories { + mavenCentral() + } + + dependencies { + classpath 'org.apache.tomee.gradle:tomee-embedded:7.0.0' + } +} + +apply plugin: 'org.apache.tomee.tomee-embedded' + +// ... +---- + +Then just start tomee with: + +[source] +---- +gradle tomee-embedded -i +---- + +== Configuration + +All the configuration is optional. + +[source,java] +---- +// plugin setup +def tomeeEmbedded = extensions.getByName('tomee-embedded') +tomeeEmbedded.tomeeVersion = 'other version' +tomeeEmbedded.skipDefaultRepository = true // don't use central to retrieve tomee + +// container dependencies +def tomeeEmbeddedDeps = configurations.getByName('tomee-embedded') +// add dependencies you need to this configuration +---- + +tomee-embedded task has several more advanced configuration like tomee properties, modules to deploy etc... +Its configuration is pretty close to link:maven/embedded.html[Embedded Maven Plugin]. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/tools/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/index.adoc b/src/main/jbake/content/developer/tools/index.adoc new file mode 100755 index 0000000..713638e --- /dev/null +++ b/src/main/jbake/content/developer/tools/index.adoc @@ -0,0 +1,8 @@ += TomEE developer tools +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:maven-plugins.html[Maven Plugins] +- link:gradle-plugins.html[Gradle Plugin] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/tools/maven-plugins.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/maven-plugins.adoc b/src/main/jbake/content/developer/tools/maven-plugins.adoc new file mode 100755 index 0000000..3f335d2 --- /dev/null +++ b/src/main/jbake/content/developer/tools/maven-plugins.adoc @@ -0,0 +1,12 @@ += TomEE Maven Plugins +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE provides several maven plugins: + +- one for a link:maven/tomee.html[standalone TomEE] +- one for link:maven/embedded.html[TomEE embedded] +- one for link:maven/applicationcomposer.html[application composer] based applications +- Note: there is one for `EJBContainer` but this one is easily replaced by one of the previous in general http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc b/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc new file mode 100755 index 0000000..8694c37 --- /dev/null +++ b/src/main/jbake/content/developer/tools/maven/applicationcomposer.adoc @@ -0,0 +1,47 @@ += Application Composer Maven Plugin +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +This plugin has two goal: + +- `applicationcomposer:run`: to start the application from mvn command line +- `applicationcomposer:zip`: to package a zip with dependencies and start scripts + +IMPORTANT: the dependencies are retrieved with `MavenProject.getArtifacts()` which means you artifacts should be a `war` +- maven doesn't populate it with a `jar` - and the compile phase - at least - should be passed to ensure it is populated. + +=== Run goal configuration + +[source] +---- +mvn process-classes applicationcomposer:run -DskipTests +---- + +[.table.table-bordered,options="header"] +|=== +| Name | Default | Description +| args | - | a list of application arguments +|application|-|application qualified name +|binaries|${project.build.outputDirectory}|where is your module code (target/classes) +|mavenLog|true|force to use maven logging in openejb +|=== + +=== Zip goal configuration + +[source] +---- +mvn process-classes applicationcomposer:zip -DskipTests +---- + +[.table.table-bordered,options="header"] +|=== +| Name | Default | Description +|workDir|${project.build.directory}/${project.build.finalName}-applicationcomposer| where the container can "work" and create temp files +|zip|${project.build.directory}/${project.build.finalName}-applicationcomposer.zip| where to create the zip +|attach|true|attach the created artifact +|classifier|-|artifact classifier if needed +|application|-|application qualified name +|binaries|${project.build.outputDirectory}|where is your module code (target/classes) +|=== http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/developer/tools/maven/embedded.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/developer/tools/maven/embedded.adoc b/src/main/jbake/content/developer/tools/maven/embedded.adoc new file mode 100755 index 0000000..6e27054 --- /dev/null +++ b/src/main/jbake/content/developer/tools/maven/embedded.adoc @@ -0,0 +1,53 @@ += TomEE Embedded Maven Plugin +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE Embedded Maven plugin has a single goal: `tomee-embedded:run`. + +=== Configuration + +[.table.table-bordered,options="header"] +|=== +| Name | Default | Description +| warFile | ${project.build.directory}/${project.build.finalName} | where is the binary +| httpPort | 8080 | HTTP port +| httpsPort | 8443 | HTTPS port +| ajpPort | 8009 | AJP port +| stopPort | 8005 | shutdown port +| host | localhost | the server host +| dir | ${project.build.directory}/apache-tomee-embedded | the work directory +| keystoreFile | - | the keystore file for the HTTPS connector +| keystorePass | - | the keystore password for the HTTPS connector +| keystoreType | JKS | the keystore type for the HTTPS connector +| clientAuth | - | should HTTPS use client authentication +| keyAlias | - | the key to use for HTTPS +| sslProtocol | - | the protocol to use for SSL/HTTPS +| serverXml | - | a custom server.xml +| ssl | false | is HTTPS active +| withEjbRemote |false | is EJBd active +| quickSession | true | is sessions using Random instead of SecureRandom to generate id (faster but less secure, good for dev purposes) +| skipHttp | false | don't activate HTTP connector (allow to have only HTTPS for instance) +| classpathAsWar | false | deploy the classpath instead of the binary/war +| useProjectClasspath | true | in previous case use the project classpath and not plugin one +| webResourceCached | true | should web resources be cached +| modules | ${project.build.outputDirectory} | list of module to add to the classpath of the application +| docBase | ${project.basedir}/src/main/webapp | where is the docBase in classpath deployment mode (where are web resources) +| context | - | which context to use for the main artifact/deployment +| containerProperties | - | map of container properties +| mavenLog | true | should the plugin use maven logger instead of JUL +| keepServerXmlAsThis | false | don't apply port/host configuration to the server.xml if provided +| users | - | map of user/password +| roles | - | map of role/users +| forceJspDevelopment | true | ensure JSP are in development mode (updated) +| applications | - | list of applications to deploy +| applicationScopes | - | scope of the artifact to take into account for the classpath (ignore PROVIDED for instance) +| skipCurrentProject | - | don't deploy current project but only configured applications +| applicationCopyFolder | - | a folder containing applications +| workDir | - | tomee embedded work dir +| inlinedServerXml | - | server.xml content directly in the pom +| inlinedTomEEXml | - | tomee.xml content directly in the pom +| liveReload | - | livereload configuration if activated. This is an object containing these options: {watchedFolder: 'src/main/webapp', path: '/', port: 35729} +| withLiveReload | false | activate livereload for web resources +|===
