GEODE-5296 Rewrite introductory prose on transactions #2056
Conversation
karensmolermiller
requested review from
sbawaska,
davebarnes97 and
joeymcallister
There was a problem hiding this comment.
A few suggestions regarding the text itself:
Typos:
-
Transaction have repeatable read isolation (should be "Transactions...")
-
sets a property and encpsulates (should be "encapsulates...")
Tense - This is optional. I prefer present tense in this case:
- will throw an
UnsupportedOperationException(change "will throw..." to "throws...")
Some occurrences of "cache transactions" that should be changed to "transaction":
-
<%=vars.product_name%> cache transactions are used
-
Applications create cache transactions
-
for details on <%=vars.product_name%> cache transactions
-
coordinate a <%=vars.product_name%> cache transaction
-
See [How to Run a <%=vars.product_name%> Cache Transaction
| @@ -22,61 +22,160 @@ limitations under the License. | |||
| <a id="topic_jbt_2y4_wk"></a> | |||
|
|
|||
|
|
|||
| This section covers the features of <%=vars.product_name%> transactions. | |||
| This section introduces <%=vars.product_name%> transactions. | |||
| Geode offers an API for client applications that do transactional work. | |||
|
|
||
| ## Overview of the Application's Transaction | ||
|
|
||
| There are two ways that an application can run a transaction: |
There was a problem hiding this comment.
The developer is still using the transaction API in function, so I would not call them two different ways.
| The application starts the transaction by invoking `begin`, | ||
| invokes the function within the transaction, | ||
| and then does the `commit` to end the transaction. | ||
| - A transaction is embedded in a function. |
There was a problem hiding this comment.
This does not impart performance benefits that we talk about previously, so I don't how much value add this is.
|
|
||
| <%=vars.product_name%> cache transactions are used to group the execution of cache operations and to gain the control offered by transactional commit and rollback. Applications create cache transactions by using an instance of the <%=vars.product_name%> `CacheTransactionManager`. During a transaction, cache operations are performed and distributed through <%=vars.product_name%> as usual. See [<%=vars.product_name%> Cache Transactions](cache_transactions.html#topic_e15_mr3_5k) for details on <%=vars.product_name%> cache transactions and how these transactions work. | ||
| 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. |
There was a problem hiding this comment.
Do we also want to say listeners/writers? ( like triggers in RDBMS)
| Relational databases provide durability by using disk storage for | ||
| recovery and transaction logging. | ||
| <%=vars.product_name%> is optimized for performance | ||
| and does not support on-disk or in-memory durability for transactions. |
There was a problem hiding this comment.
in-memory by definition is not durable, so I think it should be removed.
|
|
||
| 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. | ||
| JTA global transactions allow you to use the standard JTA interface to coordinate <%=vars.product_name%> transactions with JDBC transactions. When performing JTA global transactions, you have the option of using <%=vars.product_name%>’s own implementation of JTA or a third party’s implementation (typically application servers such as WebLogic or JBoss) of JTA. In addition, some third party JTA implementations allow you to set <%=vars.product_name%> as a “last resource” to ensure transactional consistency across data sources in the event that <%=vars.product_name%> or another data source becomes unavailable. For global transactions, applications use `java:/UserTransaction` to start and terminate transactions while <%=vars.product_name%> cache operations are performed in the same manner as regular <%=vars.product_name%> cache transactions. See [JTA Global Transactions with <%=vars.product_name%>](JTA_transactions.html) for details on JTA Global transactions. |
There was a problem hiding this comment.
Not necessarily only JDBC, you can have message queues and other no-relational data stores too. I would say "to coordinate with other XA datastores".
Please remove references to Geod's own implementation of JTA.
* GEODE-5296 Rewrite introductory prose on transactions * GEODE-5296 Correct errors, per review * GEODE-5296 Revise transactions intro prose per review
I welcome reviews and input from the wider Geode community on this PR. It replaces the introductory doc material on transactions with updated prose. I attempted to revise this prose to be useful for app developers. I hope that reviewers will weigh in on technical accuracy and identify items that are missing from this introductory prose.