| = StatelessContainer Configuration |
| :index-group: Unrevised |
| :jbake-date: 2018-12-05 |
| :jbake-type: page |
| :jbake-status: published |
| |
| |
| A StatelessContainer can be declared via xml in the |
| `<tomee-home>/conf/tomee.xml` file or in a `WEB-INF/resources.xml` file |
| using a declaration like the following. All properties in the element |
| body are optional. |
| |
| [source,xml] |
| ---- |
| <Container id="myStatelessContainer" type="STATELESS"> |
| accessTimeout = 30 seconds |
| callbackThreads = 5 |
| closeTimeout = 5 minutes |
| garbageCollection = false |
| idleTimeout = 0 minutes |
| maxAge = 0 hours |
| maxAgeOffset = -1 |
| maxSize = 10 |
| minSize = 0 |
| replaceAged = true |
| replaceFlushed = false |
| strictPooling = true |
| sweepInterval = 5 minutes |
| </Container> |
| ---- |
| |
| Alternatively, a StatelessContainer can be declared via properties in |
| the `<tomee-home>/conf/system.properties` file or via Java |
| VirtualMachine `-D` properties. The properties can also be used when |
| embedding TomEE via the `javax.ejb.embeddable.EJBContainer` API or |
| `InitialContext` |
| |
| [source,properties] |
| ---- |
| myStatelessContainer = new://Container?type=STATELESS |
| myStatelessContainer.accessTimeout = 30 seconds |
| myStatelessContainer.callbackThreads = 5 |
| myStatelessContainer.closeTimeout = 5 minutes |
| myStatelessContainer.garbageCollection = false |
| myStatelessContainer.idleTimeout = 0 minutes |
| myStatelessContainer.maxAge = 0 hours |
| myStatelessContainer.maxAgeOffset = -1 |
| myStatelessContainer.maxSize = 10 |
| myStatelessContainer.minSize = 0 |
| myStatelessContainer.replaceAged = true |
| myStatelessContainer.replaceFlushed = false |
| myStatelessContainer.strictPooling = true |
| myStatelessContainer.sweepInterval = 5 minutes |
| ---- |
| |
| Properties and xml can be mixed. Properties will override the xml |
| allowing for easy configuration change without the need for $\{} style |
| variable substitution. Properties are not case sensitive. If a property |
| is specified that is not supported by the declared StatelessContainer a |
| warning will be logged. If a StatelessContainer is needed by the |
| application and one is not declared, TomEE will create one dynamically |
| using default settings. Multiple StatelessContainer declarations are |
| allowed. # Supported Properties |
| |
| Property |
| |
| Type |
| |
| Default |
| |
| Description |
| |
| accessTimeout |
| |
| time |
| |
| 30 seconds |
| |
| Specifies the time an invokation should wait for an instance of the pool |
| to become available. |
| |
| callbackThreads |
| |
| int |
| |
| 5 |
| |
| The number of threads for constructing and destroying beans. |
| |
| closeTimeout |
| |
| time |
| |
| 5 minutes |
| |
| Maximum time to wait for instances to be destroyed when shutting down |
| the pool |
| |
| garbageCollection |
| |
| boolean |
| |
| false |
| |
| Allows Garbage Collection to be used as a mechanism for shrinking the |
| pool. |
| |
| idleTimeout |
| |
| time |
| |
| 0 minutes |
| |
| 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. |
| |
| maxAge |
| |
| time |
| |
| 0 hours |
| |
| Specifies the maximum time that an instance should live before it should |
| be retired and removed from use. |
| |
| maxAgeOffset |
| |
| int |
| |
| -1 |
| |
| Applies to MaxAge usage and would rarely be changed, but is a nice |
| feature to understand. |
| |
| maxSize |
| |
| int |
| |
| 10 |
| |
| Specifies the size of the instance pool for this stateless SessionBean |
| container. |
| |
| minSize |
| |
| int |
| |
| 0 |
| |
| Specifies the minimum number of bean instances that should be in the |
| pool for each bean. |
| |
| replaceAged |
| |
| boolean |
| |
| true |
| |
| 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. |
| |
| replaceFlushed |
| |
| boolean |
| |
| false |
| |
| 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. |
| |
| strictPooling |
| |
| boolean |
| |
| true |
| |
| StrictPooling tells the container what to do when the pool reaches it's |
| maximum size and there are incoming requests that need instances. |
| |
| sweepInterval |
| |
| time |
| |
| 5 minutes |
| |
| The frequency in which the container will sweep the pool and evict |
| expired instances. |
| |
| == 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. |
| |
| == callbackThreads |
| |
| The number of threads for constructing and destroying beans. |
| |
| 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 |
| |
| Maximum time to wait for instances to be destroyed when shutting down |
| the pool |
| |
| 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` |
| |
| == 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`. |
| |
| == 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. |
| |
| Only instances in surplus of the pool's `MinSize` are eligible to expire |
| via `IdleTimeout` Instances that expire due to `IdleTimeout` will have |
| their `@PreDestroy` methods invoked before being completely destroyed. |
| |
| Usable time units: nanoseconds, microsecons, milliseconds, seconds, |
| minutes, hours, days. Or any combination such as "1 hour and 27 minutes |
| and 10 seconds" |
| |
| == 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` |
| |
| == 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. |
| |
| == maxSize |
| |
| Specifies the size of the instance pool for this stateless SessionBean |
| container. |
| |
| Each `@Stateless` bean will get its own instance pool. 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 expire. |
| |
| == 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 `@DependsOn` annotation can be used to |
| appropriately influence 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`. |
| |
| == 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(); |
| } |
| } |
| ---- |
| |
| == 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. |
| |
| == 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` |