In terms of the alternative, you said "all error conditions seem to be handled by exceptions" that would imply that any situation with failing to register the resource (the first time) can be considered an "unexpected error condition" but if unable to enlist the resource when XAResource.start is called (during Jakarta Transactions 3.3.1) and XA_RETRY error code is returned is that something to consider an error?
All I'm trying to do is understand the javadocs of enlistResource. If it returns false, what must I do? Or what must I not do? Will it ever return true again? Or what must I expect about the state of the system? Shouldn't the javadocs tell me? If there are other documents (like the specification document or various other related documents) that do tell me, that I must read to fill in the missing instructions, where are the links to them from the javadocs?
You've been very helpful in helping me understand how this specification and API were put together and how to fill in the gaps; thank you.
Best,
Laird