| = 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. |