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:
