Clarify requirements for XAResourceProducer unique name

[klr8]

Each XAResourceProducer needs to have a unique name that is used by the ResourceRegistrar to keep track of the resource. The JavaDoc of XAResourceProducer simply says:

Get the resource name as registered in the transactions journal.

The JavaDoc of ResourceBean additionally states:

Specify the resource unique name to be used to identify this resource during recovery. This name will be registered in the transactions journal so once assigned it must never be changed.

What exactly does this mean?

• How unique does the name need to be? Does it only need to be unique per ResourceRegistrar? Or unique across the whole system, for instance when running in a cluster?
• What does "must never be changed" mean? No changes while the transaction manager is up-and-running? Or no changes ever? For instance, image a resource is named X the first time an application starts up. Is it okay for that same resource to be named Y after a later restart of the application where of course the transaction manager is using the same journal files?

[klr8]

Having looked at the source code a bit more I indeed see that for instance the Recoverer class looks up a resource using the unique name that it gets from the journal (TransactionLogRecord / DanglingTransaction).

If I understand things correctly, this implies:

• The names need to be unique 'per journal'. If each server in a cluster maintains its own journal, its acceptable that the same resource (i.e. the database) has a different unique name on each server, but this is not required, and I would say not even advised.
• As long as you're using the same journal files, the unique names must not be changed, not even inbetween transaction manager restarts. Otherwise, resource recovered will be impossible.

[lorban]

Both your statements are correct. For completeness sake I would also add that the configured serverId must also stay unchanged "for eternity".

Fortunately, BTM is reasonably lenient in case you changed one of those names by mistake. As long as you did not use resource A's name for an unrelated B resource -in which case the recoverer would try to reapply totally unrelated transactions and would log heuristic errors- once you restore the names to their original value, the recoverer will manage to resume everything as it should, thanks to its ability to perform incremental recovery. I wouldn't advise to rely on that, though.

If you feel the need to rename anything, just make sure to exit properly so that no resource has any in-doubt transaction, then simply delete the existing journal fragments.

[klr8]

Thanks for confirming that!