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