ostore.replica
Class Replica

java.lang.Object
  |
  +--ostore.replica.Replica

public class Replica

extends Object

Stores the Heartbeats, etc. used by the ReplicaStage to handle client requests for a replica.

A Replica stores the top block of as many versions of a replica as possible. Normally it will at least have the top block for all versions that have not yet been archived and the most recent one which has been archived. Those versions are sufficient to fully traverse the version history.

The release_blocks method uses the clock algorithm to remove versions that have not been referenced recently. Versions are considered "referenced" when they are first inserted and also when they are returned through either the block_vid or missing_block_id.

This class will eventually also track the degree to which entire versions are stored.

Version:

$Id: Replica.java,v 1.28 2003/02/07 20:57:22 hweather Exp $

Author:

Dennis Geels

Field Summary

static int	DISCONNECTED The value for dtree_status when this node is not connected to the dissemination tree.
static int	INVALIDATES_ONLY The value for dtree_status when this node is only partially connected to the dissemination tree.
static int	RECEIVING_UPDATES The value for dtree_status when this node is fully connected to the dissemination tree, receiving all updates from the inner ring.

Constructor Summary

Replica(SecureHash aguid)
Constructs a new Replica.

Method Summary

void	add_hb(SignedQS signed_hb) Updates the set of Heartbeats.
void	add_tentative_hb(Heartbeat hb) Updates the most recent Heartbeat.
void	add_top_block(CacheableIdentity id, CacheablePinned handle) Store a possibly-new version of this replica.
VID	block_vid(int index) Return a name for the specified version.
int	get_dtree_status() Returns the current level for dissemination tree connectivity.
Heartbeat	get_hb() Returns the most recent Heartbeat for this Replica.
boolean	get_local_flag() Returns the current value of the local_only flag.
Metadata	get_metadata(VID version) Returns the Metadata object for the specified version, or null for unknown versions.
boolean	get_open_flag() Returns the current value of the open_locally flag.
boolean	get_primary_flag() Returns the current value of the is_primary flag.
SignedQS	get_signed_guid_hb() Returns the most recent signed Heartbeat received for this Replica that contains a valid Heartbeat.vguid field.
SignedQS	get_signed_hb() Returns the most recent signed Heartbeat received for this Replica.
boolean	is_gap(int index) Tests whether this Replica's history chain is missing a version.
CacheableIdentity	missing_block_id(int index) Return a cache name for the specified missing version.
CacheablePinned[]	release_all_blocks() Surrenders all cache state.
CacheablePinned[]	release_blocks(int num_to_leave) Surrenders cache state.
int	search_versions(Date expiration_date, Date creation_date, Long seq_num) Searches a replica's version history.
int	set_dtree_status(int level) Sets the current level for dissemination tree connectivity.
boolean	set_local_flag(boolean local) Sets the local_only flag.
boolean	set_open_flag(boolean open) Sets the open_locally flag.
boolean	set_primary_flag(boolean primary) Sets the is_primary flag.
int	size() Returns the number of versions currently stored in the history chain.

Methods inherited from class java.lang.Object

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

Field Detail

RECEIVING_UPDATES

public static final int RECEIVING_UPDATES

The value for dtree_status when this node is fully connected to the dissemination tree, receiving all updates from the inner ring.

See Also:

Constant Field Values

INVALIDATES_ONLY

public static final int INVALIDATES_ONLY

The value for dtree_status when this node is only partially connected to the dissemination tree. It receives heartbeats from the inner ring, which invalidate stale versions on this node. Updates, which require more bandwidth, are not sent.

See Also:

Constant Field Values

DISCONNECTED

public static final int DISCONNECTED

The value for dtree_status when this node is not connected to the dissemination tree.

See Also:

Constant Field Values

Constructor Detail

Replica

public Replica(SecureHash aguid)

Constructs a new Replica.

Method Detail

set_open_flag

public boolean set_open_flag(boolean open)

Sets the open_locally flag.

This flag should be true iff the local ClientStage wants this Replica open. If false, we can discard the Replica at will.

Parameters:

open - the new value.

Returns:

the previous value.

get_open_flag

public boolean get_open_flag()

Returns the current value of the open_locally flag.

See Also:

set_open_flag(boolean)

set_local_flag

public boolean set_local_flag(boolean local)

Sets the local_only flag.

Parameters:

local - the new value.

Returns:

the previous value.

get_local_flag

public boolean get_local_flag()

Returns the current value of the local_only flag.

See Also:

set_local_flag(boolean)

set_dtree_status

public int set_dtree_status(int level)

Sets the current level for dissemination tree connectivity.

Parameters:

level - One of RECEIVING_UPDATES, INVALIDATES_ONLY, or DISCONNECTED.

Returns:

the previous value.

get_dtree_status

public int get_dtree_status()

Returns the current level for dissemination tree connectivity.

See Also:

set_dtree_status(int)

get_hb

public Heartbeat get_hb()

Returns the most recent Heartbeat for this Replica.

get_signed_hb

public SignedQS get_signed_hb()

Returns the most recent signed Heartbeat received for this Replica.

get_signed_guid_hb

public SignedQS get_signed_guid_hb()

Returns the most recent signed Heartbeat received for this Replica that contains a valid Heartbeat.vguid field.

set_primary_flag

public boolean set_primary_flag(boolean primary)

Sets the is_primary flag.

Parameters:

primary - the new value.

Returns:

the previous value.

get_primary_flag

public boolean get_primary_flag()

Returns the current value of the is_primary flag.

See Also:

set_primary_flag(boolean)

add_tentative_hb

public void add_tentative_hb(Heartbeat hb)

Updates the most recent Heartbeat. If this Heartbeat is not more recent/relevant than the current one, it will be dropped.

add_hb

public void add_hb(SignedQS signed_hb)

Updates the set of Heartbeats. If this Heartbeat is not more recent/relevant than the current ones, it will be dropped.

add_top_block

public void add_top_block(CacheableIdentity id,
                          CacheablePinned handle)

Store a possibly-new version of this replica. All the useful metadata is extracted and stored in a local version object, which is then added to the list of such objects.

Parameters:

id - The name of the top block of the version

handle - A pinned handle for the block in the cache.

search_versions

public int search_versions(Date expiration_date,
                           Date creation_date,
                           Long seq_num)

Searches a replica's version history.

This method returns the index of the version with the specified expiration date, creation date or sequence number. If that version does not exist in the chain, the method returns a negative number code.

Only one of expiration_date, creatin_date, or seq_num should be non-null.

Parameters:

expiration_date - The expiration date to find, or null.

creation_date - The creation date to find, or null.

seq_num - The sequence number to find, or null

Returns:

the index (0-based) of the version which satisfies the specified restrictions. For missing versions, this method returns (-1 * best - 1), where best is the index which the version would have if it were added.

See Also:

Collections.binarySearch(java.util.List, java.lang.Object)

is_gap

public boolean is_gap(int index)

Tests whether this Replica's history chain is missing a version.

This method returns true either if one or more versions were created between the specified version and its predecessor (later version) in the chain, or if the specified index is out of range (not present in this Replica).

Versions are considered consecutive if the last_vhash field of the later version correctly names the earlier version.

If index == 0, this method tests whether the latest Heartbeat still points to the most recent version in the history chain.

Parameters:

index - An index into the version history chain

block_vid

public VID block_vid(int index)

Return a name for the specified version. If the version has both a temporary name and a permanent name, the temporary one will be returned (for now).

Parameters:

index - An index into the version history chain.

missing_block_id

public CacheableIdentity missing_block_id(int index)

Return a cache name for the specified missing version. The name is constructed using information from the preceding (newer) version in the history chain, and is generally unrelated to the version currently stored at the specified index.

If the missing version appears to be older than a version with sequence number "0", this method returns null.

Parameters:

index - An index into the version history chain.

get_metadata

public Metadata get_metadata(VID version)

Returns the Metadata object for the specified version, or null for unknown versions.

size

public int size()

Returns the number of versions currently stored in the history chain.

release_all_blocks

public CacheablePinned[] release_all_blocks()

Surrenders all cache state.

Returns:

an array holding this Replica's pinned handles.

release_blocks

public CacheablePinned[] release_blocks(int num_to_leave)

Surrenders cache state. Only the most important historical versions are kept; others are removed from the local data structures and their cache pins are returned. We define "importance" using the clock algorithm.

Parameters:

num_to_leave - The number of historical versions to save.

Returns:

an array holding the pinned handles to release.