org.neo4j.kernel.impl.transaction.xaframework
Class XaCommand

java.lang.Object
  org.neo4j.kernel.impl.transaction.xaframework.XaCommand

Direct Known Subclasses:

Command, IndexCommand, IndexDefineCommand

public abstract class XaCommand
extends Object

A command is part of the work done during a transaction towards a XA resource. Any modifying operation invoked on a XaResource must be in a transaction and wrapped in a XaCommand. Each command created will be written to the XaLogicalLog once it is added to the transaction.

Commands are memory buckets containing information on how to presist the operation in the XA resource. Any nececcery constraint checks must take place before any command has been executed. Once a command in the transaction has started to execute there is no turning back, all of the following commands must execute without problems. To ensure this check the constraints via a tx synchronization hook, at prepare or upon command creation and signal the transaction before it starts to commit if something is wrong.

Throwing exception when the command rollbacks or executes could (depending on TransactionManager implementation) bring down the whole system. Should however a execute or rollback call fail throw a proper runtime exception.

Note that a command is during normal execution only executed once but it must be able to execute again "re-writing" it self to underlying persistance store during recovery. Think of the following scenario:

A transaction containing 50 commands begins to commit. When 24.5 commands have been executed the system crashes. System is brought up again and the transaction is recreated. The transaction manager tells the resource to commit (again) and the 25 first commands will be executed for a second time while the 25 last commands will be executed for the first time. Also it would be possible for the system to crash during recovery causing commands to execute again and again and so on.

Constructor Summary

XaCommand()

Method Summary

abstract void	execute() Executes the command and makes it persistent.
boolean	isRecovered() Returns wether or not this is a "recovered command".
void	rollback() Default implementation of rollback that does nothing.
protected void	setRecovered() If this command is created by the command factory during a recovery scan of the logical log this method will be called to mark the command as a "recovered command".
abstract void	writeToFile(LogBuffer buffer) When a command is added to a transaction (usually when it is created) it must be written to the XaLogicalLog.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XaCommand

public XaCommand()

Method Detail

rollback

public void rollback()

Default implementation of rollback that does nothing. This method is not to undo any work done by the execute() method. Commands in a XaTransaction are either all rolled back or all executed, they're not linked together as usual execute/rollback methods.

Since a command only is in memory nothing has been made persistent so rollback usually don't have to do anything. Sometimes however a command needs to acquire resources when created (since the application thinks it has done the work when the command is created). For example, if a command creates some entity that has a primary id we need to generate that id upon command creation. But if the command is rolled back we should release that id. This is the place to do just that.

execute

public abstract void execute()

Executes the command and makes it persistent. This method must succeed, any protests about this command not being able to execute should be done before execution of any command within the transaction.

writeToFile

public abstract void writeToFile(LogBuffer buffer)
                          throws IOException

When a command is added to a transaction (usually when it is created) it must be written to the XaLogicalLog. This method should write all the data that is needed to re-create the command (see XaCommandFactory).

Write the data to the fileChannel, you can use the buffer supplied or create your own buffer since its capacity is very small (137 bytes or something). Acccess to writing commands is synchronized, only one command will be written at a time so if you need to write larger data sets the commands can share the same buffer.

Don't throw an IOException to imply something is wrong with the command. An exception should only be thrown here if there is a real IO failure. If something is wrong with this command it should have been detected when it was created.

Don't force, position or anything except normal forward write with the file channel.

Parameters:

fileChannel - The channel to the XaLogicalLog

buffer - A small byte buffer that can be used to write command data

Throws:

IOException - In case of *real* IO failure

setRecovered

protected void setRecovered()

If this command is created by the command factory during a recovery scan of the logical log this method will be called to mark the command as a "recovered command".

isRecovered

public boolean isRecovered()

Returns wether or not this is a "recovered command".

Returns:

true if command was created during a recovery else false is returned