http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/cache_transactions.html.md.erb ---------------------------------------------------------------------- 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 7e00e42..0000000 --- a/geode-docs/developing/transactions/cache_transactions.html.md.erb +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Geode Cache 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 Geode cache transactions to group the execution of cache operations and to gain the control offered by transactional commit and rollback. Geode cache transactions control operations within the Geode cache while the Geode distributed system handles data distribution in the usual way. - -- **[Cache Transaction Performance](../../developing/transactions/cache_transaction_performance.html)** - - Cache transaction performance can vary depending on the type of regions you are using. - -- **[Data Location for Cache Transactions](../../developing/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 Geode Cache Transaction](../../developing/transactions/run_a_cache_transaction.html)** - - This topic describes how to run a Geode cache transaction. - -- **[How to Run a Geode Cache Transaction that Coordinates with an External Database](../../developing/transactions/run_a_cache_transaction_with_external_db.html)** - - Coordinate a Geode cache transaction with an external database by using CacheWriter/CacheListener and TransactionWriter/TransactionListener plug-ins, **to provide an alternative to using JTA transactions**. - -- **[Working with Geode Cache Transactions](../../developing/transactions/working_with_transactions.html)** - - This section contains guidelines and additional information on working with Geode and its cache transactions. - -- **[How Geode Cache Transactions Work](../../developing/transactions/how_cache_transactions_work.html#topic_fls_1j1_wk)** - - This section provides an explanation of how transactions work on Geode caches. - -
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/cache_transactions_by_region_type.html.md.erb ---------------------------------------------------------------------- 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 fa3318a..0000000 --- a/geode-docs/developing/transactions/cache_transactions_by_region_type.html.md.erb +++ /dev/null @@ -1,156 +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 Geode cache 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 host is the same one running the application. - -- 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](../../developing/transactions/cache_transactions_by_region_type.html#concept_ysk_xj1_wk)** - -- **[Transactions and Replicated Regions](../../developing/transactions/cache_transactions_by_region_type.html#concept_nl5_pk1_wk)** - -- **[Transactions and Persistent Regions](../../developing/transactions/cache_transactions_by_region_type.html#concept_omy_341_wk)** - -## Transactions and Partitioned Regions -<a id="concept_ysk_xj1_wk"> - -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_partitioning_and_data_colocation). In addition, the data must not be moved during the transaction. Design partitioned region rebalancing to avoid rebalancing while transactions are running. See [Rebalancing Partitioned Region Data](../partitioned_regions/rebalancing_pr_data.html#rebalancing_pr_data). -- 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 Geode 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 Geode 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. Geode 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"> - -By default, Geode 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 Geode 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: - -- Geode 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 Geode process crashes, atomicity still exists. The overall risk of losing disk updates can also be mitigated by enabling synchronized disk file mode for the disk stores, but this incurs a high performance penalty. - -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. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/chapter_overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/chapter_overview.html.md.erb b/geode-docs/developing/transactions/chapter_overview.html.md.erb deleted file mode 100644 index b5e84a4..0000000 --- a/geode-docs/developing/transactions/chapter_overview.html.md.erb +++ /dev/null @@ -1,48 +0,0 @@ ---- -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. ---> - -Geode provides a transactions API, with `begin`, `commit`, and `rollback` methods. These methods are much the same as the familiar relational database transactions methods. - -- **[About Transactions](../../developing/transactions/about_transactions.html)** - - This section covers the features of Geode transactions. - -- **[Types of Transactions](../../developing/transactions/about_transactions.html#concept_w3b_wh3_5k)** - - Geode supports two kinds of transactions: **Geode cache transactions** and **JTA global transactions**. - -- **[Geode Cache Transactions](../../developing/transactions/cache_transactions.html)** - - Use Geode cache transactions to group the execution of cache operations and to gain the control offered by transactional commit and rollback. Geode cache transactions control operations within the Geode cache while the Geode distributed system handles data distribution in the usual way. - -- **[JTA Global Transactions with Geode](../../developing/transactions/JTA_transactions.html)** - - Use JTA global transactions to coordinate Geode cache transactions and JDBC transactions. - -- **[Monitoring and Troubleshooting Transactions](../../developing/transactions/monitor_troubleshoot_transactions.html)** - - This topic covers errors that may occur when running transactions in Geode. - -- **[Transaction Coding Examples](../../developing/transactions/transaction_coding_examples.html)** - - This section provides several code examples for writing and executing transactions. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/client_server_transactions.html.md.erb ---------------------------------------------------------------------- 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 727683a..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 Geode 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 Geode Cache Transaction](run_a_cache_transaction.html#task_f15_mr3_5k). - -- **[How Geode Runs Client Transactions](../../developing/transactions/client_server_transactions.html#how_gemfire_runs_clients)** - -- **[Client Cache Access During a Transaction](../../developing/transactions/client_server_transactions.html#client_cache_access)** - -- **[Client Transactions and Client Application Plug-Ins](../../developing/transactions/client_server_transactions.html#client_app_plugins)** - -- **[Client Transaction Failures](../../developing/transactions/client_server_transactions.html#client_transaction_failures)** - -## <a id="how_gemfire_runs_clients" class="no-quick-link"></a>How Geode 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, Geode 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). - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/configuring_db_connections_using_JNDI.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/configuring_db_connections_using_JNDI.html.md.erb b/geode-docs/developing/transactions/configuring_db_connections_using_JNDI.html.md.erb deleted file mode 100644 index 55ad402..0000000 --- a/geode-docs/developing/transactions/configuring_db_connections_using_JNDI.html.md.erb +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Configuring Database Connections Using JNDI ---- - -<!-- -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_A5E3A67C808D48C08E1F0DC167C5C494"></a> - - -When using JTA transactions, you can configure database JNDI data sources in `cache.xml`. The `DataSource` object points to either a JDBC connection or, more commonly, a JDBC connection pool. The connection pool is usually preferred, because a program can use and reuse a connection as long as necessary and then free it for another thread to use. - -The following are a list of `DataSource` connection types used in JTA transactions. - -- **XAPooledDataSource**. Pooled SQL connections. -- **ManagedDataSource**. JNDI binding type for the J2EE Connector Architecture (JCA) ManagedConnectionFactory. -- **PooledDataSource**. Pooled SQL connections. -- **SimpleDataSource**. Single SQL connection. No pooling of SQL connections is done. Connections are generated on the fly and cannot be reused. - -The `jndi-name` attribute of the `jndi-binding` element is the key binding parameter. If the value of `jndi-name` is a DataSource, it is bound as `java:/`*myDatabase*, where *myDatabase* is the name you assign to your data source. If the data source cannot be bound to JNDI at runtime, Geode logs a warning. For information on the `DataSource` interface, see: [http://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html](http://docs.oracle.com/javase/8/docs/api/javax/sql/DataSource.html) - -Geode supports JDBC 2.0 and 3.0. - -**Note:** -Include any data source JAR files in your CLASSPATH. - -## <a id="topic_F67EC20067124A618A8099AB4CBF634C" class="no-quick-link"></a>Example DataSource Configurations in cache.xml - -The following sections show example `cache.xml` files configured for each of the `DataSource` connection types. - -## XAPooledDataSource cache.xml Example (Derby) - -The example shows a `cache.xml` file configured for a pool of `XAPooledDataSource` connections connected to the data resource `newDB`. - -The log-in and blocking timeouts are set lower than the defaults. The connection information, including `user-name` and `password`, is set in the `cache.xml` file, instead of waiting until connection time. The password is encrypted; for details, see [Encrypting Passwords for Use in cache.xml](../../managing/security/encrypting_passwords.html#topic_730CC61BA84F421494956E2B98BDE2A1). - -When specifying the configuration properties for JCA-implemented database drivers that support XA transactions (in other words, **XAPooledDataSource**), you must use configuration properties to define the datasource connection instead of the `connection-url` attribute of the `<jndi-binding>` element. Configuration properties differ depending on your database vendor. Specify JNDI binding properties through the `config-property` tag, as shown in this example. You can add as many `config-property` tags as required. - -``` pre -<?xml version="1.0" encoding="UTF-8"?> -<cache - xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" lock-timeout="60" search-timeout="300"> - <region name="root"> - <region-attributes scope="distributed-no-ack" data-policy="cached" initial-capacity="16" -load-factor="0.75" concurrency-level="16" statistics-enabled="true"> - . . . - </region> - <jndi-bindings> - <jndi-binding type="XAPooledDataSource" - jndi-name="newDB2trans" - init-pool-size="20" - max-pool-size="100" - idle-timeout-seconds="20" - blocking-timeout-seconds="5" - login-timeout-seconds="10" - xa-datasource-class="org.apache.derby.jdbc.EmbeddedXADataSource" - user-name="mitul" - password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)"> - <config-property> - <config-property-name>Description</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>pooled_transact</config-property-value> - </config-property> - <config-property> - <config-property-name>DatabaseName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>newDB</config-property-value> - </config-property> - <config-property> - <config-property-name>CreateDatabase</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>create</config-property-value> - </config-property> - . . . - </jndi-binding> - </jndi-bindings> -</cache> -``` - -## JNDI Binding Configuration Properties for Different XAPooledDataSource Connections - -The following are some example data source configurations for different databases. Consult your vendor database's documentation for additional details. - -**MySQL** - -``` pre -... -<jndi-bindings> - <jndi-binding type="XAPooledDataSource" - ... - xa-datasource-class="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"> - <config-property> - <config-property-name>URL</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>"jdbc:mysql://mysql-servername:3306/databasename"</config-property-value> - </config-property> - ... - </jndi-binding> - ... -</jndi-bindings> -``` - -**PostgreSQL** - -``` pre -... -<jndi-bindings> - <jndi-binding type="XAPooledDataSource" - ... - xa-datasource-class="org.postgresql.xa.PGXADataSource"> - <config-property> - <config-property-name>ServerName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>postgresql-hostname</config-property-value> - </config-property> - <config-property> - <config-property-name>DatabaseName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>postgresqldbname</config-property-value> - </config-property> - ... - </jndi-binding> - ... -</jndi-bindings> -``` - -**Oracle** - -``` pre -... -<jndi-bindings> - <jndi-binding type="XAPooledDataSource" - ... - xa-datasource-class="oracle.jdbc.xa.client.OracleXADataSource"> - <config-property> - <config-property-name>URL</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>jdbc:oracle:oci8:@tc</config-property-value> - </config-property> - ... - </jndi-binding> - ... -</jndi-bindings> -``` - -**Microsoft SQL Server** - -``` pre -... -<jndi-bindings> - <jndi-binding type="XAPooledDataSource" - ... - xa-datasource-class="com.microsoft.sqlserver.jdbc.SQLServerXADataSource"> - <config-property> - <config-property-name>ServerName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>mysqlserver</config-property-value> - </config-property> - <config-property> - <config-property-name>DatabaseName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>databasename</config-property-value> - </config-property> - <config-property> - <config-property-name>SelectMethod</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>cursor</config-property-value> - </config-property> - ... - </jndi-binding> - ... -</jndi-bindings> -``` - -## ManagedDataSource Connection Example (Derby) - -`ManagedDataSource` connections for the JCA `ManagedConnectionFactory` are configured as shown in the example. This configuration is similar to `XAPooledDataSource` connections, except the type is `ManagedDataSource`, and you specify a `managed-conn-factory-class` instead of an `xa-datasource-class`. - -``` pre -<?xml version="1.0"?> -<cache xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" - lock-timeout="60" - search-timeout="300"> - <region name="root"> - <region-attributes scope="distributed-no-ack" data-policy="cached" initial-capacity="16" -load-factor="0.75" concurrency-level="16" statistics-enabled="true"> - . . . - </region> - <jndi-bindings> - <jndi-binding type="ManagedDataSource" - jndi-name="DB3managed" - init-pool-size="20" - max-pool-size="100" - idle-timeout-seconds="20" - blocking-timeout-seconds="5" - login-timeout-seconds="10" - managed-conn-factory-class="com.myvendor.connection.ConnFactory" - user-name="mitul" - password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)"> - <config-property> - <config-property-name>Description</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>pooled_transact</config-property-value> - </config-property> - <config-property> - <config-property-name>DatabaseName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>newDB</config-property-value> - </config-property> - <config-property> - <config-property-name>CreateDatabase</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>create</config-property-value> - </config-property> - . . . - </jndi-binding> - </jndi-bindings> - </cache> - -``` - -## PooledDataSource Example (Derby) - -Use the `PooledDataSource` and `SimpleDataSource` connections for operations executed outside of any transaction. This example shows a `cache.xml` file configured for a pool of `PooledDataSource` connections to the data resource `newDB`. For this non-transactional connection pool, the log-in and blocking timeouts are set higher than for the transactional connection pools in the two previous examples. The connection information, including `user-name` and `password`, is set in the `cache.xml` file, instead of waiting until connection time. The password is encrypted; for details, see [Encrypting Passwords for Use in cache.xml](../../managing/security/encrypting_passwords.html#topic_730CC61BA84F421494956E2B98BDE2A1). - -``` pre -<?xml version="1.0"?> -<cache xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" - lock-timeout="60" - search-timeout="300"> - <region name="root"> - <region-attributes scope="distributed-no-ack" data-policy="cached" -initial-capacity="16" load-factor="0.75" concurrency-level="16" statistics-enabled="true"> - . . . - </region> - <jndi-bindings> - <jndi-binding - type="PooledDataSource" - jndi-name="newDB1" - init-pool-size="2" - max-pool-size="7" - idle-timeout-seconds="20" - blocking-timeout-seconds="20" - login-timeout-seconds="30" - conn-pooled-datasource-class="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource" - user-name="mitul" - password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)"> - <config-property> - <config-property-name>Description</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>pooled_transact</config-property-value> - </config-property> - <config-property> - <config-property-name>DatabaseName</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>newDB</config-property-value> - </config-property> - <config-property> - <config-property-name>CreateDatabase</config-property-name> - <config-property-type>java.lang.String</config-property-type> - <config-property-value>create</config-property-value> - </config-property> - . . . - </jndi-binding> - </jndi-bindings> -</cache> - -``` - -## SimpleDataSource Connection Example (Derby) - -The example below shows a very basic configuration in the `cache.xml` file for a `SimpleDataSource` connection to the data resource `oldDB`. You only need to configure a few properties like a `jndi-name` for this connection pool, `oldDB1`, and the `databaseName`, `oldDB`. This password is in clear text. - -A simple data source connection does not generally require vendor-specific property settings. If you need them, add `config-property` tags as shown in the earlier examples. - -``` pre -<?xml version="1.0"?> -<cache xmlns="http://geode.incubator.apache.org/schema/cache"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://geode.incubator.apache.org/schema/cache http://geode.incubator.apache.org/schema/cache/cache-1.0.xsd"; - version="1.0" - lock-lease="120" - lock-timeout="60" - search-timeout="300"> - <region name="root"> - <region-attributes scope="distributed-no-ack" data-policy="cached" initial-capacity="16" -load-factor="0.75" concurrency-level="16" statistics-enabled="true"> - . . . - </region-attributes> - </region> - <jndi-bindings> - <jndi-binding type="SimpleDataSource" - jndi-name="oldDB1" - jdbc-driver-class="org.apache.derby.jdbc.EmbeddedDriver" - user-name="mitul" - password="password" - connection-url="jdbc:derby:newDB;create=true"> - . . . - </jndi-binding> - </jndi-bindings> -</cache> -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/data_location_cache_transactions.html.md.erb ---------------------------------------------------------------------- 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 d96de82..0000000 --- a/geode-docs/developing/transactions/data_location_cache_transactions.html.md.erb +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Data Location for Cache 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. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/how_cache_transactions_work.html.md.erb ---------------------------------------------------------------------- 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 4cb0473..0000000 --- a/geode-docs/developing/transactions/how_cache_transactions_work.html.md.erb +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: How Geode Cache 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 Geode caches. - -All the regions in a Geode 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](../../developing/transactions/how_cache_transactions_work.html#concept_hls_1j1_wk)** - -- **[Committing Transactions](../../developing/transactions/how_cache_transactions_work.html#concept_sbj_lj1_wk)** - -- **[Transactions by Region Type](../../developing/transactions/cache_transactions_by_region_type.html#topic_nlq_sk1_wk)** - -- **[Client Transactions](../../developing/transactions/client_server_transactions.html)** - -- **[Comparing Transactional and Non-Transactional Operations](../../developing/transactions/transactional_and_nontransactional_ops.html#transactional_and_nontransactional_ops)** - -- **[Geode Cache Transaction Semantics](../../developing/transactions/transaction_semantics.html)** - -## 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 the entryâs original state and uses it at commit time to discover write conflicts. - -<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. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/jca_adapter_example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/jca_adapter_example.html.md.erb b/geode-docs/developing/transactions/jca_adapter_example.html.md.erb deleted file mode 100644 index 409b93e..0000000 --- a/geode-docs/developing/transactions/jca_adapter_example.html.md.erb +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: 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 Geode . - -``` 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(); -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/monitor_troubleshoot_transactions.html.md.erb ---------------------------------------------------------------------- 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 7956cac..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 Geode. - -<a id="monitor_troubleshoot_transactions__section_881D2FF6761B4D689DDB46C650E2A2E1"></a> -Unlike database transactions, Geode 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 Cache Transactions - -During the operation of Geode cache 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 Geode 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_colocation.html#custom_partitioning_and_data_colocation). -- **`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. - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/run_a_cache_transaction.html.md.erb ---------------------------------------------------------------------- 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 7ec2be6..0000000 --- a/geode-docs/developing/transactions/run_a_cache_transaction.html.md.erb +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: How to Run a Geode Cache 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 Geode cache transaction. - -Applications manage transactions on a per-cache basis. A Geode cache 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 Geode 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 Geode do conflict checks at commit time. Without this, the transaction will throw an `UnsupportedOperationInTransactionException ` exception. | - | **global JTA transactions with only Geode cache 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 Geode](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_suspend_resume_example.html#concept_40AAC4332DCE4E4EB60C4BA141B729A4) 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 Geode reads. This choice sacrifices atomic visibility in favor of performance; reads do not block writes, and writes do not block reads. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/run_a_cache_transaction_with_external_db.html.md.erb ---------------------------------------------------------------------- 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 16a1397..0000000 --- a/geode-docs/developing/transactions/run_a_cache_transaction_with_external_db.html.md.erb +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: How to Run a Geode Cache 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 Geode cache 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 Geode cache 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 Geode cache transaction that coordinates with an external database: - -1. Configure Geode regions as necessary as described in [How to Run a Geode Cache 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 Geode 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 Geode, the TransactionListener is invoked. The TransactionListener calls COMMIT PREPARED to commit the database transaction. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/transaction_coding_examples.html.md.erb ---------------------------------------------------------------------- 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 26aac45..0000000 --- a/geode-docs/developing/transactions/transaction_coding_examples.html.md.erb +++ /dev/null @@ -1,44 +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](../../developing/transactions/transactions_overview.html)** - - 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](../../developing/transactions/transaction_suspend_resume_example.html)** - - This example suspends and resumes a transaction. - -- **[Transaction Embedded within a Function Example](../../developing/transactions/transactional_function_example.html)** - - This example demonstrates a function that does transactional updates to Customer and Order regions. - -- **[Geode JTA Transaction Example](../../developing/transactions/transaction_jta_gemfire_example.html)** - - An example code fragment shows how to run a JTA global transaction using Geode as the JTA transaction manager. - -- **[JCA Resource Adapter Example](../../developing/transactions/jca_adapter_example.html)** - - This example shows how to use the JCA Resource Adapter in Geode . - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/transaction_event_management.html.md.erb ---------------------------------------------------------------------- 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 9ec6b82..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, Geode passes the `TransactionEvent` to the transaction writer local to the transactional view, if one is available. After commit, Geode : - - 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 Geode and global JTA transactions, the `EntryEvent` object contains the Geode transaction ID. JTA transaction events do not contain the JTA transaction ID. - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/transaction_jta_gemfire_example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/transaction_jta_gemfire_example.html.md.erb b/geode-docs/developing/transactions/transaction_jta_gemfire_example.html.md.erb deleted file mode 100644 index 131d164..0000000 --- a/geode-docs/developing/transactions/transaction_jta_gemfire_example.html.md.erb +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Geode JTA Transaction 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. ---> - -An example code fragment shows how to run a JTA global transaction using Geode as the JTA transaction manager. - -The external data sources used in this transaction are configured in the `cache.xml` file. See [Configuring Database Connections Using JNDI](configuring_db_connections_using_JNDI.html#topic_A5E3A67C808D48C08E1F0DC167C5C494) for a configuration example. - -``` pre -Region r = ...; // the region data source -ds = ...; // other data source - - try { - Context ctx = cache.getJNDIContext(); - Connection conn = null; - UserTransaction tx = (UserTransaction) ctx.lookup("java:/UserTransaction"); - tx.begin(); - conn = ds.getConnection(); - Statement stmt = conn.createStatement(); - String sqlSTR = "insert into " + tableName + " values (........ )"; - stmt.executeUpdate(sqlSTR); - r.put("key", "value"); - stmt.close(); - tx.commit(); - conn.close(); - } catch (NamingException e) { - // handle the exception - } -``` - - http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/transaction_semantics.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/transaction_semantics.html.md.erb b/geode-docs/developing/transactions/transaction_semantics.html.md.erb deleted file mode 100644 index 9a2e21e..0000000 --- a/geode-docs/developing/transactions/transaction_semantics.html.md.erb +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Geode Cache Transaction 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. ---> - -Geode transaction semantics differ in some ways from the Atomicity-Consistency-Isolation-Durability (ACID) semantics of traditional relational databases. For performance reasons, Geode transactions do not adhere to ACID constraints by default, but can be configured for ACID support as described in this section. - -## <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. - -Geode 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 reservation system, an intersecting transaction is simply discarded. The serialization of obtaining locks is avoided. See [Committing Transactions](how_cache_transactions_work.html#concept_sbj_lj1_wk) for details on the two-phase commit protocol that implements the reservation system. - -## <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 of the system or its 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. As a distributed cache-based system optimized for performance, Geode in its default configuration does not enforce read isolation. Geode transactions support 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. - -In the default configuration, Geode isolates transactions at the process thread level, so while a transaction is in progress, its changes are visible only inside the thread that is running the transaction. Threads inside the same process and in other processes cannot see changes until after the commit operation begins. At this point, the changes are visible in the cache, but other threads that access the changing data might see only partial results of the transaction leading to a dirty read. - -If an application requires the slower conventional isolation model (such that dirty reads of transitional states are not allowed), read operations must be encapsulated within transactions and the `gemfire.detectReadConflicts` parameter must be set to âtrueâ: - -`-Dgemfire.detectReadConflicts=true` - -This parameter causes read operations to succeed only when they read a consistent pre- or post-transactional state. If not, a `CommitConflictException` is thrown to the calling application. - -## <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. As a distributed cache-based system optimized for performance, Geode does not support on-disk or in-memory durability for transactions. - -Applications can emulate the conventional disk-based durability model by setting the `gemfire.ALLOW_PERSISTENT_TRANSACTIONS` parameter to âtrueâ. - -`-Dgemfire.ALLOW_PERSISTENT_TRANSACTIONS=true` - -This allows permanent regions to participate in transactions, thus providing disk-based durability. See [Transactions and Persistent Regions](cache_transactions_by_region_type.html#concept_omy_341_wk) for more detail on the use of this parameter. http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/84cfbdfc/geode-docs/developing/transactions/transaction_suspend_resume_example.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/developing/transactions/transaction_suspend_resume_example.html.md.erb b/geode-docs/developing/transactions/transaction_suspend_resume_example.html.md.erb deleted file mode 100644 index 7944cde..0000000 --- a/geode-docs/developing/transactions/transaction_suspend_resume_example.html.md.erb +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Basic Suspend and Resume Transaction 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 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(); -``` - -
