ptolemy.backtrack.util
Class FieldRecord

java.lang.Object
  ptolemy.backtrack.util.FieldRecord

public class FieldRecord
extends java.lang.Object

The records (or change history) of a field in a class. In a Java program refactored with ptolemy.backtrack.eclipse.ast.Transformer to support backtracking, every change on a field by means of assignment is recorded. The old value of the field is stored in a FieldRecord. Every entry in the record includes the information of the timestamp (see Checkpoint) denoting the time when the value was recorded, as well as that old value of the field.

It is possible the records of a field have more than zero dimension, when the field is an array. In that case, records of different dimensions are stored in different tables. E.g., an int is considered zero-dimensional, and only one list is used to store its change history. an int[] is considered one-dimensional (with one possible index). Two lists are used in order to record assignments to the array itself, and the assignment to one of its element. In the latter case, the index of the changed element is also recorded. Similarly, a field of type int[][] requires three lists.

Lists of records are added with different add functions, which take a timestamp and record the old value taken at that timestamp at the head position of the corresponding list. Timestamps must be increasing. A value with larger timestamp means it is taken later in time.

To access the lists, iterators must be used to iterate from the most recent recorded value to the earliest ones. Records in the lists may also be removed with remove functions of the iterators. As with many other iterators, modifications cannot be made simultaneously with two different iterators. add functions cannot be called while accessing any list with an iterator, either. If changes are made simultaneously, the effect is unpredictable.

Since:

Ptolemy II 5.1

Version:

$Id: FieldRecord.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Thomas Feng

Accepted Rating:

Red (tfeng)

Proposed Rating:

Red (tfeng)

Nested Class Summary

class	FieldRecord.CombinedIterator Combinated iterator of all the dimensions.
class	FieldRecord.IndividualIterator Iterator of the records for the given dimension.
class	FieldRecord.Record Record of an old value.
protected class	FieldRecord.RecordList Double linked list of records.

Field Summary

private java.util.Stack<FieldRecordState>

_states The stack of (possibly) multiple field record states.

Constructor Summary

FieldRecord()
Construct a zero-dimensional (scalar) field record.

FieldRecord(int dimensions)
Construct a multi-dimensional field record.

Method Summary

protected void	_addRecord(int index, FieldRecord.Record record) Add a record to the list at the given index.
protected boolean	_deepCopyArray(java.lang.Object source, java.lang.Object destination) Perform a deep copy from a source array to a destination array.
protected FieldRecord.Record	_findRecord(java.util.Iterator recordListIterator, long timestamp, boolean trim) Find the record with the smallest timestamp that is larger than the given timestamp.
protected FieldRecordState	_getTopState() Get the state on the top of the states stack.
protected java.lang.Object	_restoreField(java.lang.Object field, FieldRecord.Record record) Restore the old value in a record to the field.
void	add(boolean value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(byte value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(char value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(double value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(float value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(int[] indices, boolean value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, byte value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, char value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, double value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, float value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, int value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, long value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, java.lang.Object value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int[] indices, short value, long timestamp) Add an old value to the specified indices of the records, and associate it with a timestamp.
void	add(int value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(long value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(java.lang.Object value, long timestamp) Add an old value to the records, associated with a timestamp.
void	add(short value, long timestamp) Add an old value to the records, associated with a timestamp.
void	backup(int[] indices, java.lang.Object array, long timestamp) Backup the values in an array, and associate the record with a timestamp.
void	backup(java.lang.Object array, long timestamp) Backup the values in an array, and associate the record with a timestamp.
static void	commit(FieldRecord[] records, long timestamp, long topStackTimestamp) Commit the changes in all the FieldRecord objects up to the time represented by the timestamp.
void	commit(long timestamp) Commit the changes up to the time represented by the timestamp.
void	commitState() Commit the state of this field record, and delete older states in its stack.
java.util.Iterator	iterator() Return the iterator of all the records.
java.util.Iterator	iterator(int index) Return the iterator of the records with the specified index.
void	popState() Pop out the top state in the states stack, and the state next to it becomes the top state.
static void	popState(FieldRecord[] records) For each state in the given array, pop out the top state.
void	pushState() Push a new state onto the top of the states stack, and the current top state becomes the one right below it.
static void	pushState(FieldRecord[] records) For each state in the given array, push in a new state.
boolean	restore(boolean current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
byte	restore(byte current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
char	restore(char current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
double	restore(double current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
float	restore(float current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
int	restore(int current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
long	restore(long current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
java.lang.Object	restore(java.lang.Object current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.
short	restore(short current, long timestamp, boolean trim) Restore the old value at the timestamp to the field.

Methods inherited from class java.lang.Object

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

Field Detail

_states

private java.util.Stack<FieldRecordState> _states

The stack of (possibly) multiple field record states.

Constructor Detail

FieldRecord

public FieldRecord()

Construct a zero-dimensional (scalar) field record.

FieldRecord

public FieldRecord(int dimensions)

Construct a multi-dimensional field record.

Parameters:

dimensions - Number of dimensions; can be omitted when it is 1.

Method Detail

add

public void add(java.lang.Object value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], Object, long)

add

public void add(boolean value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], boolean, long)

add

public void add(byte value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], byte, long)

add

public void add(char value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], char, long)

add

public void add(double value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], double, long)

add

public void add(float value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], float, long)

add

public void add(int value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], int, long)

add

public void add(int[] indices,
                java.lang.Object value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                boolean value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                byte value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                char value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                double value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                float value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                int value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                long value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(int[] indices,
                short value,
                long timestamp)

Add an old value to the specified indices of the records, and associate it with a timestamp. The indices is the array of indices to locate the element in the array. E.g., the following assignment makes it necessary to record the old value at indices [1][2][3]:

buf[1][2][3] = new char[10];

If the indices array is null, it is assumed that no index is needed.

Parameters:

indices - The indices.

value - The old value.

timestamp - The current timestamp to be associated with the old value.

add

public void add(long value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], long, long)

add

public void add(short value,
                long timestamp)

Add an old value to the records, associated with a timestamp. This is the same as calling add(null, value, timestamp), where the value is stored without any indexing (e.g., the field is not an array, or no indexing is needed for the value).

Parameters:

value - The old value.

timestamp - The current timestamp to be associated with the old value.

See Also:

add(int[], short, long)

backup

public void backup(java.lang.Object array,
                   long timestamp)

Backup the values in an array, and associate the record with a timestamp. This is the same as calling backup(null, array, timestamp).

Parameters:

array - The array.

timestamp - The current timestamp to be associated with the old value.

backup

public void backup(int[] indices,
                   java.lang.Object array,
                   long timestamp)

Backup the values in an array, and associate the record with a timestamp.

Parameters:

indices - The indices.

array - The array.

timestamp - The current timestamp to be associated with the old value.

commit

public static void commit(FieldRecord[] records,
                          long timestamp,
                          long topStackTimestamp)

Commit the changes in all the FieldRecord objects up to the time represented by the timestamp. Records older than that time are deleted.

Parameters:

records - The array of field records.

timestamp - The timestamp.

topStackTimestamp - The timestamp taken when the checkpoint object was assigned.

See Also:

commit(long), CheckpointRecord.getTopTimestamp()

commit

public void commit(long timestamp)

Commit the changes up to the time represented by the timestamp. Records older than that time are deleted.

Parameters:

timestamp - The timestamp.

commitState

public void commitState()

Commit the state of this field record, and delete older states in its stack.

Old states of field records are kept when a new checkpoint object is assigned to a monitored object. This function deletes those old states, but keep only the last (current) state.

See Also:

popState(), pushState()

iterator

public java.util.Iterator iterator()

Return the iterator of all the records. If the field is an array, the records with different indices are stored in separate lists. The iterator returned by this function combines all those lists, and the records that it returns are sorted with their timestamps. Records created more recently are returned earlier with FieldRecord.CombinedIterator.next().

Returns:

The iterator.

See Also:

iterator(int)

iterator

public java.util.Iterator iterator(int index)

Return the iterator of the records with the specified index. E.g., for a field f of type int[][] (2-dimensional):

1. When index is 0, it returns the iterator of records saved for assignments to the field itself.
2. When index is 1, it returns the iterator of records saved for assignments to the field with one index (e.g., f[1] = new int[10]).
3. When index is 2, it returns the iterator of records saved for assignments to the field with two indices (e.g., f[1][2] = 3).

Parameters:

index - The index.

Returns:

The iterator.

See Also:

iterator()

popState

public void popState()

Pop out the top state in the states stack, and the state next to it becomes the top state. The states stack must have at least two states in it.

popState

public static void popState(FieldRecord[] records)

For each state in the given array, pop out the top state. Used to simplify the implementation of refactoring.

Parameters:

records - The array of field records.

See Also:

popState()

pushState

public void pushState()

Push a new state onto the top of the states stack, and the current top state becomes the one right below it.

pushState

public static void pushState(FieldRecord[] records)

For each state in the given array, push in a new state. Used to simplify the implementation of refactoring.

Parameters:

records - The array of field records.

See Also:

pushState()

restore

public java.lang.Object restore(java.lang.Object current,
                                long timestamp,
                                boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public boolean restore(boolean current,
                       long timestamp,
                       boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public byte restore(byte current,
                    long timestamp,
                    boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public char restore(char current,
                    long timestamp,
                    boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public double restore(double current,
                      long timestamp,
                      boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public float restore(float current,
                     long timestamp,
                     boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public int restore(int current,
                   long timestamp,
                   boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public long restore(long current,
                    long timestamp,
                    boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

restore

public short restore(short current,
                     long timestamp,
                     boolean trim)

Restore the old value at the timestamp to the field.

The given timestamp refers to the time when the field still possesses its old value. If the timestamp is increased at an assignment, the old value at that timestamp refers to the value of the field before assignment.

Parameters:

current - The current value of the field.

timestamp - The timestamp.

trim - If true, any values newer than the restored value are deleted from the record.

Returns:

The old value to be assigned back to the field.

_addRecord

protected void _addRecord(int index,
                          FieldRecord.Record record)

Add a record to the list at the given index.

Parameters:

index - The index.

record - The record.

_deepCopyArray

protected boolean _deepCopyArray(java.lang.Object source,
                                 java.lang.Object destination)

Perform a deep copy from a source array to a destination array. If those arrays are multi-dimensional, sub-arrays of them are copied respectively.

Parameters:

source - The source array.

destination - The destination array.

Returns:

true if successfully copied; otherwise, false.

_findRecord

protected FieldRecord.Record _findRecord(java.util.Iterator recordListIterator,
                                         long timestamp,
                                         boolean trim)

Find the record with the smallest timestamp that is larger than the given timestamp.

Parameters:

recordListIterator - The iterator with which the records are searched.

timestamp - The timestamp.

trim - If true, the records found with timestamps equal to or larger than the given timestamp are deleted.

Returns:

The record, if found; otherwise, null.

_getTopState

protected FieldRecordState _getTopState()

Get the state on the top of the states stack.

Returns:

The state on the top, or null if the states stack is empty.

_restoreField

protected java.lang.Object _restoreField(java.lang.Object field,
                                         FieldRecord.Record record)

Restore the old value in a record to the field.

Parameters:

field - The field to be restored.

record - The record.

Returns:

The field. It may differ from the field in the arguments.