http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/configuration/containers.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/configuration/containers.adoc b/src/main/jbake/content/admin/configuration/containers.adoc new file mode 100755 index 0000000..3d86272 --- /dev/null +++ b/src/main/jbake/content/admin/configuration/containers.adoc @@ -0,0 +1,585 @@ += Resources +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +All containers will be created automatically - which means you don't need to define them +if you don't need to tune their configuration - when a bean of their type if found. + +To avoid that use `openejb.offline` property and set it to `true`. See link:server.html[Server Configuration] for more detail. + +=== @Stateless + +A `@Stateless` container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="STATELESS"> + AccessTimeout = 30 seconds + MaxSize = 10 + MinSize = 0 + StrictPooling = true + MaxAge = 0 hours + ReplaceAged = true + ReplaceFlushed = false + MaxAgeOffset = -1 + IdleTimeout = 0 minutes + GarbageCollection = false + SweepInterval = 5 minutes + CallbackThreads = 5 + CloseTimeout = 5 minutes + UseOneSchedulerThreadByBean = false + EvictionThreads = 1 +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=STATELESS +Foo.AccessTimeout = 30 seconds +Foo.MaxSize = 10 +Foo.MinSize = 0 +Foo.StrictPooling = true +Foo.MaxAge = 0 hours +Foo.ReplaceAged = true +Foo.ReplaceFlushed = false +Foo.MaxAgeOffset = -1 +Foo.IdleTimeout = 0 minutes +Foo.GarbageCollection = false +Foo.SweepInterval = 5 minutes +Foo.CallbackThreads = 5 +Foo.CloseTimeout = 5 minutes +Foo.UseOneSchedulerThreadByBean = false +Foo.EvictionThreads = 1 +---- + +==== Configuration + +===== AccessTimeout + +Specifies the time an invokation should wait for an instance +of the pool to become available. + +After the timeout is reached, if an instance in the pool cannot +be obtained, the method invocation will fail. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +"1 hour and 27 minutes and 10 seconds" + +Any usage of the `javax.ejb.AccessTimeout` annotation will +override this setting for the bean or method where the +annotation is used. + +===== MaxSize + +Specifies the size of the bean pools for this stateless +SessionBean container. If StrictPooling is not used, instances +will still be created beyond this number if there is demand, but +they will not be returned to the pool and instead will be +immediately destroyed. + +===== MinSize + +Specifies the minimum number of bean instances that should be in +the pool for each bean. Pools are prefilled to the minimum on +startup. Note this will create start order dependencies between +other beans that also eagerly start, such as other `@Stateless` +beans with a minimum or `@Singleton` beans using `@Startup`. The +start order. + +The minimum pool size is rigidly maintained. Instances in the +minimum side of the pool are not eligible for `IdleTimeout` or +`GarbageCollection`, but are subject to `MaxAge` and flushing. + +If the pool is flushed it is immediately refilled to the minimum +size with `MaxAgeOffset` applied. If an instance from the minimum +side of the pool reaches its `MaxAge`, it is also immediately +replaced. Replacement is done in a background queue using the +number of threads specified by `CallbackThreads`. + +===== StrictPooling + +StrictPooling tells the container what to do when the pool +reaches it's maximum size and there are incoming requests that +need instances. + +With strict pooling, requests will have to wait for instances to +become available. The pool size will never grow beyond the the +set `MaxSize` value. The maximum amount of time a request should +wait is specified via the `AccessTimeout` setting. + +Without strict pooling, the container will create temporary +instances to meet demand. The instances will last for just one +method invocation and then are removed. + +Setting `StrictPooling` to `false` and `MaxSize` to `0` will result in +no pooling. Instead instances will be created on demand and live +for exactly one method call before being removed. + +===== MaxAge + +Specifies the maximum time that an instance should live before +it should be retired and removed from use. This will happen +gracefully. Useful for situations where bean instances are +designed to hold potentially expensive resources such as memory +or file handles and need to be periodically cleared out. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +`1 hour and 27 minutes and 10 seconds` + +===== ReplaceAged + +When `ReplaceAged` is enabled, any instances in the pool that +expire due to reaching their `MaxAge` will be replaced immediately +so that the pool will remain at its current size. Replacement +is done in a background queue so that incoming threads will not +have to wait for instance creation. + +The aim of his option is to prevent user requests from paying +the instance creation cost as `MaxAge` is enforced, potentially +while under heavy load at peak hours. + +Instances from the minimum side of the pool are always replaced +when they reach their `MaxAge`, this setting dictates the +treatment of non-minimum instances. + +===== ReplaceFlushed + +When `ReplaceFlushed` is enabled, any instances in the pool that +are flushed will be replaced immediately so that the pool will +remain at its current size. Replacement is done in a background +queue so that incoming threads will not have to wait for +instance creation. + +The aim of his option is to prevent user requests from paying +the instance creation cost if a flush performed while under +heavy load at peak hours. + +Instances from the minimum side of the pool are always replaced +when they are flushed, this setting dictates the treatment of +non-minimum instances. + +A bean may flush its pool by casting the `SessionContext` to +`Flushable` and calling `flush()`. See `SweepInterval` for details on +how flush is performed. + +[source,java] +---- +import javax.annotation.Resource; +import javax.ejb.SessionContext; +import javax.ejb.Stateless; +import java.io.Flushable; +import java.io.IOException; + +public class MyBean { + + private SessionContext sessionContext; + + public void flush() throws IOException { + + ((Flushable) sessionContext).flush(); + } +} +---- + +===== MaxAgeOffset + +Applies to MaxAge usage and would rarely be changed, but is a +nice feature to understand. + +When the container first starts and the pool is filled to the +minimum size, all those "minimum" instances will have the same +creation time and therefore all expire at the same time dictated +by the `MaxAge` setting. To protect against this sudden drop +scenario and provide a more gradual expiration from the start +the container will spread out the age of the instances that fill +the pool to the minimum using an offset. + +The `MaxAgeOffset` is not the final value of the offset, but +rather it is used in creating the offset and allows the +spreading to push the initial ages into the future or into the +past. The pool is filled at startup as follows: + +[source,java] +---- +for (int i = 0; i < poolMin; i++) { + long ageOffset = (maxAge / poolMin * i * maxAgeOffset) % maxAge; + pool.add(new Bean(), ageOffset)); +} +---- + +The default `MaxAgeOffset` is -1 which causes the initial +instances in the pool to live a bit longer before expiring. As +a concrete example, let's say the MinSize is 4 and the MaxAge is +100 years. The generated offsets for the four instances created +at startup would be 0, -25, -50, -75. So the first instance +would be "born" at age 0, die at 100, living 100 years. The +second instance would be born at -25, die at 100, living a total +of 125 years. The third would live 150 years. The fourth 175 +years. + +A `MaxAgeOffset` of 1 would cause instances to be "born" older +and therefore die sooner. Using the same example `MinSize` of 4 +and `MaxAge` of `100 years`, the life spans of these initial four +instances would be 100, 75, 50, and 25 years respectively. + +A `MaxAgeOffset` of 0 will cause no "spreading" of the age of the +first instances used to fill the pool to the minimum and these +instances will of course reach their MaxAge at the same time. +It is possible to set to decimal values such as -0.5, 0.5, -1.2, +or 1.2. + +===== IdleTimeout + +Specifies the maximum time that an instance should be allowed to +sit idly in the pool without use before it should be retired and +removed. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +"1 hour and 27 minutes and 10 seconds" + +===== GarbageCollection + +Allows Garbage Collection to be used as a mechanism for shrinking +the pool. When set to true all instances in the pool, excluding +the minimum, are eligible for garbage collection by the virtual +machine as per the rules of `java.lang.ref.SoftReference` and can be +claimed by the JVM to free memory. Instances garbage collected +will have their `@PreDestroy` methods called during finalization. + +In the OpenJDK VM the `-XX:SoftRefLRUPolicyMSPerMB` flag can adjust +how aggressively SoftReferences are collected. The default +OpenJDK setting is 1000, resulting in inactive pooled instances +living one second of lifetime per free megabyte in the heap, which +is very aggressive. The setting should be increased to get the +most out of the `GarbageCollection` feature of the pool. Much +higher settings are safe. Even a setting as high as 3600000 (1 +hour per free MB in the heap) does not affect the ability for the +VM to garbage collect SoftReferences in the event that memory is +needed to avoid an `OutOfMemoryException`. + +===== SweepInterval + +The frequency in which the container will sweep the pool and +evict expired instances. Eviction is how the `IdleTimeout`, +`MaxAge`, and pool "flush" functionality is enforced. Higher +intervals are better. + +Instances in use are excluded from sweeping. Should an instance +expire while in use it will be evicted immediately upon return +to the pool. Effectively `MaxAge` and flushes will be enforced as +a part of normal activity or sweeping, while IdleTimeout is only +enforcable via sweeping. This makes aggressive sweeping less +important for a pool under moderate load. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +`1 hour and 27 minutes and 10 seconds` + +===== CallbackThreads + +When sweeping the pool for expired instances a thread pool is +used to process calling `@PreDestroy` on expired instances as well +as creating new instances as might be required to fill the pool +to the minimum after a Flush or `MaxAge` expiration. The +`CallbackThreads` setting dictates the size of the thread pool and +is shared by all beans deployed in the container. + +===== CloseTimeout + +PostConstruct methods are invoked on all instances in the pool +when the bean is undeployed and its pool is closed. The +`CloseTimeout` specifies the maximum time to wait for the pool to +close and `PostConstruct` methods to be invoked. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +`1 hour and 27 minutes and 10 seconds` + +===== UseOneSchedulerThreadByBean + +back to previous behavior (TomEE 1.x) where 1 scheduler thread was used for stateless eviction +by bean (ie for 500 stateless beans you get 500 eviction threads) + +===== EvictionThreads + +number of threads to associate to eviction threads (1 is not bad for most applications) + + +=== @Stateful + +A `@Stateful` container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="STATEFUL"> + AccessTimeout = 30 seconds + Cache = org.apache.openejb.core.stateful.SimpleCache + Passivator = org.apache.openejb.core.stateful.SimplePassivater + TimeOut = 20 + Frequency = 60 + Capacity = 1000 + BulkPassivate = 100 +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=STATEFUL +Foo.AccessTimeout = 30 seconds +Foo.Cache = org.apache.openejb.core.stateful.SimpleCache +Foo.Passivator = org.apache.openejb.core.stateful.SimplePassivater +Foo.TimeOut = 20 +Foo.Frequency = 60 +Foo.Capacity = 1000 +Foo.BulkPassivate = 100 +---- + +==== Configuration + +===== AccessTimeout + +Specifies the maximum time an invocation could wait for the +`@Stateful` bean instance to become available before giving up. + +After the timeout is reached a `javax.ejb.ConcurrentAccessTimeoutException` +will be thrown. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +"1 hour and 27 minutes and 10 seconds" + +Any usage of the `javax.ejb.AccessTimeout` annotation will +override this setting for the bean or method where the +annotation is used. + +===== Cache + +The cache is responsible for managing stateful bean +instances. The cache can page instances to disk as memory +is filled and can destroy abandoned instances. A different +cache implementation can be used by setting this property +to the fully qualified class name of the Cache implementation. + +===== Passivator + +The passivator is responsible for writing beans to disk +at passivation time. Different passivators can be used +by setting this property to the fully qualified class name +of the `PassivationStrategy` implementation. The passivator +is not responsible for invoking any callbacks or other +processing, its only responsibly is to write the bean state +to disk. + +Known implementations: + +- org.apache.openejb.core.stateful.RAFPassivater +- org.apache.openejb.core.stateful.SimplePassivater + +===== TimeOut + +Specifies the time a bean can be idle before it is removed by the container. + +This value is measured in minutes. A value of 5 would +result in a time-out of 5 minutes between invocations. +A value of -1 would mean no timeout. +A value of 0 would mean a bean can be immediately removed by the container. + +Any usage of the `javax.ejb.StatefulTimeout` annotation will +override this setting for the bean where the annotation is used. + +===== Frequency + +Specifies the frequency (in seconds) at which the bean cache is checked for +idle beans. + +===== Capacity + +Specifies the size of the bean pools for this +stateful SessionBean container. + +===== BulkPassivate + +Property name that specifies the number of instances +to passivate at one time when doing bulk passivation. + + +=== @Singleton + +A `@Singleton` container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="SINGLETON"> + AccessTimeout = 30 seconds +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=SINGLETON +Foo.AccessTimeout = 30 seconds +---- + +==== Configuration + +===== AccessTimeout + +Specifies the maximum time an invocation could wait for the +`@Singleton` bean instance to become available before giving up. + +After the timeout is reached a `javax.ejb.ConcurrentAccessTimeoutException` +will be thrown. + +Usable time units: nanoseconds, microsecons, milliseconds, +seconds, minutes, hours, days. Or any combination such as +`1 hour and 27 minutes and 10 seconds` + +Any usage of the `javax.ejb.AccessTimeout` annotation will +override this setting for the bean or method where the +annotation is used. + + +=== @MessageDriven + +A MDB container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="MESSAGE"> + ResourceAdapter = Default JMS Resource Adapter + MessageListenerInterface = javax.jms.MessageListener + ActivationSpecClass = org.apache.activemq.ra.ActiveMQActivationSpec + InstanceLimit = 10 + FailOnUnknowActivationSpec = true +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=MESSAGE +Foo.ResourceAdapter = Default JMS Resource Adapter +Foo.MessageListenerInterface = javax.jms.MessageListener +Foo.ActivationSpecClass = org.apache.activemq.ra.ActiveMQActivationSpec +Foo.InstanceLimit = 10 +Foo.FailOnUnknowActivationSpec = true +---- + +==== Configuration + +===== ResourceAdapter + +The resource adapter delivers messages to the container + +===== MessageListenerInterface + +Specifies the message listener interface handled by this container + +===== ActivationSpecClass + +Specifies the activation spec class + +===== InstanceLimit + +Specifies the maximum number of bean instances that are +allowed to exist for each MDB deployment. + +===== FailOnUnknowActivationSpec + +Log a warning if true or throw an exception if false is an activation spec can't be respected + + +=== @Managed + +A managed bean container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="MANAGED" /> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=MANAGED +---- + + +=== CMP entity + +A CMP bean container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="CMP_ENTITY"> + CmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=CMP_ENTITY +Foo.CmpEngineFactory = org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory +---- + +==== Configuration + +===== CmpEngineFactory + +The engine to use for this container. By default TomEE only provides the JPA implementation. + + +=== BMP entity + +A BMP entity container. + +Declarable in tomee.xml via + +[source,xml] +---- +<Container id="Foo" type="BMP_ENTITY"> + PoolSize = 10 +</Container> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Container?type=BMP_ENTITY +Foo.PoolSize = 10 +---- + +==== Configuration + +===== PoolSize + +Specifies the size of the bean pools for this +bmp entity container.
http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/configuration/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/configuration/index.adoc b/src/main/jbake/content/admin/configuration/index.adoc new file mode 100755 index 0000000..223d780 --- /dev/null +++ b/src/main/jbake/content/admin/configuration/index.adoc @@ -0,0 +1,24 @@ += Configuration +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +=== Container + +TomEE specific configuration (ie not inherited one from Tomcat) is based on properties. Therefore +you can fully configure TomEE using properties in `conf/system.properties`. +However for convenience it also provides a hybrid XML alternative a.k.a. `conf/tomee.xml`. + +- link:server.html[Server Configuration: Properties]. +- link:resources.html[Resources] +- link:containers.html[Containers] + +=== Application + +Some settings can be specific to applications, these ones are also properties based and +are read in `WEB-INF/application.properties`. When you can't use `tomee.xml` to configure +resources you can use `WEB-INF/resources.xml` which inherit from `tomee.xml` its syntax +but binds the resources to the application and reuses the application classloader. + +More about link:application.html[Container Configuration]. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/configuration/resources.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/configuration/resources.adoc b/src/main/jbake/content/admin/configuration/resources.adoc new file mode 100755 index 0000000..dc8d84a --- /dev/null +++ b/src/main/jbake/content/admin/configuration/resources.adoc @@ -0,0 +1,572 @@ += Resources +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +In TomEE resources are mainly "singleton" (understood as defined once per server or application). Technically +it can be anything but you will probably meet more Datasources than other type of resources. + + +Most resources will be created automatically if there is no matching resources - by name and type - +when an injection will be found. To avoid that use `openejb.offline` property and set it to `true`. +See link:server.html[Server Configuration] for more detail. + +=== Definition a resource: how does it work? + +Before all let see how properties syntax is equivalent to XML one (system.properties and tomee.xml typically). + +Properties syntax uses dot notation to represent setters/properties which are plain properties in XML syntax +and a URL syntax with query parameters to define the resource where it is directly the resource and tag attributes in XML. +Finally the id is an attribute in XML and the key of the resource definition in properties. + +Let see it with a sample, both delcarations are the same: + +[source,bash] +---- +myDataSource = new://Resource?type=DataSource +myDataSource.JdbcUrl = jdbc:hsqldb:mem:site +myDataSource.UserName = sa +---- + +[source,xml] +---- +<Resource id="myDataSource" type="DataSource"> + JdbcUrl = jdbc:hsqldb:mem:site + UserName = sa +</Resource> +---- + +One started you can get injected any resource using `@Resource`: + +[source,java] +---- +@Resource(name = "myDataSource") +private DataSource dataSource; +---- + +=== Factory syntax + +Here are the attributes of a resource: + +[.table.table-bordered,options="header"] +|=== +| Name | Optional |Description +| id | false | name of the resource, will match `openejb:Resource/id` in JNDI tree. +| provider | true | define a default resource definition using service-jar.xml +| class-name | true |specify which class to instantiate +| factory-name | true |specify which method to invoke on the class-name when specified to create the resource +| properties-provider | true |a class responsible to provide to tomee the properties to use, it can have a property `serviceId` to know which resource it is. +| classpath | true | a classpath to use to create the resource. Note: if not implementing an interface the resource will be isolated from the applications. +| aliases | true | other names for the resource, allows for instance to share the same pool for a datasource used with multiple names in applications. +| post-construct/pre-destroy | true | methods called when creating/destroying the resources. +| Lazy | true | for resources set them to be created when first accessed and not when deployed +|=== + +TomEE supports some implicit properties for resources but sometimes you just want to fully control the +resource and not use implicit properties which can be affected to a property which doesn't expect such a value (typically the case +if you create a custom Oracle datasource). For such case you can set `SkipImplicitAttributes` property to `true` and your resource +will ignore implicit properties. + +Implicit properties are: + +[.table.table-bordered,options="header"] +|=== +| Name | Description +| transactionManager | The JTA transaction manager +| ServiceId | the "id" of the resource (its name) +|=== + +In the same spirit you can skip properties fallback using `SkipPropertiesFallback` and setting it to `true`. It typically avoids to +fallback all unset properties (no matching property found) to a `Properties` instance and set it if one matching property is found. +In Oracle case for instance it matches the connection properties which can have side effects. + +===== Value ciphering + +The propertie values support ciphering using the syntax `cipher:{algorithm}:{cipheredValue}`, for instance `cipher:Static3DES:xMH5uM1V9vQzVUv5LG7YLA==` will +be read as `Passw0rd`. Ciphers can be computed using `tomee.sh` script: `${tomee.home}/bin/tomee.sh cipher Passw0rd`. + +=== Common Resources + +==== DataSources + +DataSources have defaults for all values and a default datasource can be provided automatically but if you want to +configure it here are the common properties: + +You can set the boolean `JtaManaged` to false if you don't want your datasource to be using JTA - if you manage transactions yourself. + +Then other configurations are linked the pool the datasource is using. By default TomEE uses https://tomcat.apache.org/tomcat-7.0-doc/jdbc-pool.html[tomcat-jdbc] but we also provide +https://commons.apache.org/proper/commons-dbcp/configuration.html[commons-dbcp] (2 for TomEE 7.x and 1 for TomEE 1.x). +The properties are then the related configurations with these particular +entries we try to keep in sync for both: + +[.table.table-bordered,options="header"] +|=== +| Name|Description +| JdbcDriver | the jdbc driver of the datasource +| JdbcUrl | the jdbc url of the datasource +| Username | the user to use +| Password | the password of the user +|=== + +===== Password and ciphering + +DataSource were the first resource to support password ciphering. Originally it was another property which is still supported. +It is called `PasswordCipher`. Its value is the ciphering algorithm and it affects the password value. However `cipher:xxx` +is still supported on `Password` value. Default `PasswordCipher` being `PlainText` it behaves as no ciphering is in place by default. + +Sample: + +[source,bash] +---- +ds = new://Resource?type=javax.sql.DataSource +# our password is "Passw0rd" +ds.Password = xMH5uM1V9vQzVUv5LG7YLA== +ds.PasswordCipher = Static3DES +---- + +===== Advanced DataSource configuration + +TomEE also provides few utilities you can add in DataSource properties: + +[.table.table-bordered,options="header"] +|=== +| Name | Description +| LogSql | Should SQL be logged (using TomEE logger) +| LogSqlPackages | if set the logging will show the matching packages (separated by comma) inline when logging the query, allows to know where a query comes from +| Flushable| if true the datasource can be casted as a Flushable to recreate the pool +| ResetOnError | if a `SQLException` happens the pool is automatically recreated. Configuration is either "true" to do it each time an exception occurs, `x` or `retry(x)` to do it and retry until maximum `x` times +| ResetOnErrorMethods | which methods are handled by ResetOnError +| TomEEProxyHandler | Custom `InvocationHandler` wrapping the datasource calls +| DataSourceCreator | which pool to use, `dbcp`, `tomcat`, `dbcp-alternative` (DBCP and TomEE proxying instead of DBCP JTA integration), `simple` (no pooling) +|=== + +===== DataSource and JTA + +`JtaManaged` determines wether or not this data source should be JTA managed +or user managed. If set to 'true' it will automatically be enrolled +in any ongoing transactions. Calling begin/commit/rollback or setAutoCommit +on the datasource or connection will not be allowed. If you need to perform +these functions yourself, set `JtaManaged` to `false` + +===== DataSource and JPA + +In terms of JPA persistence.xml: + +- `JtaManaged=true` can be used as a 'jta-data-source' +- `JtaManaged=false` can be used as a 'non-jta-data-source' + +=== ActiveMQResourceAdapter + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ActiveMQResourceAdapter"> + BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false + ServerUrl = vm://localhost?waitForStart=20000&async=true + DataSource = Default Unmanaged JDBC Database + StartupTimeout = 10 seconds +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ActiveMQResourceAdapter +Foo.BrokerXmlConfig = broker:(tcp://localhost:61616)?useJmx=false +Foo.ServerUrl = vm://localhost?waitForStart=20000&async=true +Foo.DataSource = Default Unmanaged JDBC Database +Foo.StartupTimeout = 10 seconds +---- + +==== Configuration + +===== BrokerXmlConfig + +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 + +===== ServerUrl + +Broker address + +===== DataSource + +DataSource for persistence messages + +===== StartupTimeout + +How long to wait for broker startup + + +=== javax.jms.ConnectionFactory + +An ActiveMQ (JMS) connection factory. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="javax.jms.ConnectionFactory"> + ResourceAdapter = Default JMS Resource Adapter + TransactionSupport = xa + PoolMaxSize = 10 + PoolMinSize = 0 + ConnectionMaxWaitTime = 5 seconds + ConnectionMaxIdleTime = 15 Minutes +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=javax.jms.ConnectionFactory +Foo.ResourceAdapter = Default JMS Resource Adapter +Foo.TransactionSupport = xa +Foo.PoolMaxSize = 10 +Foo.PoolMinSize = 0 +Foo.ConnectionMaxWaitTime = 5 seconds +Foo.ConnectionMaxIdleTime = 15 Minutes +---- + +==== Configuration + +===== ResourceAdapter + +An ActiveMQ (JMS) resource adapter. + +===== TransactionSupport + +Specifies if the connection is enrolled in global transaction +allowed values: `xa`, `local` or `none`. Default to `xa`. + +===== PoolMaxSize + +Maximum number of physical connection to the ActiveMQ broker. + +===== PoolMinSize + +Minimum number of physical connection to the ActiveMQ broker. + +===== ConnectionMaxWaitTime + +Maximum amount of time to wait for a connection. + +===== ConnectionMaxIdleTime + +Maximum amount of time a connection can be idle before being reclaimed. + + +=== javax.jms.Queue + +An ActiveMQ (JMS) queue. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="javax.jms.Queue"> + # not set means id + destination = +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=javax.jms.Queue +# not set means id +Foo.destination = +---- + +==== Configuration + +===== destination + +Specifies the name of the queue + + +=== javax.jms.Topic + +An ActiveMQ (JMS) topic. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="javax.jms.Topic"> + # not set means id + destination = +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=javax.jms.Topic +# not set means id +Foo.destination = +---- + +==== Configuration + +===== destination + +Specifies the name of the topic + + +=== org.omg.CORBA.ORB + +NOTE: to use it you need to add an implementation of corba. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="org.omg.CORBA.ORB" /> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=org.omg.CORBA.ORB +---- + + +=== javax.mail.Session + +A mail session. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="mail/mysession" type="javax.mail.Session"> + mail.transport.protocol = smtp + mail.smtp.host = smtp.provider.com + mail.smtp.auth = true + mail.smtp.starttls.enable = true + mail.smtp.port = 587 + mail.smtp.user = u...@provider.com + password = abcdefghij +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +mail/mysession = new://Resource?type=javax.mail.Session +mail/mysession.mail.transport.protocol = smtp +mail/mysession.mail.smtp.host = smtp.provider.com +mail/mysession.mail.smtp.auth = true +mail/mysession.mail.smtp.starttls.enable = true +mail/mysession.mail.smtp.port = 587 +mail/mysession.mail.smtp.user = u...@provider.com +mail/mysession.password = abcdefghij +---- + +The properties are `javax.mail.Session` ones with the addition of `useDefault` which specifies if `getDefaultInstance()` +or `getInstance` is used to create the session. `getDefaultInstance()` will ensure that several calls are done with the +same configuration and return the same instance. For tomee it is likely better to rely on `getInstance()`(ie keep `useDefault` to false) +and use `aliases` option of the resource to define an alias if you need to share the same instance accross multiple names. + + +=== ManagedExecutorService + +A concurrency utility for EE executor service. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ManagedExecutorService"> + Core = 5 + Max = 25 + KeepAlive = 5 s + Queue = 15 + ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl + Lazy = true +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ManagedExecutorService +Foo.Core = 5 +Foo.Max = 25 +Foo.KeepAlive = 5 s +Foo.Queue = 15 +Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl +Foo.Lazy = true +---- + +==== Configuration + +===== Core + +The pool core size. + +===== Max + +The pool max size. + +===== KeepAlive + +The thread keep alive time (in duration format) + +===== Queue + +The queue type size. + +===== ThreadFactory + +The thread factory implementation class. + +===== Lazy + +If set to true the pool is created when first accessed otherwise it is created at startup. + + +=== ManagedScheduledExecutorService + +Inherit from `ManagedExecutorService` and adds scheduling abilities. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ManagedScheduledExecutorService"> + Core = 5 + ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl + Lazy = true +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ManagedScheduledExecutorService +Foo.Core = 5 +Foo.ThreadFactory = org.apache.openejb.threads.impl.ManagedThreadFactoryImpl +Foo.Lazy = true +---- + +==== Configuration + +See `ManagedExecutorService`. + + +=== ManagedThreadFactory + +A thread factory for a `ManagedExecutorService`. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ManagedThreadFactory"> + Prefix = openejb-managed-thread- + Lazy = true +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ManagedThreadFactory +Foo.Prefix = openejb-managed-thread- +Foo.Lazy = true +---- + +==== Configuration + +===== Prefix + +The thread prefix (suffixed with thread id). + + + +=== ContextService + +A concurrency utilities for JavaEE context service. It allows to create +contextual proxies (inheriting from security, classloader...contexts). + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ContextService" /> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ContextService +---- + + +=== JndiProvider: inject remote clients + +A thread factory for a `ManagedExecutorService`. +Default implementation is `org.apache.openejb.threads.impl.ManagedThreadFactoryImpl`. + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ManagedThreadFactory"> + Prefix = openejb-managed-thread- + Lazy = true +</Resource> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ManagedThreadFactory +Foo.Prefix = openejb-managed-thread- +Foo.Lazy = true +---- + +==== Configuration + +===== Prefix + +The thread prefix (suffixed with thread id). + + + +=== ContextService + +A concurrency utilities for JavaEE context service. It allows to create +contextual proxies (inheriting from security, classloader...contexts). + +Declarable in tomee.xml via + +[source,xml] +---- +<Resource id="Foo" type="ContextService" /> +---- + +Declarable in properties via + +[source,bash] +---- +Foo = new://Resource?type=ContextService +---- + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/configuration/server.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/configuration/server.adoc b/src/main/jbake/content/admin/configuration/server.adoc new file mode 100755 index 0000000..db2ff19 --- /dev/null +++ b/src/main/jbake/content/admin/configuration/server.adoc @@ -0,0 +1,86 @@ += Container Configuration +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +=== Server + +[.table.table-bordered,options="header"] +|=== +|Name |Value| Description +|openejb.embedded.remotable| bool| activate or not the remote services when available +|.bind, <service prefix>.port, <service prefix>.disabled, <service prefix>.threads | host or IP, port, bool|override the host. Available for ejbd and httpejbd services (used by jaxws and jaxrs), number of thread to manage requests +|openejb.embedded.initialcontext.close |LOGOUT or DESTROY| configure the hook called when closing the initial context. Useful when starting OpenEJB from a new InitialContext([properties]) instantiation. By default it simply logs out the logged user if it exists. DESTROY means clean the container. +|javax.persistence.provider |string| override the JPA provider value +|javax.persistence.transactionType |string| override the transaction type for persistence contexts +|javax.persistence.jtaDataSource |string| override the JTA datasource value for persistence contexts +|javax.persistence.nonJtaDataSource| string |override the non JTA datasource value for persistence contexts +|openejb.descriptors.output |bool| dump memory deployment descriptors. Can be used to set complete metadata to true and avoid scanning when starting the container or to check the used configuration. +|openejb.deployments.classpath.require.descriptor |CLIENT or EJB| can allow to filter what you want to scan (client modules or ejb modules) +|openejb.descriptors.output.folder| path| where to dump deployement descriptors if activated. +|openejb.strict.interface.declaration |bool| add some validations on session beans (spec validations in particular). false by default. +|openejb.conf.file or openejb.configuration| string| OpenEJB configuration file path +|openejb.debuggable-vm-hackery |bool| remove JMS informations from deployment +|openejb.validation.skip |bool |skip the validations done when OpenEJB deploys beans +|openejb.deployments.classpath.ear |bool| deploy the classpath as an ear +|openejb.webservices.enabled| bool |activate or not webservices +|openejb.validation.output.level| TERSE or MEDIUM or VERBOSE| level of the logs used to report validation errors +|openejb.user.mbeans.list * or a list of classes separated by ,| list of mbeans to deploy automatically +|openejb.deploymentId.format composition (+string) of {ejbName} {ejbType} {ejbClass} and {ejbClass.simpleName} default {ejbName}. The format to use to deploy ejbs. +|openejb.deployments.classpath |bool| whether or not deploy from classpath +|openejb.deployments.classpath.include and openejb.deployments.classpath.exclude |regex| regex to filter the scanned classpath (when you are in this case) +|openejb.deployments.package.include and openejb.deployments.package.exclude| regex| regex to filter scanned packages +|openejb.autocreate.jta-datasource-from-non-jta-one| bool| whether or not auto create the jta datasource if it doesn't exist but a non jta datasource exists. Useful when using hibernate to be able to get a real non jta datasource. +|openejb.altdd.prefix |string| prefix use for altDD (example test to use a test.ejb-jar.xml). +|org.apache.openejb.default.system.interceptors |class names|list of interceptor (qualified names) separated by a comma or a space add these interceptor on all beans +|openejb.jndiname.strategy.class |class name| an implementation of org.apache.openejb.assembler.classic.JndiBuilder.JndiNameStrategy +|openejb.jndiname.failoncollision| bool| if a NameAlreadyBoundException is thrown or not when 2 EJBs have the same name +|openejb.jndiname.format |string|composition of these properties: ejbType, ejbClass, ejbClass.simpleName, ejbClass.packageName, ejbName, deploymentId, interfaceType, interfaceType.annotationName, interfaceType.annotationNameLC, interfaceType.xmlName, interfaceType.xmlNameCc, interfaceType.openejbLegacyName, interfaceClass, interfaceClass.simpleName, interfaceClass.packageName default {deploymentId}{interfaceType.annotationName}. Change the name used for the ejb. +|openejb.org.quartz.threadPool.class |class| qualified name which implements org.quartz.spi.ThreadPool the thread pool used by quartz (used to manage ejb timers) +|openejb.localcopy |bool| default true. whether or not copy EJB arguments[/method/interface] for remote invocations. +|openejb.cxf.jax-rs.providers |string|the list of the qualified name of the JAX-RS providers separated by comma or space. Note: to specify a provider for a specific service suffix its class qualified name by ".providers", the value follow the same rules. Note 2: default is a shortcut for jaxb and json providers. +|openejb.wsAddress.format |string| composition of {ejbJarId}, ejbDeploymentId, ejbType, ejbClass, ejbClass.simpleName, ejbName, portComponentName, wsdlPort, wsdlService default /{ejbDeploymentId}. The WS name format. +|org.apache.openejb.server.webservices.saaj.provider| axis2, sun or null |specified the saaj configuration +|[<uppercase service name>.]<service id>.<name> or [<uppercase service name>.]<service id> |whatever is supported (generally string, int ...)| set this value to the corresponding service. example: [EnterpriseBean.]<ejb-name>.activation.<property>, [PERSISTENCEUNIT.]<persistence unit name>.<property>, [RESOURCE.]<name> +|log4j.category.OpenEJB.options| DEBUG, INFO, ... |active one OpenEJB log level. need log4j in the classpath +|openejb.jmx.active| bool| activate (by default) or not the OpenEJB JMX MBeans +|openejb.nobanner |bool| activate or not the OpenEJB banner (activated by default) +|openejb.check.classloader |bool| if true print some information about duplicated classes +|openejb.check.classloader.verbose| bool| if true print classes intersections +|openejb.additional.exclude |string separated by comma| list of prefixes you want to exclude and are not in the default list of exclusion +|openejb.additional.include |string separated by comma| list of prefixes you want to remove from thedefault list of exclusion +|openejb.offline |bool| if true can create datasources and containers automatically +|openejb.exclude-include.order| include-exclude or exclude-include| if the inclusion/exclusion should win on conflicts (intersection) +|openejb.log.color |bool| activate or not the color in the console in embedded mode +|openejb.log.color.<level in lowercase> |color in uppercase |set a color for a particular level. Color are BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, DEFAULT. +|tomee.serialization.class.blacklist| string |default list of packages/classnames excluded for EJBd deserialization (needs to be set on server and client sides). Please see the description of Ejbd Transport for details. +|tomee.serialization.class.whitelist| string| default list of packages/classnames allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on server and client sides). Please see the description of Ejbd Transport for details. +|tomee.remote.support |boolean |if true /tomee webapp is auto-deployed and EJBd is active (true by default for 1.x, false for 7.x excepted for tomee maven plugin and arquillian) +|openejb.crosscontext |bool| set the cross context property on tomcat context (can be done in the traditionnal way if the deployment is don through the webapp discovery and not the OpenEJB Deployer EJB) +|openejb.jsessionid-support |bool| remove URL from session tracking modes for this context (see javax.servlet.SessionTrackingMode) +|openejb.myfaces.disable-default-values |bool| by default TomEE will initialize myfaces with some its default values to avoid useless logging +|openejb.web.xml.major |int| major version of web.xml. Can be useful to force tomcat to scan servlet 3 annotatino when deploying with a servlet 2.x web.xml +|tomee.jaxws.subcontext |string| sub context used to bind jaxws web services, default is webservices +|openejb.servicemanager.enabled |bool| run all services detected or only known available services (WS and RS +|tomee.jaxws.oldsubcontext |bool| wether or not activate old way to bind jaxws webservices directly on root context +|openejb.modulename.useHash |bool| add a hash after the module name of the webmodule if it is generated from the webmodule location, it avoids conflicts between multiple deployment (through ear) of the same webapp. Note: it disactivated by default since names are less nice this way. +|openejb.session.manager |qualified name (string)| configure a session managaer to use for all contexts +|tomee.tomcat.resource.wrap |bool|wrap tomcat resources (context.xml) as tomee resources if possible (true by default) +|tomee.tomcat.datasource.wrap |bool|same as tomee.tomcat.resource.wrap for datasource (false by default). Note that setting it to true will create tomee datasources but can have the side effect to create twice singleton resources +|openejb.environment.default |bool|should default JMS resources be created or not, default to false to ensure no port is bound or multiple resources are created and completely uncontrolled (doesn't apply to datasources etc for compatibility). For tests only! +|=== + +=== Client + +[.table.table-bordered,options="header"] +|=== +|Name| Value |Description +|openejb.client.identityResolver |implementation of org.apache.openejb.client.IdentityResolver| default org.apache.openejb.client.JaasIdentityResolver. The class to get the client identity. +|openejb.client.connection.pool.timeout or openejb.client.connectionpool.timeout |int (ms)| the timeout of the client +|openejb.client.connection.pool.size or openejb.client.connectionpool.size |int| size of the socket pool +|openejb.client.keepalive |int (ms)| the keepalive duration +|openejb.client.protocol.version |string| Optional legacy server protocol compatibility level. Allows 4.6.x clients to potentially communicate with older servers. OpenEJB 4.5.2 and older use version "3.1", and 4.6.x currently uses version "4.6" (Default). This does not allow old clients to communicate with new servers prior to 4.6.0 +|tomee.serialization.class.blacklist| string |default list of packages/classnames excluded for EJBd deserialization (needs to be set on server and client sides). Please see the description of Ejbd Transport for details. +|tomee.serialization.class.whitelist| string| default list of packages/classnames allowed for EJBd deserialization (blacklist wins over whitelist, needs to be set on server and client sides). Please see the description of Ejbd Transport for details. +|=== http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/file-layout.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/file-layout.adoc b/src/main/jbake/content/admin/file-layout.adoc new file mode 100755 index 0000000..d2f2446 --- /dev/null +++ b/src/main/jbake/content/admin/file-layout.adoc @@ -0,0 +1,144 @@ += TomEE File Layout +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +ifndef::backend-pdf[] + +[#filetree.col-md-4] +[ + { + label: 'apps', + description: 'A common but optional folder containing the applications (war, ear, jar). Note: this folder needs to be activated in tomee.xml for instance and is not there by default.', + children: [ + {label:'module1.jar',description:'An ejbmodule'}, + {label:'myapp',description:'An exploded war or ear'}, + {label:'anotherapp.war',description:'A war'}, + {label:'anotherapp',description:'By default TomEE will explode the war next to the .war file, this is customizable.'}, + {label:'anotherapp2.ear',description:'An ear'}, + {label:'anotherapp2',description:'By default TomEE will explode the ear next to the .ear file, this is customizable.'} + ] + }, + { + label: 'bin', + description: 'The executable and boot related files', + children: [ + {label:'bootstrap.jar',description:'The jar allowing Tomcat to start'}, + {label:'catalina.bat',description:'The windows main Tomcat script'}, + {label:'catalina.bat.original',description:'The original catalina.bat from Tomcat. TomEE customizes it.'}, + {label:'catalina.sh',description:'The UNIx main Tomcat script'}, + {label:'catalina.sh.original',description:'The original catalina.sh from Tomcat. TomEE customizes it.'}, + {label:'catalina-tasks.xml',description:'Some Ant tasks Tomcat provides to work with JMX'}, + {label:'commons-daemon.jar',description:'When setting up TomEE as a service you need this jar.'}, + {label:'commons-daemon-native.tar.gz',description:'The native needed by commons-daemon'}, + {label:'configtest.bat',description:'A windows script to validate the server.xml'}, + {label:'configtest.sh',description:'A UNIx script to validate the server.xml'}, + {label:'daemon.sh',description:'A script which can be used as init.d script'}, + {label:'digest.bat',description:'A windows script to compute a digest'}, + {label:'digest.sh',description:'A UNIx script to compute a digest'}, + {label:'service.bat',description:'The windows service script'}, + {label:'service.install.as.admin.bat',description:'Install TomEE as a service on windows'}, + {label:'service.readme.txt',description:'The explanations on how to setup TomEE as a windows service'}, + {label:'service.remove.as.admin.bat',description:'Uninstall TomEE service on windows'}, + {label:'setclasspath.bat',description:'The script called by catalina.bat to initialize Tomcat classpath'}, + {label:'setclasspath.sh',description:'The script called by catalina.bat to initialize TomEE classpath'}, + {label:'setenv.sh',description:'A UNIx user script (optional) where you can specify some JVM options like CATALINA_OPTS environment variable'}, + {label:'setenv.bat',description:'A windows user script (optional) where you can specify some JVM options like CATALINA_OPTS environment variable'}, + {label:'shutdown.bat',description:'Stop the server on windows, it is commonly used with -force and a timeout as options'}, + {label:'shutdown.sh',description:'Stop the server on UNIx, it is commonly used with -force and a timeout as options'}, + {label:'startup.bat',description:'Start (and forget) TomEE on windows'}, + {label:'startup.sh',description:'Start (and forget) TomEE on UNIx'}, + {label:'tomcat-juli.jar',description:'The Tomcat Java Util Logging extensions which allow for instance to configure the logging per application'}, + {label:'tomcat-native.tar.gz',description:'The Tomcat native used by some connectors'}, + {label:'TomEE....exe',description:'TomEE windows executables when setup as a service for amd64 architectures'}, + {label:'tomee.bat',description:'TomEE utility script for windows, allows to compute ciphers for instance'}, + {label:'tomee.sh',description:'TomEE utility script for UNIx, allows to compute ciphers for instance'}, + {label:'tool-wrapper.bat',description:'Windows script calling Tomcat Tool utility. It executes a command line with Tomcat classloader.'}, + {label:'tool-wrapper.sh',description:'UNIx script calling Tomcat Tool utility. It executes a command line with Tomcat classloader.'}, + {label:'version.bat',description:'Print Tomcat version (for windows)'}, + {label:'version.sh',description:'Print Tomcat version (for UNIx)'} + ] + }, + { + label: 'conf', + description: 'Folder containing the configuration of TomEE', + children: [ + {label:'Catalina',description:'A folder where Tomcat can copy web application configuration (typically context.xml can be overriden from there)'}, + {label:'catalina.policy',description:'The server security policy rules'}, + {label:'catalina.properties',description:'The server boot configuration (classloader etc...)'}, + {label:'conf.d',description:'A TomEE folder where services can pick configuration'}, + {label:'context.xml',description:'The default context.xml configuration'}, + {label:'logging.properties',description:'The logging configuration for the server and applications (overridable)'}, + {label:'server.xml',description:'The server configuration (Host, Context, Valves, ...)'}, + {label:'server.xml.original',description:'The original server.xml, TomEE updates it to add its lifecycle manager.'}, + {label:'system.properties',description:'TomEE global configuration'}, + {label:'tomcat-users.xml',description:'The default location where tomcat stores users.'}, + {label:'tomcat-users.xml.original',description:'The Tomcat tomcat-users.xml (TomEE add comments)'}, + {label:'tomcat-users.xsd',description:'The XSD for tomcat-users.xml'}, + {label:'tomee.xml',description:'The TomEE configuration file, syntax is hybrid between XML and Properties and it is fully replaceable with system.properties but users generally prefer this file.'}, + {label:'web.xml',description:'The default web.xml'} + ] + }, + { + label: 'lib', + description: 'Folder containing TomEE binaries', + children: [ + {label:'*.jar',description:'Tomcat + TomEE libraries'} + ] + }, + { + label: 'logs', + description: 'Default location of log files', + children: [ + {label:'catalina.$day.log',description:'By default container logs go there'}, + {label:'xxx.2016-03-16.log',description:'By default application xxx logs go there (when using servlet API)'}, + {label:'localhost.$day.log',description:'By default host related logs go there'}, + {label:'localhost_access_log.$day.txt',description:'By default access logs (request the container processed) go there'} + ] + }, + { + label: 'temp', + description: 'Java temporary directory is redirected by default to this folder', + children: [ + {label:'OpenEJB-dejlzdbhjzbfrzeofrh',description:'A temporary file TomEE can create (suffix depends the startup) to check the instance'} + ] + }, + { + label: 'webapps', + description: 'Folder containing the web applications', + children: [ + {label:'myapp',description:'An exploded war'}, + {label:'anotherapp.war',description:'A war'}, + {label:'anotherapp',description:'By default TomEE will explode the war next to the .war file, this is customizable.'} + ] + }, + { + label: 'work', + description: 'Folder where Tomcat and TomEE can work', + children: [ + { + label:'Catalina',description:'By default Tomcat Engine is called Catalina. This folder matches engine name.', + children: [ + { + label:'localhost',description:'A folder by host by engine to seggregate data of each ones', + children: [ + { + label:'myapp',description:'An application deployed on the previous level host', + children: [ + { label:'org.apache.jsp.index_jsp.java',description:'The generated JSP source (index.jsp there)' }, + { label:'org.apache.jsp.index_jsp.class',description:'The compiled JSP binary' } + ] + } + ] + } + ] + } + ] + } +] + +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary] +Click on a tree node or open a folder to see the detail there. + +endif::[] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/admin/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/admin/index.adoc b/src/main/jbake/content/admin/index.adoc new file mode 100755 index 0000000..8ec3283 --- /dev/null +++ b/src/main/jbake/content/admin/index.adoc @@ -0,0 +1,9 @@ += TomEE Administration +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:file-layout.html[TomEE File Layout] +- link:configuration/index.html[Configuration Reference] +- link:cluster/index.html[Clustering] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/applicationcomposer/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/applicationcomposer/index.adoc b/src/main/jbake/content/advanced/applicationcomposer/index.adoc new file mode 100755 index 0000000..23e5156 --- /dev/null +++ b/src/main/jbake/content/advanced/applicationcomposer/index.adoc @@ -0,0 +1,76 @@ += Application Composer Advanced Usage +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +ApplicationComposer can be a way to run a JBatch not needing any HTTP connector. + +Here is an example making batch integration easy - note you can extract the generic part in a library very easily: + +TIP: if you didn't check yet BatchEE provides some standalone utilities for JBatch but the idea of this page can be reused for a lot of applications. + +[source,java] +---- +// helper class reusable for any batch +abstract class BatchApplication { + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("YYYYMMddHHmmss"); + + protected Report runBatch(final String batchName, final Properties config) { + final JobOperator operator = BatchRuntime.getJobOperator(); + final long id = operator.start(batchName, config); + Batches.waitForEnd(operator, id); + return new Report(operator.getJobExecution(id), operator.getParameters(id)); + } + + @Module // we enforce BatchEE to be initialized as an EJB context to get JNDI for JTA init, needed for TomEE 1 + public EjbModule ensureBatchEESetupIsDoneInTheRightContext() { + final EjbJar ejbJar = new EjbJar().enterpriseBean(new SingletonBean(BatchEEBeanManagerInitializer.class)); + + final Beans beans = new Beans(); + beans.addManagedClass(BatchEEBeanManagerInitializer.Init.class); + + final EjbModule ejbModule = new EjbModule(ejbJar); + ejbModule.setModuleId("batchee-shared-components"); + ejbModule.setBeans(beans); + return ejbModule; + } + + public static class Report { + private final JobExecution execution; + private final Properties properties; + + public Report(final JobExecution execution, final Properties properties) { + this.execution = execution; + this.properties = properties; + } + + public JobExecution getExecution() { + return execution; + } + + public Properties getProperties() { + return properties; + } + } +} + +@Classes(cdi = true, value = { MyFilter.class, MoveFile.class, InputFile.class, MyReader.class, LoggingListener.class }) +public class MyBatch extends BatchApplication { + private final Properties config; + + public Mybatch(final String[] args) { // main args + this.config = new Properties() {{ // create the batch config + setProperty("input-directory", args[0]); + }}; + } + + public Report execute(final String inputDirectory) { + return runBatch("sunstone", config); + } + + public static void main(final String[] args) throws Exception { + ApplicationComposers.run(MyBatch.class, args); + } +} +---- http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/client/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/client/index.adoc b/src/main/jbake/content/advanced/client/index.adoc new file mode 100644 index 0000000..3e78b33 --- /dev/null +++ b/src/main/jbake/content/advanced/client/index.adoc @@ -0,0 +1,7 @@ += Advanced +:jbake-date: 2016-10-14 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:jndi.html[JNDI clients] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/client/jndi.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/client/jndi.adoc b/src/main/jbake/content/advanced/client/jndi.adoc new file mode 100644 index 0000000..7a42782 --- /dev/null +++ b/src/main/jbake/content/advanced/client/jndi.adoc @@ -0,0 +1,116 @@ += Advanced +:jbake-date: 2016-10-14 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +TomEE has several JNDI client intended for multiple usages. + +== Default one + +In a standalone instance you generally don't need (or want) to specify anything +to do a lookup. Doing so you will inherit from the contextual environment: + +[source,java] +---- +final Context ctx = new InitialContext(); +ctx.lookup("java:...."); +---- + +== LocalInitialContextFactory + +This is the legacy context factory used by OpenEJB. It is still useful to fallback +on the "default" one in embedded mode where sometimes classloaders or libraries can mess +up the automatic conextual context. + +Usage: + +[source,java] +---- +Properties properties = new Properties(); +properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.LocalInitialContextFactory"); +final Context ctx = new InitialContext(properties); +ctx.lookup("java:...."); +---- + +This context factory supports few more options when *you boot the container* creating a context: + +|=== +| Name | Description +| openejb.embedded.remotable | true/false: starts embedded services +| Context.SECURITY_PRINCIPAL/Context.SECURITY_CREDENTIALS | the *global* security identity for the whole container +|=== + +IMPORTANT: `Context.SECURITY_*` shouldn't be used for runtime lookups with `LocalInitialContextFactory`, it would leak a security identity and make the runtime no more thread safe. +This factory was deprecated starting with 7.0.2 in favor of `org.apache.openejb.core.OpenEJBInitialContextFactory`. + +== OpenEJBInitialContextFactory + +This factory allows you to access local EJB and container resources. + +[source,java] +---- +Properties properties = new Properties(); +properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.core.OpenEJBInitialContextFactory"); +final Context ctx = new InitialContext(properties); +ctx.lookup("java:...."); +---- + +== RemoteInitialContextFactory + +Intended to be used to contact a remote server, the `org.apache.openejb.client.RemoteInitialContextFactory` relies on the provider url +to contact a tomee instance: + +[source,java] +---- +Properties p = new Properties(); +p.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.RemoteInitialContextFactory"); +p.put(Context.PROVIDER_URL, "failover:ejbd://192.168.1.20:4201,ejbd://192.168.1.30:4201"); + +final InitialContext remoteContext = new InitialContext(p); +ctx.lookup("java:...."); +---- + +Contrarly to local one, the remote factory supports `Context.SECURITY_*` options in a thread safe manner and you can do lookups at runtime using them. + +See link:../../admin/cluster/index.html[Cluster] page for more details on the options. + +=== Security + +The context configuration can take additional configuration to handle EJB security: + +[source] +---- +p.put("openejb.authentication.realmName", "my-realm"); // optional +p.put(Context.SECURITY_PRINCIPAL, "alfred"); +p.put(Context.SECURITY_CREDENTIALS, "bat"); +---- + +The realm will be used by JAAS to get the right LoginModules and principal/credentials to +do the actual authentication. + +==== HTTP case + +Often HTTP layer is secured and in this case you need to authenticate before the EJBd (remote EJB TomEE protocol) layer. +Thanks to TomEE/Tomcat integration login there will propagate to the EJBd context. + +This can be done passing the token you need to set as `Authorization` header in the `PROVIDER_URL`: + +[source] +---- +// tomee/openejb principal/credentials +p.put(Context.PROVIDER_URL, "http://localhost:8080/tomee/ejb?authorization=Basic%20dG9tZWU6b3BlbmVqYg==";); +---- + +The token passed as `authorization` query parameter is the header value URL encoded. It can +be any token like a basic one, a custom one, an OAuth2 one (in this case you need to renew it programmatically +and change your client instance when renewing) etc... + +TIP: basic being very common there is a shortcut with two alternate query parameter replacing `authorization` one: `basic.password` and `basic.username`. + +Finally if you don't use `Authorization` header you can change the used header setting `authorizationHeader` query parameter. + +NOTE: `authorization`, `authorizationHeader`, `basic.username`, and `basic.password` are removed +from the URL before opening the connection and therefore not logged in the remote server access log since version 7.0.3. + + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/index.adoc b/src/main/jbake/content/advanced/index.adoc new file mode 100755 index 0000000..6b3ba64 --- /dev/null +++ b/src/main/jbake/content/advanced/index.adoc @@ -0,0 +1,11 @@ += Advanced +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +- link:applicationcomposer/index.html[Use `ApplicationComposer` to write mains] +- link:setup/index.html[How to install TomEE properly] +- link:shading/index.html[Simple deployable: fat/uber jars] +- link:client/index.html[Clients (JNDI)] +- link:jms/jms-configuration.html[JMS Configuration Tips] http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/jms/jms-configuration.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/jms/jms-configuration.adoc b/src/main/jbake/content/advanced/jms/jms-configuration.adoc new file mode 100644 index 0000000..bd2fe16 --- /dev/null +++ b/src/main/jbake/content/advanced/jms/jms-configuration.adoc @@ -0,0 +1,67 @@ += JMS Configuration Tips +:jbake-date: 2017-02-22 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +== Why my ActiveMQ/JMS MDB is not scaling as expected? + +There are multiple configurations points to ensure you scale as much as you want. + +Here some common configuration to validate (note that when possible the sample value is the default): + +- The resource adapter thread pool ("worker threads" or `WorkManager`) limits the number of max work threads: + +[source,xml] +---- +<Resource id="my resource adapter" ....> + # using -1 will make the server using cached threads (unbounded) + # min recommanded: maxSessions + 1 (for connect()) + threadPoolSize = 30 +</Resource> +---- + +- Then the MDB container itself has a upper bound through `InstanceLimit` which controls the max MDB instance count: + +[source,xml] +---- +<Container id="my mdb container" type="MESSAGE"> + # -1 will disable it + # min recommanded = maxSessions + InstanceLimit = 10 +</Container> +---- + +- ActiveMQ `maxSessions` controls how many sessions a MDB can use: + +[source,java] +---- +@MessageDriven(activationConfig = { + @javax.ejb.ActivationConfigProperty(propertyName = "maxSessions", propertyValue = "1"), + @javax.ejb.ActivationConfigProperty(propertyName = "destination", propertyValue = "target-queue") +}) +public static class MyMdb implements MessageListener { + @Override + public void onMessage(final Message message) { + // ... + } +} +---- + +- The ConnectionFactory has also an instance pool through geronimo-connector logic, configuration + can make the behavior changing but this is controlled through pool related variables (the pool and resource properties are merged in the definition): + +[source,xml] +---- +<Resource id="my connection factory" type="ConnectionFactory"> + # recommanded to be aligned on maxSessions + PoolMaxSize = 10 + # for 100% MDB (no client) you can evaluate to turn it off/false, for client it can still be useful depending what you do + Pooling = true +</Resource> +---- + +== Slow consumption + +If you find you have a slow consumption of messages there are several options to have a look (activemq website explains it very well) +but one very impacting option can be the prefetch size. http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/setup/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/setup/index.adoc b/src/main/jbake/content/advanced/setup/index.adoc new file mode 100755 index 0000000..3eeb386 --- /dev/null +++ b/src/main/jbake/content/advanced/setup/index.adoc @@ -0,0 +1,142 @@ += How to Setup TomEE in production +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published + + +You can use TomEE as described on link:../../admin/file-layout.html[File Layout] page but in production it is better to +split TomEE and application binaries and configuration. + +Idea is to have this kind of layout (the root is the one you prefer): + +ifndef::backend-pdf[] + +[#filetree.col-md-4] +[{ + label: '/some/path', + description: 'any location on your file system', + children: [ + { + label: 'tomee', + description: 'all tomee binaries will be there, note: you often do the same for the JVM versions you have', + children: [ + { + label: 'tomee-1.7.1', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + }, + { + label: 'tomee-1.7.2', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + }, + { + label: 'tomee-7.0.0-M3', + description: 'a particular tomee version (just unzip it there)', + children: [ + { label: 'bin', description: 'the startup binaries/scripts' }, + { label: 'conf', description: 'default shared configuration for this version, can be overwritten by instance' }, + { label: 'lib', description: 'the binaries' } + ] + } + ] + }, + { + label: 'applications', + description: 'all applications', + children: [ + { + label: 'application1', + description: 'any application instance (ie configuration + binaries)', + children: [ + { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' }, + { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' }, + { label: 'lib', description: 'some additional binaries like JDBC drivers' }, + { label: 'logs', description: 'instances logs location' }, + { label: 'work', description: 'dedicated work directory' }, + { label: 'temp', description: 'instance temporary folder' }, + { label: 'webapps', description: 'instance webapp folder' } + ] + }, + { + label: 'application2', + description: 'any application instance (ie configuration + binaries)', + children: [ + { label: 'bin', description: 'provide scripts for this instance (see under that file layout)' }, + { label: 'conf', description: 'the instance configuration, typically what is in tomee/conf when used in standalone' }, + { label: 'lib', description: 'some additional binaries like JDBC drivers' }, + { label: 'logs', description: 'instances logs location' }, + { label: 'work', description: 'dedicated work directory' }, + { label: 'temp', description: 'instance temporary folder' }, + { label: 'webapps', description: 'instance webapp folder' } + ] + } + ] + } + ] +}] + + +[#filetreedetail.col-md-8.bs-callout.bs-callout-primary] +Click on a tree node or open a folder to see the detail there. + +[.clearfix] + + +endif::[] + +=== Instance scripts + +The idea for instances (applications) scripts is to simply delegate to tomcat ones but customizing the JVM and TomEE versions. + +Customizing the version (and locations) is done in `bin/setenv.sh` of instances. + +Here are an example for the common scripts (of course you can write helper version like restart etc). + +==== setenv.sh + +[source,bash] +---- +#! /bin/sh + +# which java +export JAVA_HOME="/some/path/java/jdk-8u60" +# which tomee +export CATALINA_HOME="/some/path/tomee/tomee-7.0.0-M3" +# where is the application - to let tomcat/tomee finds the configuration +export CATALINA_BASE="/some/path/application1/" +# to let tomee be able to kill the instance if shutdown doesn't work (see shutdown script) +export CATALINA_PID="/some/path/application1/work/tomee.pid" +---- + +==== startup + +[source,bash] +---- +#! /bin/bash + +proc_script_base="`cd $(dirname $0) && cd .. && pwd`" +source "$proc_script_base/bin/setenv.sh" +nohup "$CATALINA_HOME/bin/startup.sh" "$@" > $proc_script_base/logs/nohup.log & +---- + +==== shutdown + +[source,bash] +---- +#! /bin/bash + +proc_script_base="`cd $(dirname $0) && cd .. && pwd`" +source "$proc_script_base/bin/setenv.sh" +# we support parameters like timeout and force, typically we would call it this way: ./shutdown 1200 -force +"$CATALINA_HOME/bin/shutdown.sh" "$@" +---- + http://git-wip-us.apache.org/repos/asf/tomee-site-generator/blob/972cc356/src/main/jbake/content/advanced/shading/index.adoc ---------------------------------------------------------------------- diff --git a/src/main/jbake/content/advanced/shading/index.adoc b/src/main/jbake/content/advanced/shading/index.adoc new file mode 100755 index 0000000..22ac0c3 --- /dev/null +++ b/src/main/jbake/content/advanced/shading/index.adoc @@ -0,0 +1,278 @@ += TomEE Shading +:jbake-date: 2016-03-16 +:jbake-type: page +:jbake-status: published +:jbake-tomeepdf: + +== Fat Jars with Maven + +Shading the container and the application has some challenges like merging correctly resources (`META-INF/services/` typically). + +Here is a maven shade plugin configuration working for most cases: + +[source,xml] +---- +<plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-shade-plugin</artifactId> + <version>2.3</version> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>shade</goal> + </goals> + <configuration> + <dependencyReducedPomLocation>${project.build.directory}/reduced-pom.xml</dependencyReducedPomLocation> + <transformers> + <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> + <mainClass>org.apache.tomee.embedded.FatApp</mainClass> + </transformer> + <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer"> + <resource>META-INF/cxf/bus-extensions.txt</resource> + </transformer> + <transformer implementation="org.apache.openwebbeans.maven.shade.OpenWebBeansPropertiesTransformer" /> + </transformers> + <filters> + <filter> <!-- we don't want JSF to be activated --> + <artifact>*:*</artifact> + <excludes> + <exclude>META-INF/faces-config.xml</exclude> + </excludes> + </filter> + </filters> + </configuration> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.apache.openwebbeans</groupId> + <artifactId>openwebbeans-maven</artifactId> + <version>1.7.0/version> + </dependency> + </dependencies> +</plugin> +---- + +NOTE: see link:../tomee-embedded/index.html[TomEE Embedded] page for more information about tomee embedded options. + +IMPORTANT: this shade uses TomEE Embedded but you can do the same with an link:../applicationcomposer/index.html[Application Composer] application. + +TIP: if you have `META-INF/web-fragment.xml` in your application you will need to merge them in a single one in the shade. Note that tomcat provides one +which can be skipped in this operation since it is there only as a marker for jasper detection. + +Then just build the jar: + +[source,bash] +---- +mvn clean package +---- + +And you can run it: + +[source,bash] +---- +java -jar myapp-1.0-SNAPSHOT.jar +---- + +== Fat Jars with Gradle + +With gradle you can rely on either jar plugin, fatjar plugin or shadowjar plugin. Last one is likely the closer to maven shade plugin +so that's the one used for next sample: + +[source,groovy] +---- +// run $ gradle clean shadowJar +import org.apache.openwebbeans.gradle.shadow.OpenWebBeansPropertiesTransformer + +buildscript { + repositories { + mavenLocal() + jcenter() + } + dependencies { + classpath 'com.github.jengelman.gradle.plugins:shadow:1.2.3' + classpath 'org.apache.openwebbeans:openwebbeans-gradle:1.7.0' + } +} + +apply plugin: 'com.github.johnrengelman.shadow' + +group 'org.apache.tomee.demo.gradle' +version '1.0-SNAPSHOT' + +apply plugin: 'idea' +apply plugin: 'java' + +sourceCompatibility = 1.8 + +repositories { + mavenLocal() + mavenCentral() +} + +dependencies { + compileOnly 'org.projectlombok:lombok:1.16.10' + compile 'org.apache.tomee:tomee-embedded:7.0.2-SNAPSHOT' +} + +// customize exclusions depending your app + +// first the not used dependencies like JSF, JAXWS, JMS ones +def excludedDependenciesGroups = [ + // gradle is buggy with poms, scope provided and optional I think + 'com.google.code.findbugs', + 'com.google.guava', + 'javax.annotation', + 'javax.ws.rs', + 'net.sf.ehcache', + 'org.apache.httpcomponents', + 'org.ow2.asm', + // tomee jaxws, jms, etc... + 'commons-codec', + 'com.sun.xml.messaging.saaj', + 'joda-time', + 'junit', + 'net.shibboleth.utilities', + 'org.apache.activemq', + 'org.apache.activemq.protobuf', + 'org.apache.myfaces.core', + 'org.apache.neethi', + 'org.apache.santuario', + 'org.apache.ws.xmlschema', + 'org.apache.wss4j', + 'org.bouncycastle', + 'org.cryptacular', + 'org.fusesource.hawtbuf', + 'org.jasypt', + 'org.jvnet.mimepull', + 'org.opensaml', + 'wsdl4j', + 'xml-resolver' +] + +// then cxf+tomee specific dependencies so we need to be more precise than the group +// to not exclude everything +def excludedDependenciesArtifacts = [ + 'cxf-rt-bindings-soap', + 'cxf-rt-bindings-xml', + 'cxf-rt-databinding-jaxb', + 'cxf-rt-frontend-jaxws', + 'cxf-rt-frontend-simple', + 'cxf-rt-security-saml', + 'cxf-rt-ws-addr', + 'cxf-rt-wsdl', + 'cxf-rt-ws-policy', + 'cxf-rt-ws-security', + 'openejb-cxf', + 'openejb-webservices', + 'tomee-webservices', + 'geronimo-connector', + 'geronimo-javamail_1.4_mail' +] +shadowJar { + classifier = 'bundle' + + // merge SPI descriptors + mergeServiceFiles() + append 'META-INF/cxf/bus-extensions.txt' + transform(OpenWebBeansPropertiesTransformer.class) + + // switch off JSF + JMS + JAXWS + exclude 'META-INF/faces-config.xml' + dependencies { + exclude(dependency { + excludedDependenciesGroups.contains(it.moduleGroup) || + excludedDependenciesArtifacts.contains(it.moduleName) + }) + } + + // ensure we define the expected Main (if you wrap tomee main use your own class) + manifest { + attributes 'Main-Class': 'org.apache.tomee.embedded.FatApp' + } +} +---- + +Then run: + +[source] +---- +gradle clean build shadowJar +---- + +and you'll get `build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar` ready to run with: + +[source] +---- +java -jar build/libs/demo-gradle-tomee-embedded-shade-1.0-SNAPSHOT-bundle.jar --as-war --simple-log=true +---- + +== Fat Wars + +Fat Wars are executable wars. Note they can be fancy for demos but they have the drawback to put the server in web resources +at packaging time (to ensure the war is actually an executable jar) so adding a filter preventing these files to be read +can be needed if you don't already use a web technology doing it (a servlet bound to /*). + +Here how to do a fat war: + +[source,xml] +---- +<properties> + <!-- can be uber (for all), jaxrs, jaxws for lighter ones --> + <tomee.flavor>uber</tomee.flavor> +</properties> + +<dependencies> + <!-- ...your dependencies as usual... --> + <dependency> + <groupId>org.apache.tomee</groupId> + <artifactId>tomee-embedded</artifactId> + <classifier>${tomee.flavor}</classifier> + <version>7.0.0</version> + <scope>provided</scope> + </dependency> +</dependencies> + +<build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-war-plugin</artifactId> + <version>2.6</version> + <configuration> + <failOnMissingWebXml>false</failOnMissingWebXml> + <archive> + <manifest> + <mainClass>org.apache.tomee.embedded.Main</mainClass> + </manifest> + </archive> + <dependentWarExcludes /> + <overlays> + <overlay> + <groupId>org.apache.tomee</groupId> + <artifactId>tomee-embedded</artifactId> + <classifier>${tomee.flavor}</classifier> + <type>jar</type> + <excludes /> + </overlay> + </overlays> + </configuration> + </plugin> + </plugins> +</build> +---- + +Then just build the war: + +[source,bash] +---- +mvn clean package +---- + +And you can run it: + +[source,bash] +---- +java -jar myapp-1.0-SNAPSHOT.war +----
