This is an automated email from the ASF dual-hosted git repository.
dbarnes 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 dca0240 GEODE-5298: User Guide - Document Transactions + Functions
Limitation
dca0240 is described below
commit dca0240e60ab0e0b81f77dc18a0074e6dbb07bb5
Author: Dave Barnes <[email protected]>
AuthorDate: Wed Jun 6 16:20:01 2018 -0700
GEODE-5298: User Guide - Document Transactions + Functions Limitation
---
.../working_with_transactions.html.md.erb | 40 ++++++++++++++--------
1 file changed, 25 insertions(+), 15 deletions(-)
diff --git
a/geode-docs/developing/transactions/working_with_transactions.html.md.erb
b/geode-docs/developing/transactions/working_with_transactions.html.md.erb
index d75f6ad..5e89c1a 100644
--- a/geode-docs/developing/transactions/working_with_transactions.html.md.erb
+++ b/geode-docs/developing/transactions/working_with_transactions.html.md.erb
@@ -62,7 +62,7 @@ Cache c = CacheFactory.getInstance(system);
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).
-## Making a Safe Change Within a Transaction Using CopyHelper.copy
+## <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:
@@ -76,37 +76,47 @@ r.put("stringBuf", s);
cTxMgr.commit();
```
-## Transactions and Functions
+## <a id="concept_ihn_zmt_vk" class="no-quick-link"></a>Transactions and
Functions
-You can run a function from inside a transaction and you can nest a
transaction within a function, as long as your combination of functions and
transactions does not result in nested transactions. See [Function
Execution](../function_exec/chapter_overview.html) for more about functions.
+A function may contain transactions, and a transaction may contain functions,
as long as you observe these restrictions:
-A single transaction may contain multiple functions.
+ - **Your combination of functions and transactions must not result in nested
transactions.**
-If you are suspending and resuming a transaction with multiple function calls,
all functions in the transaction must execute on the same member.
+ - **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 Cache
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](transactional_function_example.html#concept_22331B3DBFAB4C0BA95EF103BFB71257)
for an example.
-## Using Queries and Indexes with Transactions
+## <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.
-## Collections and Region.Entry Instances in Transactions
+## <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.
-## Using Eviction and Expiration Operations
+## <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
+### 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
+### 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.
@@ -128,7 +138,7 @@ Local expiration actions do not cause write conflicts, but
distributed expiratio
- Run the transactions from the member in which expiration is configured.
-## Transactions and Consistent Regions
+## <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.
@@ -136,7 +146,7 @@ If a transaction modifies a normal, preloaded or empty
region, the transaction i
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.
-## Suspending and Resuming Transactions
+## <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.
@@ -152,7 +162,7 @@ If a suspended transaction is not touched for a period of
time, <%=vars.product_
See [Basic Suspend and Resume Transaction
Example](transaction_suspend_resume_example.html) for a sample code fragment
that suspends and resumes a transaction.
-## Using Cache Writer and Cache Listener Plug-Ins
+## <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.
@@ -175,7 +185,7 @@ Like JTA global transactions, you can use transaction
plug-in event handlers to
**Note:**
You can also use transaction plug-in event handlers when running JTA global
transactions.
-## TransactionWriter
+### 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.
@@ -183,7 +193,7 @@ The transaction writer is the last place that an
application can rollback a tran
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
+### 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.
--
To stop receiving notification emails like this one, please contact
[email protected].
