com.atomikos.datasource
Interface RecoverableResource

All Known Subinterfaces:

TransactionalResource

All Known Implementing Classes:

AcceptAllXATransactionalResource, JcaTransactionalResource, JdbcTransactionalResource, JmsTransactionalResource, TemporaryXATransactionalResource, XATransactionalResource

public interface RecoverableResource

A Recoverable Resource is the abstraction of a resource that supports recoverable work (i.e., that supports Participant instances). Its primary use is for Participant instances that are not self-containing, as for instance in XA transactions (where the Participant can not contain the entire transaction context of the server, but only an external reference to it in the form of an Xid instance). A recoverable resource is invoked at recovery time by its own Participant instances (typically in the readExternal method), who iteratively ask each resource in the com.atomikos.icatch.Configuration whether or not they can be recovered by them. At the end of recovery, the TM will invoke the endRecovery method, to indicate to the resource that whatever private logs it has, any remaining and non-recovered participants should be aborted.

Method Summary

void	close() Close the resource for shutdown.
void	endRecovery() Notify the resource that recovery is ended.
String	getName() Get the name of the resource.
boolean	isClosed() Test if the resource is closed.
boolean	isSameRM(RecoverableResource res) Test if a resource is the same as another one.
boolean	recover(Participant participant) Recover the partially reconstructed Participant.
void	setRecoveryService(RecoveryService recoveryService) Initialize this resource with the recovery service.

Method Detail

setRecoveryService

void setRecoveryService(RecoveryService recoveryService)
                        throws ResourceException

Initialize this resource with the recovery service. This method is called by the transaction service during intialization of the transaction service or when the resource is added, whichever comes last. If the resource wants to recover, it should subsequently ask the recoveryService to do so.

Parameters:

recoveryService - The recovery service. This instance can be used by the resource to ask recovery from the transaction engine.

Throws:

ResourceException - On errors.

recover

boolean recover(Participant participant)
                throws ResourceException

Recover the partially reconstructed Participant.

Parameters:

participant - A partially recovered Participant.

Returns:

boolean True iff reconstruction was successful. If the resource is not responsible for the given participant, then this will return false. A Participant can use this to iterate over all resources in order to eventually recover itself. This is particularly useful if the Participant instance can not serialize its full state, because some of it is on its backside resource (as, for instance, in XA). This way, the TransactionalResource can be used to assist in reconstruction of the Participant's state.

Throws:

ResourceException - On failure.

endRecovery

void endRecovery()
                 throws ResourceException

Notify the resource that recovery is ended. Called by TM at end of recovery; any remaining resourcetransactions (i.e., that have not been associated with any recover call) should be rolled back. This is because if the were not recovered by the TM, then surely they are not supposed to be indoubt (the TM recovers ALL indoubt work!) and should be rolled back.

Throws:

ResourceException - On failure.

close

void close()
           throws ResourceException

Close the resource for shutdown. This notifies the resource that it is no longer needed.

Throws:

ResourceException

getName

String getName()

Get the name of the resource. Names should be unique within one TM domain.

Returns:

String The name.

isSameRM

boolean isSameRM(RecoverableResource res)
                 throws ResourceException

Test if a resource is the same as another one.

Throws:

ResourceException

isClosed

boolean isClosed()

Test if the resource is closed.

Returns:

boolean True if the resource is closed.