Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.store.replication.slave.ReplicationLogScan

Scan a chunk of log received from the master. The log chunk (byte[] logToScan) is assumed to always contain (an unknown) number of complete log records. If the last log record is incomplete, something is wrong. This will raise a StandardException, and will probably mean that replication has to be aborted. That decision is not made here, though.

When a new chunk of log records is to be scanned, ReplicationLogScan is initialized by calling init(...). Every time next() is called after that, ReplicationLogScan reads a new log record from logToScan. If next() returns true, the next log record was successfully read. The information in this last read log record either indicates that a log file switch has taken place on the master (isLogSwitch() = true) or it is a normal log record which information can be retrieved by using the get-methods (if isLogRecord() = true).

Threads: The class does not provide thread synchronization since it is assumed that only one thread will be receiving and applying log per replicated database when in slave mode. Since a ReplicationLogScan object belongs to only one slave database, this means that only one thread will access the object.

The format of the log chunk byte[] is defined in org.apache.derby.impl.store.raw.log.LogAccessFile

Field Summary

Modifier and Type	Field and Description
private byte[]	currentData
private int	currentDataOffset
private long	currentInstant
private int	currentPosition
private boolean	hasInfo hasInfo = true when the scan will return meaningful information, either in the form of a log record (in which case the above variables will be set), or when it has found a log record indicating that a log file switch has taken place on the master (isLogSwitch = true).
private boolean	isLogSwitch true if the last read log record indicates a log switch, false if it is a normal log record private boolean isLogSwitch;
private byte[]	logToScan

Constructor Summary

Access	Constructor and Description
protected	ReplicationLogScan()

Method Summary

Modifier and Type	Method and Description
protected byte[]	Returns: The byte[] containing data+optional_data of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. getData() Method to get the data byte[] read by the last call to next().
protected int	Returns: The number of bytes in the byte[] returned by getData() for the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. getDataLength()
protected long	Returns: The instant of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. getInstant()
protected boolean	Returns: true if next() has been called and the end of the log chunk has not yet been reached. Returns the same answer as the last call to next() did. Use isLogFileSwitch() and isLogRecord() to find out if the current log record indicates a log file switch or is a normal log record. hasValidInformation() Used to determine whether or not the last call to next() was successful.
protected void	init(byte[] A chunk of log records received from the master logToScan) Set all variables to default values, and makes logToScan the byte[] that will be scanned for log records.
protected boolean	Returns: true if the last call to next() found a log record indicating a log file switch has taken place on the master. isLogFileSwitch() Used to determine whether the last call to next() found a log file switch
protected boolean	Returns: true if the last call to next() found a normal log record. isLogRecord() Used to determine whether the last call to next() read a log record
protected boolean	Returns: true if a log record was successfully read, false if end of logToScan has been reached. next() Read the next log record in logToScan.
private void	retrieveBytes(byte[] The byte[] copied to readInto, int The number of bytes copied from logToScan to readInto length) Copy length number of bytes from logToScan into readInto.
private int	Returns: an int read from logToScan retrieveInt() Read an int from logToScan.
private long	Returns: a long read from logToScan retrieveLong() Read a long from logToScan.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

currentData	back to summary
private byte[] currentData

currentDataOffset	back to summary
private int currentDataOffset

currentInstant	back to summary
private long currentInstant

currentPosition	back to summary
private int currentPosition

hasInfo	back to summary
private boolean hasInfo hasInfo = true when the scan will return meaningful information, either in the form of a log record (in which case the above variables will be set), or when it has found a log record indicating that a log file switch has taken place on the master (isLogSwitch = true). hasInfo = false before next() is called for the first time, after next() has reached the end of logToScan and if an error occured when parsing logToScan (i.e. when next() has thrown a StandardException)

hasInfo

back to summary

private boolean hasInfo

hasInfo = true when the scan will return meaningful information, either in the form of a log record (in which case the above variables will be set), or when it has found a log record indicating that a log file switch has taken place on the master (isLogSwitch = true). hasInfo = false before next() is called for the first time, after next() has reached the end of logToScan and if an error occured when parsing logToScan (i.e. when next() has thrown a StandardException)

isLogSwitch	back to summary
private boolean isLogSwitch true if the last read log record indicates a log switch, false if it is a normal log record private boolean isLogSwitch;

logToScan	back to summary
private byte[] logToScan

Constructor Detail

ReplicationLogScan	back to summary
protected ReplicationLogScan()

Method Detail

getData	back to summary
protected byte[] getData() throws NoSuchElementException Method to get the data byte[] read by the last call to next(). Note that this byte[] contains both byte[] data and byte[] optional_data from LogAccessFile. To split this byte[] into data and optional_data, we would need to create a Loggable object from it because the log does not provide information on where to split. There is no need to split since this byte[] will only be written to the slave log anyway. If it was split, LogAccessFile would simply merge them when writing to file. Returns:byte[] The byte[] containing data+optional_data of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. Exceptions NoSuchElementException: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

getData

back to summary

protected byte[] getData() throws NoSuchElementException

Method to get the data byte[] read by the last call to next(). Note that this byte[] contains both byte[] data and byte[] optional_data from LogAccessFile. To split this byte[] into data and optional_data, we would need to create a Loggable object from it because the log does not provide information on where to split. There is no need to split since this byte[] will only be written to the slave log anyway. If it was split, LogAccessFile would simply merge them when writing to file.

Returns:byte[]

The byte[] containing data+optional_data of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true.

Exceptions

NoSuchElementException:: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

getDataLength	back to summary
protected int getDataLength() throws NoSuchElementException Returns:int The number of bytes in the byte[] returned by getData() for the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. Exceptions NoSuchElementException: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

getDataLength

back to summary

protected int getDataLength() throws NoSuchElementException

Returns:int

The number of bytes in the byte[] returned by getData() for the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true.

Exceptions

NoSuchElementException:: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

getInstant	back to summary
protected long getInstant() throws NoSuchElementException Returns:long The instant of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true. Exceptions NoSuchElementException: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

getInstant

back to summary

protected long getInstant() throws NoSuchElementException

Returns:long

The instant of the log record read by the last call to next(). Only returns meaningful information if isLogRecord() returns true.

Exceptions

NoSuchElementException:: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

hasValidInformation	back to summary
protected boolean hasValidInformation() Used to determine whether or not the last call to next() was successful. Returns:boolean true if next() has been called and the end of the log chunk has not yet been reached. Returns the same answer as the last call to next() did. Use isLogFileSwitch() and isLogRecord() to find out if the current log record indicates a log file switch or is a normal log record.

hasValidInformation

back to summary

protected boolean hasValidInformation()

Used to determine whether or not the last call to next() was successful.

Returns:boolean: true if next() has been called and the end of the log chunk has not yet been reached. Returns the same answer as the last call to next() did. Use isLogFileSwitch() and isLogRecord() to find out if the current log record indicates a log file switch or is a normal log record.

init	back to summary
protected void init(byte[] logToScan) Set all variables to default values, and makes logToScan the byte[] that will be scanned for log records. Parameters logToScan:byte[] A chunk of log records received from the master

init

back to summary

protected void init(byte[] logToScan)

Set all variables to default values, and makes logToScan the byte[] that will be scanned for log records.

Parameters

logToScan:byte[]: A chunk of log records received from the master

isLogFileSwitch	back to summary
protected boolean isLogFileSwitch() throws NoSuchElementException Used to determine whether the last call to next() found a log file switch Returns:boolean true if the last call to next() found a log record indicating a log file switch has taken place on the master. Exceptions NoSuchElementException: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

isLogFileSwitch

back to summary

protected boolean isLogFileSwitch() throws NoSuchElementException

Used to determine whether the last call to next() found a log file switch

Returns:boolean

true if the last call to next() found a log record indicating a log file switch has taken place on the master.

Exceptions

NoSuchElementException:: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

isLogRecord	back to summary
protected boolean isLogRecord() throws NoSuchElementException Used to determine whether the last call to next() read a log record Returns:boolean true if the last call to next() found a normal log record. Exceptions NoSuchElementException: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

isLogRecord

back to summary

protected boolean isLogRecord() throws NoSuchElementException

Used to determine whether the last call to next() read a log record

Returns:boolean

true if the last call to next() found a normal log record.

Exceptions

NoSuchElementException:: if next() has not been called or if there are no more log records in this chunk of log. Should never be thrown unless ReplicationLogScan is used in a wrong way.

next	back to summary
protected boolean next() throws StandardException Read the next log record in logToScan. The information in this log record can be read by using the getXXX methods. Side effects: On a successful read (return true): either... ... the scan read a log record indicating that a log file switch has taken place on the master, in which case isLogFileSwitch() returns true. In this case, getXXX will not contain valid data. Asserts handle calls to these methods when in sane mode. currentPosition is updated to point to the byte immediately following this log file switch log record. ... or the scan read a normal log record, in which case isLogRecord() returns true. Also sets currentInstant and currentData, and updates currentPosition to point to the byte immediatly following the log record. In this case, getXXX will return meaningful information about the log record. If there are no more log records in logToScan (returns false) or a problem occurs (throws StandardException): setting hasInfo = false Returns:boolean true if a log record was successfully read, false if end of logToScan has been reached. Exceptions StandardException: if logToScan is found to be corrupted.

back to summary

protected boolean next() throws StandardException

Read the next log record in logToScan. The information in this log record can be read by using the getXXX methods.

Side effects:

On a successful read (return true): either...

... the scan read a log record indicating that a log file switch has taken place on the master, in which case isLogFileSwitch() returns true. In this case, getXXX will not contain valid data. Asserts handle calls to these methods when in sane mode. currentPosition is updated to point to the byte immediately following this log file switch log record.

... or the scan read a normal log record, in which case isLogRecord() returns true. Also sets currentInstant and currentData, and updates currentPosition to point to the byte immediatly following the log record. In this case, getXXX will return meaningful information about the log record.

If there are no more log records in logToScan (returns false) or a problem occurs (throws StandardException): setting hasInfo = false

Returns:boolean

true if a log record was successfully read, false if end of logToScan has been reached.

Exceptions

StandardException:: if logToScan is found to be corrupted.

retrieveBytes	back to summary
private void retrieveBytes(byte[] readInto, int length) throws StandardException Copy length number of bytes from logToScan into readInto. Starts to copy from currentPosition. Also increments currentPosition by length. Parameters readInto:byte[] The byte[] copied to length:int The number of bytes copied from logToScan to readInto Exceptions StandardException: if there are less then length bytes left to read in logToScan, meaning that the chunk of log is corrupt.

retrieveBytes

back to summary

private void retrieveBytes(byte[] readInto, int length) throws StandardException

Copy length number of bytes from logToScan into readInto. Starts to copy from currentPosition. Also increments currentPosition by length.

Parameters

readInto:byte[]: The byte[] copied to
length:int: The number of bytes copied from logToScan to readInto

Exceptions

StandardException:: if there are less then length bytes left to read in logToScan, meaning that the chunk of log is corrupt.

retrieveInt	back to summary
private int retrieveInt() throws StandardException Read an int from logToScan. Also increments currentPosition by 4 (the number of bytes in an int). Returns:int an int read from logToScan Exceptions StandardException: if there are less then 4 bytes left to read in logToScan, meaning that the chunk of log is corrupt.

retrieveInt

back to summary

private int retrieveInt() throws StandardException

Read an int from logToScan. Also increments currentPosition by 4 (the number of bytes in an int).

Returns:int

an int read from logToScan

Exceptions

StandardException:: if there are less then 4 bytes left to read in logToScan, meaning that the chunk of log is corrupt.

retrieveLong	back to summary
private long retrieveLong() throws StandardException Read a long from logToScan. Also increments currentPosition by 8 (the number of bytes in a long). Returns:long a long read from logToScan Exceptions StandardException: if there are less then 8 bytes left to read in logToScan, meaning that the chunk of log is corrupt.

retrieveLong

back to summary

private long retrieveLong() throws StandardException

Read a long from logToScan. Also increments currentPosition by 8 (the number of bytes in a long).

Returns:long

a long read from logToScan

Exceptions

StandardException:: if there are less then 8 bytes left to read in logToScan, meaning that the chunk of log is corrupt.

pack-priv Class ReplicationLogScan

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail