Skip to content
Browse files

BLACKTIE-386 JBTM-1070 moved the documentation to a single repo

  • Loading branch information...
1 parent d9dd6d6 commit 5db530b9a089fd0913c4791d2c9cacc7a2bbc591 @tomjenkinson tomjenkinson committed Mar 29, 2012
Showing with 24,266 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +45 −0 ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml
  3. +45 −0 ArjunaCore/docs/development_guide/en-US/Appendix_Class_Definitions.xml
  4. +307 −0 ArjunaCore/docs/development_guide/en-US/Appendix_Object_Store_Implementations.xml
  5. +4 −0 ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent
  6. +21 −0 ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml
  7. +49 −0 ArjunaCore/docs/development_guide/en-US/Author_Group.xml
  8. +31 −0 ArjunaCore/docs/development_guide/en-US/Book_Info.xml
  9. +19 −0 ArjunaCore/docs/development_guide/en-US/Chapter.xml
  10. +184 −0 ...naCore/docs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
  11. +244 −0 ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml
  12. +149 −0 ArjunaCore/docs/development_guide/en-US/Hints_and_Tips.xml
  13. +507 −0 ArjunaCore/docs/development_guide/en-US/Overview.xml
  14. +13 −0 ArjunaCore/docs/development_guide/en-US/Preface.xml
  15. +42 −0 ArjunaCore/docs/development_guide/en-US/Revision_History.xml
  16. +595 −0 ArjunaCore/docs/development_guide/en-US/Using_TxCore.xml
  17. +79 −0 ArjunaCore/docs/development_guide/en-US/extras/Array_class.java
  18. +21 −0 ArjunaCore/docs/development_guide/en-US/extras/AtomicAction_class.java
  19. +5 −0 ArjunaCore/docs/development_guide/en-US/extras/CheckedAction.java
  20. +4 −0 ArjunaCore/docs/development_guide/en-US/extras/EnvironmentBeans.xml
  21. +29 −0 ArjunaCore/docs/development_guide/en-US/extras/Example_extends_LockManager.java
  22. +21 −0 ArjunaCore/docs/development_guide/en-US/extras/InputBuffer.java
  23. +9 −0 ArjunaCore/docs/development_guide/en-US/extras/InputObjectState.java
  24. +14 −0 ArjunaCore/docs/development_guide/en-US/extras/LastResourceRecord.java
  25. +38 −0 ArjunaCore/docs/development_guide/en-US/extras/LockManager_class.java
  26. +25 −0 ArjunaCore/docs/development_guide/en-US/extras/LockMode.java
  27. +37 −0 ArjunaCore/docs/development_guide/en-US/extras/LockResult.java
  28. +9 −0 ArjunaCore/docs/development_guide/en-US/extras/LockStore.java
  29. +11 −0 ArjunaCore/docs/development_guide/en-US/extras/ObjectStore.java
  30. +21 −0 ArjunaCore/docs/development_guide/en-US/extras/OutputBuffer.java
  31. +42 −0 ArjunaCore/docs/development_guide/en-US/extras/OutputBuffer_class.java
  32. +9 −0 ArjunaCore/docs/development_guide/en-US/extras/OutputObjectState.java
  33. +18 −0 ArjunaCore/docs/development_guide/en-US/extras/OutputObjectState_class.java
  34. +15 −0 ArjunaCore/docs/development_guide/en-US/extras/StateManager-signature.java
  35. +2 −0 ArjunaCore/docs/development_guide/en-US/extras/StateManager_activate_method.java
  36. +42 −0 ArjunaCore/docs/development_guide/en-US/extras/StateManager_class.java
  37. +2 −0 ArjunaCore/docs/development_guide/en-US/extras/StateManager_deactivate_method.java
  38. +1 −0 ArjunaCore/docs/development_guide/en-US/extras/StateManager_modified_method.java
  39. +8 −0 ArjunaCore/docs/development_guide/en-US/extras/StateStatus.java
  40. +61 −0 ArjunaCore/docs/development_guide/en-US/extras/TxStats.java
  41. +21 −0 ArjunaCore/docs/development_guide/en-US/extras/Uid_class.java
  42. +53 −0 ArjunaCore/docs/development_guide/en-US/extras/abstract_record_subclass.java
  43. +11 −0 ArjunaCore/docs/development_guide/en-US/extras/activation_termination_commitment.java
  44. +13 −0 ArjunaCore/docs/development_guide/en-US/extras/aliasing.java
  45. +63 −0 ArjunaCore/docs/development_guide/en-US/extras/appendix_StateStatus.java
  46. +19 −0 ArjunaCore/docs/development_guide/en-US/extras/array_get_method.java
  47. +22 −0 ArjunaCore/docs/development_guide/en-US/extras/array_set_method.java
  48. +2 −0 ArjunaCore/docs/development_guide/en-US/extras/defaultTimeout.java
  49. +11 −0 ArjunaCore/docs/development_guide/en-US/extras/default_layout.txt
  50. +34 −0 ArjunaCore/docs/development_guide/en-US/extras/example-TransactionalQueue.java
  51. +37 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_enqueue.java
  52. +50 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_inspectValue.java
  53. +33 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_main.java
  54. +28 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_queueSize.java
  55. +22 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_restore_state.java
  56. +22 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_save_state.java
  57. +4 −0 ArjunaCore/docs/development_guide/en-US/extras/example-queue_type.java
  58. +18 −0 ArjunaCore/docs/development_guide/en-US/extras/example-save_state.java
  59. +18 −0 ArjunaCore/docs/development_guide/en-US/extras/example_methods_for_StateManager.java
  60. +26 −0 ArjunaCore/docs/development_guide/en-US/extras/example_queue_class.java
  61. +4 −0 ArjunaCore/docs/development_guide/en-US/extras/example_queue_destructor.java
  62. +6 −0 ArjunaCore/docs/development_guide/en-US/extras/jdbcaccess.java
  63. +10 −0 ArjunaCore/docs/development_guide/en-US/extras/nested_transactions_in_constructors.java
  64. +47 −0 ArjunaCore/docs/development_guide/en-US/extras/object_store_implementation_using_StateManager.java
  65. +8 −0 ArjunaCore/docs/development_guide/en-US/extras/osv-plugin-ant.xml
  66. +55 −0 ArjunaCore/docs/development_guide/en-US/extras/osv_plugin.java
  67. +11 −0 ArjunaCore/docs/development_guide/en-US/extras/setlock.java
  68. +8 −0 ArjunaCore/docs/development_guide/en-US/extras/simple_concurrency_control.java
  69. +175 −0 ArjunaCore/docs/development_guide/en-US/fallback_content/Conventions.xml
  70. +16 −0 ArjunaCore/docs/development_guide/en-US/fallback_content/Feedback.xml
  71. +9 −0 ArjunaCore/docs/development_guide/en-US/fallback_content/Legal_Notice.xml
  72. BIN ArjunaCore/docs/development_guide/en-US/images/independent_top_level_action.png
  73. BIN ArjunaCore/docs/development_guide/en-US/images/multiple_object_model.png
  74. BIN ArjunaCore/docs/development_guide/en-US/images/single_object_model.png
  75. BIN ArjunaCore/docs/development_guide/en-US/images/txcore_class_hierarchy.png
  76. BIN ArjunaCore/docs/development_guide/en-US/images/txoj-lifecycle.png
  77. +37 −0 ArjunaCore/docs/development_guide/pom.xml
  78. +24 −0 ArjunaCore/docs/failure_recovery_guide/en-US/About_This_Guide.xml
  79. +7 −0 ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.ent
  80. +11 −0 ArjunaCore/docs/failure_recovery_guide/en-US/ArjunaCore_Failure_Recovery_Guide.xml
  81. +14 −0 ArjunaCore/docs/failure_recovery_guide/en-US/Author_Group.xml
  82. +29 −0 ArjunaCore/docs/failure_recovery_guide/en-US/Book_Info.xml
  83. +297 −0 ArjunaCore/docs/failure_recovery_guide/en-US/Further_failure_recovery.xml
  84. +13 −0 ArjunaCore/docs/failure_recovery_guide/en-US/Preface.xml
  85. +31 −0 ArjunaCore/docs/failure_recovery_guide/en-US/Revision_History.xml
  86. +60 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/SimpleRecord.java
  87. +57 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/SimpleRecoveryModule.java
  88. +35 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/TestRecoveryModule.java
  89. +22 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/atomicaction.txt
  90. +4 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/recoveryEnvironmentBean.xml
  91. +3 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/recoveryEnvironmentBeanExpiryScanners.xml
  92. +3 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/recoveryEnvironmentBeanRecoveryExtensions.xml
  93. +25 −0 ArjunaCore/docs/failure_recovery_guide/en-US/extras/txoj.txt
  94. +175 −0 ArjunaCore/docs/failure_recovery_guide/en-US/fallback_content/Conventions.xml
  95. +16 −0 ArjunaCore/docs/failure_recovery_guide/en-US/fallback_content/Feedback.xml
  96. +9 −0 ArjunaCore/docs/failure_recovery_guide/en-US/fallback_content/Legal_Notice.xml
  97. +3,936 −0 ArjunaCore/docs/failure_recovery_guide/en-US/icons/icon.svg
  98. +3,936 −0 ArjunaCore/docs/failure_recovery_guide/en-US/images/icon.svg
  99. +37 −0 ArjunaCore/docs/failure_recovery_guide/pom.xml
  100. +39 −0 ArjunaCore/docs/pom.xml
  101. +49 −0 ArjunaJTA/docs/administration_guide/en-US/Author_Group.xml
  102. +27 −0 ArjunaJTA/docs/administration_guide/en-US/Book_Info.xml
  103. +10 −0 ArjunaJTA/docs/administration_guide/en-US/Chapter.xml
  104. +51 −0 ArjunaJTA/docs/administration_guide/en-US/Errors_And_Exceptions.xml
  105. +212 −0 ArjunaJTA/docs/administration_guide/en-US/Failure_Recovery_Administration.xml
  106. +51 −0 ArjunaJTA/docs/administration_guide/en-US/Introduction.xml
  107. +4 −0 ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.ent
  108. +18 −0 ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Administration_Guide.xml
  109. +17 −0 ArjunaJTA/docs/administration_guide/en-US/JBossJTA_Runtime_Information.xml
  110. +22 −0 ArjunaJTA/docs/administration_guide/en-US/ObjectStore_Management.xml
  111. +23 −0 ArjunaJTA/docs/administration_guide/en-US/Preface.xml
  112. +41 −0 ArjunaJTA/docs/administration_guide/en-US/Revision_History.xml
  113. +66 −0 ArjunaJTA/docs/administration_guide/en-US/Selecting_The_JTA_Implementation.xml
  114. +42 −0 ArjunaJTA/docs/administration_guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
  115. +5 −0 ArjunaJTA/docs/administration_guide/en-US/extras/default_recovery_extension_settings.xml
  116. +3 −0 ArjunaJTA/docs/administration_guide/en-US/extras/expiry_scanner_properties.xml
  117. +175 −0 ArjunaJTA/docs/administration_guide/en-US/fallback_content/Conventions.xml
  118. +16 −0 ArjunaJTA/docs/administration_guide/en-US/fallback_content/Feedback.xml
  119. +9 −0 ArjunaJTA/docs/administration_guide/en-US/fallback_content/Legal_Notice.xml
  120. +37 −0 ArjunaJTA/docs/administration_guide/pom.xml
  121. +39 −0 ArjunaJTA/docs/development_guide/en-US/About_This_Guide.xml
  122. +49 −0 ArjunaJTA/docs/development_guide/en-US/Author_Group.xml
  123. +29 −0 ArjunaJTA/docs/development_guide/en-US/Book_Info.xml
  124. +9 −0 ArjunaJTA/docs/development_guide/en-US/Chapter.xml
  125. +61 −0 ArjunaJTA/docs/development_guide/en-US/Examples.xml
  126. +4 −0 ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.ent
  127. +16 −0 ArjunaJTA/docs/development_guide/en-US/JBossJTA_Development_Guide.xml
  128. +309 −0 ArjunaJTA/docs/development_guide/en-US/JDBC.xml
  129. +23 −0 ArjunaJTA/docs/development_guide/en-US/Preface.xml
  130. +41 −0 ArjunaJTA/docs/development_guide/en-US/Revision_History.xml
  131. +86 −0 ArjunaJTA/docs/development_guide/en-US/Using_JBossTA_In_Application_Servers.xml
  132. +8 −0 ArjunaJTA/docs/development_guide/en-US/extras/BasicXARecovery_Config_Example.xml
  133. +8 −0 ArjunaJTA/docs/development_guide/en-US/extras/JDBCXARecovery_Config_Example.xml
  134. +1 −0 ArjunaJTA/docs/development_guide/en-US/extras/TransactionSynchronizationRegistry_standalone.java
  135. +5 −0 ArjunaJTA/docs/development_guide/en-US/extras/Transaction_Equality.java
  136. +5 −0 ArjunaJTA/docs/development_guide/en-US/extras/XAResourceRecoveryHelper.java
  137. +8 −0 ArjunaJTA/docs/development_guide/en-US/extras/XAResourceRecovery_implementation.java
  138. +3 −0 ArjunaJTA/docs/development_guide/en-US/extras/class.forName.java
  139. +14 −0 ArjunaJTA/docs/development_guide/en-US/extras/creating_and_using_a_connection.java
  140. +167 −0 ArjunaJTA/docs/development_guide/en-US/extras/failure_recovery_example.java
  141. +9 −0 ArjunaJTA/docs/development_guide/en-US/extras/instantiating_dynamic_class.java
  142. +1 −0 ArjunaJTA/docs/development_guide/en-US/extras/instantiating_transactionaldriver.java
  143. +120 −0 ArjunaJTA/docs/development_guide/en-US/extras/jdbc_example.java
  144. +1 −0 ArjunaJTA/docs/development_guide/en-US/extras/jrmp_invoker_proxy.java
  145. +13 −0 ArjunaJTA/docs/development_guide/en-US/extras/passing_connection_url_to_jdbc.java
  146. +13 −0 ...ocs/development_guide/en-US/extras/registering_transactionaldriver_using_jdbc_driver_manager.java
  147. +14 −0 ArjunaJTA/docs/development_guide/en-US/extras/resource_sharing_example.java
  148. +9 −0 ArjunaJTA/docs/development_guide/en-US/extras/storing_datasource_in_jndi.java
  149. +3 −0 ArjunaJTA/docs/development_guide/en-US/extras/using_suspend_method.java
  150. +175 −0 ArjunaJTA/docs/development_guide/en-US/fallback_content/Conventions.xml
  151. +16 −0 ArjunaJTA/docs/development_guide/en-US/fallback_content/Feedback.xml
  152. +9 −0 ArjunaJTA/docs/development_guide/en-US/fallback_content/Legal_Notice.xml
  153. +19 −0 ArjunaJTA/docs/development_guide/en-US/images/icon.svg
  154. +37 −0 ArjunaJTA/docs/development_guide/pom.xml
  155. +16 −0 ArjunaJTA/docs/installation_guide/en-US/Additional_JAR_Requirements.xml
  156. +49 −0 ArjunaJTA/docs/installation_guide/en-US/Author_Group.xml
  157. +29 −0 ArjunaJTA/docs/installation_guide/en-US/Book_Info.xml
  158. +4 −0 ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.ent
  159. +16 −0 ArjunaJTA/docs/installation_guide/en-US/JBossJTA_Installation_Guide.xml
  160. +35 −0 ArjunaJTA/docs/installation_guide/en-US/Logging.xml
  161. +161 −0 ArjunaJTA/docs/installation_guide/en-US/Operating_System_Services.xml
  162. +23 −0 ArjunaJTA/docs/installation_guide/en-US/Preface.xml
  163. +41 −0 ArjunaJTA/docs/installation_guide/en-US/Preparing_Your_System.xml
  164. +41 −0 ArjunaJTA/docs/installation_guide/en-US/Revision_History.xml
  165. +51 −0 ArjunaJTA/docs/installation_guide/en-US/Setting_Properties.xml
  166. +175 −0 ArjunaJTA/docs/installation_guide/en-US/fallback_content/Conventions.xml
  167. +16 −0 ArjunaJTA/docs/installation_guide/en-US/fallback_content/Feedback.xml
  168. +9 −0 ArjunaJTA/docs/installation_guide/en-US/fallback_content/Legal_Notice.xml
  169. +37 −0 ArjunaJTA/docs/installation_guide/pom.xml
  170. +41 −0 ArjunaJTA/docs/pom.xml
  171. +26 −0 ArjunaJTA/docs/quick_start_guide/en-US/About_This_Guide.xml
  172. +41 −0 ArjunaJTA/docs/quick_start_guide/en-US/Author_Group.xml
  173. +23 −0 ArjunaJTA/docs/quick_start_guide/en-US/Book_Info.xml
  174. +7 −0 ArjunaJTA/docs/quick_start_guide/en-US/JBossJTA_Quick_Start_Guide.ent
  175. +13 −0 ArjunaJTA/docs/quick_start_guide/en-US/JBossJTA_Quick_Start_Guide.xml
  176. +27 −0 ArjunaJTA/docs/quick_start_guide/en-US/Preface.xml
  177. +210 −0 ArjunaJTA/docs/quick_start_guide/en-US/Quick_Start_to_JTA.xml
  178. +27 −0 ArjunaJTA/docs/quick_start_guide/en-US/Revision_History.xml
  179. +8 −0 ArjunaJTA/docs/quick_start_guide/en-US/extras/userTransactionExample.java
  180. +175 −0 ArjunaJTA/docs/quick_start_guide/en-US/fallback_content/Conventions.xml
  181. +16 −0 ArjunaJTA/docs/quick_start_guide/en-US/fallback_content/Feedback.xml
  182. +9 −0 ArjunaJTA/docs/quick_start_guide/en-US/fallback_content/Legal_Notice.xml
  183. +37 −0 ArjunaJTA/docs/quick_start_guide/pom.xml
  184. +20 −0 ArjunaJTS/docs/README_FIRST.txt
  185. +49 −0 ArjunaJTS/docs/administration_guide/en-US/Author_Group.xml
  186. +29 −0 ArjunaJTS/docs/administration_guide/en-US/Book_Info.xml
  187. +10 −0 ArjunaJTS/docs/administration_guide/en-US/Chapter.xml
  188. +210 −0 ArjunaJTS/docs/administration_guide/en-US/Failure_Recovery_Administration.xml
  189. +16 −0 ArjunaJTS/docs/administration_guide/en-US/Initializing_JBossTS_Applications.xml
  190. +61 −0 ArjunaJTS/docs/administration_guide/en-US/Introduction.xml
  191. +4 −0 ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.ent
  192. +17 −0 ArjunaJTS/docs/administration_guide/en-US/JBossJTS_Administration_Guide.xml
  193. +82 −0 ArjunaJTS/docs/administration_guide/en-US/ORB_Specific_Configurations.xml
  194. +276 −0 ArjunaJTS/docs/administration_guide/en-US/OTS_Java_EE_Transaction_Service_Management.xml
  195. +24 −0 ArjunaJTS/docs/administration_guide/en-US/Preface.xml
  196. +27 −0 ArjunaJTS/docs/administration_guide/en-US/Revision_History.xml
  197. +42 −0 ArjunaJTS/docs/administration_guide/en-US/Starting_And_Stopping_Transaction_Manager.xml
  198. +7 −0 ArjunaJTS/docs/administration_guide/en-US/extras/default_recovery_extension_settings.xml
  199. +3 −0 ArjunaJTS/docs/administration_guide/en-US/extras/expiry_scanner_properties.xml
  200. +175 −0 ArjunaJTS/docs/administration_guide/en-US/fallback_content/Conventions.xml
  201. +16 −0 ArjunaJTS/docs/administration_guide/en-US/fallback_content/Feedback.xml
  202. +9 −0 ArjunaJTS/docs/administration_guide/en-US/fallback_content/Legal_Notice.xml
  203. +37 −0 ArjunaJTS/docs/administration_guide/pom.xml
  204. +49 −0 ArjunaJTS/docs/development_guide/en-US/Author_Group.xml
  205. +29 −0 ArjunaJTS/docs/development_guide/en-US/Book_Info.xml
  206. +9 −0 ArjunaJTS/docs/development_guide/en-US/Chapter.xml
  207. +386 −0 ArjunaJTS/docs/development_guide/en-US/Constructing_An_OTS_Application.xml
  208. +296 −0 ArjunaJTS/docs/development_guide/en-US/Example.xml
  209. +657 −0 ArjunaJTS/docs/development_guide/en-US/Failure_Recovery.xml
  210. +23 −0 ArjunaJTS/docs/development_guide/en-US/IDL_Definitions.xml
  211. +4 −0 ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.ent
  212. +24 −0 ArjunaJTS/docs/development_guide/en-US/JBossJTS_Development_Guide.xml
  213. +376 −0 ArjunaJTS/docs/development_guide/en-US/JBossTS_Basics.xml
  214. +376 −0 ArjunaJTS/docs/development_guide/en-US/JBossTS_Interface.xml
  215. +44 −0 ArjunaJTS/docs/development_guide/en-US/JTA_And_JTS.xml
  216. +19 −0 ArjunaJTS/docs/development_guide/en-US/ORB_Specific_Configurations.xml
  217. +1,897 −0 ArjunaJTS/docs/development_guide/en-US/OTS.xml
  218. +318 −0 ArjunaJTS/docs/development_guide/en-US/Overview.xml
  219. +44 −0 ArjunaJTS/docs/development_guide/en-US/Preface.xml
  220. +33 −0 ArjunaJTS/docs/development_guide/en-US/References.xml
  221. +41 −0 ArjunaJTS/docs/development_guide/en-US/Revision_History.xml
  222. +52 −0 ArjunaJTS/docs/development_guide/en-US/Tools.xml
  223. +54 −0 ArjunaJTS/docs/development_guide/en-US/extras/ArjunaOTS.idl
  224. +5 −0 ArjunaJTS/docs/development_guide/en-US/extras/ArjunaSubtranAwareResource.java
  225. +22 −0 ArjunaJTS/docs/development_guide/en-US/extras/AtomicTransaction.java
  226. +7 −0 ArjunaJTS/docs/development_guide/en-US/extras/CheckedAction-implementation.java
  227. +145 −0 ArjunaJTS/docs/development_guide/en-US/extras/CosTransactions.idl
  228. +15 −0 ArjunaJTS/docs/development_guide/en-US/extras/Current.java
  229. +34 −0 ArjunaJTS/docs/development_guide/en-US/extras/DemoClient.java
  230. +32 −0 ArjunaJTS/docs/development_guide/en-US/extras/DemoServer.java
  231. +6 −0 ArjunaJTS/docs/development_guide/en-US/extras/ExpiryScanner-properties.xml
  232. +9 −0 ArjunaJTS/docs/development_guide/en-US/extras/ExplicitInterposition.java
  233. +19 −0 ArjunaJTS/docs/development_guide/en-US/extras/ExplicitInterposition_example.java
  234. +17 −0 ArjunaJTS/docs/development_guide/en-US/extras/OTSAbstractRecord.java
  235. +7 −0 ArjunaJTS/docs/development_guide/en-US/extras/OTS_Thread.java
  236. +3 −0 ArjunaJTS/docs/development_guide/en-US/extras/RecoveryManager-properties.xml
  237. +5 −0 ArjunaJTS/docs/development_guide/en-US/extras/SubtransactionAwareResource.java
  238. +224 −0 ArjunaJTS/docs/development_guide/en-US/extras/XAConnectionRecovery.java
  239. +53 −0 ArjunaJTS/docs/development_guide/en-US/extras/abstract_record_subclass.java
  240. +11 −0 ArjunaJTS/docs/development_guide/en-US/extras/completing_top_level_transaction.java
  241. +7 −0 ArjunaJTS/docs/development_guide/en-US/extras/default-RecoveryExtension-settings.xml
  242. +10 −0 ArjunaJTS/docs/development_guide/en-US/extras/direct_and_explicit.java
  243. +2 −0 ArjunaJTS/docs/development_guide/en-US/extras/direct_and_explicit_client_requests.java
  244. +2 −0 ArjunaJTS/docs/development_guide/en-US/extras/direct_and_explicit_commit.java
  245. +35 −0 ArjunaJTS/docs/development_guide/en-US/extras/example-DemoResource.java
  246. +13 −0 ArjunaJTS/docs/development_guide/en-US/extras/example-idl-interface.java
  247. +2 −0 ArjunaJTS/docs/development_guide/en-US/extras/exampleRMICDeclaration.xml
  248. +8 −0 ArjunaJTS/docs/development_guide/en-US/extras/indirect_and_implicit.java
  249. +3 −0 ArjunaJTS/docs/development_guide/en-US/extras/indirect_and_implicit_close.java
  250. +1 −0 ArjunaJTS/docs/development_guide/en-US/extras/orportability-properties.xml
  251. +8 −0 ArjunaJTS/docs/development_guide/en-US/extras/osv-plugin-ant.xml
  252. +55 −0 ArjunaJTS/docs/development_guide/en-US/extras/osv_plugin.java
  253. +44 −0 ArjunaJTS/docs/development_guide/en-US/extras/reliable_server.java
  254. +16 −0 ArjunaJTS/docs/development_guide/en-US/extras/simple_transactional_client.java
  255. +9 −0 ArjunaJTS/docs/development_guide/en-US/extras/simple_transactional_client_2.java
  256. +17 −0 ArjunaJTS/docs/development_guide/en-US/extras/simple_transactional_client_3.java
  257. +5 −0 ArjunaJTS/docs/development_guide/en-US/extras/synchronization.java
  258. +31 −0 ArjunaJTS/docs/development_guide/en-US/extras/terminator_coordinator_control.java
  259. +28 −0 ArjunaJTS/docs/development_guide/en-US/extras/transactional-implementation.java
  260. +25 −0 ArjunaJTS/docs/development_guide/en-US/extras/transactional_object.java
  261. +175 −0 ArjunaJTS/docs/development_guide/en-US/fallback_content/Conventions.xml
  262. +16 −0 ArjunaJTS/docs/development_guide/en-US/fallback_content/Feedback.xml
  263. +9 −0 ArjunaJTS/docs/development_guide/en-US/fallback_content/Legal_Notice.xml
  264. BIN ArjunaJTS/docs/development_guide/en-US/images/control_and_resources.png
  265. +19 −0 ArjunaJTS/docs/development_guide/en-US/images/icon.svg
  266. BIN ArjunaJTS/docs/development_guide/en-US/images/img-2phase.png
  267. BIN ArjunaJTS/docs/development_guide/en-US/images/interface_relationship.png
  268. BIN ArjunaJTS/docs/development_guide/en-US/images/jbossts-class-hierarchy.png
  269. BIN ArjunaJTS/docs/development_guide/en-US/images/ots_architecture.png
  270. BIN ArjunaJTS/docs/development_guide/en-US/images/register_resource.png
  271. BIN ArjunaJTS/docs/development_guide/en-US/images/register_subtran_aware.png
  272. BIN ArjunaJTS/docs/development_guide/en-US/images/resource-and-recoverycoordinator.png
  273. BIN ArjunaJTS/docs/development_guide/en-US/images/resource_nested_transactions.png
  274. BIN ArjunaJTS/docs/development_guide/en-US/images/sequence-diagram.png
  275. BIN ArjunaJTS/docs/development_guide/en-US/images/subtransaction-rollback.png
  276. BIN ArjunaJTS/docs/development_guide/en-US/images/subtransaction_commit.png
  277. BIN ArjunaJTS/docs/development_guide/en-US/images/subtransaction_current.png
  278. BIN ArjunaJTS/docs/development_guide/en-US/images/top-level-commit.png
  279. BIN ArjunaJTS/docs/development_guide/en-US/images/top-level-rollback.png
  280. BIN ArjunaJTS/docs/development_guide/en-US/images/top_level_transaction_current.png
  281. +37 −0 ArjunaJTS/docs/development_guide/pom.xml
  282. +70 −0 ArjunaJTS/docs/orbportability_guide/en-US/About_This_Guide.xml
  283. +41 −0 ArjunaJTS/docs/orbportability_guide/en-US/Author_Group.xml
  284. +23 −0 ArjunaJTS/docs/orbportability_guide/en-US/Book_Info.xml
  285. +7 −0 ArjunaJTS/docs/orbportability_guide/en-US/JBossJTS_ORB_Portability_Guide.ent
  286. +13 −0 ArjunaJTS/docs/orbportability_guide/en-US/JBossJTS_ORB_Portability_Guide.xml
  287. +540 −0 ArjunaJTS/docs/orbportability_guide/en-US/ORB_Portability_API.xml
  288. +27 −0 ArjunaJTS/docs/orbportability_guide/en-US/Preface.xml
  289. +27 −0 ArjunaJTS/docs/orbportability_guide/en-US/Revision_History.xml
  290. +13 −0 ArjunaJTS/docs/orbportability_guide/en-US/extras/Attribute.java
  291. +72 −0 ArjunaJTS/docs/orbportability_guide/en-US/extras/OA.java
  292. +32 −0 ArjunaJTS/docs/orbportability_guide/en-US/extras/ORB.java
  293. +34 −0 ArjunaJTS/docs/orbportability_guide/en-US/extras/Services.java
  294. +7 −0 ArjunaJTS/docs/orbportability_guide/en-US/extras/Shutdown.java
  295. +175 −0 ArjunaJTS/docs/orbportability_guide/en-US/fallback_content/Conventions.xml
  296. +16 −0 ArjunaJTS/docs/orbportability_guide/en-US/fallback_content/Feedback.xml
  297. +9 −0 ArjunaJTS/docs/orbportability_guide/en-US/fallback_content/Legal_Notice.xml
  298. +37 −0 ArjunaJTS/docs/orbportability_guide/pom.xml
  299. +41 −0 ArjunaJTS/docs/pom.xml
  300. +26 −0 ArjunaJTS/docs/quick_start_guide/en-US/About_This_Guide.xml
Sorry, we could not display the entire diff because too many files (521) changed.
View
1 .gitignore
@@ -0,0 +1 @@
+target/
View
45 ArjunaCore/docs/development_guide/en-US/About_This_Guide.xml
@@ -0,0 +1,45 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "JBossJTA_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>About This Guide</title>
+ <para>
+ The TxCore and TXOJ Programmers Guide contains information on how to use &PRODUCT;.
+ This document provides a detailed look at the design and operation of the TxCore
+ transaction
+ engine and the Transactional Objects for Java toolkit. It describes the architecture
+ and the
+ interaction of components within this architecture.
+ </para>
+ <section>
+ <title>Audience</title>
+ <para>
+ This guide is most relevant to engineers who want to use &PRODUCT;
+ in
+ installations that are not covered elsewhere. It is assumed that the reader is already
+ familiar with the core &PRODUCT;
+ documentation set.
+ </para>
+ </section>
+ <section>
+ <title>Prerequisites</title>
+ <para>
+ This guide assumes a basic familiarity with Java service development and object-oriented
+ programming.
+ A
+ fundamental level of understanding in the following areas will also be useful:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>General understanding of the APIs, components, and objects that are present in Java
+ applications.</para>
+ </listitem>
+ <listitem>
+ <para>A general understanding of the Windows and UNIX operating systems.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
+
View
45 ArjunaCore/docs/development_guide/en-US/Appendix_Class_Definitions.xml
@@ -0,0 +1,45 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<appendix>
+ <title>Class definitions</title>
+ <para>
+ This appendix contains an overview of those classes that the application programmer will typically use. The aim of
+ this appendix is to provide a quick reference guide to these classes for use when writing applications in
+ TxCore. For clarity only the public and protected interfaces of the classes will be given.
+ </para>
+
+ <example>
+ <title>Class <classname>LockManager</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/LockManager_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Class <classname>StateManager</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/StateManager_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Classes <classname>OutputObjectState</classname> and <classname>InputObjectState</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/OutputObjectState_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Classes <classname>OutputBuffer</classname> and <classname>InputBuffer</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/OutputBuffer_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Class <classname>Uid</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/Uid_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Class <classname>AtomicAction</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/AtomicAction_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+</appendix>
+
View
307 ArjunaCore/docs/development_guide/en-US/Appendix_Object_Store_Implementations.xml
@@ -0,0 +1,307 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<appendix>
+ <title>Object store implementations</title>
+ <para>
+
+ </para>
+ <section>
+ <title>The ObjectStore</title>
+ <para>
+ This appendix examines the various TxCore object store implementations and gives guidelines for creating other
+ implementations and plugging into an application.
+ </para>
+ <para>
+ This release of JBoss Transaction Service contains several different implementations of a basic object store. Each
+ serves a particular purpose and is generally optimized for that purpose. Each of the implementations is derived
+ from the <interfacename>ObjectStore</interfacename> interface, which defines the minimum operations which must be
+ provided for an object store implementation to be used by the Transaction Service. You can override the default
+ object store implementation at runtime by setting the
+ <varname>com.arjuna.ats.arjuna.objectstore.objectStoreType</varname> property variable to one of the types
+ described below.
+ </para>
+ <example>
+ <title>Class <classname>StateStatus</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/appendix_StateStatus.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ JBoss Transaction Service programmers do not usually need to interact with any of the object store implementations
+ directly, apart from possibly creating them in the first place. Even this is not necessary if the default store
+ type is used, since JBoss Transaction Service creates stores as necessary. All stores manipulate instances of the
+ class <classname>ObjectState</classname>. These instances are named using a <systemitem>type</systemitem> (via the
+ object's <methodname>type()</methodname> operation) and a <systemitem>Uid</systemitem>.
+ </para>
+ <para>
+ For atomic actions purposes, object states in the store can be principally in two distinct states:
+ <literal>OS_COMMITTED</literal> or <literal>OS_UNCOMMITTED</literal>. An object state starts in the
+ <literal>OS_COMMITTED</literal> state, but when it is modified under the control of an atomic action, a new second
+ object state may be written that is in the <literal>OS_UNCOMMITTED</literal> state. If the action commits, this
+ second object state replaces the original and becomes <literal>OS_COMMITTED</literal>. If the action aborts, this
+ second object state is discarded. All of the implementations provided with this release handle these state
+ transitions by making use of shadow copies of object states. However, any other implementation that maintains this
+ abstraction is permissible.
+ </para>
+ <para>
+ Object states may become hidden, and thus inaccessible, under the control of the crash recovery system.
+ </para>
+ <para>
+ You can browse the contents of a store through the <methodname>allTypes</methodname> and <methodname>allObjUids</methodname> operations. <methodname>allTypes</methodname> returns
+ an <classname>InputObjectState</classname> containing all of the type names of all objects in a store, terminated by a null
+ name. <methodname>allObjUids</methodname> returns an <classname>InputObjectState</classname> containing all of the Uids of all objects of a given type,
+ terminated by the special <methodname>Uid.nullUid()</methodname>.
+ </para>
+
+ <section>
+ <title>Persistent object stores</title>
+ <para>
+ This section briefly describes the characteristics and optimizations of each of the supplied implementations of
+ the persistent object store. Persistent object states are mapped onto the structure of the file system supported
+ by the host operating system.
+ </para>
+
+ <section>
+ <title>Common functionality</title>
+ <para>
+ In addition to the features mentioned earlier, all of the supplied persistent object stores obey the following
+ rules:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Each object state is stored in its own file, which is named using the Uid of the object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The type of an object, as given by the <methodname>type()</methodname> operation, determines the directory
+ into which the object is placed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All of the stores have a common root directory that is determined when JBoss Transaction Service is
+ configured. This directory name is automatically prepended to any store-specific root information.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All stores also have the notion of a localized root directory that is automatically prepended to the type
+ of the object to determine the ultimate directory name. The localized root name is specified when the
+ store is created. The default name is <literal>defaultStore</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <screen><xi:include href="extras/default_layout.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></screen>
+ </section>
+
+ <section>
+ <title>The shadowing store</title>
+ <para>
+ The shadowing store s the original version of the object store, which was provided in prior releases. It is
+ implemented by the class <classname>ShadowingStore</classname>. It is simple but slow. It uses pairs of files
+ to represent objects. One file is the shadow version and the other is the committed version. Files are opened,
+ locked, operated upon, unlocked, and closed on every interaction with the object store. This causes a lot of
+ I/O overhead.
+ </para>
+ <para>
+ If you are overriding the object store implementation, the type of this object store is
+ <literal>ShadowingStore</literal>.
+ </para>
+ </section>
+
+
+ <section>
+ <title>No file-level locking</title>
+ <para>
+ Since transactional objects are concurrency-controlled through <classname>LockManager</classname>, you do not
+ need to impose additional locking at the file level. The basic ShadowingStore implementation handles
+ file-level locking. Therefore, the default object store implementation for JBoss Transaction Service,
+ <systemitem>ShadowNoFileLockStore</systemitem>, relies upon user-level locking. This enables it to provide
+ better performance than the <systemitem>ShadowingStore</systemitem> implementation.
+ </para>
+ <para>
+ If you are overriding the object store implementation, the type of this object store is
+ <literal>ShadowNoFileLockStore</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>The hashed store</title>
+ <para>
+ The HashedStore has the same structure for object states as the ShadowingStore, but has an alternate directory
+ structure that is better suited to storing large numbers of objects of the same type. Using this store,
+ objects are scattered among a set of directories by applying a hashing function to the object's Uid. By
+ default, 255 sub-directories are used. However, you can override this by setting the
+ <varname>ObjectStoreEnvironmentBean.hashedDirectories</varname> environment variable accordingly.
+ </para>
+ <para>
+ If you are overriding the object store implementation, the type of this object store is <literal>HashedStore</literal>.
+ </para>
+ </section>
+
+
+ <section>
+ <title>The JDBC store</title>
+ <para>
+ The JDBCStore uses a JDBC database to save persistent object states. When used in conjunction with the
+ Transactional Objects for Java API, nested transaction support is available. In the current implementation,
+ all object states are stored as <firstterm>Binary Large Objects (BLOBs)</firstterm> within the same table. The
+ limitation on object state size imposed by using BLOBs is <literal>64k</literal>. If you try to store an
+ object state which exceeds this limit, an error is generated and the state is not stored. The transaction is
+ subsequently forced to roll back.
+ </para>
+ <para>
+ When using the JDBC object store, the application must provide an implementation of the
+ <interfacename>JDBCAccess</interfacename> interface, located in the com.arjuna.ats.arjuna.objectstore package:
+ </para>
+ <example>
+ <title>Interface <interfacename>JDBCAccess</interfacename></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/jdbcaccess.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The implementation of this class is responsible for providing the <classname>Connection</classname> which the
+ JDBC ObjectStore uses to save and restore object states:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><methodname>getConnection</methodname></term>
+ <listitem>
+ <para>
+ Returns the Connection to use. This method is called whenever a connection is required, and the
+ implementation should use whatever policy is necessary for determining what connection to return. This
+ method need not return the same <classname>Connection</classname> instance more than once.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>putConnection</term>
+ <listitem>
+ <para>
+ Returns one of the <classname>Connections</classname> acquired from
+ <methodname>getConnection</methodname>. Connections are returned if any errors occur when using them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>initialise</term>
+ <listitem>
+ <para>
+ Used to pass additional arbitrary information to the implementation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The JDBC object store initially requests the number of <classname>Connections</classname> defined in the
+ <varname>ObjectStoreEnvironmentBean.jdbcPoolSizeInitial</varname> property and will use no more than defined
+ in the <varname>ObjectStoreEnvironmentBean.jdbcPoolSizeMaximum property</varname>.
+ </para>
+ <para>
+ The implementation of the <interfacename>JDBCAccess</interfacename> interface to use should be set in the
+ <varname>ObjectStoreEnvironmentBean.jdbcUserDbAccessClassName</varname> property variable.
+ </para>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>JDBCStore</type>.
+ </para>
+ <para>
+ A JDBC object store can be used for managing the transaction log. In this case, the transaction log
+ implementation should be set to <literal>JDBCActionStore</literal> and the <classname>JDBCAccess</classname>
+ implementation must be provided via the <varname>ObjectStoreEnvironmentBean.jdbcTxDbAccessClassName property</varname>
+ variable. In this case, the default table name is <systemitem>JBossTSTxTable</systemitem>.
+ </para>
+ <para>
+ You can use the same <classname>JDBCAccess</classname> implementation for both the user object store and the
+ transaction log.
+ </para>
+ </section>
+
+ <section>
+ <title>The cached store</title>
+ <para>
+ This object store uses the hashed object store, but does not read or write states to the persistent backing
+ store immediately. It maintains the states in a volatile memory cache and either flushes the cache
+ periodically or when it is full. The failure semantics associated with this object store are different from
+ the normal persistent object stores, because a failure could result in states in the cache being lost.
+ </para>
+ <para>
+ If overriding the object store implementation, the type of this object store is <type>CacheStore</type>.
+ </para>
+ <variablelist>
+ <title>Configuration Properties</title>
+ <varlistentry>
+ <term>ObjectStoreEnvironmentBean.cacheStoreHash</term>
+ <listitem>
+ <para>
+ sets the number of internal stores to hash the states over. The default value is 128.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ObjectStoreEnvironmentBean.cacheStoreSize</term>
+ <listitem>
+ <para>
+ the maximum size the cache can reach before a flush is triggered. The default is 10240 bytes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ObjectStoreEnvironmentBean.cacheStoreRemovedItems</term>
+ <listitem>
+ <para>
+ the maximum number of removed items that the cache can contain before a flush is triggered. By default,
+ calls to remove a state that is in the cache will simply remove the state from the cache, but leave a
+ blank entry (rather than remove the entry immediately, which would affect the performance of the
+ cache). When triggered, these entries are removed from the cache. The default value is twice the size of
+ the hash.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ObjectStoreEnvironmentBean.cacheStoreWorkItems</term>
+ <listitem>
+ <para>
+ the maximum number of items that are allowed to build up in the cache before it is flushed. The default
+ value is 100. <varname>ObjectStoreEnvironmentBean.cacheStoreScanPeriod</varname> sets the time in
+ milliseconds for periodically flushing the cache. The default is 120 seconds.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ObjectStoreEnvironmentBean.cacheStoreSync</term>
+ <listitem>
+ <para>
+ determines whether flushes of the cache are sync-ed to disk. The default is <literal>OFF</literal>. To
+ enable, set to <literal>ON</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+
+ <section>
+ <title>LogStore</title>
+ <para>
+ This implementation is based on a traditional transaction log. All transaction states within the same process
+ (VM instance) are written to the same log (file), which is an append-only entity. When transaction data would
+ normally be deleted, at the end of the transaction, a <systemitem>delete</systemitem> record is added to the
+ log instead. Therefore, the log just keeps growing. Periodically a thread runs to prune the log of entries
+ that have been deleted.
+ </para>
+ <para>
+ A log is initially given a maximum capacity beyond which it cannot grow. After it reaches this size, the
+ system creates a new log for transactions that could not be accommodated in the original log. The new log and
+ the old log are pruned as usual. During the normal execution of the transaction system, there may be an
+ arbitrary number of log instances. These should be garbage collected by the system,(or the recovery
+ sub-system, eventually.
+ </para>
+ <para>
+ Check the Configuration Options table for how to configure the LogStore.
+ </para>
+ </section>
+ </section>
+ </section>
+</appendix>
View
4 ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.ent
@@ -0,0 +1,4 @@
+<!ENTITY PRODUCT "Documentation">
+<!ENTITY BOOKID "ArjunaCore_Development_Guide">
+<!ENTITY YEAR "2011">
+<!ENTITY HOLDER "jboss.org">
View
21 ArjunaCore/docs/development_guide/en-US/ArjunaCore_Development_Guide.xml
@@ -0,0 +1,21 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<book>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml" />
+ <xi:include href="About_This_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Using_TxCore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="General_Transaction_Issues.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Hints_and_Tips.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Constructing_A_Transactional_Objects_For_Java_Application.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Appendix_Object_Store_Implementations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Appendix_Class_Definitions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <index /> -->
+</book>
+
View
49 ArjunaCore/docs/development_guide/en-US/Author_Group.xml
@@ -0,0 +1,49 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<authorgroup>
+ <author>
+ <firstname>Mark</firstname>
+ <surname>Little</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>mlittle@redhat.com</email>
+ </author>
+ <author>
+ <firstname>Jonathan</firstname>
+ <surname>Halliday</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>jhallida@redhat.com</email>
+ </author>
+ <author>
+ <firstname>Andrew</firstname>
+ <surname>Dinn</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>adinn@redhat.com</email>
+ </author>
+ <author>
+ <firstname>Kevin</firstname>
+ <surname>Connor</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>kconnor@redhat.com</email>
+ </author>
+ <editor>
+ <firstname>Misty</firstname>
+ <surname>Stanley-Jones</surname>
+ <affiliation>
+ <orgname>Red Hat</orgname>
+ </affiliation>
+ <email>misty@redhat.com</email>
+ </editor>
+
+</authorgroup>
+
View
31 ArjunaCore/docs/development_guide/en-US/Book_Info.xml
@@ -0,0 +1,31 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<bookinfo id="book-ArjunaCore_Development_Guide-ArjunaCore_Development_Guide">
+ <title>ArjunaCore Development Guide</title>
+ <subtitle>TxCore and TXOJ Programmers Guide</subtitle>
+ <productname>ArjunaCore</productname>
+ <productnumber>4.15.1</productnumber>
+ <edition>0</edition>
+ <pubsnumber>0</pubsnumber>
+ <abstract>
+ <para>
+ This guide is most relevant to engineers who are responsible for administering JBoss Transactions
+ installations. Although this guide is specifically intended for service developers, it will be useful to anyone
+ who would like to gain an understanding of transactions and how they function.
+ </para>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
+ </imageobject>
+ <textobject><phrase>Logo</phrase></textobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <!--FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Legal_Notice.xml"> <!--FOR JDOCBOOK:--> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="fallback_content/Legal_Notice.xml"/> </xi:fallback> </xi:include>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
+
View
19 ArjunaCore/docs/development_guide/en-US/Chapter.xml
@@ -0,0 +1,19 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Test Chapter</title>
+ <para>
+
+ </para>
+ <section>
+ <title>Test Section 1</title>
+ <para>
+
+ </para>
+ </section>
+
+</chapter>
+
View
184 ...ocs/development_guide/en-US/Constructing_A_Transactional_Objects_For_Java_Application.xml
@@ -0,0 +1,184 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Constructing a Transactional Objects for Java application</title>
+ <orderedlist>
+ <title>Development Phases of a TxCore Application</title>
+ <listitem>
+ <para>
+ First, develop new classes with characteristics like persistence, recoverability, and concurrency control.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Then develop the applications that make use of the new classes of objects.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ Although these two phases may be performed in parallel and by a single person, this guide refers to the first step
+ as the job of the class developer, and the second as the job of the applications developer.<!--Rewrite this --> The
+ class developer defines appropriate <methodname>save_state</methodname> and <methodname>restore_state</methodname>
+ operations for the class, sets appropriate locks in operations, and invokes the appropriate TxCore class
+ constructors. The applications developer defines the general structure of the application, particularly with regard
+ to the use of atomic actions.
+ </para>
+ <para>
+ This chapter outlines a simple application, a simple FIFO Queue class for integer values. The Queue is implemented
+ with a doubly linked list structure, and is implemented as a single object. This example is used throughout the rest
+ of this manual to illustrate the various mechanisms provided by TxCore. Although this is an unrealistic example
+ application, it illustrates all of the TxCore modifications without requiring in depth knowledge of the application
+ code.
+ </para>
+ <note>
+ <para>
+ The application is assumed not to be distributed. To allow for distribution, context information must be
+ propagated either implicitly or explicitly.
+ </para>
+ </note>
+
+
+ <section>
+ <title>Queue description</title>
+ <para>
+ The queue is a traditional FIFO queue, where elements are added to the front and removed from the back. The
+ operations provided by the queue class allow the values to be placed on to the queue (<methodname>enqueue</methodname>) and to be removed
+ from it (<methodname>dequeue</methodname>), and values of elements in the queue can also be changed or inspected. In this
+ example implementation, an array represents the queue. A limit of <varname>QUEUE_SIZE</varname> elements has been imposed
+ for this example.
+ </para>
+ <example>
+ <title>Java interface definition of class <classname>queue</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example_queue_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ </section>
+
+ <section>
+ <title>Constructors and destructors</title>
+ <para>
+ Using an existing persistent object requires the use of a special constructor
+ that takes the Uid of the persistent object, as shown in <xref linkend="example-TransactionalQueue" />.
+ </para>
+ <example id="example-TransactionalQueue">
+ <title>Class <classname>TransactionalQueue</classname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/example-TransactionalQueue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The use of an atomic action within the constructor for a new object follows the guidelines outlined earlier and
+ ensures that the object’s state will be written to the object store when the appropriate top level atomic action
+ commits (which will either be the action A or some enclosing action active when the TransactionalQueue was
+ constructed). The use of atomic actions in a constructor is simple: an action must first be declared and its begin
+ operation invoked; the operation must then set an appropriate lock on the object (in this case a WRITE lock must
+ be acquired), then the main body of the constructor is executed. If this is successful the atomic action can be
+ committed, otherwise it is aborted.
+ </para>
+ <para>
+ The destructor of the <classname>queue</classname> class is only required to call the
+ <methodname>terminate</methodname> operation of <classname>LockManager</classname>.
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example_queue_destructor.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+
+ </section>
+
+ <section>
+ <title>Required methods</title>
+ <section>
+ <title><methodname>save_state</methodname>, <methodname>restore_state</methodname>, and <methodname>type</methodname></title>
+ <example>
+ <title>Method <methodname>save_state</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_save_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <example>
+ <title>Method <methodname>restore_state</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_restore_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <example>
+ <title>Method <methodname>type</methodname></title>
+ <para>
+ Because the Queue class is derived from the LockManager class, the operation type should be:
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_type.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title><methodname>enqueue</methodname> and <methodname>dequeue</methodname> methods</title>
+ <para>
+ If the operations of the <classname>queue</classname> class are to be coded as atomic actions, then the enqueue
+ operation might have the structure given below. The <methodname>dequeue</methodname> operation is similarly
+ structured, but is not implemented here.
+ </para>
+ <example>
+ <title>Method <methodname>enqueue</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_enqueue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+
+ <section>
+ <title><methodname>queueSize</methodname> method</title>
+ <example>
+ <title>Method <methodname>queueSize</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_queueSize.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+
+ <section>
+ <title><methodname>inspectValue</methodname> and <methodname>setValue</methodname> methods</title>
+ <note>
+ <para>
+ The <methodname>setValue</methodname> method is not implemented here, but is similar in structure to <xref
+ linkend="example_queue-inspectValue" />.
+ </para>
+ </note>
+ <example id="example_queue-inspectValue">
+ <title>Method <methodname>inspectValue</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-queue_inspectValue.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+ </section>
+
+
+ <section>
+ <title>The client</title>
+ <para>
+ Rather than show all of the code for the client, this example concentrates on a representative portion. Before
+ invoking operations on the object, the client must first bind to the object. In the local case this simply
+ requires the client to create an instance of the object.
+ </para>
+ <example>
+ <title>Binding to the Object</title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/example-queue_main.java"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ </section>
+
+
+ <section>
+ <title>Comments</title>
+ <para>
+ Since the <systemitem>queue</systemitem> object is persistent, the state of the object survives any failures of
+ the node on which it is located. The state of the object that survives is the state produced by the last top-level
+ committed atomic action performed on the object. If an application intends to perform two
+ <methodname>enqueue</methodname> operations atomically, for example, you can nest the
+ <methodname>enqueue</methodname> operations in another enclosing atomic action. In addition, concurrent operations
+ on such a persistent object are serialized, preventing inconsistencies in the state of the object.
+ </para>
+ <para>
+ However, since the elements of the <systemitem>queue</systemitem> objects are not individually concurrency
+ controlled, certain combinations of concurrent operation invocations are executed serially, even though logically
+ they could be executed concurrently. An example of this is modifying the states of two different elements in the
+ queue. The platform Development Guide addresses some of these issues.
+ </para>
+
+ </section>
+
+</chapter>
+
View
244 ArjunaCore/docs/development_guide/en-US/General_Transaction_Issues.xml
@@ -0,0 +1,244 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Advanced transaction issues with TxCore</title>
+ <para>
+ Atomic actions (transactions) can be used by both application programmers and class developers. Thus entire
+ operations (or parts of operations) can be made atomic as required by the semantics of a particular operation. This
+ chapter will describe some of the more subtle issues involved with using transactions in general and TxCore in
+ particular.
+
+ </para>
+
+ <section>
+ <title>Last resource commit optimization (LRCO)</title>
+ <para>
+ In some cases it may be necessary to enlist participants that are not two-phase commit aware into a two-phase
+ commit transaction. If there is only a single resource then there is no need for two-phase commit. However, if
+ there are multiple resources in the transaction, the <firstterm>Last Resource Commit optimization
+ (LRCO)</firstterm> comes into play. It is possible for a single resource that is one-phase aware (i.e., can only
+ commit or roll back, with no prepare), to be enlisted in a transaction with two-phase commit aware resources. The
+ coordinator treats the one-phase aware resource slightly differently, in that it executes the prepare phase on all
+ other resource first, and if it then intends to commit the transaction it passes control to the one-phase aware
+ resource. If it commits, then the coordinator logs the decision to commit and attempts to commit the other
+ resources as well.
+ </para>
+ <para>
+ In order to utilize the LRCO, your participant must implement the
+ <interfacename>com.arjuna.ats.arjuna.coordinator.OnePhase</interfacename> interface and be registered with the
+ transaction through the <methodname>BasicAction.add</methodname> operation. Since this operation expects instances
+ of <classname>AbstractRecord</classname>, you must create an instance of
+ <classname>com.arjuna.ats.arjuna.LastResourceRecord</classname> and give your participant as the constructor
+ parameter.
+ </para>
+ <example>
+ <title>Class <classname>com.arjuna.ats.arjuna.LastResourceRecord</classname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/LastResourceRecord.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Nested transactions</title>
+ <para>
+ There are no special constructs for nesting of transactions. If an action is begun while another action is running
+ then it is automatically nested. This allows for a modular structure to applications, whereby objects can be
+ implemented using atomic actions within their operations without the application programmer having to worry about
+ the applications which use them, and whether or not the applications will use atomic actions as well. Thus, in
+ some applications actions may be top-level, whereas in others they may be nested. Objects written in this way can
+ then be shared between application programmers, and TxCore will guarantee their consistency.
+ </para>
+ <para>
+ If a nested action is aborted, all of its work will be undone, although strict two-phase locking means that
+ any locks it may have obtained will be retained until the top-level action commits or aborts. If a nested action
+ commits then the work it has performed will only be committed by the system if the top-level action commits. If
+ the top-level action aborts then all of the work will be undone.
+ </para>
+ <para>
+ The committing or aborting of a nested action does not automatically affect the outcome of the action within which
+ it is nested. This is application dependent, and allows a programmer to structure atomic actions to contain
+ faults, undo work, etc.
+ </para>
+ </section>
+
+ <section>
+ <title>Asynchronously committing a transaction</title>
+ <para>
+ By default, the Transaction Service executes the <methodname>commit</methodname> protocol of a top-level
+ transaction in a synchronous manner. All registered resources will be told to prepare in order by a single thread,
+ and then they will be told to commit or rollback. This has several possible disadvantages:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ In the case of many registered resources, the <methodname>prepare</methodname> operating can logically be
+ invoked in parallel on each resource. The disadvantage is that if an “early” resource in the list of
+ registered resource forces a rollback during <methodname>prepare</methodname>, possibly many prepare
+ operations will have been made needlessly.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In the case where heuristic reporting is not required by the application, the second phase of the commit
+ protocol can be done asynchronously, since its success or failure is not important.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Therefore, JBoss Transaction Service provides runtime options to enable possible threading optimizations. By
+ setting the <varname>CoordinatorEnvironmentBean.asyncPrepare</varname> environment variable to
+ <literal>YES</literal>, during the <methodname>prepare</methodname> phase a separate thread will be created for
+ each registered participant within the transaction. By setting
+ <varname>CoordinatorEnvironmentBean.asyncCommit</varname> to <literal>YES</literal>, a separate thread will be
+ created to complete the second phase of the transaction if knowledge about heuristics outcomes is not required.
+ </para>
+ </section>
+
+ <section>
+ <title>Independent top-level transactions</title>
+ <para>
+ In addition to normal top-level and nested atomic actions, TxCore also supports independent top-level actions,
+ which can be used to relax strict serializability in a controlled manner. An independent top-level action can be
+ executed from anywhere within another atomic action and behaves exactly like a normal top-level action. Its
+ results are made permanent when it commits and will not be undone if any of the actions within which it was
+ originally nested abort.
+ </para>
+ <figure>
+ <title>Independent Top-Level Action</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/independent_top_level_action.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>
+ a typical nesting of atomic actions, where action B is nested within action A. Although atomic action C is
+ logically nested within action B (it had its Begin operation invoked while B was active) because it is an
+ independent top-level action, it will commit or abort independently of the other actions within the
+ structure. Because of the nature of independent top-level actions they should be used with caution and only
+ in situations where their use has been carefully examined.
+ </para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Top-level actions can be used within an application by declaring and using instances of the class
+ <classname>TopLevelTransaction</classname>. They are used in exactly the same way as other transactions.
+ </para>
+ </section>
+
+ <section>
+ <title>Transactions within <methodname>save_state</methodname> and <methodname>restore_state</methodname>
+ methods</title>
+ <para>
+ Exercise caution when writing the <methodname>save_state</methodname> and <methodname>restore_state</methodname>
+ operations to ensure that no atomic actions are started, either explicitly in the operation or implicitly through
+ use of some other operation. This restriction arises due to the fact that TxCore may invoke
+ <methodname>restore_state</methodname> as part of its commit processing resulting in the attempt to execute an
+ atomic action during the commit or abort phase of another action. This might violate the atomicity properties of
+ the action being committed or aborted and is thus discouraged.
+ </para>
+
+ <example>
+ <title></title>
+ <para>
+ If we consider the <xref linkend="array-example" /> given previously, the <methodname>set</methodname> and
+ <methodname>get</methodname> operations could be implemented as shown below.
+ </para>
+ <para>
+ This is a simplification of the code, ignoring error conditions and exceptions.
+ </para>
+
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/array_set_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/array_get_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Garbage collecting objects</title>
+ <para>
+ Java objects are deleted when the garbage collector determines that they are no longer required. Deleting an
+ object that is currently under the control of a transaction must be approached with caution since if the object is
+ being manipulated within a transaction its fate is effectively determined by the transaction. Therefore,
+ regardless of the references to a transactional object maintained by an application, TxCore will always retain its
+ own references to ensure that the object is not garbage collected until after any transaction has terminated.
+ </para>
+ </section>
+
+ <section>
+ <title>Transaction timeouts</title>
+ <para>
+ By default, transactions live until they are terminated by the application that created them or a failure
+ occurs. However, it is possible to set a timeout (in seconds) on a per-transaction basis such that if the
+ transaction has not terminated before the timeout expires it will be automatically rolled back.
+ </para>
+ <para>
+ In TxCore, the timeout value is provided as a parameter to the <methodname>AtomicAction</methodname>
+ constructor. If a value of <literal>AtomicAction.NO_TIMEOUT</literal> is provided (the default) then the
+ transaction will not be automatically timed out. Any other positive value is assumed to be the timeout for the
+ transaction (in seconds). A value of zero is taken to be a global default timeout, which can be provided by the
+ property <varname>CoordinatorEnvironmentBean.defaultTimeout</varname>, which has a default value of 60 seconds.
+ </para>
+ <note>
+ <para>
+ Default timeout values for other JBoss Transaction Service components, such as JTS, may be different and you should consult the
+ relevant documentation to be sure.
+ </para>
+ </note>
+ <para>
+ When a top-level transaction is created with a non-zero timeout, it is subject to being rolled back if it has not
+ completed within the specified number of seconds. JBoss Transaction Service uses a separate reaper thread which
+ monitors all locally created transactions, and forces them to roll back if their timeouts elapse. If the
+ transaction cannot be rolled back at that point, the reaper will force it into a rollback-only state so that it
+ will eventually be rolled back.
+ </para>
+ <para>
+ By default this thread is dynamically scheduled to awake according to the timeout values for any transactions
+ created, ensuring the most timely termination of transactions. It may alternatively be configured to awake at a
+ fixed interval, which can reduce overhead at the cost of less accurate rollback timing. For periodic operation,
+ change the <varname>CoordinatorEnvironmentBean.txReaperMode</varname> property from its default value of
+ <literal>DYNAMIC</literal> to <literal>PERIODIC</literal> and set the interval between runs, in milliseconds,
+ using the property <varname>CoordinatorEnvironmentBean.txReaperTimeout</varname>. The default interval in
+ <literal>PERIODIC</literal> mode is 120000 milliseconds.
+ </para>
+ <warning>
+ <para>
+ In earlier versions the <literal>PERIODIC</literal> mode was known as <literal>NORMAL</literal> and was the
+ default behavior. The use of the configuration value <literal>NORMAL</literal> is deprecated and
+ <literal>PERIODIC</literal> should be used instead if the old scheduling behavior is still required.
+ </para>
+ </warning>
+ <para>
+ If a value of <literal>0</literal> is specified for the timeout of a top-level transaction, or no timeout is
+ specified, then JBoss Transaction Service will not impose any timeout on the transaction, and the transaction will
+ be allowed to run indefinitely. This default timeout can be overridden by setting the
+ <varname>CoordinatorEnvironmentBean.defaultTimeout</varname> property variable when using to the required timeout
+ value in seconds, when using ArjunaCore, ArjunaJTA or ArjunaJTS.
+ </para>
+ <note>
+ <para>
+ As of JBoss Transaction Service 4.5, transaction timeouts have been unified across all transaction components
+ and are controlled by ArjunaCore.
+ </para>
+ </note>
+ <section>
+ <title>Monitoring transaction timeouts</title>
+ <para>
+ If you want to be informed when a transaction is rolled back or forced into a rollback-only mode by the reaper,
+ you can create a class that inherits from class
+ <classname>com.arjuna.ats.arjuna.coordinator.listener.ReaperMonitor</classname> and overrides the
+ <methodname>rolledBack</methodname> and <methodname>markedRollbackOnly</methodname> methods. When registered
+ with the reaper via the <methodname>TransactionReaper.addListener</methodname> method, the reaper will invoke
+ one of these methods depending upon how it tries to terminate the transaction.
+ </para>
+ <note>
+ <para>
+ The reaper will not inform you if the transaction is terminated (committed or rolled back) outside of its
+ control, such as by the application.
+ </para>
+ </note>
+ </section>
+ </section>
+</chapter>
+
View
149 ArjunaCore/docs/development_guide/en-US/Hints_and_Tips.xml
@@ -0,0 +1,149 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Hints and tips</title>
+ <section>
+ <title>General</title>
+
+ <section>
+ <title>Using transactions in constructors</title>
+ <para>
+ Examples throughout this manual use transactions in the implementation of constructors for new persistent
+ objects. This is deliberate because it guarantees correct propagation of the state of the object to the object
+ store. The state of a modified persistent object is only written to the object store when the top-level
+ transaction commits. Thus, if the constructor transaction is top-level and it commits, the newly-created object
+ is written to the store and becomes available immediately. If, however, the constructor transaction commits but
+ is nested because another transaction that was started prior to object creation is running, the state is written
+ only if all of the parent transactions commit.
+ </para>
+ <para>
+ On the other hand, if the constructor does not use transactions, inconsistencies in the system can arise. For
+ example, if no transaction is active when the object is created, its state is not saved to the store until the
+ next time the object is modified under the control of some transaction.
+ </para>
+ <example>
+ <title>Nested Transactions In Constructors</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/nested_transactions_in_constructors.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ The two objects are created outside of the control of the top-level action
+ <systemitem>A</systemitem>. <systemitem>obj1</systemitem> is a new object. <systemitem>obj2</systemitem> is an
+ old existing object. When the <methodname>remember</methodname> operation of <systemitem>obj2</systemitem> is
+ invoked, the object will be activated and the <type>Uid</type> of <systemitem>obj1</systemitem>
+ remembered. Since this action commits, the persistent state of <systemitem>obj2</systemitem> may now contain the
+ <type>Uid</type> of <systemitem>obj1</systemitem>. However, the state of <systemitem>obj1</systemitem> itself
+ has not been saved since it has not been manipulated under the control of any action. In fact, unless it is
+ modified under the control of an action later in the application, it will never be saved. If, however, the
+ constructor had used an atomic action, the state of <systemitem>obj1</systemitem> would have automatically been
+ saved at the time it was constructed and this inconsistency could not arise.
+ </para>
+ </section>
+
+ <section>
+ <title><methodname>save_state</methodname> and <methodname>restore_state</methodname> methods</title>
+ <para>
+ TxCore may invoke the user-defined <methodname>save_state</methodname> operation of an object at any time during
+ the lifetime of an object, including during the execution of the body of the object’s constructor. This is
+ particularly a possibility if it uses atomic actions. It is important, therefore, that all of the variables
+ saved by <methodname>save_state</methodname> are correctly initialized. Exercise caution when writing the
+ <methodname>save_state</methodname> and <methodname>restore_state</methodname> operations, to ensure that no
+ transactions are started, either explicitly in the operation, or implicitly through use of some other
+ operation. The reason for this restriction is that TxCore may invoke <methodname>restore_state</methodname> as
+ part of its commit processing. This would result in the attempt to execute an atomic transaction during the
+ commit or abort phase of another transaction. This might violate the atomicity properties of the transaction
+ being committed or aborted, and is thus discouraged. In order to support crash recovery for persistent objects,
+ all <methodname>save_state</methodname> and <methodname>restore_state</methodname> methods of user objects must
+ call <methodname>super.save_state</methodname> and <methodname>super.restore_state</methodname>.
+ </para>
+
+ <section>
+ <title>Packing objects</title>
+ <para>
+ All of the basic types of Java (<type>int</type>, <type>long</type>, etc.) can be saved and restored from an
+ <classname>InputObjectState</classname> or <classname>OutputObjectState</classname>
+ instance by using the <methodname>pack</methodname> and <methodname>unpack</methodname> routines provided by
+ <classname>InputObjectState</classname> and <classname>OutputObjectState</classname>. However packing and
+ unpacking objects should be handled differently. This is because packing objects brings in the additional
+ problems of aliasing. Aliasing happens when two different object references may point at the same item. For
+ example:
+ </para>
+ <example>
+ <title>Aliasing</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/aliasing.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ Here, both <varname>s1</varname> and <varname>s2</varname> point at the same string. A naive implementation of
+ <methodname>save_state</methodname> might copy the string twice. From a <methodname>save_state</methodname>
+ perspective this is simply inefficient. However, <methodname>restore_state</methodname> would unpack the two
+ strings into different areas of memory, destroying the original aliasing information. The current version of
+ TxCore packs and unpacks separate object references.
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Direct use of StateManager</title>
+ <para>
+ The examples throughout this manual derive user classes from <classname>LockManager</classname>. These are two
+ important reasons for this.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Firstly, and most importantly, the serializability constraints of atomic actions require it.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It reduces the need for programmer intervention.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ However, if you only require access to TxCore's persistence and recovery mechanisms, direct derivation of a user
+ class from <classname>StateManager</classname> is possible.
+ </para>
+ <para>
+ Classes derived directly from <classname>StateManager</classname> must make use of its state management mechanisms
+ explicitly. These interactions are normally undertaken by <classname>LockManager</classname>. From a programmer's
+ point of view this amounts to making appropriate use of the operations <methodname>activate</methodname>,
+ <methodname>deactivate</methodname>, and <methodname>modified</methodname>, since
+ <classname>StateManager</classname>'s constructors are effectively identical to those of
+ <classname>LockManager</classname>.
+ </para>
+ <example>
+ <title><methodname>activate</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/StateManager_activate_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ Activate loads an object from the object store. The object’s UID must already have been set via the constructor
+ and the object must exist in the store. If the object is successfully read then restore_state is called to build
+ the object in memory. Activate is idempotent so that once an object has been activated further calls are
+ ignored. The parameter represents the root name of the object store to search for the object. A value of null
+ means use the default store.
+ </para>
+ </example>
+ <example>
+ <title><methodname>deactivate</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/StateManager_deactivate_method.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ The inverse of activate. First calls save_state to build the compacted image of the object which is then saved
+ in the object store. Objects are only saved if they have been modified since they were activated. The parameter
+ represents the root name of the object store into which the object should be saved. A value of null means use
+ the default store.
+ </para>
+ </example>
+ <example>
+ <title><methodname>modified</methodname></title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/StateManager_modified_method.java"
+ xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ Must be called prior to modifying the object in memory. If it is not called, the object will not be saved in the
+ object store by <methodname>deactivate</methodname>.
+ </para>
+ </example>
+ </section>
+</chapter>
View
507 ArjunaCore/docs/development_guide/en-US/Overview.xml
@@ -0,0 +1,507 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaCore_Development_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter>
+ <title>Overview</title>
+ <para>
+ A transaction is a unit of work that encapsulates multiple database actions such that that either all the
+ encapsulated actions fail or all succeed.
+ </para>
+ <para>
+ Transactions ensure data integrity when an application interacts with multiple datasources.
+ </para>
+ <para>
+ This chapter contains a description of the use of the TxCore transaction engine and the <application>Transactional
+ Objects for Java (TXOJ)</application> classes and facilities. The classes mentioned in this chapter are the key to
+ writing fault-tolerant applications using transactions. Thus, they are described and then applied in the
+ construction of a simple application. The classes to be described in this chapter can be found in the
+ <package>com.arjuna.ats.txoj</package> and <package>com.arjuna.ats.arjuna</package> packages.
+ </para>
+ <note>
+ <title>Stand-Alone Transaction Manager</title>
+ <para>
+ Although JBoss Transaction Service can be embedded in various containers, such as JBoss Application Server, it
+ remains a stand-alone transaction manager as well. There are no dependencies between the core JBoss Transaction
+ Service and any container implementations.
+ </para>
+ </note>
+
+ <section>
+ <title>TxCore</title>
+ <subtitle>The Transaction Engine</subtitle>
+ <para>
+ In keeping with the object-oriented view, the mechanisms needed to construct reliable distributed applications are
+ presented to programmers in an object-oriented manner. Some mechanisms need to be inherited, for example,
+ concurrency control and state management. Other mechanisms, such as object storage and transactions, are
+ implemented as TxCore objects that are created and manipulated like any other object.
+ </para>
+ <note>
+ <para>
+ When the manual talks about using persistence and concurrency control facilities it assumes that the
+ <application>Transactional Objects for Java (TXOJ)</application> classes are being used. If this is not the case
+ then the programmer is responsible for all of these issues.
+ </para>
+ </note>
+ <para>
+ TxCore exploits object-oriented techniques to present programmers with a toolkit of Java classes from which
+ application classes can inherit to obtain desired properties, such as persistence and concurrency control. These
+ classes form a hierarchy, part of which is shown in <xref linkend="txcore_class_hierarchy" /> and which will be
+ described later in this document.
+ </para>
+ <figure id="txcore_class_hierarchy">
+ <title>TxCore Class Hierarchy</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="440" fileref="images/txcore_class_hierarchy.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Apart from specifying the scopes of transactions, and setting appropriate locks within objects, the application
+ programmer does not have any other responsibilities: TxCore and <application>TXOJ</application> guarantee that
+ transactional objects will be registered with, and be driven by, the appropriate transactions, and crash recovery
+ mechanisms are invoked automatically in the event of failures.
+ </para>
+ </section>
+
+ <section>
+ <title>Saving object states</title>
+ <para>
+ TxCore needs to be able to remember the state of an object for several purposes.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>recovery</term>
+ <listitem>
+ <para>
+ The state represents some past state of the object.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>persistence</term>
+ <listitem>
+ <para>
+ The state represents the final state of an object at application termination.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Since these requirements have common functionality they are all implemented using the same mechanism: the classes
+ <classname>InputObjectState</classname> and <classname>OutputObjectState</classname>. The classes maintain an
+ internal array into which instances of the standard types can be contiguously packed or unpacked using appropriate
+ <methodname>pack</methodname> or <methodname>unpack</methodname> operations. This buffer is automatically resized
+ as required should it have insufficient space. The instances are all stored in the buffer in a standard form
+ called <firstterm>network byte order</firstterm>, making them machine independent. Any other
+ architecture-independent format, such as XDR or ASN.1, can be implemented simply by replacing the operations with
+ ones appropriate to the encoding required.
+ </para>
+ </section>
+
+ <section>
+ <title>The object store</title>
+ <para>
+ Implementations of persistence can be affected by restrictions imposed by the Java SecurityManager. Therefore, the
+ object store provided with TxCore is implemented using the techniques of interface and implementation. The current
+ distribution includes implementations which write object states to the local file system or database, and remote
+ implementations, where the interface uses a client stub (proxy) to remote services.
+ </para>
+ <para>
+ Persistent objects are assigned unique identifiers, which are instances of the <classname>Uid</classname> class,
+ when they are created. These identifiers are used to identify them within the object store. States are read using
+ the <methodname>read_committed</methodname> operation and written by the <methodname>write_committed</methodname>
+ and <methodname>write_uncommitted</methodname> operations.
+ </para>
+ </section>
+
+ <section>
+ <title>Recovery and persistence</title>
+ <para>
+ At the root of the class hierarchy is the class
+ <classname>StateManager</classname>. <classname>StateManager</classname> is responsible for object activation and
+ deactivation, as well as object recovery. Refer to <xref linkend="StateManager-signature" /> for the simplified
+ signature of the class.
+ </para>
+ <example id="StateManager-signature">
+ <title><classname>Statemanager</classname></title>
+ <programlisting language="Java" role="JAVA"> <xi:include href="extras/StateManager-signature.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ Objects are assumed to be of three possible flavors.
+ </para>
+ <variablelist>
+ <title>Three Flavors of Objects</title>
+ <varlistentry>
+ <term>Recoverable</term>
+ <listitem>
+ <para>
+ <classname>StateManager</classname> attempts to generate and maintain appropriate recovery information for
+ the object. Such objects have lifetimes that do not exceed the application program that creates them.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Recoverable and Persistent</term>
+ <listitem>
+ <para>
+ The lifetime of the object is assumed to be greater than that of the creating or accessing application, so
+ that in addition to maintaining recovery information, <classname>StateManager</classname> attempts to
+ automatically load or unload any existing persistent state for the object by calling the
+ <methodname>activate</methodname> or <methodname>deactivate</methodname> operation at appropriate times.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Neither Recoverable nor Persistent</term>
+ <listitem>
+ <para>
+ No recovery information is ever kept, nor is object activation or deactivation ever automatically attempted.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If an object is <phrase>recoverable</phrase> or <phrase>recoverable and persistent</phrase>, then
+ <classname>StateManager</classname> invokes the operations <methodname>save_state</methodname> while performing
+ <methodname>deactivate</methodname>, and <methodname>restore_state</methodname> while performing
+ <methodname>activate</methodname>,) at various points during the execution of the application. These operations
+ must be implemented by the programmer since <classname>StateManager</classname> cannot detect user-level state
+ changes. <!--(We are examining the automatic generation of default save_state and restore_state operations,
+ allowing the programmer to override this when application specific knowledge can be used to improve
+ efficiency.)-->This gives the programmer the ability to decide which parts of an object’s state should be made
+ persistent. For example, for a spreadsheet it may not be necessary to save all entries if some values can simply
+ be recomputed. The <methodname>save_state</methodname> implementation for a class <classname>Example</classname>
+ that has integer member variables called A, B and C might be implemented as in <xref linkend="example-save_state"
+ />.
+ </para>
+ <example id="example-save_state">
+ <title><methodname>save_state</methodname> Implementation</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/example-save_state.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <note>
+ <para>
+ it is necessary for all <methodname>save_state</methodname> and <methodname>restore_state</methodname> methods
+ to call <methodname>super.save_state</methodname> and <methodname>super.restore_state</methodname>. This is to
+ cater for improvements in the crash recovery mechanisms.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>The life cycle of a Transactional Object for Java</title>
+ <para>
+ A persistent object not in use is assumed to be held in a passive state, with its state residing in an object
+ store and activated on demand. The fundamental life cycle of a persistent object in TXOJ is shown in <xref
+ linkend="txoj-lifecycle" />.
+ </para>
+ <figure id="txoj-lifecycle">
+ <title>Life cycle of a persistent Object in TXOJ</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="440" fileref="images/txoj-lifecycle.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <orderedlist>
+ <listitem>
+ <para>
+ The object is initially passive, and is stored in the object store as an instance of the class
+ <classname>OutputObjectState</classname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When required by an application, the object is automatically activated by reading it from the store
+ using a <methodname>read_committed</methodname> operation and is then converted from an
+ <classname>InputObjectState</classname> instance into a fully-fledged object by the
+ <methodname>restore_state</methodname> operation of the object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When the application has finished with the object, it is deactivated by converting it back into an
+ <classname>OutputObjectState</classname> instance using the <methodname>save_state</methodname>
+ operation, and is then stored back into the object store as a shadow copy using
+ <methodname>write_uncommitted</methodname>. This shadow copy can be committed, overwriting the previous
+ version, using the <methodname>commit_state</methodname> operation. The existence of shadow copies is
+ normally hidden from the programmer by the transaction system. Object deactivation normally only occurs
+ when the top-level transaction within which the object was activated commits
+ </para>
+ </listitem>
+ </orderedlist>
+ </textobject>
+ </mediaobject>
+ </figure>
+ <note>
+ <para>
+ During its life time, a persistent object may be made active then passive many times.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>The concurrency controller</title>
+ <para>
+ The concurrency controller is implemented by the class <classname>LockManager</classname>, which provides sensible
+ default behavior while allowing the programmer to override it if deemed necessary by the particular semantics of
+ the class being programmed. As with <classname>StateManager</classname> and persistence, concurrency control
+ implementations are accessed through interfaces. As well as providing access to remote services, the current
+ implementations of concurrency control available to interfaces include:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>Local disk/database implementation</term>
+ <listitem>
+ <para>
+ Locks are made persistent by being written to the local file system or database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>A purely local implementation</term>
+ <listitem>
+ <para>
+ Locks are maintained within the memory of the virtual machine which created them. This implementation has
+ better performance than when writing locks to the local disk, but objects cannot be shared between virtual
+ machines. Importantly, it is a basic Java object with no requirements which can be affected by the
+ SecurityManager.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The primary programmer interface to the concurrency controller is via the <methodname>setlock</methodname>
+ operation. By default, the runtime system enforces strict two-phase locking following a multiple reader, single
+ writer policy on a per object basis. However, as shown in <xref linkend="txcore_class_hierarchy" />, by inheriting
+ from the <classname>Lock</classname> class, you can provide your own lock implementations with different lock
+ conflict rules to enable type specific concurrency control.
+ </para>
+ <para>
+ Lock acquisition is, of necessity, under programmer control, since just as <classname>StateManager</classname>
+ cannot determine if an operation modifies an object, <classname>LockManager</classname> cannot determine if an
+ operation requires a read or write lock. Lock release, however, is under control of the system and requires no
+ further intervention by the programmer. This ensures that the two-phase property can be correctly maintained.
+ </para>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/LockManager_class.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <para>
+ The <classname>LockManager</classname> class is primarily responsible for managing requests to set a lock on an
+ object or to release a lock as appropriate. However, since it is derived from <classname>StateManager</classname>,
+ it can also control when some of the inherited facilities are invoked. For example,
+ <classname>LockManager</classname> assumes that the setting of a write lock implies that the invoking operation
+ must be about to modify the object. This may in turn cause recovery information to be saved if the object is
+ recoverable. In a similar fashion, successful lock acquisition causes <methodname>activate</methodname> to be
+ invoked.
+ </para>
+ <para>
+ <xref linkend="Example_extends_LockManager" /> shows how to try to obtain a write lock on an object.
+ </para>
+ <example id="Example_extends_LockManager">
+ <title><classname>Example</classname> Class</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/Example_extends_LockManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>The transactional protocol engine</title>
+ <para>
+ The transaction protocol engine is represented by the <classname>AtomicAction</classname> class, which uses
+ <classname>StateManager</classname> to record sufficient information for crash recovery mechanisms to complete the
+ transaction in the event of failures. It has methods for starting and terminating the transaction, and, for those
+ situations where programmers need to implement their own resources, methods for registering them with the current
+ transaction. Because TxCore supports sub-transactions, if a transaction is begun within the scope of an already
+ executing transaction it will automatically be nested.
+ </para>
+ <para>
+ You can use TxCore with multi-threaded applications. Each thread within an application can share a transaction or
+ execute within its own transaction. Therefore, all TxCore classes are also thread-safe.
+ </para>
+ <example id="activation_termination_commitment">
+ <title>Relationships Between Activation, Termination, and Commitment</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/activation_termination_commitment.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>Creation of bindings to persistent objects</term>
+ <listitem>
+ <para>
+ This could involve the creation of stub objects and a call to remote objects. Here, we re-bind to an
+ existing persistent object identified by <systemitem>Name-A</systemitem>, and a new persistent object. A
+ naming system for remote objects maintains the mapping between object names and locations and is described
+ in a later chapter.<!--xref-->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Start of the atomic transaction</term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Operation invocations</term>
+ <listitem>
+ <para>
+ As a part of a given invocation, the object implementation is responsible to ensure that it is locked in
+ read or write mode, assuming no lock conflict, and initialized, if necessary, with the latest committed
+ state from the object store. The first time a lock is acquired on an object within a transaction the
+ object’s state is acquired, if possible, from the object store.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Commit of the top-level action</term>
+ <listitem>
+ <para>
+ This includes updating of the state of any modified objects in the object store.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Breaking of the previously created bindings</term>
+ <listitem>
+ <para>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </example>
+ </section>
+
+ <section>
+ <title>The class hierarchy</title>
+ <para>
+ The principal classes which make up the class hierarchy of TxCore are depicted below.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para><classname>StateManager</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para><classname>LockManager</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para>User-Defined Classes</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><classname>Lock</classname></para>
+ <itemizedlist>
+ <listitem>
+ <para>User-Defined Classes</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para><classname>AbstractRecord</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>RecoveryRecord</classname></para></listitem>
+ <listitem><para><classname>LockRecord</classname></para></listitem>
+ <listitem><para><classname>RecordList</classname></para></listitem>
+ <listitem><para>Other management record types</para></listitem>
+ </itemizedlist>
+ </listitem><!-- End AbstractRecord -->
+ </itemizedlist>
+ </listitem> <!-- End StateManager -->
+ <listitem>
+ <para><classname>AtomicAction</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>TopLevelTransaction</classname></para></listitem>
+ </itemizedlist>
+ </listitem> <!-- End AtomicAction -->
+ <listitem>
+ <para><classname>Input/OutputObjectBuffer</classname></para>
+ <itemizedlist>
+ <listitem><para><classname>Input/OutputObjectState</classname></para></listitem>
+ </itemizedlist>
+ </listitem><!-- End Input/OutputObjectBuffer -->
+ <listitem>
+ <para><classname>ObjectStore</classname></para>
+ </listitem><!-- End ObjectStore -->
+ </itemizedlist>
+
+ <!-- Keeping this around in case the other way is hard to read StateManager // Basic naming, persistence and
+ recovery control LockManager // Basic two-phase locking concurrency control service User-Defined Classes Lock
+ // Standard lock type for multiple readers/single writer User-Defined Lock Classes AbstractRecord // Important
+ utility class, similar to Resource RecoveryRecord // handles object recovery LockRecord // handles object
+ locking RecordList // Intentions list other management record types AtomicAction // Implements transaction
+ control abstraction TopLevelTransaction Input/OutputBuffer // Architecture neutral representation of an
+ objects’ state Input/OutputObjectState // Convenient interface to Buffer ObjectStore // Interface to the object
+ storage services-->
+ <para>
+ Programmers of fault-tolerant applications will be primarily concerned with the classes
+ <classname>LockManager</classname>, <classname>Lock</classname>, and <classname>AtomicAction</classname>. Other
+ classes important to a programmer are <classname>Uid</classname> and <classname>ObjectState</classname>.
+ </para>
+ <para>
+ Most TxCore classes are derived from the base class <classname>StateManager</classname>, which provides primitive
+ facilities necessary for managing persistent and recoverable objects. These facilities include support for the
+ activation and de-activation of objects, and state-based object recovery.
+ </para>
+ <para>
+ The class <classname>LockManager</classname> uses the facilities of <classname>StateManager</classname> and
+ <classname>Lock</classname> to provide the concurrency control required for implementing the serializability
+ property of atomic actions. The concurrency control consists of two-phase locking in the current implementation.
+ The implementation of atomic action facilities is supported by <classname>AtomicAction</classname> and
+ <classname>TopLevelTransaction</classname>.
+ </para>
+ <para>
+ Consider a simple example. Assume that <classname>Example</classname> is a user-defined persistent class suitably
+ derived from the <classname>LockManager</classname>. An application containing an atomic transaction
+ <systemitem>Trans</systemitem> accesses an object called <systemitem>O</systemitem> of type <type>Example</type>,
+ by invoking the operation <methodname>op1</methodname>, which involves state changes to
+ <systemitem>O</systemitem>. The serializability property requires that a write lock must be acquired on
+ <systemitem>O</systemitem> before it is modified. Therefore, the body of <methodname>op1</methodname> should
+ contain a call to the <methodname>setlock</methodname> operation of the concurrency controller.
+ </para>
+ <example id="simple_concurrency_control">
+ <title>Simple Concurrency Control</title>
+ <programlisting language="Java" role="JAVA"><xi:include href="extras/simple_concurrency_control.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <procedure>
+ <title>Steps followed by the operation <methodname>setlock</methodname></title>
+ <para>
+ The operation <methodname>setlock</methodname>, provided by the <classname>LockManager</classname> class,
+ performs the following functions in <xref linkend="simple_concurrency_control" />.
+ </para>
+ <step>
+ <para>Check write lock compatibility with the currently held locks, and if allowed, continue.</para>
+ </step>
+ <step>
+ <para>
+ Call the StateManager operation <methodname>activate</methodname>.<methodname>activate</methodname> will load,
+ if not done already, the latest persistent state of <classname>O</classname> from the object store, then call
+ the <classname>StateManager</classname> operation <methodname>modified</methodname>, which has the effect of
+ creating an instance of either <classname>RecoveryRecord</classname> or
+ <classname>PersistenceRecord</classname> for <classname>O</classname>, depending upon whether
+ <classname>O</classname> was persistent or not. The Lock is a WRITE lock so the old state of the object must
+ be retained prior to modification. The record is then inserted into the RecordList of Trans.
+ </para>
+ </step>
+ <step>
+ <para>
+ Create and insert a <classname>LockRecord</classname> instance in the <classname>RecordList</classname> of
+ <systemitem>Trans</systemitem>.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ Now suppose that action <systemitem>Trans</systemitem> is aborted sometime after the lock has been acquired. Then
+ the <methodname>rollback</methodname> operation of <classname>AtomicAction</classname> will process the
+ <classname>RecordList</classname> instance associated with <systemitem>Trans</systemitem> by invoking an
+ appropriate <methodname>Abort</methodname> operation on the various records. The implementation of this operation
+ by the <classname>LockRecord</classname> class will release the WRITE lock while that of
+ <classname>RecoveryRecord</classname> or <classname>PersistenceRecord</classname> will restore the prior state of
+ <classname>O</classname>.
+ </para>
+ <para>
+ It is important to realize that all of the above work is automatically being performed by TxCore on behalf of the
+ application programmer. The programmer need only start the transaction and set an appropriate lock; TxCore and
+ <application>TXOJ</application> take care of participant registration, persistence, concurrency control and
+ recovery.
+ </para>
+ </section>
+</chapter>
+