[jbossts-issues] [JBoss JIRA] (JBTM-758) Errors in documentation: Transaction Core Programmers Guide

[Michael Musgrove (JIRA)]

     [ https://issues.jboss.org/browse/JBTM-758?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Michael Musgrove resolved JBTM-758.
-----------------------------------

    Resolution: Done


page 31: fixed in trunk (Using_TxCore.xml)
page 36: fix is in extras/LastResourceRecord.java
page 64: the reference is fixed in trunk with the text: "The platform Development Guide addresses some of these issues" (Constructing_A_Transactional_Objects_For_Java_Application.xml)
page 69: replace the reference with ObjectStoreAPI which is an interface (Appendix_Object_Store_Implementations.xml)

The example finalization code should be calling super.finalize(). Fixes are in Array_class.java, example_queue_class.java and example_queue_destructor.java

I have replaced various occurences of destructor with finalizer to more accurately reflect the meaning.

We do say on page 32 that the finalizer must invoke terminate.

Finally, we don't call terminate in the finalizer of LockManager to allow maximal control over the lifecycle of persistent objects and to avoid breaking any code out there that are using LockManager.

                
> Errors in documentation: Transaction Core Programmers Guide
> -----------------------------------------------------------
>
>                 Key: JBTM-758
>                 URL: https://issues.jboss.org/browse/JBTM-758
>             Project: JBoss Transaction Manager
>          Issue Type: Bug
>      Security Level: Public(Everyone can see) 
>          Components: Documentation
>    Affects Versions: 4.11.0
>            Reporter: Mauro Molinari
>            Assignee: Michael Musgrove
>            Priority: Minor
>             Fix For: 5.0.0.Final
>
>
> I'm going to highlight some errors I found during the reading of the Transaction Core Programmers Guide (TX-PG-5/11/10):
> - page 31: when describing LogManager: "The *shared* parameter only has meaning if *ot* is RECOVERABLE"; actually the two parameters are named *objectModel* and *ObjectType* respectively in the caption of the paragraph
> - page 36: in the example, I think the line with "A.add(new ShutdownRecord(...)" is not pertinent
> - page 64: the last sentence says that the issues described in that paragraph will be addressed in the next section, but the next section is about configuration
> - page 65: the second paragraph has some typographic problem (<module>propertyManager, <name>EnvironmentBean)
> - page 69: in the second paragraph: "All of the implementations are derived from the ObjectStore interface"; actually, ObjectStore is a class to extend, not an interface to implement
> Lastly, an observation about the depiction of finalizers as "destructors": in this guide, the finalize method is considered a destructor. However, in Java it is not actually. Anyway, it's not clear if calling terminate() in the finalize() is mandatory or not. If so, why isn't it called directly in com.arjuna.ats.arjuna.StateManager.finalize()? If not, I have another doubt. In all the examples of user classes (i.e. page 60) the finalize() is implemented as:
> public void finalize()
> {
>   super.terminate();
> }
> However, super.finalize() is not called. Isn't it risky? I mean, in this way the code in com.arjuna.ats.arjuna.StateManager.finalize() is never called... I think the documentation should be more clear on this subject.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.jboss.org/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira