Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jta-dev] What is the specified behavior of enlistResource when called with the same payload twice?

On Sat, 12 Nov 2022 at 23:10, Laird Nelson <ljnelson@xxxxxxxxx> wrote:
On Fri, Nov 11, 2022 at 2:57 AM Michael Musgrove <mmusgrov@xxxxxxxxxx> wrote:
The section on "Resource Enlistment" [1] in the JTA specification also implies that your second assertion will succeed.

Well, not really—I mean, I understand that once a resource is enlisted, it's enlisted. But I'm asking about the very specific semantics of the boolean return value of enlistResource, not about resource enlistment in general.  For example—simply reading the documentation of the enlistResource method, ("Returns: true if the resource was enlisted successfully; otherwise false")—does a boolean value of true returned from enlistResource mean that this very invocation was the one to cause enlistment to happen, or does it mean that this invocation or possibly another earlier invocation on this thread caused enlistment to happen (viz. what you claim the specification "implies")? And under what circumstances may false be returned, given that all error conditions seem to be handled by exceptions?

Many other Java methods that alter state and that return a boolean value conventionally indicate in so doing whether the invocation itself had any effect (see, for example, Collection#add(Object) as an arbitrary example); this one I guess does not for some reason that is good, historical or both.

Anyway, I'm not making a huge point: it's just that I find the method as documented to be underspecified.  It seems like such a simple thing to amend the method documentation to say exactly what an implementation must do, and under what circumstances.  If I knew what these requirements were, I'd be happy to submit a pull request or whatever we do in this space nowadays to fix things.

For example, naïvely in a vacuum I would change it to:

"Returns: true if the supplied XAResource was enlisted successfully as a result of this invocation; otherwise false"

…but despite there being no language in the specification document about enlistResource's return value it seems like you're suggesting the general interpretation is rather:

"Returns: true if the supplied XAResource has ever been enlisted successfully [on this thread?]; otherwise false"

I think the best fit of the current status is the latter one. The specification needs to be read in conjunction with the API docs and that includes "if the resource was enlisted successfully" which does not preclude it being a previous call.

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?

…but I don't know, so I don't know which to propose.

Your observations about how the Narayana project implements the specification are interesting, we could continue that over on the narayana-users forum if you wish.

Sure.  Thanks for the discussion so far.

jta-dev mailing list
To unsubscribe from this list, visit

Back to the top