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-native.git
The following commit(s) were added to refs/heads/develop by this push:
new 8778172 GEODE-4728: User Guide - Add top-level topics: Data
serialization and Transactions
8778172 is described below
commit 8778172e5306a2ffe40611cd2c2a01e4f13175ac
Author: Dave Barnes <dbar...@pivotal.io>
AuthorDate: Fri May 18 09:47:33 2018 -0700
GEODE-4728: User Guide - Add top-level topics: Data serialization and
Transactions
---
.../data-serialization.html.md.erb | 14 +++-
.../transactions/how-client-xacts-work.html.md.erb | 56 ++++++++++++++
.../transactions/running-client-xact.html.md.erb | 90 ++++++++++++++++++++++
.../transactions/suspend-resume-xacts.html.md.erb | 34 ++++++++
.../transactions/transactions.html.md.erb | 46 +++++++++++
5 files changed, 239 insertions(+), 1 deletion(-)
diff --git a/docs/geode-native-docs/data-serialization.html.md.erb
b/docs/geode-native-docs/data-serialization.html.md.erb
index 9a41cf0..10c4823 100644
--- a/docs/geode-native-docs/data-serialization.html.md.erb
+++ b/docs/geode-native-docs/data-serialization.html.md.erb
@@ -19,5 +19,17 @@ See the License for the specific language governing
permissions and
limitations under the License.
-->
-This page is a placeholder - it needs further expansion.
+All data moving out of the client cache must be serializable.
+
+Region data that must be serializable falls under the following categories:
+
+- Partitioned regions (except functions that add data locally to a
partitioned region use the deserialized form).
+- Distributed regions.
+- Regions that are persisted or overflowed to disk.
+- Server or client regions in a client/server installation.
+- Regions distributed between gateways in a multi-site installation.
+- Regions that receive events from remote caches.
+- Regions that provide function arguments and results.
+
+To minimize the cost of serialization and deserialization,
<%=vars.product_name%> avoids changing the data format whenever possible. This
means your data may be stored in the cache in serialized or deserialized form,
depending on how you use it. For example, if a server acts only as a storage
location for data distribution between clients, it makes sense to leave the
data in serialized form, ready to be transmitted to clients that request it.
Partitioned region data is always stored in s [...]
diff --git
a/docs/geode-native-docs/transactions/how-client-xacts-work.html.md.erb
b/docs/geode-native-docs/transactions/how-client-xacts-work.html.md.erb
new file mode 100644
index 0000000..7a2737e
--- /dev/null
+++ b/docs/geode-native-docs/transactions/how-client-xacts-work.html.md.erb
@@ -0,0 +1,56 @@
+---
+title: How Client 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.
+-->
+
+The syntax for writing client transactions is the same as with server or peer
transactions, but when a client performs a transaction, the transaction is
delegated to a server that brokers the transaction.
+
+## <a
id="how-native-client-xacts-work__section_C804F1FE5BDF49CEA037AA589BBF284E"
class="no-quick-link"></a>Role of Server Delegates in Transactions
+
+The client can run transactions on the Java cache server, using a server
delegate to actually run the transaction code.
+
+For information on transaction requirements and activities on the
+server side, see the server documentation at
+[Transactions](geodeman/developing/transactions/chapter_overview.html).
+
+**Note:**
+The client cache blocks until the transaction is successfully committed.
+However, the block is removed if the transaction is suspended.
+
+Depending on where the data resides, the server transaction delegate may or
not be the same member that hosts the transaction. This is the same as for
transactions run by the servers, but for server-run transactions, there is no
delegate. There is just the member that is directly running its own transaction
code.
+
+In this figure, the application code on the client makes changes to data
entries Y and Z within a transaction. The server delegate that performs the
transaction, M1, does not host the primary copy of the data being modified. The
transaction takes place on server M2, where the data resides.
+
+<a id="how-native-client-xacts-work__fig_7E408D84E18C452683077528756E31C3"></a>
+<span class="figtitleprefix">Figure: </span>Transaction Run From a Client
+
+<img src="../common/images/xact-run-from-client.gif"
id="how-native-client-xacts-work__image_E9ED33166A994014942ABAD9E6F61755"
class="image" />
+
+To maintain cache consistency, the local client cache is not accessible during
a transaction as it may reflect information inconsistent with the transaction
in progress. When the transaction completes, the local cache is accessible
again.
+
+In addition to the failure conditions common to all transactions, client
transactions can also fail if the transaction delegate fails. If the delegate
performing the transaction fails, the transaction code throws a
`TransactionException`.
+
+## <a
id="how-native-client-xacts-work__section_434BA87403C1449FADC3E7796E30F3C7"
class="no-quick-link"></a>Client Transaction APIs
+
+The API for distributed transactions has the familiar relational database
methods, `begin`, `commit`, and `rollback`. There are also APIs available to
suspend and resume transactions.
+
+The .NET classes for executing transactions are:
+
+- Apache.Geode.Client.CacheTransactionManager
+- Apache.Geode.Client.TransactionId
diff --git
a/docs/geode-native-docs/transactions/running-client-xact.html.md.erb
b/docs/geode-native-docs/transactions/running-client-xact.html.md.erb
new file mode 100644
index 0000000..07f99a4
--- /dev/null
+++ b/docs/geode-native-docs/transactions/running-client-xact.html.md.erb
@@ -0,0 +1,90 @@
+---
+title: Running a 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.
+-->
+
+Before you can run a transaction, you must configure your clients and servers,
define your server regions for your transactions, and define your client
regions.
+
+1. Retrieve the transaction manager.
+
+ **C++ example**
+
+ ``` pre
+ std::shared_ptr<CacheTransactionManager> txManager =
+ cache->getTransactionManager();
+ ```
+
+ **C\# .NET example**
+
+ ``` pre
+ CacheTransactionManager txManager =
+ cache.CacheTransactionManager;
+ ```
+
+2. Run the transaction. (Detailed steps follow the examples.)
+
+ **C++ example**
+
+ ``` pre
+ TransactionId& tid;
+ txManager->begin();
+ // ..do work
+ tid = txManager->suspend();
+ // following code can be run from another
+ // thread that has access to tid
+ try {
+ txManager->resume(tid);
+ // ..do work
+ tid = txManager->commit();
+ } catch (const CommitConflictException& e) {
+ // ..on exception
+ }
+ ```
+
+ **C\# .NET example**
+
+ ``` pre
+ TransactionId tid;
+ txManager.Begin();
+ // ..do work
+ tid = txManager.Suspend();
+ // following code can be run from another
+ // thread that has access to tid
+ try {
+ txManager.Resume(tid);
+ // ..do work
+ txManager.Commit();
+ } catch (CommitConflictException e)
+ ```
+ - Start each transaction with a `begin` operation.
+ - If the transaction runs on server regions that are a mix of
partitioned and replicated regions, perform the first transaction operation on
a partitioned region. This sets the server data host for the entire
transaction. If you are using PR single-hop, single-hop will be applied as
usual to this first operation.
+ - Run the operations that you want included in the transaction.
+ - End the transaction with a `commit` or a `rollback`.
+ **Note:**
+ Do not leave any transaction in an uncommitted and unrolled back state
unless you have suspended the transaction. Transactions that have not been
explicitly suspended do not time out, so will remain in the system for the life
of your application.
+
+3. Review all of your client code for compatibility with transactions.
+
+When you commit a transaction, while the commit is taking place, the changes
are visible in the cache. This is also known as transition commits. This
provides better performance than locking everything to do 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, keys 1 and 2 are written to in a transaction so both of their
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, while the transaction is being committed. This
can happen because of how <%=vars.product_name%> performs reads. This choice
sacrifices atomic visibility in favor of performance. Reads do not block
writes. Writes do not block reads.
+
+Because the client cache waits during transaction execution, and client
regions are not distributed, the only activities that interact with a client
transaction are those that occur on the server.
+
+
diff --git
a/docs/geode-native-docs/transactions/suspend-resume-xacts.html.md.erb
b/docs/geode-native-docs/transactions/suspend-resume-xacts.html.md.erb
new file mode 100644
index 0000000..3c7d821
--- /dev/null
+++ b/docs/geode-native-docs/transactions/suspend-resume-xacts.html.md.erb
@@ -0,0 +1,34 @@
+---
+title: Suspending and Resuming 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 ability to suspend and resume transactions is useful when a thread must
perform operations that should not be part of the transaction before the
transaction can complete.
+
+When a transaction is suspended, it loses the transactional view of the cache.
None of the previous operations (before calling suspend) are visible to the
thread. Subsequently any operations that are performed by the thread do not
participate in the suspended transaction.
+
+When a transaction is resumed, the resuming thread assumes the transactional
view. A transaction that is suspending 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. You may optionally use the
`tryResume` method.
+
+If the member with the primary copy of the data crashes, the transactional
view that applied to that data is lost. The secondary member for the data
cannot resume transactions suspended on the crashed member. You 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 by using the
`suspended-tx-timeout` property of the `geode.properties` file. The suspended
transaction timeout value is specified in milliseconds.
+
+See [Running a Client Transaction](running-client-xact.html) for code examples
that show a how to suspend and resume a transaction.
+
+
diff --git a/docs/geode-native-docs/transactions/transactions.html.md.erb
b/docs/geode-native-docs/transactions/transactions.html.md.erb
new file mode 100644
index 0000000..dc56a4e
--- /dev/null
+++ b/docs/geode-native-docs/transactions/transactions.html.md.erb
@@ -0,0 +1,46 @@
+---
+title: 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 section describes how transactions work on the client side. It provides
examples for running, suspending, and resuming transactions.
+
+Client transactions run on the server tier. The client uses a server delegate
+that runs the transaction as it would a local transaction.
+Thus, the key to running client transactions lies in making sure the server
+is properly configured and programmed.
+For complete information about transactions in the Java server,
+see the server documentation at
+[Transactions](geodeman/developing/transactions/chapter_overview.html).
+It provides detailed information including server data requirements,
+interactions of transactions with other operations running on the server tier,
+server-side application plug-ins with transactions,
+and querying with transactions.
+
+- **[How Client Transactions Work](how-client-xacts-work.html)**
+
+ The syntax for writing client transactions is the same as with server or
peer transactions, but when a client performs a transaction, the transaction is
delegated to a server that brokers the transaction.
+
+- **[Running a Client Transaction](running-client-xact.html)**
+
+ Before you can run a client transaction, you must configure your clients
and servers; define your server regions for your transactions; and define your
client regions.
+
+- **[Suspending and Resuming Transactions](suspend-resume-xacts.html)**
+
+ The ability to suspend and resume transactions is useful when a thread
must perform operations that should not be part of the transaction before the
transaction can complete.
--
To stop receiving notification emails like this one, please contact
dbar...@apache.org.
