While deploying in tomcat 8 server, I got following error
AssertionFailure: Transaction MARKED_FOR_JOINED after isOpen() call
Following are the details of the configuration.
Server: tomcat 8
Hibernate 3
Spring 3
Context.xml of server..
I have done database setting:
<Resource name="jdbc/meerkatDataSource"
auth="Container"
type="javax.sql.DataSource"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
driverClassName="oracle.jdbc.driver.OracleDriver"
url="jdbc:oracle:thin:#10.237.59.104:1521:MEERKAT"
username="meerkat"
password="meerkat"
maxActive="100"
maxIdle="20"
minIdle="5"
maxWait="10000"/>
<Resource name="UserTransaction" auth="Container" type="javax.transaction.UserTransaction"
factory = "org.objectweb.jotm.UserTransactionFactory"/>
<Transaction factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
<Resource
name="TransactionSynchronizationRegistry"
auth="Container"
type="javax.transaction.TransactionSynchronizationRegistry"
factory="org.objectweb.jotm.TransactionSynchronizationRegistryFactory"/>
Transaction.xml -->
<bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager">
<property name="userTransactionName" value="java:comp/UserTransaction">
<property name="transactionSynchronizationRegistryName" value="java:comp/env/TransactionSynchronizationRegistry"/>
</bean>
<tx:annotation-driven transaction-manager="transactionManager" />
Persistent.xml-->
<persistence-unit name="meerkatPersistenceUnit" transaction-type="JTA">
<jta-data-source>jdbc/meerkatDataSource</jta-data-source>
Please suggest if any changes to be done. Also note that, database setting is strictly under tomcat server.
As per my understanding ,
here you are using data source type="javax.sql.DataSource" using the factory : "org.apache.tomcat.jdbc.pool.DataSourceFactory"
and the transaction manager is jta type :
class="org.springframework.transaction.jta.JtaTransactionManager">
It can be solved if it the data bas is replaced by having the type
javax.sql.XADataSource in turn using the class :
an org.enhydra.jdbc.pool.StandardXAPoolDataSource. Make sure the prsistence manager uses the same datasource.
For further info go through :
https://tomcat.apache.org/tomcat-8.0-doc/jdbc-pool.html
http://xapool.ow2.org/doc/api/jdoc-1.3/org/enhydra/jdbc/pool/StandardXAPoolDataSource.html
Related
Has anybody a running example configuration for:
Apache Tomcat (TomEE)/8.5.6 (7.0.2) PLUME
Oracle 11g (ojdbc7.jar)
to match EE/JPA 2.1-Development as near as possible?
Currently i get TomEE's user database, if i try to use my datasource. I think it's caused by the log entry "org.apache.openejb.config.AutoConfig.deploy Found matching datasource: jdbc/jKgvDS but this one is not a JTA datasource", falling back to the last known running datasource. So how can i configure a valid JTA datasource?
server.xml:
<Resource id="jKgvDS" name="jdbc/jKgvDS"
jtaManaged="true"
auth="Container"
type="oracle.jdbc.xa.client.OracleXADataSource"
driverClassName="oracle.jdbc.xa.client.OracleXADataSource"
factory="oracle.jdbc.pool.OracleDataSourceFactory"
url="jdbc:oracle:thin:#db:1521:db"
username="myuser"
password="mypass"
maxActive="20"
maxIdle="30"
maxWait="-1"
validationQuery="SELECT 1 FROM DUAL"
/>
context.xml (tried in conf and app-file)
<ResourceLink global='jdbc/jKgvDS'
name='jdbc/jKgvDS' type="javax.sql.XADatasource"
auth="Container" />
persistence.xml
<persistence-unit name="jKgvPU" transaction-type="JTA">
<jta-data-source>jdbc/jKgvDS</jta-data-source>
<exclude-unlisted-classes>false</exclude-unlisted-classes>
<validation-mode>NONE</validation-mode>
<properties>
<property
name="openjpa.jdbc.DBDictionary"
value="org.apache.openjpa.jdbc.sql.OracleDictionary" />
<property
name="openjpa.jdbc.DBDictionary"
value="oracle(maxEmbeddedBlobSize=-1,maxEmbeddedClobSize=-1)" />
<property
name="openjpa.jdbc.SynchronizeMappings"
value="buildSchema(ForeignKeys=true)" />
</properties>
</persistence-unit>
Here we go (yeah...):
<Resource id="jKgvDS" name="jdbc/jKgvDS"
jtaManaged="true"
auth="Container"
type="javax.sql.DataSource"
driverClassName="oracle.jdbc.driver.OracleDriver"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
url="jdbc:oracle:thin:#POSDBORA:1521:posdbora"
username="myuser"
password="mypass"
maxActive="20"
maxIdle="30"
maxWait="-1"
validationQuery="SELECT 1 FROM DUAL"
/>
References in web.xml or context.xml are not needed to run.
I'm using Spring batch and spring batch admin and i write in applicationContext this code, defining a bean called dataSource:
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" ... />
Now, i would change this code, defining my "dataSource" in the context.xml file of Tomcat and then load it.
I read that this is possible defining a Resource like this:
<Resource auth="Container" driverClassName="oracle.jdbc.driver.OracleDriver"
maxActive="100" maxIdle="30" maxWait="10000" name="jdbc/myDatabase"
password="myPass" type="javax.sql.DataSource"
url="jdbc:oracle:thin:#host.com:1521/abc" username="myUser" />
and then loading it in my applicationContext.xml using this:
<jee:jndi-lookup id="dataSource" jndi-name="jdbc/myDatabase" />
But with this i have a problem. It is possible to define a resource for my dataSource so that it is of class org.apache.commons.dbcp.BasicDataSource and not javax.sql.DataSource?
Any help?
Thank you
Background:
I have a relatively old application that uses Websphere MQ for messaging. It runs on WAS (Websphere Application Server) and uses MDBs (Message Driven Beans). I was successfully able to replace all MDBs using Spring Integration - JMS. My next step is try to see if I can port it out of WAS so that it can run on any other servlet container with a non-IBM JRE (I am trying: apache tomcat). Note that securing channels using SSL is a requirement. I prefer using JNDI.
End Goal:
To decouple my application from the application server (WAS) and other infrastructure like messaging (MQ). But taking this out of WAS onto tomcat is the first step. Next comes the task of updating my messaging infrastructure with something more scalable. This allows me to update individual components of the infrastructure that my app relies on, one thing at a time (app server, messaging layer, datastore) without disrupting my application too much, as I go.
Question:
Now, my challenge is to define JNDI resources on tomcat that can access Websphere MQ. I have made some progress on this using non-SSL channels that I defined in the context.xml file like so:
<Resource
name="jms/qcf_sandbox"
auth="Container"
type="com.ibm.mq.jms.MQQueueConnectionFactory"
factory="com.ibm.mq.jms.MQQueueConnectionFactoryFactory"
description="JMS Queue Connection Factory for sending messages"
HOST="localhost"
PORT="1414"
CHAN="CHANNEL_SANDBOX"
TRAN="1"
QMGR="QM_SANDBOX"/>
<Resource
name="jms/SandboxQ"
auth="Container"
type="com.ibm.mq.jms.MQQueue"
factory="com.ibm.mq.jms.MQQueueFactory"
description="JMS Queue"
QU="SANDBOX_Q"/>
My next step is to get this to work with SSL channels. I understand the part that involves setting up the keystores (kdb file and cert generation and exchanging), configuring the SSL channels on the QM etc. I have all that working already. How do I get tomcat to use my keystore, cipher suite etc? Pointers or a working example would be great!
Note: I am using Spring Integration 4.2, Websphere MQ v8, Tomcat v9, currently.
I must add that I did try everything without the JNDI first. So here's my spring jms non-ssl config without the JNDI, that works:
<bean id="mq-jms-cf-sandbox"
class="org.springframework.jms.connection.SingleConnectionFactory">
<property name="targetConnectionFactory">
<ref bean="mqQueueConnectionFactory" />
</property>
</bean>
<bean id="mqQueueConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
<property name="hostName" value="localhost" />
<property name="port" value="1414" />
<property name="queueManager" value="QM_SANDBOX" />
<property name="transportType" value="1" />
<property name="channel" value="CHANNEL_SANDBOX" />
</bean>
<bean id="jms-destination-sandbox" class="com.ibm.mq.jms.MQQueue">
<constructor-arg value="SANDBOX_Q" />
<property name="baseQueueManagerName">
<value>QM_SANDBOX</value>
</property>
<property name="baseQueueName">
<value>SANDBOX_Q</value>
</property>
</bean>
I think I finally figured out how to pull this off... here's a brief description of the steps. If you need more details let me know.
Pre-reqs:
Websphere MQ Server installed (at least v 8.0.0.2)
Configure the QM, SSL and non-SSL channels, create Qs and all that good stuff you need.
Needless to say, you need the Websphere MQ jars. Be mindful of any licensing restrictions.
Step 1: Get the direct connection working with no SSL, no JNDI. You will need to use these beans to configure your spring based JMS listeners and JMS Templates etc.
<bean id="mq-jms-cf-sandbox"
class="org.springframework.jms.connection.SingleConnectionFactory">
<property name="targetConnectionFactory">
<ref bean="mqQueueConnectionFactory" />
</property>
</bean>
<bean id="mqQueueConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
<property name="hostName" value="localhost" />
<property name="port" value="1414" />
<property name="queueManager" value="QM_SANDBOX" />
<property name="transportType" value="1" />
<property name="channel" value="NON_SSL_CHANNEL" />
</bean>
<bean id="jms-destination-sandbox" class="com.ibm.mq.jms.MQQueue">
<constructor-arg value="SANDBOX_Q" />
<property name="baseQueueManagerName">
<value>QM_SANDBOX</value>
</property>
<property name="baseQueueName">
<value>SANDBOX_Q</value>
</property>
</bean>
Step 2: Get the direct connection working with SSL, no JNDI. I found setting this up a little tricky.
2a. Since I was using a non-IBM JRE, I had to make sure the cipher specs & cipher suites needed to be configured according to the mappings specified here:
http://www-01.ibm.com/support/docview.wss?uid=swg1IV66840
This obviously means that we at least have to have our Websphere MQ upgraded to 8.0.0.2. In my case I used ECDHE_RSA_AES_256_GCM_SHA384 on the SSL channel and configured the jms beans within application to use TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, like so:
<bean id="mq-jms-cf-sandbox"
class="org.springframework.jms.connection.SingleConnectionFactory">
<property name="targetConnectionFactory">
<ref bean="mqQueueConnectionFactory" />
</property>
</bean>
<bean id="mqQueueConnectionFactory" class="com.ibm.mq.jms.MQQueueConnectionFactory">
<property name="hostName" value="localhost" />
<property name="port" value="1414" />
<property name="queueManager" value="QM_SANDBOX" />
<property name="transportType" value="1" />
<property name="channel" value="SSL_CHANNEL" />
<property name="SSLCipherSuite" value="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"/>
</bean>
<bean id="jms-destination-sandbox" class="com.ibm.mq.jms.MQQueue">
<constructor-arg value="SANDBOX_Q" />
<property name="baseQueueManagerName">
<value>QM_SANDBOX</value>
</property>
<property name="baseQueueName">
<value>SANDBOX_Q</value>
</property>
</bean>
2b. Create certs, keystores (kdbs), exchange certs etc. There are many ways to do this. But be mindful that you will need to stash passwords, the key label for the queue manager must be ‘ibmwebspheremqqmgr’ – all in lower case, no spaces, (without quotes), the key label must be like ‘ibmwebspheremquserid’ – all in lower case, no spaces, (without quotes) where userid is the userid that runs tomcat. If you need more details on exactly how I did it using self signed certs, let me know.
2c. Now you have to get the JVM that tomcat runs, to read your keystores. There are many ways but here's how I did it:
Create a setenv.bat file in the tomcat bin folder, with the following contents (debugging SSL is optional)
set JAVA_OPTS="-Djavax.net.ssl.trustStore=C:\path-to-keystore\key.jks" "-Djavax.net.ssl.trustStorePassword=topsecret" "-Djavax.net.ssl.keyStore=C:\path-to-keystore\key.jks" "-Djavax.net.ssl.keyStorePassword=topsecret" "-Djavax.net.debug=ssl" "-Dcom.ibm.mq.cfg.useIBMCipherMappings=false"
2d. Start tomcat using the following command:
catalina.bat run > ..\logs\tomcat.log 2>&1
To stop, just press ctrl+c (on windows). Whichever way you do it, make sure that setenv.bat is used during start up. Or use JAVA_OPTS to set the keystore properties.
2e. Verify that the using the SSL channel works.
Step 3: Get a JNDI connection working with non-SSL, JNDI
There are many was to set up JNDI on tomcat. Here's how I did it: Within the web application create a file META-INF/Context.xml with the following contents:
<Resource
name="jms/qcf_sandbox"
auth="Container"
type="com.ibm.mq.jms.MQQueueConnectionFactory"
factory="com.ibm.mq.jms.MQQueueConnectionFactoryFactory"
description="JMS Queue Connection Factory for sending messages"
HOST="localhost"
PORT="1414"
CHAN="NON_SSL_CHANNEL"
TRAN="1"
QMGR="QM_SANDBOX"/>
<Resource
name="jms/SandboxQ"
auth="Container"
type="com.ibm.mq.jms.MQQueue"
factory="com.ibm.mq.jms.MQQueueFactory"
description="JMS Queue"
QU="SANDBOX_Q"/>
Now in your spring config, instead of the direct configurations, all you have to do is:
<jee:jndi-lookup id="mq-jms-cf-sandbox" jndi-name="java:/comp/env/jms/qcf_sandbox" resource-ref="false" />
<jee:jndi-lookup id="jms-destination-sandbox" jndi-name="java:/comp/env/jms/SandboxQ" resource-ref="false" />
Note that for brevity, I just didn't use resource references. In case you do, there a few additional steps which are straight forward.
Step 4: Now the final step is to use an SSL channel and JNDI. Assuming you have done step 2, this is easy. Modify the META-INF/Context.xml with the following contents:
<Resource
name="jms/qcf_sandbox"
auth="Container"
type="com.ibm.mq.jms.MQQueueConnectionFactory"
factory="com.ibm.mq.jms.MQQueueConnectionFactoryFactory"
description="JMS Queue Connection Factory for sending messages"
HOST="localhost"
PORT="1414"
CHAN="SSL_CHANNEL"
TRAN="1"
QMGR="QM_SANDBOX"
SCPHS="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"/>
<Resource
name="jms/SandboxQ"
auth="Container"
type="com.ibm.mq.jms.MQQueue"
factory="com.ibm.mq.jms.MQQueueFactory"
description="JMS Queue"
QU="SANDBOX_Q"/>
Note the line with SCPHS="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384". If you need to set other such parameters, see the "Short Form" column in this link:
https://www.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.ref.dev.doc/q111800_.htm%23jm10910_?lang=en
Hopefully all this works for you. Good luck!
Once this configuration works, sending messages is pretty straight forward. But this is how you can listen for a message on a queue using Spring JMS
Reference: https://docs.spring.io/spring/docs/current/spring-framework-reference/html/jms.html
Step 1: Use Spring's DefaultMessageListenerContainer and configure your beans in an xml file like so (spring-beans.xml):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
"http://www.springframework.org/dtd/spring-beans.dtd">
<!-- this is the Message Driven POJO (MDP) -->
<bean id="messageListener" class="jmsexample.ExampleListener" />
<!-- and this is the message listener container -->
<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
<property name="connectionFactory" ref="mq-jms-cf-sandbox"/>
<property name="destination" ref="jms-destination-sandbox"/>
<property name="messageListener" ref="messageListener" />
</bean>
</beans>
Step 2: Add this to your web.xml
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/context/spring-beans.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
Step 3: Write a Message Listener class like so:
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.TextMessage;
public class ExampleListener implements MessageListener {
public void onMessage(Message message) {
if (message instanceof TextMessage) {
try {
System.out.println(((TextMessage) message).getText());
}
catch (JMSException ex) {
throw new RuntimeException(ex);
}
}
else {
throw new IllegalArgumentException("Message must be of type TextMessage");
}
}
}
Alternatively, instead of step 3, if you are using spring integration, you can do something like so:
<int:channel id="jms-inbound"/>
<int-jms:message-driven-channel-adapter
id="jms-inbound-adapter" container="jmsContainer" channel="jms-inbound"
extract-payload="true" acknowledge="transacted"
message-converter="messagingMessageConverter" />
<beans:bean id="messagingMessageConverter" class="org.springframework.jms.support.converter.MessagingMessageConverter">
</beans:bean>
I have a web application that uses Tomcat 7, Spring MVC 4.0, and JPA (Hibernate implementation). I am migrating this application to jBoss/Wildfly application server.
Currently, the DataSource is injected in the application with JNDI in a Spring configuration file:
<jee:jndi-lookup id="dataSource" jndi-name="jdbc/MY_DB" expected-type="javax.sql.DataSource" />
The data source itself is defined in $CATALINA_HOME/conf/context.xml in the following way:
<Context>
<Resource name="jdbc/MY_DB"
auth="Container"
type="javax.sql.DataSource"
driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/MY_DB?useUnicode=yes&characterEncoding=UTF-8"
username="user1"
password=""
validationQuery="select 1"
removeAbandoned="true"
removeAbandonedTimeout="120"
maxWait="60"
maxActive="20"
maxIdle="10" />
</Context>
How can I define this JNDI DataSource in JBoss/Wildfly?
First, you must make the JDBC driver available to the application server; then you can configure the data source itself.
See more details in Data Source Configuration in AS 7 and DataSource configuration
I'm trying to configure Spring, JPA and DB2 in order to have the entity manager instance to be used in my spring controllers but according how I have configured Spring this not happens.
These are the two attempts of configuration of spring:
<bean id="dataSource"
class="org.springframework.jdbc.datasource.DriverManagerDataSource" />
<bean name="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
<property name="entityManagerFactory" ref="em" />
</bean>
<bean id="em"
class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
<property name="persistenceUnitName" value="fileUtility" />
<property name="jpaVendorAdapter">
<bean class="org.springframework.orm.jpa.vendor.OpenJpaVendorAdapter">
<property name="database" value="DB2" />
<property name="showSql" value="true" />
</bean>
</property>
</bean>
the second is this:
<!-- Entity manager factory bean. -->
<bean id="entityManagerFactory"
class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
<property name="persistenceUnitName" value="Sample" />
</bean>
<!-- Entity manager bean. -->
<bean id="em" factory-bean="entityManagerFactory"
factory-method="createEntityManager" />
and the entity manager is injected in this way:
<bean id="messageService" class="utilities.services.impl.MessageServiceImpl">
<property name="entityManager" ref="em" />
</bean>
but I have always this exception:
Caused by: java.lang.IllegalArgumentException: methods with same signature createEntityManager() but incompatible return types: [interface com.ibm.websphere.persistence.WsJpaEntityManager, interface org.apache.openjpa.persistence.OpenJPAEntityManagerSPI]
I don't know how can be fixed. Has anyone encountered this problem?
Thanks in advance.
[EDIT]
This is my persistence.xml:
<?xml version="1.0"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
<persistence-unit name="fileUtility"
transaction-type="RESOURCE_LOCAL">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<mapping-file>META-INF/mapping.xml</mapping-file>
<properties>
<property name="openjpa.ConnectionURL" value="jdbc:db2://localhost:50000/db2admin" />
<property name="openjpa.ConnectionDriverName" value="COM.ibm.db2.jdbc.app.DB2Driver" />
<property name="openjpa.ConnectionUserName" value="db2admin" />
<property name="openjpa.ConnectionPassword" value="XXXX" />
<property name="openjpa.FlushBeforeQueries" value="true"/>
<property name="openjpa.RuntimeUnenhancedClasses" value="supported" />
</properties>
</persistence-unit>
<persistence-unit name="fileUtility2" transaction-type="JTA">
<provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
<jta-data-source>file_ds</jta-data-source>
<mapping-file>META-INF/mapping.xml</mapping-file>
<properties>
<property name="openjpa.Log" value="SQL=TRACE"/>
<property name="openjpa.ConnectionFactoryProperties" value="PrettyPrint=true, PrettyPrintLineLength=72"/>
</properties>
</persistence-unit>
</persistence>
WebSphere has a JPA implementation bundled. So no need to add openjpa to your lib. In fact, WebSphere is using OpenJPA, so you are not losing anything. Look here for more details
When using a jda-data-source, you need to have transaction-type="JTA". Also, you should not specify connection properties - they are specified in the datasource.
And get rid of the <provider> - the document I linked says:
If no JPA provider is configured in the element of the persistence.xml file within an EJB module, the default JPA provider that is currently configured for this server is used
I believe you're doing the wrong configuration, because you're configuring it "à la Tomcat". If you're using a Java EE application server, such as WAS, you should:
In Spring application context xml file
configure the DAO bean by a <bean> definition
configure the JNDI definition for the datasource created in the application server via a
<jee:jndi-lookup>
definition; the
name
attribute should be
persistence/XXX, where XXX shall match the
<persistence-unit name="XXX" transaction-type="JTA">
in persistence.xml file
The id attribute in the
<jee:jndi-lookup id=YYY> should point to the
name=YYY parameter of the Entity Manager definition in the DAO, this is to say,
#PersistenceContext(name=YYY) EntityManager em;
Specify
<tx:annotation-driven /> and
<tx:jta-transaction-manager />
In file
web.xml of your web app you should include a definition using the xml tag
<persistence-unit-ref> whose
<persistence-unit-ref-name> parameter shall be the
persistence/XXX JNDI name as specified in persistence.xml (shown above).
Finally, you should create a JNDI definition in the application server (AS dependant) that defines the JNDI name for the JDBC connection. This name should match the
<jta-data-source> xml tag in the persistence.xml file, and it is the only link between the JPA definition and the JDBC defined in the application server.
To round up:
Application Context Spring file
<bean class="DAO implementation class" />
<jee:jndi-lookup id="YYY" jndi-name="persistence/XXX" />
<tx:annotation-driven />
<tx:jta-transaction-manager />
persistence.xml file
<persistence-unit name="XXX" transaction-type="JTA">
<jta-data-source>jdbc/DSN</jta-data-source>
</persistence-unit>
web.xml file
...
<persistence-unit-ref>
<persistence-unit-ref-name>persistence/XXX</persistence-unit-ref-name>
</persistence-unit-ref>
...
DAO (only #PersistenceContext shown)
...
#PersistenceContext(name = "YYY")
EntityManager em;
...
Application Server: jdbc/DSN links to the connection definition, where the driver for the DBM is. Depends on both the AS and the DBM used.
Thus, you may see the connection between the DAO -> Spring Application Context file -> persistence.xml and web.xml files -> Application Server JNDI names. IF you're using a full Java EE application server (such as WAS, Weblogic or GlassFish) you don't have to use Spring interface modules; only defnitions in the app server (see Spring documentation, section 12.6.3).