This is an automated email from the ASF dual-hosted git repository.
rzo1 pushed a commit to branch xbean-4.30-SNAPSHOT
in repository https://gitbox.apache.org/repos/asf/tomee.git
The following commit(s) were added to refs/heads/xbean-4.30-SNAPSHOT by this
push:
new cd9b5dde0d Update documentation
cd9b5dde0d is described below
commit cd9b5dde0da4e359a3943c2cb593ec75ddd48f8e
Author: Richard Zowalla <[email protected]>
AuthorDate: Mon Jan 5 19:29:24 2026 +0100
Update documentation
---
docs/admin/configuration/application.adoc | 2 +-
docs/application-resources.adoc | 19 +
docs/containers-and-resources.adoc | 586 ++++++++++++++----------------
3 files changed, 285 insertions(+), 322 deletions(-)
diff --git a/docs/admin/configuration/application.adoc
b/docs/admin/configuration/application.adoc
index 775492e1a0..a91ba38a20 100644
--- a/docs/admin/configuration/application.adoc
+++ b/docs/admin/configuration/application.adoc
@@ -87,7 +87,7 @@ to use a MySQL database on OpenShift you can do:
`resources.xml` supports `Resource`, `Service` and `Container`.
-=== `resources.xml` mecanism
+=== `resources.xml` mechanism
`resources.xml` resources are still available globally like any `tomee.xml`
resource.
diff --git a/docs/application-resources.adoc b/docs/application-resources.adoc
index 8620ac1124..21f04e5903 100644
--- a/docs/application-resources.adoc
+++ b/docs/application-resources.adoc
@@ -290,6 +290,25 @@ specify the arguments as a comma separated list:
</Resource>
----
+=== constructor-types
+
+When no types are explicitly defined, the underlying mechanism relies on
implicit matching to bind
+the declared properties to the constructor parameter names.
+
+Because of this, it can be useful to explicitly define the constructor
argument types to ensure that
+the correct constructor or factory method is selected for the configured
resource.
+
+You can specify the types as shown below:
+
+[source,xml]
+----
+<Resource id="config" class-name="org.superbiz.Configuration" constructor="id,
poolSize" constructor-types="java.lang.String,int">
+ url http://localhost
+ username tomee
+ poolSize 20
+</Resource>
+----
+
=== factory-name method
In some circumstances, it may be desirable to add some additional logic
diff --git a/docs/containers-and-resources.adoc
b/docs/containers-and-resources.adoc
index 2f5c17c5b9..77a3c1aca2 100644
--- a/docs/containers-and-resources.adoc
+++ b/docs/containers-and-resources.adoc
@@ -4,461 +4,405 @@
:jbake-type: page
:jbake-status: published
+== Containers
-[source,xml]
-----
- <p><a name="ContainersandResources-containers"></a></p>
-----
-
-CMP_ENTITY
+=== CMP_ENTITY
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Container?type=CMP_ENTITY
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-CmpEngineFactory
-
-Default value is org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory.
-
-TransactionManager
-
-Declarable in tomee.xml via
-
-Supports the following properties
+Supports the following properties:
-Property Name
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-Description
+| CmpEngineFactory
+| Default value is `org.apache.openejb.core.cmp.jpa.JpaCmpEngineFactory`.
-defaultTransactionTimeoutSeconds
+| TransactionManager
+| Transaction manager used by the container.
+|===
-Default value is 10 minutes.
+---
-BMP_ENTITY
+=== BMP_ENTITY
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Container?type=BMP_ENTITY
+----
-Supports the following properties
-
-Property Name
+Supports the following properties:
-Description
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-PoolSize
+| PoolSize
+| Specifies the size of the bean pools for this BMP entity container.
+Default value is `10`.
+|===
-Specifies the size of the bean pools for this bmp entity container.
-Default value is 10.
+---
-STATELESS
+=== STATELESS
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Container?type=STATELESS
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-TimeOut
+Supports the following properties:
-Specifies the time to wait between invocations. This value is measured
-in milliseconds. A value of 5 would result in a time-out of 5
-milliseconds between invocations. A value of zero would mean no timeout.
-Default value is 0.
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-PoolSize
+| TimeOut
+| Specifies the time to wait between invocations, in milliseconds.
+A value of `0` means no timeout.
+Default value is `0`.
-Specifies the size of the bean pools for this stateless SessionBean
-container. Default value is 10.
+| PoolSize
+| Specifies the size of the bean pools for this stateless SessionBean
container.
+Default value is `10`.
-StrictPooling
+| StrictPooling
+| Controls behavior when the pool reaches its maximum size.
+If `true`, requests wait for instances to become available and the pool never
grows beyond `PoolSize`.
+If `false`, temporary instances are created for one invocation and then
discarded.
+Default value is `true`.
+|===
-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 PoolSize
-value. 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. Default value is true.
+---
-STATEFUL
+=== STATEFUL
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Container?type=STATEFUL
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-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 Default value is
-org.apache.openejb.core.stateful.SimplePassivater.
+Supports the following properties:
-TimeOut
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-Specifies the time to wait between invocations. This value is measured
-in minutes. A value of 5 would result in a time-out of 5 minutes between
-invocations. A value of zero would mean no timeout. Default value is 20.
+| Passivator
+| Responsible for writing beans to disk during passivation.
+Known implementations:
+`org.apache.openejb.core.stateful.RAFPassivater`
+`org.apache.openejb.core.stateful.SimplePassivater`
+Default value is `org.apache.openejb.core.stateful.SimplePassivater`.
-PoolSize
+| TimeOut
+| Specifies the time to wait between invocations, in minutes.
+A value of `0` means no timeout.
+Default value is `20`.
-Specifies the size of the bean pools for this stateful SessionBean
-container. Default value is 1000.
+| PoolSize
+| Specifies the size of the bean pools for this stateful SessionBean container.
+Default value is `1000`.
-BulkPassivate
+| BulkPassivate
+| Number of instances to passivate at one time during bulk passivation.
+Default value is `100`.
+|===
-Property name that specifies the number of instances to passivate at one
-time when doing bulk passivation. Default value is 100.
+---
-MESSAGE
+=== MESSAGE
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Container?type=MESSAGE
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-ResourceAdapter
-
-The resource adapter delivers messages to the container Default value is
-Default JMS Resource Adapter.
+Supports the following properties:
-MessageListenerInterface
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-Specifies the message listener interface handled by this container
-Default value is jakarta.jms.MessageListener.
+| ResourceAdapter
+| Resource adapter that delivers messages to the container.
+Default value is *Default JMS Resource Adapter*.
-ActivationSpecClass
+| MessageListenerInterface
+| Message listener interface handled by this container.
+Default value is `jakarta.jms.MessageListener`.
-Specifies the activation spec class Default value is
-org.apache.activemq.ra.ActiveMQActivationSpec.
+| ActivationSpecClass
+| Activation specification class.
+Default value is `org.apache.activemq.ra.ActiveMQActivationSpec`.
-InstanceLimit
+| InstanceLimit
+| Maximum number of bean instances allowed per MDB deployment.
+Default value is `10`.
+|===
-Specifies the maximum number of bean instances that are allowed to exist
-for each MDB deployment. Default value is 10.
+---
-Resources
+== Resources
-javax.sql.DataSource
+=== javax.sql.DataSource
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=javax.sql.DataSource
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-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' 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' Default value is true.
-
-JdbcDriver
-
-Driver class name Default value is org.hsqldb.jdbcDriver.
-
-JdbcUrl
-
-Url for creating connections Default value is
-jdbc:hsqldb:file:data/hsqldb/hsqldb.
-
-UserName
-
-Default user name Default value is sa.
-
-Password
-
-Default password
-
-ConnectionProperties
-
-The connection properties that will be sent to the JDBC driver when
-establishing new connections Format of the string must be
-[propertyName=property;]* NOTE - The "user" and "password" properties
-will be passed explicitly, so they do not need to be included here.
-
-DefaultAutoCommit
-
-The default auto-commit state of new connections Default value is true.
-
-DefaultReadOnly
-
-The default read-only state of new connections If not set then the
-setReadOnly method will not be called. (Some drivers don't support read
-only mode, ex: Informix)
-
-DefaultTransactionIsolation
-
-The default TransactionIsolation state of new connections If not set
-then the setTransactionIsolation method will not be called. The allowed
-values for this property are: NONE READ_COMMITTED
-READ_UNCOMMITTED REPEATABLE_READ SERIALIZABLE Note: Most JDBC
-drivers do not support all isolation levels
-
-InitialSize
-
-The initial number of connections that are created when the pool is
-started Default value is 0.
-
-MaxActive
-
-The maximum number of active connections that can be allocated from this
-pool at the same time, or a negative number for no limit. Default value
-is 20.
+Supports the following properties:
-MaxIdle
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-The maximum number of connections that can remain idle in the pool,
-without extra ones being released, or a negative number for no limit.
-Default value is 20.
+| JtaManaged
+| Determines whether the datasource is JTA managed.
+Default value is `true`.
-MinIdle
+| JdbcDriver
+| JDBC driver class name.
+Default value is `org.hsqldb.jdbcDriver`.
-The minimum number of connections that can remain idle in the pool,
-without extra ones being created, or zero to create none. Default value
-is 0.
+| JdbcUrl
+| JDBC URL for creating connections.
+Default value is `jdbc:hsqldb:file:data/hsqldb/hsqldb`.
-MaxWait
+| UserName
+| Default username.
+Default value is `sa`.
-The maximum number of milliseconds that the pool will wait (when there
-are no available connections) for a connection to be returned before
-throwing an exception, or -1 to wait indefinitely. Default value is -1.
+| Password
+| Default password.
-ValidationQuery
+| ConnectionProperties
+| Properties passed to the JDBC driver when creating connections.
+Format: `[propertyName=property;]*`
+`user` and `password` are passed explicitly.
-The SQL query that will be used to validate connections from this pool
-before returning them to the caller. If specified, this query MUST be an
-SQL SELECT statement that returns at least one row.
+| DefaultAutoCommit
+| Default auto-commit state of new connections.
+Default value is `true`.
-TestOnBorrow
+| DefaultReadOnly
+| Default read-only state of new connections.
+If not set, `setReadOnly` is not called.
-If true connections will be validated before being borrowed from the
-pool. If the validation fails, the connection is destroyed, and a new
-conection will be retrieved from the pool (and validated). NOTE - for a
-true value to have any effect, the ValidationQuery parameter must be
-set. Default value is true.
+| DefaultTransactionIsolation
+| Default transaction isolation level.
+Allowed values: `NONE`, `READ_COMMITTED`, `READ_UNCOMMITTED`,
`REPEATABLE_READ`, `SERIALIZABLE`.
-TestOnReturn
+| InitialSize
+| Initial number of connections created when the pool starts.
+Default value is `0`.
-If true connections will be validated before being returned to the
-pool. If the validation fails, the connection is destroyed instead of
-being returned to the pool. NOTE - for a true value to have any effect,
-the ValidationQuery parameter must be set. Default value is false.
+| MaxActive
+| Maximum number of active connections.
+Default value is `20`.
-TestWhileIdle
+| MaxIdle
+| Maximum number of idle connections.
+Default value is `20`.
-If true connections will be validated by the idle connection evictor (if
-any). If the validation fails, the connection is destroyed and removed
-from the pool NOTE - for a true value to have any effect, the
-timeBetweenEvictionRunsMillis property must be a positive number and the
-ValidationQuery parameter must be set. Default value is false.
+| MinIdle
+| Minimum number of idle connections.
+Default value is `0`.
-TimeBetweenEvictionRunsMillis
+| MaxWait
+| Maximum wait time (ms) for a connection before throwing an exception.
+Default value is `-1`.
-The number of milliseconds to sleep between runs of the idle connection
-evictor thread. When set to a negative number, no idle connection
-evictor thread will be run. Default value is -1.
+| ValidationQuery
+| SQL query used to validate connections.
-NumTestsPerEvictionRun
+| TestOnBorrow
+| Validate connections before borrowing.
+Default value is `true`.
-The number of connectionss to examine during each run of the idle
-connection evictor thread (if any). Default value is 3.
+| TestOnReturn
+| Validate connections before returning to the pool.
+Default value is `false`.
-MinEvictableIdleTimeMillis
+| TestWhileIdle
+| Validate connections during idle eviction runs.
+Default value is `false`.
-The minimum amount of time a connection may sit idle in the pool before
-it is eligable for eviction by the idle connection evictor (if any).
-Default value is 1800000.
+| TimeBetweenEvictionRunsMillis
+| Time between idle eviction runs (ms).
+Default value is `-1`.
-PoolPreparedStatements
+| NumTestsPerEvictionRun
+| Number of connections tested per eviction run.
+Default value is `3`.
-If true, a statement pool is created for each Connection and
-PreparedStatements created by one of the following methods are
-pooled: public PreparedStatement prepareStatement(String
-sql); public PreparedStatement prepareStatement(String
-sql, int resultSetType, int resultSetConcurrency)
-Default value is false.
+| MinEvictableIdleTimeMillis
+| Minimum idle time before eviction.
+Default value is `1800000`.
-MaxOpenPreparedStatements
+| PoolPreparedStatements
+| Enables pooling of prepared statements.
+Default value is `false`.
-The maximum number of open statements that can be allocated from the
-statement pool at the same time, or zero for no limit. NOTE - Some
-drivers have limits on the number of open statements, so make sure there
-are some resources left for the other (non-prepared) statements. Default
-value is 0.
+| MaxOpenPreparedStatements
+| Maximum open prepared statements.
+Default value is `0`.
-AccessToUnderlyingConnectionAllowed
+| AccessToUnderlyingConnectionAllowed
+| Allows access to the raw JDBC connection.
+Default value is `false`.
+|===
-If true the raw physical connection to the database can be accessed
-using the following construct: Connection conn =
-ds.getConnection(); Connection rawConn = ((DelegatingConnection)
-conn).getInnermostDelegate(); ... conn.close() Default is false,
-because misbehaving programs can do harmfull things to the raw
-connection shuch as closing the raw connection or continuing to use the
-raw connection after it has been assigned to another logical
-connection. Be carefull and only use when you need direct access to
-driver specific extentions. NOTE: Do NOT close the underlying
-connection, only the original logical connection wrapper. Default value
-is false.
+---
-ActiveMQResourceAdapter
+=== ActiveMQResourceAdapter
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=ActiveMQResourceAdapter
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-BrokerXmlConfig
+Supports the following properties:
-Broker configuration Default value is
-broker:(tcp://localhost:61616)?useJmx=false.
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-ServerUrl
+| BrokerXmlConfig
+| Broker configuration.
+Default value is `broker:(tcp://localhost:61616)?useJmx=false`.
-Broker address Default value is vm://localhost?async=true.
+| ServerUrl
+| Broker address.
+Default value is `vm://localhost?async=true`.
-DataSource
+| DataSource
+| Datasource for message persistence.
+Default value is *Default Unmanaged JDBC Database*.
+|===
-DataSource for persistence messages Default value is Default Unmanaged
-JDBC Database.
+---
-jakarta.jms.ConnectionFactory
+=== jakarta.jms.ConnectionFactory
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=jakarta.jms.ConnectionFactory
+----
-Supports the following properties
-
-Property Name
-
-Description
-
-ResourceAdapter
-
-Default value is Default JMS Resource Adapter.
-
-TransactionSupport
-
-Specifies if the connection is enrolled in global transaction allowed
-values: xa, local or none Default value is xa.
+Supports the following properties:
-PoolMaxSize
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-Maximum number of physical connection to the ActiveMQ broker Default
-value is 10.
+| ResourceAdapter
+| Default value is *Default JMS Resource Adapter*.
-PoolMinSize
+| TransactionSupport
+| Transaction support type: `xa`, `local`, or `none`.
+Default value is `xa`.
-Minimum number of physical connection to the ActiveMQ broker Default
-value is 0.
+| PoolMaxSize
+| Maximum number of physical connections.
+Default value is `10`.
-ConnectionMaxWaitMilliseconds
+| PoolMinSize
+| Minimum number of physical connections.
+Default value is `0`.
-Maximum amount of time to wait for a connection Default value is 5000.
+| ConnectionMaxWaitMilliseconds
+| Maximum time to wait for a connection.
+Default value is `5000`.
-ConnectionMaxIdleMinutes
+| ConnectionMaxIdleMinutes
+| Maximum idle time before reclaiming a connection.
+Default value is `15`.
+|===
-Maximum amount of time a connection can be idle before being reclaimed
-Default value is 15.
+---
-jakarta.jms.Queue
+=== jakarta.jms.Queue
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=jakarta.jms.Queue
+----
-Supports the following properties
-
-Property Name
+Supports the following properties:
-Description
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-destination
+| destination
+| Name of the queue.
+|===
-Specifies the name of the queue
+---
-jakarta.jms.Topic
+=== jakarta.jms.Topic
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=jakarta.jms.Topic
+----
-Supports the following properties
-
-Property Name
+Supports the following properties:
-Description
+[cols="1,3",options="header"]
+|===
+| Property Name | Description
-destination
+| destination
+| Name of the topic.
+|===
-Specifies the name of the topic
+---
-jakarta.mail.Session
+=== jakarta.mail.Session
-Declarable in tomee.xml via
+Declarable in `tomee.xml` via
-Declarable in properties via
+Declarable in properties via:
+----
Foo = new://Resource?type=jakarta.mail.Session
+----
No properties.
