title: How to properly use JTA resource recovery method?
body: <p>I'm trying to understand how to properly invoke <code>javax.transaction.xa.XAResource.recovery(int)</code> method. I'm dealing with an environment where I manually invoke XA operations, and do not have a container resource manager.</p>
  
  <p>JavaDocs simply say that there are possible flags values of <code>TMSTARTRSCAN</code>, <code>TMENDRSCAN</code> and <code>TMNOFLAGS</code>, but don't provide an explanation on what happens when any of those flags or combination thereof is used.</p>
  
  <p>I've combed Glassfish code for what they might be doing with the flag values, but didn't find anything helpful there. I've looked at Artemis - it will return all incomplete transactions only when a lone <code>TMSTARTRSCAN</code> flag is used. Postgres JDBC is almost the same, except it <code>TMSTARTRSCAN</code> can be coupled with <code>TMENDRSCAN</code>, everything is returned in one call as well.</p>
  
  <p>I assume that the reason the flags are there is to provide some sort of pagination to the results, in case there are too many unfinished transactions laying around. So, the right way to deal with this would be:</p>
  
  <ul>
  <li>call <code>recover()</code> with <code>TMSTARTRSCAN</code></li>
  <li>call <code>recover()</code> with <code>TMNOFLAGS</code> until resulting array is empty</li>
  <li>call <code>recover()</code> with <code>TMENDRSCAN</code></li>
  </ul>
  
  <p>For all of the above calls, be prepared to handle returned XID values.</p>
  
  <p>But I would love to be pointed to or given an explanation on how this was intended to function.</p>
  
  <p><strong>UPDATE</strong></p>
  
  <p>As @kayaman gracefully pointed me to the XA specification from X/Open, I can see that my assumption was probably correct. The standard explains the intended behavior a lot more clearly, but it doesn't apply one to one to Java implementation, due to difference in array size expectations. The standard explains when to not call <code>recover(TMENDRSCAN)</code>, but that's not clear in case of Java, and it's not clear whether calling it incorrectly may cause an exception.</p>