Nikita-tech-writer commented on a change in pull request #8948: URL: https://github.com/apache/ignite/pull/8948#discussion_r604410677
########## File path: docs/_docs/extensions-and-integrations/spring/spring-tx.adoc ########## @@ -0,0 +1,471 @@ +// Licensed to the Apache Software Foundation (ASF) under one or more +// contributor license agreements. See the NOTICE file distributed with +// this work for additional information regarding copyright ownership. +// The ASF licenses this file to You under the Apache License, Version 2.0 +// (the "License"); you may not use this file except in compliance with +// the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. += Apache Ignite with Spring Transactions + +== Overview + +http://docs.spring.io/spring/docs/current/spring-framework-reference/html/transaction.html[Spring Transactions, window="_blank"] +abstraction allows you to use a declarative transaction management to concentrate on business logic rather than +transaction life-cycle. + +Apache Ignite provides the `ignite-spring-tx-ext` extension that allows to manage +https://ignite.apache.org/docs/latest/key-value-api/transactions#performing-transactions[Apache Ignite Transactions, window="_blank"] +through the Spring Transactions abstraction. The mentioned integration is achieved by providing implementations of the +`TransactionManager` Spring Transactions interface. There are two such implementations: `SpringTransactionManager` and +`IgniteClientSpringTransactionManager`, which use Apache Ignite node or Apache Ignite thin client to connect to the +Apache Ignite cluster and manage the Apache Ignite transactions, respectively. + +To enable declarative transaction management in your Spring application, create and configure +`SpringTransactionManager` or `IgniteClientSpringTransactionManager` bean in the Spring application context. The choice +of implementation depends on your preferable way to access the Apache Ignite cluster. + +== Maven Configuration + +If you are using Maven to manage dependencies in your project, you can add Spring Transactions extension dependencies to +the application's `pom.xml` file like this: + +[NOTE] +==== +For Apache Ignite versions earlier than `2.11.0`, the `ignite-spring-tx-ext` dependency must be added to +classpath before `ignite-spring`, due to duplication of Spring Transactions integration classes. If you are using Maven +to manage dependencies, it just needs to place `ignite-spring-tx-ext` before the `ignite-spring` dependency in the +application's `pom.xml` file. +==== + +[tabs] +-- +tab:pom.xml[] +[source,xml] +---- +<dependency> + <groupId>org.apache.ignite</groupId> + <artifactId>ignite-spring-tx-ext</artifactId> + <version>${ignite-spring-tx-ext.version}</version> +</dependency> + +<dependency> + <groupId>org.apache.ignite</groupId> + <artifactId>ignite-spring</artifactId> + <version>${ignite.version}</version> +</dependency> + +<dependency> + <groupId>org.apache.ignite</groupId> + <artifactId>ignite-core</artifactId> + <version>${ignite.version}</version> +</dependency> + +<dependency> + <groupId>org.springframework</groupId> + <artifactId>spring-tx</artifactId> + <version>${spring.version}</version> +</dependency> +---- +-- + +Replace `${ignite-spring-tx-ext.version}`, `${spring.version}`, and +`${ignite.version}` with an actual version of Apache Ignite Spring Transactions extension, Spring Transactions, and +Apache Ignite dependency you are interested in, respectively. + +== Apache Ignite Node Transaction Manager Configuration +This chapter shows how to set up `SpringTransactionManager` that relies on Apache Ignite node to connect to the cluster +and manage transactions. The configuration consists of two steps - +link:extensions-and-integrations/spring/spring-tx#cluster-connection-configuration[cluster connection configuration] +and link:extensions-and-integrations/spring/spring-tx#transaction-concurrency-mode-configuration[transaction concurrency mode configuration]. + +=== Cluster Connection Configuration + +Cluster connection configuration defines Apache Ignite node that `SpringTransactionManager` will use to access the cluster. +To do this, you can use the following approaches. + +[NOTE] +==== +Mixing of multiple approaches is illegal and results in an exception during manager startup. +==== + +[discrete] +=== 1. Specifying name of the manually started Apache Ignite node instance + +This approach is suitable if you have Apache Ignite node instance already running in your application. + +[tabs] +-- +tab:Java[] +[source,java] +---- +@Configuration +@EnableTransactionManagement +public class SpringApplicationConfiguration { + @Bean + public SpringTransactionManager transactionManager() { + SpringTransactionManager mgr = new SpringTransactionManager(); + + mgr.setIgniteInstanceName("<name of the Apache Ignite node instance>"); + + return mgr; + } +} +---- +tab:XML[] +[source,xml] +---- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:tx="http://www.springframework.org/schema/tx"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd";> + <-- Provide Apache Ignite instance name. --> + <bean id="transactionManager" class="org.apache.ignite.transactions.spring.SpringTransactionManager"> + <property + name="igniteInstanceName" + value="<name of the Apache Ignite node instance>"/> + </bean> + + <-- Use annotation-driven transaction configuration. --> + <tx:annotation-driven/> +</beans> +---- +-- + +[discrete] +=== 2. Specifying Apache Ignite node configuration + +In this case Apache Ignite node instance will be started automatically by the manager based on provided configuration. + +[tabs] +-- +tab:Java[] +[source,java] +---- +@Configuration +@EnableTransactionManagement +public class SpringApplicationConfiguration { + @Bean + public SpringTransactionManager transactionManager() { + SpringTransactionManager mgr = new SpringTransactionManager(); + + mgr.setConfiguration(new IgniteConfiguration() + .setIgniteInstanceName("<name of the Ignite node instance>") + // Other required configuration parameters. + ); + + return mgr; + } +} +---- +tab:XML[] +[source,xml] +---- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:tx="http://www.springframework.org/schema/tx"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd";> + <-- Provide configuration bean. --> + <bean id="transactionManager" class="org.apache.ignite.transactions.spring.SpringTransactionManager"> + <property name="configuration"> + <bean id="gridCfg" class="org.apache.ignite.configuration.IgniteConfiguration"> + ... + </bean> + </property> + </bean> + + <-- Use annotation-driven transaction configuration. --> + <tx:annotation-driven/> +</beans> +---- +-- + +[discrete] +=== 3. Specifying path to Apache Ignite XML node configuration file + +In this case Apache Ignite node instance will be started automatically by the manager based on provided configuration. + +[tabs] +-- +tab:Java[] +[source,java] +---- +@Configuration +@EnableTransactionManagement +public class SpringApplicationConfiguration { + @Bean + public SpringTransactionManager transactionManager() { + SpringTransactionManager mgr = new SpringTransactionManager(); + + mgr.setConfigurationPath("<path to an Apache Ignite configuration XML file (path can be absolute or relative to `IGNITE_HOME`)>") + + return mgr; + } +} +---- +tab:XML[] +[source,xml] +---- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:tx="http://www.springframework.org/schema/tx"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd";> + <-- Provide configuration file path. --> + <bean id="transactionManager" class="org.apache.ignite.transactions.spring.SpringTransactionManager"> + <property + name="configurationPath" + value="<path to an Apache Ignite configuration XML file (path can be absolute or relative to `IGNITE_HOME`)"/> + </bean> + + <-- Use annotation-driven transaction configuration. --> + <tx:annotation-driven/> +</beans> +---- +-- + +[NOTE] +==== +If no connection configuration is specified, `SpringTransactionManager` will use Apache Ignite node instance with the +default name. If it does not exist, an exception will be thrown during the `SpringTransactionManager` startup. +==== + +[IMPORTANT] +==== +[discrete] +No matter what configuration approach you chose, the same Apache Ignite node instance must be used to both initialize the +transaction manager and perform transactional operations. In case Apache Ignite node was started by the transaction manager, +you can obtain its instance in your application through `Ignition.ignite("<name of the Apache Ignite node instance>");`. +==== + + +=== Transaction concurrency mode configuration + +The transaction concurrency mode configuration defines the +https://ignite.apache.org/docs/latest/key-value-api/transactions#concurrency-modes-and-isolation-levels[Apache Ignite +transaction concurrency mode, window="_blank"] +that a manager will apply to all transactions that it processes. Review comment: ```suggestion The transaction concurrency mode configuration defines the link:https://ignite.apache.org/docs/latest/key-value-api/transactions#concurrency-modes-and-isolation-levels[Apache Ignite transaction concurrency mode,window=_blank] that a manager applies to all transactions that it processes. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
