This is an automated email from the ASF dual-hosted git repository.
kmiller pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/develop by this push:
new 9f5c476 GEODE-5509 Rewrite the docs on transactions (#2304)
9f5c476 is described below
commit 9f5c476e0916c7ae724c3193e993c184ec3501f4
Author: Karen Miller <[email protected]>
AuthorDate: Thu Aug 30 15:12:31 2018 -0700
GEODE-5509 Rewrite the docs on transactions (#2304)
* GEODE-5509 Rewrite the docs on transactions
* GEODE-5509 Remove extraneous file
* GEODE-5509 Improve the prose and the code examples, per review
* GEODE-5509 Transactions docs rewrite: address most reviewer requests
* GEODE-5509 Transactions section rewrite
- remove all archival material other than that on JTA transactions
---
.../source/subnavs/geode-subnav.erb | 159 +++----------
.../transactions/about_transactions.html.md.erb | 176 --------------
.../cache_transaction_performance.html.md.erb | 29 ---
.../transactions/cache_transactions.html.md.erb | 49 ----
.../cache_transactions_by_region_type.html.md.erb | 150 ------------
.../transactions/chapter_overview.html.md.erb | 50 ++--
.../client_server_transactions.html.md.erb | 55 -----
.../data_location_cache_transactions.html.md.erb | 43 ----
.../transactions/design_considerations.html.md.erb | 137 +++++++++++
.../transactions/directed_example.html.md.erb | 256 +++++++++++++++++++++
.../how_cache_transactions_work.html.md.erb | 69 ------
.../monitor_troubleshoot_transactions.html.md.erb | 56 -----
.../run_a_cache_transaction.html.md.erb | 88 -------
..._cache_transaction_with_external_db.html.md.erb | 52 -----
.../transaction_coding_examples.html.md.erb | 204 ----------------
.../transaction_event_management.html.md.erb | 56 -----
...nsactional_and_nontransactional_ops.html.md.erb | 117 ----------
.../transactions/transactions_intro.html.md.erb | 75 ++++++
.../working_with_transactions.html.md.erb | 237 -------------------
.../diagnosing_system_probs.html.md.erb | 2 +-
.../JTA_transactions.html.md.erb | 10 +-
.../cache_plugins_with_jta.html.md.erb | 2 +-
.../chapter_overview.html.md.erb | 29 +++
.../turning_off_jta.html.md.erb | 0
24 files changed, 559 insertions(+), 1542 deletions(-)
diff --git a/geode-book/master_middleman/source/subnavs/geode-subnav.erb
b/geode-book/master_middleman/source/subnavs/geode-subnav.erb
index aa8e329..7b3b51d 100644
--- a/geode-book/master_middleman/source/subnavs/geode-subnav.erb
+++ b/geode-book/master_middleman/source/subnavs/geode-subnav.erb
@@ -1374,133 +1374,16 @@ limitations under the License.
<li class="has_submenu">
<a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/chapter_overview.html">Transactions</a>
<ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/about_transactions.html">Introduction
and the Application of ACID Semantics</a>
- </li>
- <li class="has_submenu">
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/cache_transactions.html">Geode
Transactions</a>
- <ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/cache_transaction_performance.html">Transaction
Performance</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/data_location_cache_transactions.html">Data
Location for Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/run_a_cache_transaction.html">How
to Run a Geode Transaction</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/run_a_cache_transaction_with_external_db.html">How
to Run a Geode Transaction that Coordinates with an External Database</a>
- </li>
- <li class="has_submenu">
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html">Working
with Geode Transactions</a>
- <ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_vx2_gs4_5k">Setting
Global Copy on Read
- </a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_fdr_wht_vk">Making
a Safe Change Within a Transaction Using CopyHelper.copy
- </a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_ihn_zmt_vk">Transactions
and Functions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_ty1_vnt_vk">Using
Queries and Indexes with Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_ksh_twz_vk">Collections
and Region.Entry Instances in Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_vyt_txz_vk">Using
Eviction and Expiration Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#transactions_and_consistency">Transactions
and Consistent Regions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_u5b_ryz_vk">Suspending
and Resuming Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_ysx_nf1_wk">Using
Cache Writer and Cache Listener Plug-Ins</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/working_with_transactions.html#concept_ocw_vf1_wk">Configuring
Transaction Plug-In Event Handlers</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transaction_event_management.html">How
Transaction Events Are Managed</a>
- </li>
- </ul>
- </li>
- <li class="has_submenu">
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/how_cache_transactions_work.html#topic_fls_1j1_wk">How
Geode Transactions Work</a>
- <ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/how_cache_transactions_work.html#concept_hls_1j1_wk">Transaction
View</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/how_cache_transactions_work.html#concept_sbj_lj1_wk">Committing
Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/cache_transactions_by_region_type.html">Transactions
by Region Type</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/client_server_transactions.html">Client
Transactions</a>
- </li>
- <li class="has_submenu">
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#transactional_and_nontransactional_ops">Comparing
Transactional and Non-Transactional Operations</a>
- <ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#transactional_operations">Transactional
Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#non_transactional_operations">Non-Transactional
Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#entry_operations">Entry
Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#region_operations">Region
Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#cache_operations">Cache
Operations</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactional_and_nontransactional_ops.html#no-ops">No-Ops</a>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
- </li>
- <li class="has_submenu">
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/JTA_transactions.html">JTA
Global Transactions with Geode
- </a>
- <ul>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/JTA_transactions.html#concept_cp1_zx1_wk">Coordinating
with External JTA Transaction Managers</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk">Using
Geode as the "Last Resource" in a Container-Managed JTA Transaction</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/cache_plugins_with_jta.html">Behavior
of Geode Cache Writers and Loaders Under JTA</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/turning_off_jta.html">Turning
Off JTA Transactions
- </a>
- </li>
- </ul>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/monitor_troubleshoot_transactions.html">Monitoring
and Troubleshooting Transactions</a>
- </li>
- <li>
- <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transaction_coding_examples.html">Transaction
Coding Examples</a>
- </li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/transactions_intro.html">Adherence
to ACID Promises</a>
+ <li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/directed_example.html">Code
Examples</a>
+ <li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/transactions/design_considerations.html">Design
Considerations</a>
+ <li>
</ul>
- </li>
<li class="has_submenu">
<a
href="/docs/guide/<%=vars.product_version_nodot%>/developing/function_exec/chapter_overview.html">Function
Execution</a>
<ul>
@@ -3078,6 +2961,30 @@ gfsh</a>
</li>
</ul>
</li>
+ <li class="has_submenu">
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/chapter_overview.html">Transaction
Reference Material</a>
+ <ul>
+ <li class="has_submenu">
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/JTA_transactions.html">JTA
Global Transactions with Geode
+ </a>
+ <ul>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/JTA_transactions.html#concept_cp1_zx1_wk">Coordinating
with External JTA Transaction Managers</a>
+ </li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/JTA_transactions.html#concept_csy_vfb_wk">Using
Geode as the "Last Resource" in a Container-Managed JTA Transaction</a>
+ </li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/cache_plugins_with_jta.html">Behavior
of Geode Cache Writers and Loaders Under JTA</a>
+ </li>
+ <li>
+ <a
href="/docs/guide/<%=vars.product_version_nodot%>/reference/archive_transactions/turning_off_jta.html">Turning
Off JTA Transactions
+ </a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
</ul>
</li>
<li>
diff --git a/geode-docs/developing/transactions/about_transactions.html.md.erb
b/geode-docs/developing/transactions/about_transactions.html.md.erb
deleted file mode 100644
index 5cd0a81..0000000
--- a/geode-docs/developing/transactions/about_transactions.html.md.erb
+++ /dev/null
@@ -1,176 +0,0 @@
----
-title: Introduction and the Application of ACID Semantics
----
-
-<!--
-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.
--->
-
-<a id="topic_jbt_2y4_wk"></a>
-
-
-This section introduces <%=vars.product_name%> transactions.
-<%=vars.product_name%> offers an API for client applications that do
transactional work.
-While the implementation of the API does not provide
-applications a rigid adherence to all the ACID properties of transactions,
-it handles many situations.
-It is fast in comparison to the slow,
-locking methods of a traditional database.
-
-## Overview of the Application's Transaction
-
-An application can run a transaction directly or
-invoke a function which contains a transaction:
-
-- The application uses the transaction API.
-Here is a code fragment to show the structure of a basic transaction,
-with its `begin` to start the transaction and `commit` to end the transaction.
-
- ``` pre
- CacheTransactionManager txManager =
- cache.getCacheTransactionManager();
-
- try {
- txManager.begin();
- // ... do work
- txManager.commit();
- } catch (CommitConflictException conflict) {
- // ... do necessary work for a transaction that failed on commit
- }
- ```
-
-- Use a function.
-A transaction is embedded in a function.
-The application invokes the function,
-and the function contains the transaction that does the `begin`,
-the region operations, and the `commit`.
-
- This use of a function can have performance benefits.
- The performance benefit results from both the function
- and the region data residing on servers.
- As the function invokes region operations,
- those operations on region entries stay on the server,
- so there is no network round trip time to do get or put
- operations on region data.
- Section [Transactions and Functions](working_with_transactions.html)
- details the interaction.
-
-## Adherence to ACID Promises
-
-<%=vars.product_name%> transaction semantics do not offer
-the identical Atomicity-Consistency-Isolation-Durability (ACID) semantics
-of a traditional relational database.
-This <%=vars.product_name%> implementation choice results in
-much higher transaction performance without sacrificing ACID promises.
-<%=vars.product_name%> transactions do not adhere to ACID constraints
-by default,
-but they can be configured for ACID support.
-
-### <a id="transaction_semantics__section_8362ACD06C784B5BBB0B7E986F760169"
class="no-quick-link"></a>Atomicity
-
-Atomicity is “all or nothing” behavior: a transaction completes successfully
only when all of the operations it contains complete successfully. If problems
occur during a transaction, perhaps due to other transactions with overlapping
changes, the transaction cannot successfully complete until the problems are
resolved.
-
-<%=vars.product_name%> transactions provide atomicity and realize speed by
using a reservation system, instead of using the traditional relational
database technique of a two-phase locking of rows. The reservation prevents
other, intersecting transactions from completing, allowing the commit to check
for conflicts and to reserve resources in an all-or-nothing fashion prior to
making changes to the data. After all changes have been made, locally and
remotely, the reservation is released. [...]
-
-### <a id="transaction_semantics__section_7C287DA4A5134780B3199CE074E3F890"
class="no-quick-link"></a>Consistency
-
-Consistency requires that data written within a transaction must observe the
key and value constraints established for the affected region. Note that
validity of the transaction is the responsibility of the application.
-
-### <a id="transaction_semantics__section_126A24EC499D4CF39AE766A0B526A9A5"
class="no-quick-link"></a>Isolation
-
-Isolation assures that operations will see either the pre-transaction state
-or the post-transaction state,
-but not the transitional state that occurs while a transaction is in progress.
-Write operations in a transaction are always confirmed to ensure that stale
-values are not written.
-<%=vars.product_name%>'s performance focus results in a default configuration
-that does not enforce read isolation.
-Transactions have repeatable read isolation,
-so once the committed value is read for a given key,
-it always returns that same value.
-If a transaction write, such as put or invalidate,
-deletes a value for a key that has already been read,
-subsequent reads return the transactional reference.
-
-At a deeper explanation level, the default configuration isolates
-transactions at the process thread level.
-While a transaction is in progress,
-its changes are visible only inside the thread that is running the transaction.
-Other threads within that same process and threads in other processes
-cannot see changes until after the commit operation begins.
-After beginning the commit, the changes are visible in the cache,
-but other threads that access the changing data might see
-partial results of the transaction, leading to a dirty read.
-
-An application requiring the more strict, but slower isolation model
-(such that dirty reads of transitional states are not allowed),
-sets a property and encapsulates read operations within the transaction.
-Configure this strict isolation model with the property:
-
-`-Dgemfire.detectReadConflicts=true`
-
-This property causes read operations to succeed only when they read
-a consistent pre- or post-transactional state.
-If not consistent,
-<%=vars.product_name%> throws a `CommitConflictException`.
-
-### <a id="transaction_semantics__section_F092E368724945BCBF8E5DCB36B97EB4"
class="no-quick-link"></a>Durability
-
-Relational databases provide durability by using disk storage for
-recovery and transaction logging.
-<%=vars.product_name%> is optimized for performance
-and does not support on-disk durability for transactions.
-
-The implementation of the durability promise prohibits
-regions with persistence from participating in transactions.
-The invocation of a persistent region operation within a transaction
-throws an `UnsupportedOperationException` with an associated message of
-
-``` pre
-Operations on persist-backup regions are not allowed because this thread
-has an active transaction
-```
-
-An application that wishes to allow operations on a persistent region during
-a transaction can set this system property:
-
-`-Dgemfire.ALLOW_PERSISTENT_TRANSACTIONS=true`
-
-Setting this system property eliminates the exception.
-It does not provide durability.
-See [Transactions and Persistent
Regions](cache_transactions_by_region_type.html#concept_omy_341_wk) for more
detail on the interaction of persistence
-and durability.
-
-## Types of Transactions
-
-<%=vars.product_name%> supports two kinds of transactions:
**<%=vars.product_name%> transactions** and **JTA global transactions**.
-
-<%=vars.product_name%> transactions are used to group the execution of cache
operations and to gain the control offered by transactional commit and
rollback. Applications create transactions by using an instance of the
<%=vars.product_name%> `CacheTransactionManager`. During a transaction, cache
operations are performed and distributed through <%=vars.product_name%> as
usual. See [<%=vars.product_name%> Cache
Transactions](cache_transactions.html#topic_e15_mr3_5k) for details on <%=vars.
[...]
-
-JTA global transactions allow you to use the standard JTA interface to
coordinate with other XA datastores. When performing JTA global transactions,
use a third party’s implementation (typically application servers such as
WebLogic or JBoss) of JTA. Some third party JTA implementations allow you to
set <%=vars.product_name%> as a “last resource” to ensure transactional
consistency across data sources in the event that <%=vars.product_name%> or
another data source becomes unavailable. For [...]
-
-You can also coordinate a <%=vars.product_name%> cache transaction with an
external database by specifying database operations within cache and
transaction application plug-ins (CacheWriters/CacheListeners and
TransactionWriters/TransactionListeners.) This is an alternative to using JTA
transactions. See [How to Run a <%=vars.product_name%> Transaction that
Coordinates with an External
Database](run_a_cache_transaction_with_external_db.html#task_sdn_2qk_2l).
-
-## Other Features of <%=vars.product_name%> Transactions
-
-- Additional way of doing transactions with JTA.
-Compatibility with Java Transaction API (JTA) transactions, using either
<%=vars.product_name%> JTA or a third-party implementation.
-Ability to use <%=vars.product_name%> as a “last resource” in JTA transactions
with multiple data sources to guarantee transactional consistency.
-
-- Additional capabilities offered with Geode
- - suspend and resume
- - transactions statistics
-
diff --git
a/geode-docs/developing/transactions/cache_transaction_performance.html.md.erb
b/geode-docs/developing/transactions/cache_transaction_performance.html.md.erb
deleted file mode 100644
index 8c07d29..0000000
---
a/geode-docs/developing/transactions/cache_transaction_performance.html.md.erb
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Transaction Performance
----
-
-<!--
-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.
--->
-
-<%=vars.product_name%> transaction performance can vary depending on the type
of regions you are using.
-
-The most common region configurations for use with transactions are
distributed replicated and partitioned:
-
-- Replicated regions are better suited for running transactions on small to
mid-size data sets. To ensure all or nothing behavior, at commit time,
distributed transactions use the global reservation system of the
<%=vars.product_name%> distributed lock service. This works well as long as the
data set is reasonably small.
-- Partitioned regions are the right choice for highly-performant, scalable
operations. Transactions on partitioned regions use only local locking, and
only send messages to the redundant data stores at commit time. Because of
this, these transactions perform much better than distributed transactions.
There are no global locks, so partitioned transactions are extremely scalable
as well.
-
-
diff --git a/geode-docs/developing/transactions/cache_transactions.html.md.erb
b/geode-docs/developing/transactions/cache_transactions.html.md.erb
deleted file mode 100644
index 0c29d4f..0000000
--- a/geode-docs/developing/transactions/cache_transactions.html.md.erb
+++ /dev/null
@@ -1,49 +0,0 @@
-<% set_title(product_name, "Transactions") %>
-
-<!--
-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.
--->
-
-<a id="topic_e15_mr3_5k"></a>
-
-
-Use <%=vars.product_name%> transactions to group the execution of cache
operations and to gain the control offered by transactional commit and
rollback. <%=vars.product_name%> transactions control operations within the
<%=vars.product_name%> cache while the <%=vars.product_name%> distributed
system handles data distribution in the usual way.
-
-- **[Transaction Performance](cache_transaction_performance.html)**
-
- Transaction performance can vary depending on the type of regions you are
using.
-
-- **[Data Location for Transactions](data_location_cache_transactions.html)**
-
- The location where you can run your transaction depends on where you are
storing your data.
-
-- **[How to Run a <%=vars.product_name%>
Transaction](run_a_cache_transaction.html)**
-
- This topic describes how to run a <%=vars.product_name%> transaction.
-
-- **[How to Run a <%=vars.product_name%> Transaction that Coordinates with
an External Database](run_a_cache_transaction_with_external_db.html)**
-
- Coordinate a <%=vars.product_name%> transaction with an external database
by using CacheWriter/CacheListener and TransactionWriter/TransactionListener
plug-ins, **to provide an alternative to using JTA transactions**.
-
-- **[Working with <%=vars.product_name%>
Transactions](working_with_transactions.html)**
-
- This section contains guidelines and additional information on working
with <%=vars.product_name%> transactions.
-
-- **[How <%=vars.product_name%> Transactions
Work](how_cache_transactions_work.html)**
-
- This section provides an explanation of how transactions work on
<%=vars.product_name%> caches.
-
-
diff --git
a/geode-docs/developing/transactions/cache_transactions_by_region_type.html.md.erb
b/geode-docs/developing/transactions/cache_transactions_by_region_type.html.md.erb
deleted file mode 100644
index 15b7939..0000000
---
a/geode-docs/developing/transactions/cache_transactions_by_region_type.html.md.erb
+++ /dev/null
@@ -1,150 +0,0 @@
----
-title: Transactions by Region Type
----
-
-<!--
-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.
--->
-<a id="topic_nlq_sk1_wk"></a>
-
-
-A transaction is managed on a per-cache basis, so multiple regions in the
cache can participate in a single transaction. The data scope of a
<%=vars.product_name%> transaction is the cache that hosts the transactional
data. For partitioned regions, this may be a remote host to the one running the
transaction application. Any transaction that includes one or more partitioned
regions is run on the member storing the primary copy of the partitioned region
data. Otherwise, the transaction ho [...]
-
-- The client executing the transaction code is called the transaction
initiator.
-
-- The member contacted by the transaction initiator is called the
transaction delegate.
-
-- The member that hosts the data—and the transaction—is called the
transaction host.
-
-The transaction host may be the same member or different member from the
transaction initiator. In either case, when the transaction commits, data
distribution is done from the transaction host in the same way.
-
-**Note:**
-If you have consistency checking enabled in your region, the transaction will
generate all necessary version information for the region update when the
transaction commits. See [Transactions and Consistent
Regions](working_with_transactions.html#transactions_and_consistency) for more
details.
-
-## Transactions and Partitioned Regions
-<a id="concept_ysk_xj1_wk"></a>
-
-In partitioned regions, transaction operations are done first on the primary
data store then distributed to other members from there, regardless of which
member initiates the cache operation. This is the same as is done for normal
cache operations on partitioned regions.
-
-In this figure, M1 runs two transactions.
-
-- The first transaction, T1, works on data whose primary buckets are stored
in M1, so M1 is the transaction host.
-- The second transaction, T2, works on data whose primary buckets are stored
in M2, so M1 is the transaction delegate and M2 is the transaction host.
-
-*Transaction on a Partitioned Region:*
-
-<img src="../../images_svg/transactions_partitioned_1.svg"
id="concept_ysk_xj1_wk__image_9BF680072A674BCF9F01958753F02952" class="image
imageleft" />
-
-The transaction is managed on the transaction host. This includes the
transactional view, all operations, and all local cache event handling. In this
example, when T2 is committed, the data on M2 is updated and the transaction
events are distributed throughout the system, exactly as if the transaction had
originated on M2.
-
-The first region operation within the transaction determines the transaction
host. All other operations must also work with that as their transaction host:
-
-- All partitioned region data managed inside the transaction must use the
transaction host as their primary data store. In the example, if transaction T2
tried to work on entry W in addition to entries Y and Z, the
`TransactionDataNotColocatedException` would be thrown. For information on
partitioning data so it is properly colocated for transactions, see
[Understanding Custom Partitioning and Data
Colocation](../partitioned_regions/custom_partitioning_and_data_colocation.html#custom_p
[...]
-- All non-partitioned region data managed inside the transaction must be
available on the transaction host and must be distributed. Operations on
regions with local scope are not allowed in transactions with partitioned
regions.
-
-The next figure shows a transaction that operates on two partitioned regions
and one replicated region. As with the single region example, all local event
handling is done on the transaction host.
-
-For a transaction to work, the first operation must be on one of the
partitioned regions, to establish M2 as the transaction host. Running the first
operation on a key in the replicated region would set M1 as the transaction
host, and subsequent operations on the partitioned region data would fail with
a `TransactionDataNotColocatedException` exception.
-
-*Transaction on a Partitioned Region with Other Regions:*
-
-<img src="../../images_svg/transactions_partitioned_2.svg"
id="concept_ysk_xj1_wk__image_34496249618F46F8B8F7E2D4F342E1E6" class="image" />
-
-## Transactions and Replicated Regions
-<a id="concept_nl5_pk1_wk">
-
-<a id="concept_nl5_pk1_wk__section_C55E80C7136D4A9A8327563E4B89356D"></a>
-For replicated regions, the transaction and its operations are applied to the
local member and the resulting transaction state is distributed to other
members according to the attributes of each region.
-
-**Note:**
-If possible, use `distributed-ack` scope for your regions where you will run
transactions. The `REPLICATE` region shortcuts use `distributed-ack` scope.
-
-The region’s scope affects how data is distributed during the commit phase.
Transactions are supported for these region scopes:
-
-- `distributed-ack`. Handles transactional conflicts both locally and
between members. The `distributed-ack` scope is designed to protect data
consistency. This scope provides the highest level of coordination among
transactions in different members. When the commit call returns for a
transaction run on all distributed-ack regions, you can be sure that the
transaction’s changes have already been sent and processed. In addition, any
callbacks in the remote member have been invoked.
-- `distributed-no-ack`. Handles transactional conflicts locally, with less
coordination between members. This provides the fastest transactions with
distributed regions, but it does not work for all situations. This scope is
appropriate for:
- - Applications with only one writer
- - Applications with multiple writers that write to nonoverlapping data
sets
-- `local`. No distribution, handles transactional conflicts locally.
Transactions on regions with local scope have no distribution, but they perform
conflict checks in the local member. You can have conflict between two threads
when their transactions change the same entry.
-
-Transactions on non-replicated regions (regions that use the old API with
DataPolicy EMPTY, NORMAL and PRELOADED) are always transaction initiators, and
the transaction data host is always a member with a replicated region. This is
similar to the way transactions using the PARTITION\_PROXY shortcut are
forwarded to members with primary bucket.
-
-**Note:**
-When you have transactions operating on EMPTY, NORMAL or PARTITION regions,
make sure that the <%=vars.product_name%> property `conserve-sockets` is set to
false to avoid distributed deadlocks. An empty region is a region created with
the API `RegionShortcut.REPLICATE_PROXY` or a region with that uses the old API
of `DataPolicy` set to `EMPTY`.
-
-## Conflicting Transactions in Distributed-Ack Regions
-
-In this series of figures, even after the commit operation is launched, the
transaction continues to exist during the data distribution (step 3). The
commit does not complete until the changes are made in the remote caches and M1
receives the acknowledgement that verifies that the tasks are complete.
-
-**Step 1:** Before commit, Transactions T1 and T2 each change the same entry
in Region B within their local cache. T1 also makes a change to Region A.
-
-<img src="../../images_svg/transactions_replicate_1.svg"
id="concept_nl5_pk1_wk__image_cj1_zzj_54" class="image" />
-
-**Step 2:** Conflict detected and eliminated. The distributed system
recognizes the potential conflict from Transactions T1 and T2 using the same
entry. T1 started to commit first, so it is allowed to continue. T2's commit
fails with a conflict.
-
-<img src="../../images_svg/transactions_replicate_2.svg"
id="concept_nl5_pk1_wk__image_sbh_21k_54" class="image" />
-
-**Step 3:** Changes are in transit. T1 commits and its changes are merged into
the local cache. The commit does not complete until <%=vars.product_name%>
distributes the changes to the remote regions and acknowledgment is received.
-
-<img src="../../images_svg/transactions_replicate_3.svg"
id="concept_nl5_pk1_wk__image_qgl_k1k_54" class="image" />
-
-**Step 4:** After commit. Region A in M2 and Region B in M3 reflect the
changes from transaction T1 and M1 has received acknowledgment. Results may not
be identical in different members if their region attributes (such as
expiration) are different.
-
-<img src="../../images_svg/transactions_replicate_4.svg"
id="concept_nl5_pk1_wk__image_mkm_q1k_54" class="image" />
-
-## Conflicting Transactions in Distributed-No-Ack Regions
-
-These figures show how using the no-ack scope can produce unexpected results.
These two transactions are operating on the same region B entry. Since they use
no-ack scope, the conflicting changes cross paths and leave the data in an
inconsistent state.
-
-**Step 1:** As in the previous example, Transactions T1 and T2 each change the
same entry in Region B within their local cache. T1 also makes a change to
Region A. Neither commit fails, and the data becomes inconsistent.
-
-<img src="../../images_svg/transactions_replicate_1.svg"
id="concept_nl5_pk1_wk__image_jn2_cbk_54" class="image" />
-
-**Step 2:** Changes are in transit. Transactions T1 and T2 commit and merge
their changes into the local cache. <%=vars.product_name%> then distributes
changes to the remote regions.
-
-<img src="../../images_svg/transactions_replicate_no_ack_1.svg"
id="concept_nl5_pk1_wk__image_fk1_hbk_54" class="image" />
-
-**Step 3:** Distribution is complete. The non-conflicting changes in Region A
have been distributed to M2 as expected. For Region B however, T1 and T2 have
traded changes, which is not the intended result.
-
-<img src="../../images_svg/transactions_replicate_no_ack_2.svg"
id="concept_nl5_pk1_wk__image_ijc_4bk_54" class="image" />
-
-## <a id="concept_nl5_pk1_wk__section_760DE9F2226B46AD8A025F562CEA4D40"
class="no-quick-link"></a>Conflicting Transactions with Local Scope
-
-When encountering conflicts with local scope, the first transaction to start
the commit process completes, and the other transaction’s commit fails with a
conflict.. In the diagram below, the resulting value for entry Y depends on
which transaction commits first.
-<img src="../../images_svg/transactions_replicate_local_1.svg"
id="concept_nl5_pk1_wk__image_A37172C328404796AE1F318068C18F43" class="image" />
-
-## Transactions and Persistent Regions
-<a id="concept_omy_341_wk"></a>
-
-By default, <%=vars.product_name%> does not allow transactions on persistent
regions. You can enable the use of transactions on persistent regions by
setting the property `gemfire.ALLOW_PERSISTENT_TRANSACTIONS` to true. This may
also be accomplished at server startup using gfsh:
-
-``` pre
-gfsh start server --name=server1 --dir=server1_dir \
---J=-Dgemfire.ALLOW_PERSISTENT_TRANSACTIONS=true
-```
-
-Since <%=vars.product_name%> does not provide atomic disk persistence
guarantees, the default behavior is to disallow disk-persistent regions from
participating in transactions. However, when choosing to enable transactions on
persistent regions, consider the following:
-
-- <%=vars.product_name%> does ensure atomicity for in-memory updates.
-- When any failed member is unable to complete the logic triggered by a
transaction (including subsequent disk writes), that failed member is removed
from the distributed system and, if restarted, must rebuild its state from
surviving nodes that successfully complete the updates.
-- The chances of multiple nodes failing to complete the disk writes that
result from a transaction commit due to nodes crashing for unrelated reasons
are small. The real risk is that the file system buffers holding the persistent
updates do not get written to disk in the case of operating system or hardware
failure. If only the <%=vars.product_name%> process crashes, atomicity still
exists. The overall risk of losing disk updates can also be mitigated by
enabling synchronized disk file [...]
-
-To mitigate the risk of data not get fully written to disk on all copies of
the participating persistent disk stores:
-
-- Make sure you have enough redundant copies of the data. The guarantees of
multiple/distributed in-memory copies being (each) atomically updated as part
of the Transaction commit sequence can help guard against data corruption.
-- When executing transactions on persistent regions, we recommend using the
TransactionWriter to log all transactions along with a time stamp. This will
allow you to recover in the event that all nodes fail simultaneously while a
transaction is being committed. You can use the log to recover the data
manually.
-
-
diff --git a/geode-docs/developing/transactions/chapter_overview.html.md.erb
b/geode-docs/developing/transactions/chapter_overview.html.md.erb
index 06fbcb0..f1441cd 100644
--- a/geode-docs/developing/transactions/chapter_overview.html.md.erb
+++ b/geode-docs/developing/transactions/chapter_overview.html.md.erb
@@ -18,29 +18,27 @@ 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.
-->
-
-<%=vars.product_name%> provides a transactions API, with `begin`, `commit`,
and `rollback` methods. These methods are much the same as the familiar
relational database transactions methods.
-
-- **[Introduction and the Application of ACID
Semantics](about_transactions.html)**
-
- This section presents the features of <%=vars.product_name%> transactions
and discusses how the implementation adheres to ACID semantics.
-It also details the two kinds of transaction that <%=vars.product_name%>
supports:
-**<%=vars.product_name%> transactions** and **JTA global transactions**.
-
-- **[<%=vars.product_name%> Transactions](cache_transactions.html)**
-
- Use <%=vars.product_name%> transactions to group the execution of cache
operations and to gain the control offered by transactional commit and
rollback. <%=vars.product_name%> transactions control operations within the
<%=vars.product_name%> cache while the <%=vars.product_name%> distributed
system handles data distribution in the usual way.
-
-- **[JTA Global Transactions with
<%=vars.product_name%>](JTA_transactions.html)**
-
- Use JTA global transactions to coordinate <%=vars.product_name%>
transactions and JDBC transactions.
-
-- **[Monitoring and Troubleshooting
Transactions](monitor_troubleshoot_transactions.html)**
-
- This topic covers errors that may occur when running transactions in
<%=vars.product_name%>.
-
-- **[Transaction Coding Examples](transaction_coding_examples.html)**
-
- This section provides several code examples for writing and executing
transactions.
-
-
+
+This section describes <%=vars.product_name%> transactions.
+<%=vars.product_name%> offers an API for client applications that do
+transactional work.
+<%=vars.product_name%> implements optimistic transactions,
+with the familiar `begin`, `commit`, and `rollback` methods
+that implement the same operations as in
+relational database transactions methods.
+
+- **[Adherence to ACID Promises](transactions_intro.html)**
+
+ This section explains the ways in which <%=vars.product_name%>'s
+implementation of optimistic transactions provides ACID semantics.
+
+- **[Code Examples](directed_example.html)**
+
+ An application-based transaction and a transaction embedded in
+ a function provide examples to model.
+
+- **[Design Considerations](design_considerations.html)**
+
+ Designs that extend beyond the basics introduce other considerations.
+ This section identifies and discusses how transactions interact
+ with other aspects of the system.
diff --git
a/geode-docs/developing/transactions/client_server_transactions.html.md.erb
b/geode-docs/developing/transactions/client_server_transactions.html.md.erb
deleted file mode 100644
index e450296..0000000
--- a/geode-docs/developing/transactions/client_server_transactions.html.md.erb
+++ /dev/null
@@ -1,55 +0,0 @@
----
-title: Client Transactions
----
-
-<!--
-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.
--->
-
-
-The syntax for writing client transactions is the same on the Java client as
with any other <%=vars.product_name%> member, but the underlying behavior in a
client-run transaction is different from general transaction behavior.
-
-For general information about running a transaction, refer to [How to Run a
<%=vars.product_name%>
Transaction](run_a_cache_transaction.html#task_f15_mr3_5k).
-
-- **[How <%=vars.product_name%> Runs Client
Transactions](client_server_transactions.html#how_gemfire_runs_clients)**
-
-- **[Client Cache Access During a
Transaction](client_server_transactions.html#client_cache_access)**
-
-- **[Client Transactions and Client Application
Plug-Ins](client_server_transactions.html#client_app_plugins)**
-
-- **[Client Transaction
Failures](client_server_transactions.html#client_transaction_failures)**
-
-## <a id="how_gemfire_runs_clients" class="no-quick-link"></a>How
<%=vars.product_name%> Runs Client Transactions
-
-When a client performs a transaction, the transaction is delegated to a server
that acts as the transaction initiator in the server system. As with regular,
non-client transactions, this server delegate may or may not be the transaction
host.
-
-In this figure, the application code on the client makes changes to data
entries Y and Z within a transaction. The delegate performing the transaction
(M1) does not host the primary copy of the data being modified. The transaction
takes place on the server containing this data (M2).
-
-<img src="../../images/transactions-client-1.png"
id="how_gemfire_runs_clients__image_5DCA65F2B88F450299EFD19DAAA93D4F"
class="image" />
-
-## <a id="client_cache_access" class="no-quick-link"></a>Client Cache Access
During a Transaction
-
-To maintain cache consistency, <%=vars.product_name%> blocks access to the
local client cache during a transaction. The local client cache may reflect
information inconsistent with the transaction in progress. When the transaction
completes, the local cache is accessible again.
-
-## <a id="client_app_plugins" class="no-quick-link"></a>Client Transactions
and Client Application Plug-Ins
-
-Any plug-ins installed in the client are not invoked by the client-run
transaction. The client that initiates the transaction receives changes from
its server based on transaction operations the same as any other client -
through mechanisms like subscriptions and continuous query results. The client
transaction is performed by the server delegate, where application plug-ins
operate the same as if the server were the sole initiator of the transaction.
-
-## <a id="client_transaction_failures" class="no-quick-link"></a>Client
Transaction Failures
-
-In addition to the failure conditions common to all transactions, client
transactions can fail if the transaction delegate fails. If the delegate
performing the transaction fails, the transaction code throws a transaction
exception. See [Transaction
Exceptions](monitor_troubleshoot_transactions.html#monitor_troubleshoot_transactions__section_8942ABA6F23C4ED58877C894B13F4F21).
-
-
diff --git
a/geode-docs/developing/transactions/data_location_cache_transactions.html.md.erb
b/geode-docs/developing/transactions/data_location_cache_transactions.html.md.erb
deleted file mode 100644
index a26669b..0000000
---
a/geode-docs/developing/transactions/data_location_cache_transactions.html.md.erb
+++ /dev/null
@@ -1,43 +0,0 @@
----
-title: Data Location for Transactions
----
-
-<!--
-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.
--->
-
-The location where you can run your transaction depends on where you are
storing your data.
-
-Transactions must operate on a data set that is hosted entirely by one member.
-
-- For replicated or other distributed regions, the transaction uses only the
data set in the member where the transaction is run.
-- For partitioned regions, you must colocate all your transactional data in
a single member. See [Colocate Data from Different Partitioned
Regions](../partitioned_regions/colocating_partitioned_region_data.html).
-- For transactions run on partitioned and distributed region mixes,
-you must colocate the partitioned region data
-and make sure the distributed region data is available in any member
-hosting the partitioned region data.
-
-For transactions involving partitioned regions, any member with the regions
defined can orchestrate the transactional operations, regardless of whether
that member hosts data for the regions. If the transactional data resides on a
remote member, the transaction is carried out by proxy in the member hosting
the data. The member hosting the data is referred to as the transaction host.
-
-The first operation determines and sets the transaction host for any
-transactions involving partitioned regions.
-Therefore, in a system that colocates data, the first operation must
-be to the host with the colocated data,
-such that the transaction host is the one with the colocated data.
-The first operation must not be to a replicated region,
-as any member might become the transaction host.
-If the wrong member becomes the transaction host,
-accesses of partitioned region data will result in an exception.
diff --git
a/geode-docs/developing/transactions/design_considerations.html.md.erb
b/geode-docs/developing/transactions/design_considerations.html.md.erb
new file mode 100644
index 0000000..e6a04e8
--- /dev/null
+++ b/geode-docs/developing/transactions/design_considerations.html.md.erb
@@ -0,0 +1,137 @@
+---
+title: Design Considerations
+---
+
+<!--
+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.
+-->
+
+<a id="transaction-considerations"></a>
+
+Designs that incorporate more complex features introduce further
+considerations.
+This section discusses how transactions interact with other
+<%=vars.product_name%> features.
+
+- **[Colocate Partitioned Regions](#colocate-PRs)**
+- **[Region Operations Return References](#copy-on-read-transactions)**
+- **[First Operation with Mixed Region Types](#first-op-with-mixed-types)**
+- **[Allowing Transactions to Work on Persistent
Regions](#transactions-persistence)**
+- **[Mixing Transactions with Queries and Indexes](#transactions-queries)**
+- **[Mixing Transactions with Eviction](#transactions-eviction)**
+- **[Mixing Transactions with Expiration](#transactions-expiration)**
+- **[Changing the Handling of Dirty Reads](#transactions-dirty-reads)**
+
+## <a id="colocate-PRs" class="no-quick-link"></a>Colocate Partitioned Regions
+
+For performance,
+transactions that operate on more than one partitioned region
+require that those partitioned regions colocate their entries.
+[Colocate Data from Different Partitioned
Regions](../partitioned_regions/colocating_partitioned_region_data.html)
describes how to colocate
+entries.
+
+## <a id="copy-on-read-transactions" class="no-quick-link"></a>Region
Operations Return References
+
+For performance,
+server-invoked region operations return references to region entries.
+Any assignment to that reference changes the entry within the region.
+This subverts the system's ability to maintain consistency
+and the callback chain for handlers such as cache writers
+and cache loaders.
+
+Changing an entry using a reference from within a transaction executing
+on a server has the same consistency issues, but is even worse,
+as the change will not be seen as part of the transactional state.
+
+There are two ways to work with a reference: make a copy,
+or configure the system to return copies instead of references.
+There is a performance penalty to having the system return copies.
+Both ways are detailed in [Safe Entry
Modification](../../basic_config/data_entries_custom_classes/managing_data_entries.html#managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809).
+
+## <a id="first-op-with-mixed-types" class="no-quick-link"></a>First Operation
with Mixed Region Types
+
+When more than one region participates in a transaction,
+and there is at least one partitioned and at least one
+replicated region,
+the code must do its first operation on the partitioned
+region to avoid a `TransactionDataNotColocatedException`.
+Write the transaction to do its first operation on a partitioned
+region, even if the operation will be spurious.
+
+## <a id="transactions-persistence" class="no-quick-link"></a> Allowing
Transactions to Work on Persistent Regions
+
+<%=vars.product_name%>'s implementation of atomic transactions prohibits
+regions with persistence from participating in transactions.
+The invocation of a persistent region operation within a transaction
+throws an `UnsupportedOperationException` with an associated message of
+
+``` pre
+Operations on persist-backup regions are not allowed because this thread
+has an active transaction
+```
+
+An application that wishes to allow operations on a persistent region during
+a transaction can set this system property:
+
+`-Dgemfire.ALLOW_PERSISTENT_TRANSACTIONS=true`
+
+Setting this system property eliminates the exception.
+It does not change the fact that atomicity is not enforced
+for disk writes that occur with the commit of a transaction.
+A server crash during the commit may succeed in some,
+but not all of the disk writes.
+
+## <a id="transactions-queries" class="no-quick-link"></a>Mixing Transactions
with Queries and Indexes
+
+Queries and query results reflect region state, and not any state or
+changes that occur within a transaction.
+Likewise, the contents and updates to an index do not intersect with any
+changes made within a transaction.
+Therefore, do not mix transactions with queries or indexed regions.
+
+## <a id="transactions-eviction" class="no-quick-link"></a>Mixing Transactions
with Eviction
+
+LRU eviction and transactions work well together.
+Any eviction operation on a region entry that is operated on
+from within a transaction is deferred until the transaction is committed.
+Further, because any entry touched by the transaction
+has had its LRU clock reset,
+eviction is not likely to choose those entries as victims
+immediately after the commit.
+
+## <a id="transactions-expiration" class="no-quick-link"></a>Mixing
Transactions with Expiration
+
+A transaction disables expiration on any region entries affected
+by the transaction.
+
+## <a id="transactions-dirty-reads" class="no-quick-link"></a>Changing the
Handling of Dirty Reads
+
+An application requiring a strict,
+but slower isolation model,
+such that dirty reads of transitional states are not allowed,
+should set a property and encapsulate read operations within the transaction.
+Configure this strict isolation model with the property:
+
+```
+-Dgemfire.detectReadConflicts=true
+```
+
+This property causes read operations to succeed only when they
+read a consistent pre- or post-transactional state.
+If not consistent,
+<%=vars.product_name%> throws a `CommitConflictException`.
+
+
diff --git a/geode-docs/developing/transactions/directed_example.html.md.erb
b/geode-docs/developing/transactions/directed_example.html.md.erb
new file mode 100644
index 0000000..309437e
--- /dev/null
+++ b/geode-docs/developing/transactions/directed_example.html.md.erb
@@ -0,0 +1,256 @@
+---
+title: Code Examples
+---
+
+<!--
+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.
+-->
+
+<a id="transaction-example"></a>
+
+An application can run a transaction directly or
+invoke a function which contains a transaction.
+This section illustrates these two use cases with code fragments
+that demonstrate the proper way to program a transaction.
+
+An expected use case operates on two regions within a transaction.
+For performance purposes the
+<%=vars.product_name%> transaction implementation requires that region entries
+of partitioned regions be colocated.
+See [Custom-Partitioning and Colocating
Data](../partitioned_regions/overview_custom_partitioning_and_data_colocation.html)
for details on how to colocate region entries.
+
+
+## Transaction within an Application
+
+An application/client uses the `CacheTransactionManager` API.
+This most basic code fragment shows the structure of a transaction,
+with its `begin` to start the transaction, `commit` to end the transaction,
+and handling of exceptions that these methods may throw.
+
+``` pre
+CacheTransactionManager txManager =
+ cache.getCacheTransactionManager();
+
+try {
+ txManager.begin();
+ // ... do transactional, region operations
+ txManager.commit();
+} catch (CommitConflictException conflict) {
+ // ... do necessary work for a transaction that failed on commit
+} finally {
+ // All other exceptions will be handled by the caller.
+ // Examples of some exceptions: the data is not colocated, a rebalance
+ // interfered with the transaction, or the server is gone.
+ // Any exception thrown by a method other than commit() needs
+ // to do a rollback to avoid leaking the transaction state.
+ if(mgr.exists()) {
+ mgr.rollback();
+ }
+}
+```
+
+More details of a transaction appear in this next application/client
+code fragment example.
+In this typical transaction,
+the put operations must be atomic and two regions are involved.
+
+In this transaction, a customer's purchase is recorded.
+The `cash` region contains each customer's cash balance
+available for making trades.
+The `trades` region records each customer's balance spent on trades.
+
+If there is a conflict upon commit of the transaction,
+an exception is thrown, and this example tries again.
+
+```
+// inputs needed for this transaction; shown as variables for simplicity
+final String customer = "Customer1";
+final Integer purchase = 1000;
+
+// region set up shown to promote understanding
+Cache cache = new CacheFactory().create();
+Pool pool = PoolManager.createFactory()
+ .addLocator("localhost", LOCATOR_PORT)
+ .create("pool-name");
+Region<String, Integer> cash =
+ cache.createClientRegionFactory(ClientRegionShortcut.PROXY)
+ .setPoolName(pool.getName())
+ .create("cash");
+Region<String, Integer> trades =
+ cache.createClientRegionFactory(ClientRegionShortcut.PROXY)
+ .setPoolName(pool.getName())
+ .create("trades");
+
+// transaction code
+CacheTransactionManager txmgr = cache.getCacheTransactionManager();
+boolean retryTransaction = false;
+do {
+ try {
+ txmgr.begin();
+
+ // Subtract out the cost of the trade for this customer's balance
+ Integer cashBalance = cash.get(customer);
+ Integer newBalance = (cashBalance != null ? cashBalance : 0) - purchase;
+ cash.put(customer, newBalance);
+
+ // Add in the cost of the trade for this customer
+ Integer tradeBalance = trades.get(customer);
+ newBalance = (tradeBalance != null ? tradeBalance : 0) + purchase;
+ trades.put(customer, newBalance);
+
+ txmgr.commit();
+ retryTransaction = false;
+ }
+ catch (CommitConflictException conflict) {
+ // entry value changed causing a conflict for this customer, so try again
+ retryTransaction = true;
+ } finally {
+ // All other exceptions will be handled by the caller.
+ // Any exception thrown by a method other than commit() needs
+ // to do a rollback to avoid leaking the transaction state.
+ if(mgr.exists()) {
+ mgr.rollback();
+ }
+ }
+
+} while (retryTransaction);
+```
+
+Design transactions such that any get operations are within the transaction.
+This causes those entries to be part of the transactional state,
+which is desired such that intersecting transactions can be detected
+and signal commit conficts.
+
+## Transaction within a Function
+
+A transaction may be embedded in a function.
+The application invokes the function,
+and the function contains the transaction that does the `begin`,
+the region operations, and the `commit` or `rollback`.
+
+This use of a function can have performance benefits.
+The performance benefit results from both the function
+and the region data residing on servers.
+As the function invokes region operations,
+those operations on region entries stay on the server,
+so there is no network round trip time to do get or put
+operations on region data.
+
+This function example accomplishes atomic updates on a single
+region representing the quantity of products available in inventory.
+Doing this in a transaction prevents double allocating inventory for
+two orders placed simultaneously.
+
+
+``` pre
+/**
+ * Atomically reduce inventory quantity
+ */
+public class TransactionalFunction extends Function {
+
+ /**
+ * Returns true if the function had the requested quantity of
+ * inventory and successfully completed the transaction to
+ * record the reduced inventory that fulfills the order.
+ */
+ @Override
+ public void execute(FunctionContext context) {
+ RegionFunctionContext rfc = (RegionFunctionContext) context;
+ Region<ProductId, Integer> inventoryRegion = rfc.getDataSet();
+
+ CacheTransactionManager
+ mgr = CacheFactory.getAnyInstance().getCacheTransactionManager();
+
+ // single argument will be a ProductId and a quantity
+ ProductRequest request = (ProductRequest) rfc.getArguments();
+ ProductId productRequested = request.getProductId();
+ Integer qtyRequested = request.getQuantity();
+
+ Boolean success = false;
+
+ do {
+ Boolean commitConflict = false;
+ try {
+ mgr.begin();
+
+ Integer qtyAvailable = inventoryRegion.get(productRequested);
+ Integer qtyRequested = request.getQuantity();
+ if (qtyAvail >= qtyRequested) {
+ // enough inventory is available, so process request
+ Integer remaining = qtyAvailable - qtyRequested;
+ inventoryRegion.put(productRequested, remaining);
+ success = true;
+ }
+
+ mgr.commit();
+ } catch (CommitConflictException conflict) {
+ // retry transaction, as another request on this same key succeeded,
+ // so this transaction attempt failed
+ commitConflict = true;
+ } finally {
+ // All other exceptions will be handled by the caller; however,
+ // any exception thrown by a method other than commit() needs
+ // to do a rollback to avoid leaking the transaction state.
+ if(mgr.exists()) {
+ mgr.rollback();
+ }
+ }
+
+ } while (commitConflict);
+
+ context.getResultSender().lastResult(success);
+ }
+
+ @Override
+ public String getId() {
+ return "TxFunction";
+ }
+
+ /**
+ * Returning true causes this function to execute on the server
+ * that holds the primary bucket for the given key. It can save a
+ * network hop from the secondary to the primary.
+ */
+ @Override
+ public Boolean optimizeForWrite() {
+ return true;
+ }
+}
+```
+
+The application-side details on function implementation are
+not covered in this example.
+The application sets up the function context and the argument.
+See the section on [Function
Execution](../function_exec/chapter_overview.html) for details on functions.
+
+The function implementation needs to catch the commit conflict exception
+such that it can retry the entire transaction.
+The exception only occurs if another request for the same product
+intersected with this one,
+and that other request's transaction committed first.
+
+The `optimizeForWrite` method is defined to cause the system to
+execute the function on the server that holds the primary bucket
+for the given key.
+It can save a network hop from the secondary to the primary.
+
+Note that the variable `qtyAvailable` is a reference,
+because the `Region.get` operation returns a reference
+within this server-side code.
+Read [Region Operations Return
References](design_considerations.html#copy-on-read-transactions)
+for details and how to work around the
+implications of a reference as a return value when working with server code.
+
diff --git
a/geode-docs/developing/transactions/how_cache_transactions_work.html.md.erb
b/geode-docs/developing/transactions/how_cache_transactions_work.html.md.erb
deleted file mode 100644
index 7709f3a..0000000
--- a/geode-docs/developing/transactions/how_cache_transactions_work.html.md.erb
+++ /dev/null
@@ -1,69 +0,0 @@
-<% set_title("How", product_name, "Transactions Work") %>
-
-<!--
-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.
--->
-<a id="topic_fls_1j1_wk"></a>
-
-
-This section provides an explanation of how transactions work on
<%=vars.product_name%> caches.
-
-All the regions in a <%=vars.product_name%> member cache can participate in a
transaction. A Java application can operate on the cache using multiple
transactions. A transaction is associated with only one thread, and a thread
can operate on only one transaction at a time. Child threads do not inherit
existing transactions.
-
-- **[Transaction View](#concept_hls_1j1_wk)**
-
-- **[Committing Transactions](#concept_sbj_lj1_wk)**
-
-- **[Transactions by Region
Type](cache_transactions_by_region_type.html#topic_nlq_sk1_wk)**
-
-- **[Client Transactions](client_server_transactions.html)**
-
-- **[Comparing Transactional and Non-Transactional
Operations](transactional_and_nontransactional_ops.html#transactional_and_nontransactional_ops)**
-
-## Transaction View
-
-A transaction is isolated from changes made concurrently to the cache. Each
transaction has its own private view of the cache, including the entries it has
read and the changes it has made. The first time the transaction touches an
entry in the cache, either to read or write, it produces a snapshot of that
entry’s state in the transaction’s view. The transaction maintains its current
view of the entry, which reflects only the changes made within the transaction.
The transaction remembers [...]
-
-<img src="../../images/Transaction-simple.png"
id="concept_hls_1j1_wk__image_D21EF847CD1D4B64AD1786033FB44F5C" class="image" />
-
-## Committing Transactions
-
-When a commit succeeds, the changes recorded in the transaction view are
merged into the cache. If the commit fails or the transaction is rolled back,
all of its changes are dropped.
-
-When a transaction is committed, the transaction management system uses a
two-phase commit protocol:
-
-1. Reserves all the entries involved in the transaction from changes by any
other transactional thread. For distributed regions, it reserves the entries in
the entire distributed system. For partitioned regions, it reserves them on the
data store, where the transaction is running.
-2. Checks the cache for conflicts on affected keys, to make sure all entries
are still in the same state they were in when this transaction first accessed
them.
-3. If any conflict is detected, the manager rolls back the transaction.
-4. If no conflict is detected, the manager:
- 1. Calls the `TransactionWriter` in the member where the transaction is
running. This allows the system to write through transactional updates to an
external data source.
- 2. Updates the local cache and distributes the updates to the other
members holding the data. Cache listeners are called for these updates, in each
cache where the changes are made, the same as for non-transactional operations.
- 3. Calls the `TransactionListener`s in the member where the transaction
is running.
-
-5. Releases the transaction reservations on the entries.
-
-The manager updates the local cache and distributes the updates to other
members in a non-atomic way.
-
-- If other threads read the keys the transaction is modifying, they may see
some in their pre-transaction state and some in their post-transaction state.
-- If other, non-transactional sources update the keys the transaction is
modifying, the changes may intermingle with this transaction’s changes. The
other sources can include distributions from remote members, loading
activities, and other direct cache modification calls from the same member.
When this happens, after your commit finishes, the cache state may not be what
you expected.
-
-If the transaction fails to complete any of the steps, a
CommitConflictException is thrown to the calling application.
-
-Once the members involved in the transaction have been asked to commit, the
transaction completes even if one of the participating members were to leave
the system during the commit. The transaction completes successfully so long as
all remaining members are in agreement.
-
-Each member participating in the transaction maintains a membership listener
on the transaction coordinator. If the transaction coordinator goes away after
issuing the final commit call, the transaction completes in the remaining
members.
-
-
diff --git
a/geode-docs/developing/transactions/monitor_troubleshoot_transactions.html.md.erb
b/geode-docs/developing/transactions/monitor_troubleshoot_transactions.html.md.erb
deleted file mode 100644
index 7d27071..0000000
---
a/geode-docs/developing/transactions/monitor_troubleshoot_transactions.html.md.erb
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Monitoring and Troubleshooting Transactions
----
-
-<!--
-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.
--->
-
-This topic covers errors that may occur when running transactions in
<%=vars.product_name%>.
-
-<a
id="monitor_troubleshoot_transactions__section_881D2FF6761B4D689DDB46C650E2A2E1"></a>
-Unlike database transactions, <%=vars.product_name%> does not write a
transaction log to disk. To get the full details about committed operations,
use a transaction listener to monitor the transaction events and their
contained cache events for each of your transactions.
-
-## <a
id="monitor_troubleshoot_transactions__section_2B66338C851A4FF386B60CC5CF4DCF77"
class="no-quick-link"></a>Statistics on Transactions
-
-During the operation of <%=vars.product_name%> transactions, if statistics are
enabled, transaction-related statistics are calculated and accessible from the
CachePerfStats statistic resource. Because the transaction’s data scope is the
cache, these statistics are collected on a per-cache basis.
-
-## <a
id="monitor_troubleshoot_transactions__section_EA9277E6CFD7423F95BA4D04955FDE2A"
class="no-quick-link"></a>Commit
-
-In a failed commit, the exception lists the first conflict that caused the
failure. Other conflicts can exist, but are not reported.
-
-## Capacity Limits
-
-A transaction can create data beyond the capacity limit set in the region’s
eviction attributes. The capacity limit does not take effect until commit time.
Then, any required eviction action takes place as part of the commit.
-
-## <a
id="monitor_troubleshoot_transactions__section_C7588E4F143B4D7FAFAEDCF5AE4FF2C8"
class="no-quick-link"></a>Interaction with the Resource Manager
-
-The <%=vars.product_name%> resource manager, which controls overall heap use,
either allows all transactional operations or blocks the entire transaction. If
a cache reaches the critical threshold in the middle of a commit, the commit is
allowed to finish before the manager starts blocking operations.
-
-## <a
id="monitor_troubleshoot_transactions__section_8942ABA6F23C4ED58877C894B13F4F21"
class="no-quick-link"></a>Transaction Exceptions
-
-The following sections list possible transaction exceptions.
-
-**Exceptions Indicating Transaction Failure**
-
-- **`TransactionDataNodeHasDepartedException`**. This exception means the
transaction host has departed unexpectedly. Clients and members that run
transactions but are not a transaction host can get this exception. You can
avoid this by working to ensure your transaction hosts are stable and remain
running when transactions are in progress.
-- **`TransactionDataNotColocatedException`**. You will get this error if you
try to run a transaction on data that is not all located in the same member.
Partition your data so that a single member contains all data that will be
accessed as part of a single transaction. See [Transactions and Partitioned
Regions](cache_transactions_by_region_type.html#concept_ysk_xj1_wk) and
[Understanding Custom Partitioning and Data
Colocation](../partitioned_regions/custom_partitioning_and_data_coloc [...]
-- **`TransactionDataRebalancedException`**. You get this error if your
transactional data is moved to another member for rebalancing during the
transaction. Manage your partitioned region data to avoid rebalancing during a
transaction. See [Rebalancing Partitioned Region
Data](../partitioned_regions/rebalancing_pr_data.html#rebalancing_pr_data).
-
-**Exceptions Indicating Unknown Transaction Outcome**
-
-- **`TransactionInDoubtException`**. Some of the transactional operations
may have succeeded and some may have failed. This can happen to clients and to
any member running a transaction on another data host. To manage this, you may
want to install cache listeners in the members running the transaction code.
Use the listeners to monitor and record the changes you receive from your
transactions so you can recover as needed if you get this exception.
-
diff --git
a/geode-docs/developing/transactions/run_a_cache_transaction.html.md.erb
b/geode-docs/developing/transactions/run_a_cache_transaction.html.md.erb
deleted file mode 100644
index 9376513..0000000
--- a/geode-docs/developing/transactions/run_a_cache_transaction.html.md.erb
+++ /dev/null
@@ -1,88 +0,0 @@
-<% set_title("How to Run a", product_name, "Transaction") %>
-
-<!--
-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.
--->
-<a id="task_f15_mr3_5k"></a>
-
-
-This topic describes how to run a <%=vars.product_name%> transaction.
-
-Applications manage transactions on a per-cache basis. A
<%=vars.product_name%> transaction starts with a
`CacheTransactionManager.begin` method and continues with a series of
operations, which are typically region operations such as region create,
update, clear and destroy. The begin, commit, and rollback are directly
controlled by the application. A commit, failed commit, or voluntary rollback
by the transaction manager ends the transaction.
-
-You can run transactions on any type of cache region except regions with
**global** scope. An operation attempted on a region with global scope throws
an `UnsupportedOperationException` exception.
-
-A transaction may not be nested within another transaction. An attempt to
begin a nested transaction will throw an `IllegalStateException` exception.
-
-This discussion centers on transactions on replicated and partitioned regions.
If you use non-replicated distributed regions, follow the guidelines for
replicated regions.
-
-1. **Configure the cache copy-on-read behavior in the members hosting the
transactional data, or perform cache updates that avoid in-place changes.**
This allows the transaction manager to control when cache updates are visible
outside the transaction. See [Setting Global Copy on
Read](working_with_transactions.html#concept_vx2_gs4_5k).
-2. **Configure your regions for transactions in the members hosting the
transactional data.**
-
- | If you use...
| then you should...
|
-
|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
- | **replicated regions**
| Use `distributed-ack` scope. The region shortcuts
specifying `REPLICATE` use `distributed-ack` scope. This is particularly
important if you have more than one data producer. With one data producer, you
can safely use `distributed-no-ack`.
[...]
- | **partitioned regions**
| Custom partition and colocate data among regions so all
the data for any single transaction is hosted by a single member. If the
transaction is run from a member other than the one hosting the data, the
transaction will run by proxy in the member hosting the data. The partitioned
region must be defined for the application that runs the transaction, but the
data can be hosted in a remote member. |
- | **persistent regions**
| Configure <%=vars.product_name%> to allow transactions on
persistent regions. By default, the configuration does not allow transactions
on persistent regions. Enable the use of transactions on persistent regions by
setting the property `gemfire.ALLOW_PERSISTENT_TRANSACTIONS` to true.
|
- | **a mix of partitioned and replicated regions**
| Make sure any replicated region involved in the
transaction is hosted on every member that hosts the partitioned region data.
All data for a single transaction must reside within a single host.
|
- | **delta propagation**
| Set the region attribute `cloning-enabled` to true. This
lets <%=vars.product_name%> do conflict checks at commit time. Without this,
the transaction will throw an `UnsupportedOperationInTransactionException `
exception.
|
- | **global JTA transactions with only <%=vars.product_name%>
transactions** | Set the region attribute `ignore-jta` to true for all regions
that you do *not* want to participate in JTA global transactions. It is false
by default. For instructions on how to run a JTA global transaction, see [JTA
Global Transactions with <%=vars.product_name%>](JTA_transactions.html). |
-
-3. **Update your cache event handler and transaction event handler
implementations to handle your transactions.**
- Cache event handlers may be used with transactions. Cache listeners are
called after the commit, instead of after each cache operation, and the cache
listeners receive conflated transaction events. Cache writers and loaders are
called as usual, at the time of the operation.
-
- Follow these additional guidelines when writing cache event handler
callbacks:
- - Make sure cache callbacks are transactionally aware, because a
transactional operation could launch callbacks that are not transactional.
- - Make sure cache listeners will operate properly, given entry event
conflation. Two events for the same key are conflated by removing the existing
event and queuing the new event.
-
- See [Using Cache Writer and Cache Listener
Plug-Ins](working_with_transactions.html#concept_ysx_nf1_wk) for more
information.
-
- Transaction event handlers are available. Transaction event handlers are
cache-wide. You can install one transaction writer and any number of
transaction listeners. Follow these guidelines:
-<ul>
- <li>Implement with synchronization for thread safety. Listener and writer
handlers may be invoked at the same time by different threads for different
transactions.</li>
- <li>Keep transactional callback implementations lightweight, and avoid
doing anything that might cause the callbacks to block.</li>
-</ul>
- See [Configuring Transaction Plug-In Event
Handlers](working_with_transactions.html#concept_ocw_vf1_wk) for more
information.
-
-4. **Write the transaction code.** For example:
-
- ``` pre
- CacheTransactionManager txManager =
- cache.getCacheTransactionManager();
-
- try {
- txManager.begin();
- // ... do work
- txManager.commit();
- } catch (CommitConflictException conflict) {
- // ... do necessary work for a transaction that failed on commit
- }
- ```
-
- Follow these guidelines when writing the transaction:
- - Start each transaction with a begin operation.
- - Consider whether you will want to suspend and resume the transaction.
If some operations should not be part of the transaction, you may want to
suspend the transaction while performing non-transactional operations. After
the non-transactional operations are complete, you can resume the transaction.
See [Basic Suspend and Resume Transaction
Example](transaction_coding_examples.html#suspend_resume_example) for an
example.
- - If your transaction operates on a mix of partitioned and replicated
regions, do the first region operation on an entry of the partitioned region.
This sets the host for the entire transaction.
- - If you did not configure copy-on-read to true, be sure all cache
updates avoid in-place changes.
- - Take into account the behavior of transactional and non-transactional
operations. All transactional operations that are run after the begin and
before the commit or rollback are included in the transaction.
- - End each transaction with a commit or a rollback. Do not leave any
transaction in an uncommitted or unrolled back state. Transactions do not time
out, so they will remain for the life of the application.
-
-5. **Review all of your code for compatibility with transactions.**
- When you commit a transaction, while the commit is in process, the changes
are visible in the distributed cache. This provides better performance than
locking everything involved with the transaction updates, but it means that
another process accessing data used in the transaction might get some data in
the pre-transaction state and some in the post-transaction state.
-
- For example, suppose keys 1 and 2 are modified within a transaction, such
that both values change from A to B. In another thread, it is possible to read
key 1 with value B and key 2 with value A, after the commit begins, but before
the commit completes. This is possible due to the nature of
<%=vars.product_name%> reads. This choice sacrifices atomic visibility in favor
of performance; reads do not block writes, and writes do not block reads.
-
-
diff --git
a/geode-docs/developing/transactions/run_a_cache_transaction_with_external_db.html.md.erb
b/geode-docs/developing/transactions/run_a_cache_transaction_with_external_db.html.md.erb
deleted file mode 100644
index cebb430..0000000
---
a/geode-docs/developing/transactions/run_a_cache_transaction_with_external_db.html.md.erb
+++ /dev/null
@@ -1,52 +0,0 @@
-<% set_title("How to Run a", product_name, "Transaction that Coordinates with
an External Database") %>
-
-<!--
-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.
--->
-
-Coordinate a <%=vars.product_name%> transaction with an external database by
using CacheWriter/CacheListener and TransactionWriter/TransactionListener
plug-ins, **to provide an alternative to using JTA transactions**.
-
-There are a few things you should be careful about while working with
<%=vars.product_name%> transactions and external databases:
-
-- When you set up the JDBC connection, make sure that auto-commit is
disabled. For example, in Java:
-
- ``` pre
- Connection getConnection() throws SQLException {
- Connection con = ... // create the connection
- con.setAutoCommit(false);
- return con;
- }
- ```
-
-- The BEGIN statement, database operations and the PREPARE statement must
all happen in the same connection session. In order to accomplish this, you
will need to obtain the same JDBC connection session across multiple
CacheWriter and TransactionWriter/TransactionListener invocations. One way to
do this would be to look up the connection (from a user managed Map) based on
`cacheTransactionManager.getTransactionId()`.
-- Make sure that the prepare transaction feature is enabled in your external
database. It is disabled in PostgreSQL by default. In PostgreSQL, the following
property must be modified to enable it:
-
- ``` pre
- max_prepared_transactions = 1 # 1 or more enables, zero (default) disables
this feature.
- ```
-
-Use the following procedure to write a <%=vars.product_name%> transaction that
coordinates with an external database:
-
-1. Configure <%=vars.product_name%> regions as necessary as described in [How
to Run a <%=vars.product_name%>
Transaction](run_a_cache_transaction.html#task_f15_mr3_5k).
-2. Begin the transaction.
-3. If you have not previously committed a previous transaction in this
connection, start a database transaction by issuing a BEGIN statement.
-4. Perform <%=vars.product_name%> cache operations; each cache operation
invokes the CacheWriter. Implement the CacheWriter to perform the corresponding
external database operations.
-5. Commit the transaction.
- At this point, the TransactionWriter is invoked. The TransactionWriter
returns a TransactionEvent, which contains all the operations in the
transaction. Call PREPARE TRANSACTION within your TransactionWriter code.
-
-6. After a transaction is successfully committed in <%=vars.product_name%>,
the TransactionListener is invoked. The TransactionListener calls COMMIT
PREPARED to commit the database transaction.
-
-
diff --git
a/geode-docs/developing/transactions/transaction_coding_examples.html.md.erb
b/geode-docs/developing/transactions/transaction_coding_examples.html.md.erb
deleted file mode 100644
index 2d1854f..0000000
--- a/geode-docs/developing/transactions/transaction_coding_examples.html.md.erb
+++ /dev/null
@@ -1,204 +0,0 @@
----
-title: Transaction Coding Examples
----
-
-<!--
-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.
--->
-
-This section provides several code examples for writing and executing
transactions.
-
-- **[Basic Transaction Example](#basic_transaction_example)**
-
- This example operates on two replicated regions. It begins a transaction,
updates one entry in each region, and commits the result.
-
-- **[Basic Suspend and Resume Transaction Example](#suspend_resume_example)**
-
- This example suspends and resumes a transaction.
-
-- **[Transaction Embedded within a Function
Example](#transactional_function_example)**
-
- This example demonstrates a function that does transactional updates to
Customer and Order regions.
-
-- **[JCA Resource Adapter Example](#jca_adapter_example)**
-
- This example shows how to use the JCA Resource Adapter in
<%=vars.product_name%> .
-
-
-## <a id="basic_transaction_example" class="no-quick-link"></a>Basic
Transaction Example
-
-This example operates on two replicated regions. It begins a transaction,
updates one entry in each region, and commits the result.
-
-If the commit fails, it will be due to a `CommitConflictException`, which
implies that a concurrent access caused a change to one of the items operated
on within this transaction. This code fragment catches the exception, and it
repeats the transaction attempt until the commit succeeds.
-
-``` pre
-Cache c = new CacheFactory().create();
-
-Region<String, Integer> cash = c.createRegionFactory<String, Integer>()
- .setDataPolicy(DataPolicy.REPLICATE)
- .create("cash");
-
-Region<String, Integer> trades = c.createRegionFactory<String, Integer>()
- .setDataPolicy(DataPolicy.REPLICATE)
- .create("trades");
-
-CacheTransactionManager txmgr = c.getCacheTransactionManager();
-boolean commitConflict = false;
-do {
- try {
- txmgr.begin();
- final String customer = "Customer1";
- final Integer purchase = Integer.valueOf(1000);
- // Decrement cash
- Integer cashBalance = cash.get(customer);
- Integer newBalance =
- Integer.valueOf((cashBalance != null ? cashBalance : 0)
- - purchase);
- cash.put(customer, newBalance);
- // Increment trades
- Integer tradeBalance = trades.get(customer);
- newBalance =
- Integer.valueOf((tradeBalance != null ? tradeBalance : 0)
- + purchase);
-
- trades.put(customer, newBalance);
- txmgr.commit();
- commitConflict = false;
- }
- catch (CommitConflictException conflict) {
- commitConflict = true;
- }
-} while (commitConflict);
-```
-
-## <a id="suspend_resume_example" class="no-quick-link"></a>Basic Suspend and
Resume Transaction Example
-
-This example suspends and resumes a transaction.
-
-``` pre
- CacheTransactionManager txMgr = cache.getCacheTransactionManager();
-
- txMgr.begin();
- region.put("key1", "value");
- TransactionId txId = txMgr.suspend();
- assert region.containsKey("key1") == false;
- // do other operations that should not be
- // part of a transaction
- txMgr.resume(txId);
- region.put("key2", "value");
- txMgr.commit();
-```
-
-
-## <a id="transactional_function_example"
class="no-quick-link"></a>Transaction Embedded within a Function Example
-
-This example demonstrates a function that does transactional updates to
Customer and Order regions.
-
-``` pre
-/**
- * This function does transactional updates to customer and order regions
- */
-public class TransactionalFunction extends FunctionAdapter {
-
- private Random random = new Random();
- /* (non-Javadoc)
- * @see
org.apache.geode.cache.execute.FunctionAdapter#execute(org.apache.geode.cache.execute.FunctionContext)
- */
- @Override
- public void execute(FunctionContext context) {
- RegionFunctionContext rfc = (RegionFunctionContext)context;
- Region<CustomerId, String> custRegion = rfc.getDataSet();
- Region<OrderId, String>
- orderRegion = custRegion.getRegionService().getRegion("order");
-
- CacheTransactionManager
- mgr = CacheFactory.getAnyInstance().getCacheTransactionManager();
- CustomerId custToUpdate = (CustomerId)rfc.getFilter().iterator().next();
- OrderId orderToUpdate = (OrderId)rfc.getArguments();
- System.out.println("Starting a transaction...");
- mgr.begin();
- int randomInt = random.nextInt(1000);
- System.out.println("for customer region updating "+custToUpdate);
- custRegion.put(custToUpdate,
- "updatedCustomer_"+custToUpdate.getCustId()+"_"+randomInt);
- System.out.println("for order region updating "+orderToUpdate);
- orderRegion.put(orderToUpdate,
- "newOrder_"+orderToUpdate.getOrderId()+"_"+randomInt);
- mgr.commit();
- System.out.println("transaction completed");
- context.getResultSender().lastResult(Boolean.TRUE);
- }
-
- /* (non-Javadoc)
- * @see org.apache.geode.cache.execute.FunctionAdapter#getId()
- */
- @Override
- public String getId() {
- return "TxFunction";
- }
-
-}
-```
-
-## <a id="jca_adapter_example" class="no-quick-link"></a>JCA Resource Adapter
Example
-
-<!--
-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.
--->
-
-This example shows how to use the JCA Resource Adapter in
<%=vars.product_name%> .
-
-``` pre
-Hashtable env = new Hashtable();
-env.put(Context.INITIAL_CONTEXT_FACTORY,
“weblogic.jndi.WLInitialContextFactory”);
-env.put(Context.PROVIDER_URL, “t3://localhost:7001”);
-Context ctx = new InitialContext(env);
-UserTransaction utx = (UserTransaction)
ctx.lookup(“javax.transaction.UserTransaction”);
-utx.begin();
- // the XA Resource
-javax.sql.DataSource ds = (DataSource) ctx.lookup(“derby”);
-javax.sql.Connection derbyConn = ds.getConnection();
-Statement stmt = conn.createStatement();
-stmt.executeUpdate(“insert into test values(2,4) “);
- // do ConnectionFactory lookup
-GFConnectionFactory cf = (GFConnectionFactory) ctx.lookup(“gfe/jca”);
-
- // Obtaining the connection begins the LocalTransaction.
- // If this is absent, operations will not be part of any transaction.
-GFConnection conn = cf.getConnection();
-
-testRegion.put(“foo”, “bar-”);
-utx.commit();
-
- // the connection can also be closed within the transaction
-derbyConn.close();
-conn.close();
-```
-
-
diff --git
a/geode-docs/developing/transactions/transaction_event_management.html.md.erb
b/geode-docs/developing/transactions/transaction_event_management.html.md.erb
deleted file mode 100644
index e9d84a9..0000000
---
a/geode-docs/developing/transactions/transaction_event_management.html.md.erb
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: How Transaction Events Are Managed
----
-
-<!--
-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.
--->
-
-Transactional cache operations are handled somewhat differently inside
transactions than out.
-
-# During the Transaction
-
-While the transaction is running, each transactional operation is passed to
the cache writer local to the transactional view, if one is available. As with
cache operations outside of transactions, the cache writer can abort the
operation. Each operation the cache writer allows is applied to the
transactional view in the cache and appended to the CacheEvent list in the
TransactionEvent object.
-
-## Event Conflation
-
-The cache events are conflated, so if a key already has an event in the list,
that event is removed and the current operation is added to the end of the
list. So this series of calls inside a transaction:
-
-``` pre
- Region.create (A, W);
- Region.put (A, valX);
- Region.put (B, valQ);
- Region.invalidate (A);
- Region.put (A, valY);
-```
-
-results in these events stored in the CacheEvent list:
-
-``` pre
- put (B, valQ)
- put (A, valY)
-```
-
-# At commit and after commit
-
-When the transaction is committed, <%=vars.product_name%> passes the
`TransactionEvent` to the transaction writer local to the transactional view,
if one is available. After commit, <%=vars.product_name%> :
- - Passes the `TransactionEvent` to each installed transaction listener.
- - Walks the `CacheEvent` list, calling all locally installed listeners
for each operation listed.
- - Distributes the `TransactionEvent` to all interested caches.
- **Note:**
- For <%=vars.product_name%> and global JTA transactions, the
`EntryEvent` object contains the <%=vars.product_name%> transaction ID. JTA
transaction events do not contain the JTA transaction ID.
-
-
diff --git
a/geode-docs/developing/transactions/transactional_and_nontransactional_ops.html.md.erb
b/geode-docs/developing/transactions/transactional_and_nontransactional_ops.html.md.erb
deleted file mode 100644
index 7cda91f..0000000
---
a/geode-docs/developing/transactions/transactional_and_nontransactional_ops.html.md.erb
+++ /dev/null
@@ -1,117 +0,0 @@
----
-title: Comparing Transactional and Non-Transactional Operations
----
-
-<!--
-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.
--->
-
-
-Between the begin operation and the commit or rollback operation are a series
of ordinary <%=vars.product_name%> operations. When they are launched from
within a transaction, the <%=vars.product_name%> operations can be classified
into two types:
-
-- Transactional operations affect the transactional view
-- Non-transactional operations do not affect the transactional view
-
-An operation that acts directly on the cache does not usually act on the
transactional view.
-
-- **[Transactional Operations](#transactional_operations)**
-
-- **[Non-Transactional Operations](#non_transactional_operations)**
-
-- **[Entry Operations](#entry_operations)**
-
-- **[Region Operations](#region_operations)**
-
-- **[Cache Operations](#cache_operations)**
-
-- **[No-Ops](#no-ops)**
-
-## <a id="transactional_operations" class="no-quick-link"></a>Transactional
Operations
-
-The `CacheTransactionManager` methods are the only ones used specifically for
cache operations. Otherwise, you use the same methods as usual. Most methods
that run within a transaction affect the transactional view, and they do not
change the cache until the transaction commits. Methods that behave this way
are considered transactional operations. Transactional operations are
classified in two ways: whether they modify the transactional view or the cache
itself, and whether they create w [...]
-
-In general, methods that create, destroy, invalidate, update, or read region
entries are transactional operations.
-
-Transactional operations that can cause write conflicts are those that modify
an entry, such as put, a load done to satisfy a get operation, create, delete,
local delete, invalidate and local invalidate.
-
-Transactional read operations do not cause conflicts directly, but they can
modify the transactional view. Read operations look for the entry in the
transaction view first and then, if necessary, go to the cache. If the entry is
returned by a cache read, it is stored as part of the transactional view. At
commit time, the transaction uses the initial snapshot of the entry in the view
to discover write conflicts.
-
-## <a id="non_transactional_operations"
class="no-quick-link"></a>Non-Transactional Operations
-
-A few methods, when invoked within a transaction, have no effect on the
transactional view, but they have an immediate effect on the cache. They are
considered non-transactional operations. Often, non-transactional operations
are administrative, such as `Region.destroy` and `Region.invalidate`. These
operations are not supported within a transaction. If you call them, the system
throws an exception of type `UnsupportedOperationInTransactionException`.
-
-## <a id="entry_operations" class="no-quick-link"></a>Entry Operations
-
-**Note:**
-Transactional entry operations can be rolled back.
-
-| Operations | Methods
| Transactional
| Write Conflict |
-|--------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|----------------|
-| create | `Region.create, put, putAll, Map.put,
putAll`
| yes
| yes |
-| modify | `Region.put, putAll, Map.put, putAll,
Region.Entry.setValue, Map.Entry.setValue`
| yes
| yes |
-| load | `Region.get, Map.get`
| yes
| yes |
-| creation or update using `netSearch` | `Region.get, Map.get`
| yes
| no |
-| destroy: local and distributed | `Region.localDestroy, destroy,
remove, Map.remove`
| yes
| yes |
-| invalidate: local and distributed | `Region.localInvalidate, invalidate`
| yes
| yes |
-| set user attribute | `Region.Entry.setUserAttribute`
| yes
| yes |
-| read of a single entry | `Region.get, getEntry, containsKey,
containsValue, containsValueForKey`
| yes
| no |
-| read of a collection of entries | `Region.keySet, entrySet, values`
| Becomes transactional when you access the keys or values within the
collection. | no |
-
-Some transactional write operations also do a read before they write, and
these can complete a transactional read even when the write fails. The
following table of entry operations notes the conditions under which this can
happen.
-
-**Note:**
-These operations can add a snapshot of an entry to the transaction’s view even
when the write operation does not succeed.
-
-| Operations | Methods |
Reads Without Writing |
-|-----------------------------------|--------------------------------------|---------------------------------------------------------------------------|
-| create | `Region.create` |
when it throws an `EntryExistsException` |
-| destroy: local and distributed | `Region.localDestroy, destroy` |
when it throws an `EntryNotFoundException` |
-| invalidate: local and distributed | `Region.localInvalidate, invalidate` |
when it throws an `EntryNotFoundException`or the entry is already invalid |
-
-## <a id="region_operations" class="no-quick-link"></a>Region Operations
-
-When you create a region in a transaction, any data from the getInitialImage
operation goes directly into the cache, rather than waiting for the transaction
to commit.
-
-| Operations | Methods
| Affected | Write Conflict |
-|-----------------------------------|--------------------------------------------------|-----------------------|----------------|
-| destroy: local and distributed | `Region.localDestroyRegion,
destroyRegion` | cache | yes |
-| invalidate: local and distributed | `Region.localInvalidateRegion,
invalidateRegion` | cache | yes |
-| clear: local and distributed | `Region.localClear, clear, Map.clear`
| cache and transaction | no |
-| close | `Region.close`
| cache | yes |
-| mutate attribute | `Region.getAttributesMutator` methods
| cache | no |
-| set user attribute | `Region.setUserAttribute`
| cache | no |
-
-## <a id="cache_operations" class="no-quick-link"></a>Cache Operations
-
-When you create a region in a transaction, any data from the getInitialImage
operation goes directly into the cache, rather than waiting for the transaction
to commit.
-
-| Operations | Methods | Affected State | Write
Conflict |
-|------------|----------------------------------|----------------|----------------|
-| create | `createRegionFactory().create()` | committed | no
|
-| close | `close` | committed | yes
|
-
-## <a id="no-ops" class="no-quick-link"></a>No-Ops
-
-Any operation that has no effect in a non-transactional context remains a
no-op in a transactional context. For example, if you do two `localInvalidate`
operations in a row on the same region, the second `localInvalidate` is a
no-op. No-op operations do not:
-
-- Cause a listener invocation
-- Cause a distribution message to be sent to other members
-- Cause a change to an entry
-- Cause any conflict
-
-A no-op can do a transactional read.
-
-
diff --git a/geode-docs/developing/transactions/transactions_intro.html.md.erb
b/geode-docs/developing/transactions/transactions_intro.html.md.erb
new file mode 100644
index 0000000..21b01a5
--- /dev/null
+++ b/geode-docs/developing/transactions/transactions_intro.html.md.erb
@@ -0,0 +1,75 @@
+---
+title: Adherence to ACID Promises
+---
+
+<!--
+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.
+-->
+
+<a id="ACID"></a>
+
+This section introduces <%=vars.product_name%> transactions.
+<%=vars.product_name%> offers an API for client applications
+that do transactional work.
+<%=vars.product_name%> implements optimistic transactions,
+choosing the much higher transaction performance they offer over the slow,
+locking methods of a traditional relational database.
+
+Optimistic transaction semantics are not
+identical to the Atomicity-Consistency-Isolation-Durability (ACID) semantics
+of a traditional relational database.
+
+### <a id="transaction_semantics__section_8362ACD06C784B5BBB0B7E986F760169"
class="no-quick-link"></a>Atomicity
+
+Atomicity is “all or nothing” behavior: a transaction completes successfully
only when all of the operations it contains complete successfully. If problems
occur during a transaction, perhaps due to other transactions with overlapping
changes, the transaction cannot successfully complete until the problems are
resolved.
+
+Optimistic transactions provide atomicity and realize speed by using a
reservation system, instead of using the traditional relational database
technique of a two-phase locking of rows. The reservation prevents other,
intersecting transactions from completing, allowing the commit to check for
conflicts and to reserve resources in an all-or-nothing fashion prior to making
changes to the data. After all changes have been made, locally and remotely,
the reservation is released. With the res [...]
+
+### <a id="transaction_semantics__section_7C287DA4A5134780B3199CE074E3F890"
class="no-quick-link"></a>Consistency
+
+Consistency requires that data written within a transaction must observe the
key and value constraints established for the affected region. Note that
validity of the transaction is the responsibility of the application.
+
+### <a id="transaction_semantics__section_126A24EC499D4CF39AE766A0B526A9A5"
class="no-quick-link"></a>Isolation
+
+Isolation is the level at which transactional state is
+visible to system components.
+<%=vars.product_name%> transactions have repeatable read isolation.
+Once the committed value is read for a given key,
+it always returns that same value.
+If a write within a transaction
+deletes a value for a key that has already been read,
+subsequent reads return the transactional reference.
+
+The default configuration isolates transactions at the process thread level.
+While a transaction is in progress,
+its changes are visible only inside the thread that is running the transaction.
+Other threads within that same process and threads in other processes
+cannot see changes until after the commit operation begins.
+After beginning the commit, the changes are visible in the cache,
+but other threads that access the changing data might see partial results
+of the transaction, leading to a dirty read.
+See [Changing the Handling of Dirty
Reads](design_considerations.html#transactions-dirty-reads) for how to change
the default behavior.
+
+### <a id="transaction_semantics__section_F092E368724945BCBF8E5DCB36B97EB4"
class="no-quick-link"></a>Durability
+
+Relational databases provide durability by using disk storage for
+recovery and transaction logging.
+<%=vars.product_name%> is optimized for performance
+and does not support on-disk durability for transactions.
+
+See [Allowing Transactions to Work on Persistent
Regions](design_considerations.html#transactions-persistence)
+for how to allow a transaction that operates on a persistent region
+in a non-durable way.
diff --git
a/geode-docs/developing/transactions/working_with_transactions.html.md.erb
b/geode-docs/developing/transactions/working_with_transactions.html.md.erb
deleted file mode 100644
index 781d2f0..0000000
--- a/geode-docs/developing/transactions/working_with_transactions.html.md.erb
+++ /dev/null
@@ -1,237 +0,0 @@
-<% set_title("Working with", product_name, "Transactions") %>
-
-<!--
-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.
--->
-<a id="topic_tx2_gs4_5k"></a>
-
-
-This section contains guidelines and additional information on working with
<%=vars.product_name%> transactions.
-
-- **[Setting Global Copy on Read](#concept_vx2_gs4_5k)**
-
-- **[Making a Safe Change Within a Transaction Using
CopyHelper.copy](#concept_fdr_wht_vk)**
-
-- **[Transactions and Functions](#concept_ihn_zmt_vk)**
-
-- **[Using Queries and Indexes with Transactions](#concept_ty1_vnt_vk)**
-
-- **[Collections and Region.Entry Instances in
Transactions](#concept_ksh_twz_vk)**
-
-- **[Using Eviction and Expiration Operations](#concept_vyt_txz_vk)**
-
-- **[Transactions and Consistent Regions](#transactions_and_consistency)**
-
-- **[Suspending and Resuming Transactions](#concept_u5b_ryz_vk)**
-
-- **[Using Cache Writer and Cache Listener Plug-Ins](#concept_ysx_nf1_wk)**
-
-- **[Configuring Transaction Plug-In Event Handlers](#concept_ocw_vf1_wk)**
-
-- **[How Transaction Events Are Managed](transaction_event_management.html)**
-
-## <a id="concept_vx2_gs4_5k" class="no-quick-link"></a>Setting Global Copy on
Read
-
-As many entry operations return a reference to the cache entry, copy-on-read
avoids problems within a transaction setting. To enable global copy-on-read for
all reads, modify the `cache.xml` file or use the corresponding Java API call.
-
-Using cache.xml:
-
-``` pre
-<cache lock-lease="120" lock-timeout="60" search-timeout="300"
copy-on-read="true">
-```
-
-API:
-
-``` pre
-Cache c = CacheFactory.getInstance(system);
- c.setCopyOnRead(true);
-```
-
-The copy-on-read attribute and the operations affected by the attribute
setting are discussed in detail in [Managing Data
Entries](../../basic_config/data_entries_custom_classes/managing_data_entries.html).
-
-## <a id="concept_fdr_wht_vk" class="no-quick-link"></a>Making a Safe Change
Within a Transaction Using CopyHelper.copy
-
-If `copy-on-read` is *not* globally set, and the cache uses replicated
regions, explicitly make copies of the cache objects that are to be modified
within a transaction. The `CopyHelper.copy` method makes copies:
-
-``` pre
-CacheTransactionManager cTxMgr = cache.getCacheTransactionManager();
-cTxMgr.begin();
-Object o = (StringBuffer) r.get("stringBuf");
-StringBuffer s = (StringBuffer) CopyHelper.copy(o);
-s.append("Changes unseen before commit. Read Committed.");
-r.put("stringBuf", s);
-cTxMgr.commit();
-```
-
-## <a id="concept_ihn_zmt_vk" class="no-quick-link"></a>Transactions and
Functions
-
-A function may contain transactions, and a transaction may contain functions,
as long as you observe these restrictions:
-
- - **Your combination of functions and transactions must not result in nested
transactions.**
-
- - **When a transaction contains a function,** the function must operate only
on keys that are colocated with the keys in the transaction,
-as described in [Data Location for
Transactions](data_location_cache_transactions.html). This implies:
-
- - A function within a transaction must not specify execution on a
particular server or member.
-<%=vars.product_name%> throws `UnsupportedOperationException` if
`FunctionService` calls `onMember()`, `onServer()`,
-or similar methods from within a transaction.
-
- - A function within a transaction can request a particular
region—that is, the `FunctionService.onRegion()` method is permitted.
-
-
-See [Function Execution](../function_exec/chapter_overview.html) for more
about functions.
-
-See [Transaction Embedded within a Function
Example](transaction_coding_examples.html#transactional_function_example) for
an example.
-
-## <a id="concept_ty1_vnt_vk" class="no-quick-link"></a>Using Queries and
Indexes with Transactions
-
-Queries and indexes reflect the cache contents and ignore the changes made by
ongoing transactions. If you do a query from inside a transaction, the query
does not reflect the changes made inside that transaction.
-
-## <a id="concept_ksh_twz_vk" class="no-quick-link"></a>Collections and
Region.Entry Instances in Transactions
-
-Collections and region entries used in a transaction must be created inside
the transaction. After the transaction has completed, the application can no
longer use any region entry or collection or associated iterator created within
the transaction. An attempted use outside of the transaction will throw an
`IllegalStateException` exception.
-
-Region collection operations include `Region.keySet`, `Region.entrySet`, and
`Region.values`. You can create instances of `Region.Entry` through the
`Region.getEntry` operation or by looking at the contents of the result
returned by a `Region.entrySet` operation.
-
-## <a id="concept_vyt_txz_vk" class="no-quick-link"></a>Using Eviction and
Expiration Operations
-
-Entry expiration and LRU eviction affect the committed state. They are not
part of a transaction, and therefore they cannot be rolled back.
-
-### About Eviction
-
-LRU eviction operations do not cause write conflicts with existing
transactions, despite destroying or invalidating entries. LRU eviction is
deferred on entries modified by the transaction until the commit completes.
Because anything touched by the transaction has had its LRU clock reset,
eviction of those entries is not likely to happen immediately after the commit.
-
-When a transaction commits its changes in a region with distributed scope, the
operation can invoke eviction controllers in the remote caches, as well as in
the local cache.
-
-### Configure Expiration
-
-Local expiration actions do not cause write conflicts, but distributed
expiration can cause conflicts and prevent transactions from committing in the
members receiving the distributed operation.
-
-- When you are using transactions on local, preloaded or empty regions, make
expiration local if possible. For every instance of that region, configure an
expiration action of local invalidate or local destroy. In a cache.xml
declaration, use a line similar to this:
-
- ``` pre
- <expiration-attributes timeout="60" action="local-invalidate" />
- ```
-
- In regions modified by a transaction, local expiration is suspended.
Expiration operations are batched and deferred per region until the transaction
completes. Once cleanup starts, the manager processes pending expirations.
Transactions that need to change the region wait until the expirations are
complete.
-
-- With partitioned and replicated regions, you cannot use local expiration.
When you are using distributed expiration, the expiration is not suspended
during a transaction, and expiration operations distributed from another member
can cause write conflicts. In replicated regions, you can avoid conflicts by
setting up your distributed system this way:
- - Choose an instance of the region to drive region-wide expiration. Use
a replicated region, if there is one.
- - Configure distributed expiration only in that region instance. The
expiration action must be either invalidate or destroy. In a `cache.xml` file
declaration, use a line similar to this:
-
- ``` pre
- <expiration-attributes timeout="300" action="destroy" />
- ```
-
- - Run the transactions from the member in which expiration is configured.
-
-## <a id="transactions_and_consistency" class="no-quick-link"></a>Transactions
and Consistent Regions
-
-A transaction that modifies a region in which consistency checking is enabled
generates all necessary version information for region updates when the
transaction commits.
-
-If a transaction modifies a normal, preloaded or empty region, the transaction
is first delegated to a <%=vars.product_name%> member that holds a replicate
for the region. This behavior is similar to the transactional behavior for
partitioned regions, where the partitioned region transaction is forwarded to a
member that hosts the primary for the partitioned region update.
-
-The limitation for transactions with a normal, preloaded or empty region is
that, when consistency checking is enabled, a transaction cannot perform a
`localDestroy` or `localInvalidate` operation against the region.
<%=vars.product_name%> throws an `UnsupportedOperationInTransactionException`
exception in such cases. An application should use a `Destroy` or `Invalidate`
operation in place of a `localDestroy` or `localInvalidate` when consistency
checks are enabled.
-
-## <a id="concept_u5b_ryz_vk" class="no-quick-link"></a>Suspending and
Resuming Transactions
-
-The <%=vars.product_name%> `CacheTransactionManager` API provides the ability
to suspend and resume transactions with the `suspend` and `resume` methods. The
ability to suspend and resume is useful when a thread must perform some
operations that should not be part of the transaction before the transaction
can complete. A complex use case of suspend and resume implements a transaction
that spans clients in which only one client at a time will not be suspended.
-
-Once a transaction is suspended, it loses the transactional view of the cache.
None of the operations done within the transaction are visible to the thread.
Any operations that are performed by the thread while the transaction is
suspended are not part of the transaction.
-
-When a transaction is resumed, the resuming thread assumes the transactional
view. A transaction that is suspended on a member must be resumed on the same
member.
-
-Before resuming a transaction, you may want to check if the transaction exists
on the member and whether it is suspended. The `tryResume` method implements
this check and resume as an atomic step.
-
-If the member with the primary copy of the data crashes, the transactional
view associated with that data is lost. The secondary member for the data will
not be able to resume any transactions suspended on the crashed member. You
will need to take remedial steps to retry the transaction on a new primary copy
of the data.
-
-If a suspended transaction is not touched for a period of time,
<%=vars.product_name%> cleans it up automatically. By default, the timeout for
a suspended transaction is 30 minutes and can be configured using the system
property `gemfire.suspendedtxTimeout`. For example,
`gemfire.suspendedtxTimeout=60` specifies a timeout of 60 minutes.
-
-See [Basic Suspend and Resume Transaction
Example](transaction_coding_examples.html#suspend_resume_example) for a sample
code fragment that suspends and resumes a transaction.
-
-## <a id="concept_ysx_nf1_wk" class="no-quick-link"></a>Using Cache Writer and
Cache Listener Plug-Ins
-
-All standard <%=vars.product_name%> application plug-ins work with
transactions. In addition, the transaction interface offers specialized
plug-ins that support transactional operation.
-
-No direct interaction exists between client transactions and client
application plug-ins. When a client runs a transaction, <%=vars.product_name%>
calls the plug-ins that are installed on the transaction's server delegate and
its server host. Client application plug-ins are not called for operations
inside the transaction or for the transaction as a whole. When the transaction
is committed, the changes to the server cache are sent to the client cache
according to client interest registra [...]
-
-The `EntryEvent` that a callback receives has a unique <%=vars.product_name%>
transaction ID, so the cache listener can associate each event, as it occurs,
with a particular transaction. The transaction ID of an `EntryEvent` that is
not part of a transaction is null to distinguish it from a transaction ID.
-
-- `CacheLoader`. When a cache loader is called by a transaction operation,
values loaded by the cache loader may cause a write conflict when the
transaction commits.
-- `CacheWriter`. During a transaction, if a cache writer exists, its methods
are invoked as usual for all operations, as the operations are called in the
transactions. The `netWrite` operation is not used. The only cache writer used
is the one in the member where the transactional data resides.
-- `CacheListener`. The cache listener callbacks - local and remote - are
triggered after the transaction commits. The system sends the conflated
transaction events, in the order they were stored.
-
-For more information on writing cache event handlers, see [Implementing Cache
Event Handlers](../events/implementing_cache_event_handlers.html).
-
-## <a id="concept_ocw_vf1_wk" class="no-quick-link"></a>Configuring
Transaction Plug-In Event Handlers
-
-<%=vars.product_name%> has two types of transaction plug-ins: Transaction
Writers and Transaction Listeners. You can optionally install one transaction
writer and one or more transaction listeners per cache.
-
-Like JTA global transactions, you can use transaction plug-in event handlers
to coordinate <%=vars.product_name%> transaction activity with an external data
store. However, you typically use JTA global transactions when
<%=vars.product_name%> is running as a peer data store with your external data
stores. Transaction writers and listeners are typically used when
<%=vars.product_name%> is acting as a front end cache to your backend database.
-
-**Note:**
-You can also use transaction plug-in event handlers when running JTA global
transactions.
-
-### TransactionWriter
-
-When you commit a transaction, if a transaction writer is installed in the
cache where the data updates were performed, it is called. The writer can do
whatever work you need, including aborting the transaction.
-
-The transaction writer is the last place that an application can rollback a
transaction. If the transaction writer throws any exception, the transaction is
rolled back. For example, you might use a transaction writer to update a
backend data source before the <%=vars.product_name%> transaction completes the
commit. If the backend data source update fails, the transaction writer
implementation can throw a
[TransactionWriterException](/releases/latest/javadoc/org/apache/geode/cache/Transac
[...]
-
-A typical usage scenario would be to use the transaction writer to prepare the
commit on the external database. Then in a transaction listener, you can apply
the commit on the database.
-
-### Transaction Listeners
-
-When the transaction ends, its thread calls the transaction listener to
perform the appropriate follow-up for successful commits, failed commits, or
voluntary rollbacks. The transaction that caused the listener to be called no
longer exists by the time the listener code executes.
-
-Transaction listeners have access to the transactional view and thus are not
affected by non-transactional update operations. `TransactionListener` methods
cannot make transactional changes or cause a rollback. They can, however, start
a new transaction. Multiple transactions on the same cache can cause concurrent
invocation of `TransactionListener` methods, so implement methods that do the
appropriate synchronization of the multiple threads for thread-safe operation.
-
-A transaction listener can preserve the result of a transaction, perhaps to
compare with other transactions, or for reference in case of a failed commit.
When a commit fails and the transaction ends, the application cannot just retry
the transaction, but must build up the data again. For most applications, the
most efficient action is just to start a new transaction and go back through
the application logic again.
-
-The rollback and failed commit operations are local to the member where the
transactional operations are run. When a successful commit writes to a
distributed or partitioned region, however, the transaction results are
distributed to other members the same as other updates. The transaction
listener on the receiving members reflect the changes the transaction makes in
that member, not the originating member. Any exceptions thrown by the
transaction listener are caught by <%=vars.product_n [...]
-
-To configure a transaction listener, add a `cache-transaction-manager`
configuration to the cache definition and define one or more instances of
`transaction-listener` there. The only parameter to this `transaction-listener`
is `URL`, which must be a string, as shown in the following cache.xml example.
-
-**Note:**
-The `cache-transaction-manager` allows listeners to be established. This
attribute does not install a different transaction manager.
-
-Using cache.xml:
-
-``` pre
-<cache search-timeout="60">
- <cache-transaction-manager>
- <transaction-listener>
- <class-name>com.company.data.MyTransactionListener</class-name>
- <parameter name="URL">
- <string>jdbc:cloudscape:rmi:MyData</string>
- </parameter>
- </transaction-listener>
- <transaction-listener>
- . . .
- </transaction-listener>
- </cache-transaction-manager>
- . . .
- </cache>
-```
-
-Using the Java API:
-
-``` pre
-CacheTransactionManager manager = cache.getCacheTransactionManager();
-manager.addListener(new LoggingTransactionListener());
-```
-
-
diff --git
a/geode-docs/managing/troubleshooting/diagnosing_system_probs.html.md.erb
b/geode-docs/managing/troubleshooting/diagnosing_system_probs.html.md.erb
index 0dd56a2..35799fd 100644
--- a/geode-docs/managing/troubleshooting/diagnosing_system_probs.html.md.erb
+++ b/geode-docs/managing/troubleshooting/diagnosing_system_probs.html.md.erb
@@ -229,7 +229,7 @@ Response: Bring the missing member online, if possible.
This restores the bucket
Check these possible causes.
-- Transactions—Entries that are old enough for eviction may remain in the
cache if they are involved in a transaction. Further, transactions never time
out, so if a transaction hangs, the entries involved in the transaction will
remain stuck in the cache. If you have a process with a hung transaction, you
may need to end the process to remove the transaction. In your application
programming, do not leave transactions open ended. Program all transactions to
end with a commit or a rollba [...]
+- Transactions—Entries that are due to be expired may remain in the cache if
they are involved in a transaction. Further, transactions never time out, so if
a transaction hangs, the entries involved in the transaction will remain stuck
in the cache. If you have a process with a hung transaction, you may need to
end the process to remove the transaction. In your application programming, do
not leave transactions open ended. Program all transactions to end with a
commit or a rollback.
- Partitioned regions—For performance reasons, eviction and expiration
behave differently in partitioned regions and can cause entries to be removed
before you expect. See
[Eviction](../../developing/eviction/chapter_overview.html) and
[Expiration](../../developing/expiration/chapter_overview.html).
## <a id="diagnosing_system_probs__section_346C62F16B19491E83B59B0A51D9E2B6"
class="no-quick-link"></a>Cannot find the log file
diff --git a/geode-docs/developing/transactions/JTA_transactions.html.md.erb
b/geode-docs/reference/archive_transactions/JTA_transactions.html.md.erb
similarity index 93%
rename from geode-docs/developing/transactions/JTA_transactions.html.md.erb
rename to geode-docs/reference/archive_transactions/JTA_transactions.html.md.erb
index 412fd48..b56b468 100644
--- a/geode-docs/developing/transactions/JTA_transactions.html.md.erb
+++ b/geode-docs/reference/archive_transactions/JTA_transactions.html.md.erb
@@ -43,8 +43,7 @@ When using JTA global transactions with
<%=vars.product_name%>, you have two opt
An application creates a global transaction by using
`javax.transaction.UserTransaction` bound to
the JNDI context `java:/UserTransaction` to start and terminate transactions.
During the
-transaction, cache operations are done through <%=vars.product_name%> as usual
as described in
-[<%=vars.product_name%> Transactions](cache_transactions.html).
+transaction, cache operations are done through <%=vars.product_name%> as usual.
**Note:**
See the Java documentation for more information on topics such as JTA,
`javax.transaction`, committing and rolling back global transactions, and the
related exceptions.
@@ -97,7 +96,7 @@ Use the following procedure to run a <%=vars.product_name%>
global JTA transacti
1. **Configure the external data sources in the external container.** Do not
configure the data sources in cache.xml . They are not guaranteed to get bound
to the JNDI tree.
2.
- Configure <%=vars.product_name%> for any necessary transactional behavior
in the `cache.xml` file. For example, enable `copy-on-read` and specify a
transaction listener, as needed. See [Setting Global Copy on
Read](working_with_transactions.html#concept_vx2_gs4_5k) and [Configuring
Transaction Plug-In Event
Handlers](working_with_transactions.html#concept_ocw_vf1_wk) for details.
+ Configure <%=vars.product_name%> for any necessary transactional behavior
in the `cache.xml` file. For example, enable `copy-on-read` and specify a
transaction listener, as needed. See [Safe Entry
Modification](../../basic_config/data_entries_custom_classes/managing_data_entries.html#managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809).
3.
Make sure that JTA transactions are enabled for the regions that will
participate in the transaction. See [Turning Off JTA
Transactions](turning_off_jta.html#concept_nw2_5gs_xk) for details.
@@ -177,8 +176,7 @@ path and file names:
</ol>
3. Make sure that the `geode-dependencies.jar` is accessible in the CLASSPATH
of the JTA transaction coordinator container.
4. Deploy the version-specific `geode-jca` RAR file on the JTA transaction
coordinator container. When deploying the file, you specify the JNDI name and
so on.
-5. Configure <%=vars.product_name%> for any necessary transactional behavior.
Enable `copy-on-read` and specify a transaction listener, if you need one.
-See [Setting Global Copy on
Read](working_with_transactions.html#concept_vx2_gs4_5k) and [Configuring
Transaction Plug-In Event
Handlers](working_with_transactions.html#concept_ocw_vf1_wk) for details.
+5. Configure <%=vars.product_name%> for any necessary transactional behavior.
Enable `copy-on-read` and specify a transaction listener, if you need one. See
[Safe Entry
Modification](../../basic_config/data_entries_custom_classes/managing_data_entries.html#managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809).
6. Get an initial context through
`org.apache.geode.cache.GemFireCache.getJNDIContext`. For example:
``` pre
@@ -204,5 +202,3 @@ See [Setting Global Copy on
Read](working_with_transactions.html#concept_vx2_gs4
//transaction
GFConnection gemfireConn = (GFConnection)cf.getConnection();
```
-
-See [JCA Resource Adapter
Example](transaction_coding_examples.html#jca_adapter_example) for an example
of how to set up a transaction using the JCA Resource Adapter.
diff --git
a/geode-docs/developing/transactions/cache_plugins_with_jta.html.md.erb
b/geode-docs/reference/archive_transactions/cache_plugins_with_jta.html.md.erb
similarity index 93%
rename from
geode-docs/developing/transactions/cache_plugins_with_jta.html.md.erb
rename to
geode-docs/reference/archive_transactions/cache_plugins_with_jta.html.md.erb
index e95dc99..973199a 100644
--- a/geode-docs/developing/transactions/cache_plugins_with_jta.html.md.erb
+++
b/geode-docs/reference/archive_transactions/cache_plugins_with_jta.html.md.erb
@@ -25,7 +25,7 @@ data source is transactional, which means that it can detect
the transaction man
writer and cache loader participate in the transaction. If the JTA rolls back
its transaction, the
changes made by the cache loader and the cache writer are rolled back. For
more on transactional
data sources, see the discussion of XAPooledDataSource and ManagedDataSource
in
-[Configuring Database Connections Using
JNDI](../outside_data_sources/configuring_db_connections_using_JNDI.html).
+[Configuring Database Connections Using
JNDI](../../developing/outside_data_sources/configuring_db_connections_using_JNDI.html).
If you are using a <%=vars.product_name%> cache or transaction listener with
global transactions, be aware that the EntryEvent returned by a transaction has
the <%=vars.product_name%> transaction ID, not the JTA transaction ID.
diff --git
a/geode-docs/reference/archive_transactions/chapter_overview.html.md.erb
b/geode-docs/reference/archive_transactions/chapter_overview.html.md.erb
new file mode 100644
index 0000000..690be51
--- /dev/null
+++ b/geode-docs/reference/archive_transactions/chapter_overview.html.md.erb
@@ -0,0 +1,29 @@
+---
+title: Transaction Reference Material
+---
+
+<!--
+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.
+-->
+
+This archival section on transactions exists as a reference
+for understanding how to work with JTA transactions.
+
+
+- **[JTA Global Transactions with
<%=vars.product_name%>](JTA_transactions.html)**
+
+ Use JTA global transactions to coordinate <%=vars.product_name%>
transactions and JDBC transactions.
+
diff --git a/geode-docs/developing/transactions/turning_off_jta.html.md.erb
b/geode-docs/reference/archive_transactions/turning_off_jta.html.md.erb
similarity index 100%
rename from geode-docs/developing/transactions/turning_off_jta.html.md.erb
rename to geode-docs/reference/archive_transactions/turning_off_jta.html.md.erb
