bitronix.tm.journal

Class TransactionLogRecord

java.lang.Object

bitronix.tm.journal.TransactionLogRecord

All Implemented Interfaces:

JournalRecord

public class TransactionLogRecord
extends Object
implements JournalRecord

Representation of a transaction log record on disk.

On-disk format has been implemented following Mike Spille's recommendations. Quoting him:

[RECORD_TYPE :4] [RECORD_LEN :4] [HEADER_LEN :4] [System.currentTimeMillis :8] [Sequence number :4] [Checksum :4] [Payload :X] [END_RECORD_INDICATOR :4]

Where [RECORD_TYPE] is a passed-in record type from the TM. [RECORD_LEN] is the overall record length (sans [RECORD_TYPE and [RECORD_LEN]). [HEADER_LEN] is the length of the remainder of the header - important if you want to support easy upgrades of your format. The remaining pieces are the rest of the header, and the payload. The header at least should have [System.currentTimeMillis] and [Sequence number], with the [sequence number] coming from some monotically increasing sequence generator unique to the process. The [checksum] is optional for the paranoid among us. The time information can be very useful for profiling and tracking down problems in production, and in conjunction with the sequence number it can give you precise ordering. This doesn't give you much in this solution, but can be priceless if you ever move to a system with multiple dual log file pairs to lessen single-threading on a single log file pair. Finally, I like having an [END_RECORD_INDICATOR] as an extra corruption detector device - I'm a suspenders and belt kind of guy. Actually, the END_RECORD_INDICATOR and [RECORD_LEN] in conjunction are very useful in development, as well, to catch programming mistakes in the log system early.

Payload contains [GTRID LENGTH :1] [GTRID :A] [UNIQUE NAMES COUNT :4] ([UNIQUE NAME LENGTH :2] [UNIQUE NAME :Y] ...) which makes a major difference with Mike's proposed format because here a record can vary in length: the GTRID size is A bytes long (A being the GTRID length) and there can be X unique names that are Y characters long, Y being eventually different for each name.

Author:

Ludovic Orban

See Also:

XA Exposed, Part III: The Implementor's Notebook

Constructor Summary

Constructors

Constructor and Description
TransactionLogRecord(int status, int recordLength, int headerLength, long time, int sequenceNumber, int crc32, Uid gtrid, Set<String> uniqueNames, int endRecord) Use this constructor when restoring a log from the disk.
TransactionLogRecord(int status, Uid gtrid, Set<String> uniqueNames) Create a new transaction log ready to be stored.

Method Summary

Modifier and Type	Method and Description
int	calculateCrc32() Calculate the CRC32 value of this record.
int	getCrc32()
int	getEndRecord()
Uid	getGtrid() Returns the global transaction id, identifying the transaction this record belongs to.
int	getHeaderLength()
int	getRecordLength()
Map<String,?>	getRecordProperties() Returns a map of additional properties that provide access to implementation specific record details.
int	getSequenceNumber()
int	getStatus() Returns the current status of the transaction that this record belongs to.
long	getTime() Returns the time when this record was created.
Set<String>	getUniqueNames() Returns an unmodifiable set of the unique names identifying the components that are part of this transaction.
long	getWritePosition()
boolean	isCrc32Correct() Recalculate the CRC32 value of this record (using calculateCrc32()) and compare it with the stored value.
boolean	isValid() Returns true if the record could not only be loaded but does also pass internal checksum verifications.
void	setWritePosition(long position)
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactionLogRecord

public TransactionLogRecord(int status,
                            int recordLength,
                            int headerLength,
                            long time,
                            int sequenceNumber,
                            int crc32,
                            Uid gtrid,
                            Set<String> uniqueNames,
                            int endRecord)

Use this constructor when restoring a log from the disk.

Parameters:

status - record type

recordLength - record length excluding status and recordLength

headerLength - length of all fields except gtrid, uniqueNames and endRecord

time - current time in milliseconds

sequenceNumber - atomically generated sequence number during a JVM's lifespan

crc32 - checksum of the full record

gtrid - global transaction id

uniqueNames - unique names of XA data sources used in this transaction

endRecord - end of record marker

TransactionLogRecord

public TransactionLogRecord(int status,
                            Uid gtrid,
                            Set<String> uniqueNames)

Create a new transaction log ready to be stored.

Parameters:

status - record type

gtrid - global transaction id

uniqueNames - unique names of XA data sources used in this transaction

Method Detail

getStatus

public int getStatus()

Description copied from interface: JournalRecord

Returns the current status of the transaction that this record belongs to.

Specified by:

getStatus in interface JournalRecord

Returns:

the current status of the transaction that this record belongs to.

getRecordLength

public int getRecordLength()

getHeaderLength

public int getHeaderLength()

getTime

public long getTime()

Description copied from interface: JournalRecord

Returns the time when this record was created.

Specified by:

getTime in interface JournalRecord

Returns:

the time when this record was created.

getSequenceNumber

public int getSequenceNumber()

getCrc32

public int getCrc32()

getGtrid

public Uid getGtrid()

Description copied from interface: JournalRecord

Returns the global transaction id, identifying the transaction this record belongs to.

Specified by:

getGtrid in interface JournalRecord

Returns:

the global transaction id, identifying the transaction this record belongs to.

getWritePosition

public long getWritePosition()

setWritePosition

public void setWritePosition(long position)

getUniqueNames

public Set<String> getUniqueNames()

Description copied from interface: JournalRecord

Returns an unmodifiable set of the unique names identifying the components that are part of this transaction.

Specified by:

getUniqueNames in interface JournalRecord

Returns:

an unmodifiable set of the unique names identifying the components that are part of this transaction.

getEndRecord

public int getEndRecord()

isCrc32Correct

public boolean isCrc32Correct()

Recalculate the CRC32 value of this record (using calculateCrc32()) and compare it with the stored value.

Returns:

true if the recalculated value equals the stored one, false otherwise.

isValid

public boolean isValid()

Returns true if the record could not only be loaded but does also pass internal checksum verifications.

Specified by:

isValid in interface JournalRecord

Returns:

true if the record could not only be loaded but does also pass internal checksum verifications.

getRecordProperties

public Map<String,?> getRecordProperties()

Returns a map of additional properties that provide access to implementation specific record details.

Specified by:

getRecordProperties in interface JournalRecord

Returns:

a map of additional properties that provide access to implementation specific record details.

calculateCrc32

public int calculateCrc32()

Calculate the CRC32 value of this record.

Returns:

the CRC32 value of this record.

toString

public String toString()

Overrides:

toString in class Object