rice.post.log
Class Log

java.lang.Object
  rice.post.log.Log

All Implemented Interfaces:

java.io.Serializable, PostData

Direct Known Subclasses:

EncryptedLog, ForwardLog, PostLog

public class Log

extends java.lang.Object

implements PostData

Class which represents a log in the POST system. Clients can use this log in order to get lists of sublogs, or walk backwards down all of the entries. Log classes are stored in PAST at specific locations, and are updated whenever a change is made to the log. This class also provides the proper synchronization so that quick calls to the addLogEntry() method do not overwrite each other.

Version:

$Id: Log.java 2851 2005-12-16 16:04:07Z jstewart $

See Also:

Serialized Form

Nested Class Summary

protected class

Log.AddLogEntryTask This class encapsulates the logic needed to add a log entry to the current log.

Field Summary

protected java.util.Vector	buffer A vector of ongoing buffered tasks - in case two addLogEntries() are called in quick succession.
protected java.util.HashMap	children A map of the names of the child logs to their references.
protected java.util.HashMap	childrenCache A cache of references to our children
protected Id	location The location of this log in PAST.
protected Logger	logger
protected static int	N_TOP_ENTRIES Number of topEntryReferences to keep around.
protected java.lang.Object	name Some unique identifier to name this log.
protected Post	post The current local POST service.
protected LogEntry	topEntry The most recent entry in this log.
protected LogEntryReference	topEntryReference A reference to the most recent entry in this log.
protected LogEntryReference[]	topEntryReferences References to the last n entries in this log.

Constructor Summary

Log(java.lang.Object name, Id location, Post post)
Constructs a Log for use in POST

Method Summary

void	addChildLog(Log log, Continuation command) This method adds a child log to this log, essentially forming a tree of logs.
void	addLogEntry(LogEntry entry, Continuation command) This method appends an entry into the user's log, and updates the pointer to the top of the log to reflect the new object.
ContentHashReference	buildContentHashReference(Id[] location, byte[][] key) This method is not supported (you CAN NOT store a log as a content-hash block).
SecureReference	buildSecureReference(Id location, byte[] key) This method is not supported (you CAN NOT store a log as a secure block).
SignedReference	buildSignedReference(Id location) Builds a LogReference object to this log, given a location.
boolean	cache() Returns whether or not this log should be cached
void	getChildLog(java.lang.Object name, Continuation command) This method returns a the specific child log of this log, given the child log's name.
java.lang.Object[]	getChildLogNames() This method returns an array of the names of all of the current child logs of this log.
Id	getLocation()
void	getLogEntryReferences(java.util.Set set, LogEntry entry, Continuation command) This method returns a list of all the handles stored in the folder or any subfolders.
java.lang.Object	getName()
protected void	getRealTopEntry(Continuation command) Internal method to get the *actual* top entry
void	getTopEntry(Continuation command) This method returns a reference to the most recent entry in the log, which can then be used to walk down the log.
LogEntryReference	getTopEntryReference() Returns the reference to the most recent log entry
void	removeChildLog(java.lang.Object name, Continuation command) This method removes a child log from this log.
void	setName(java.lang.Object name, Continuation command) Sets the name of this log.
void	setPost(Post post) Sets the current local Post service.
protected void	sync(Continuation command) Helper method to sync this log object on the network.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

location

protected Id location

The location of this log in PAST.

name

protected java.lang.Object name

Some unique identifier to name this log.

children

protected java.util.HashMap children

A map of the names of the child logs to their references.

post

protected transient Post post

The current local POST service. Transient: changes depending on where the log is being used.

buffer

protected transient java.util.Vector buffer

A vector of ongoing buffered tasks - in case two addLogEntries() are called in quick succession. Note that the first element in the buffer is the current outstanding task.

topEntryReference

protected LogEntryReference topEntryReference

A reference to the most recent entry in this log. deprecated, use the topEntryReferences[] array below

N_TOP_ENTRIES

protected static final int N_TOP_ENTRIES

Number of topEntryReferences to keep around.

See Also:

Constant Field Values

topEntryReferences

protected LogEntryReference[] topEntryReferences

References to the last n entries in this log.

topEntry

protected transient LogEntry topEntry

The most recent entry in this log.

childrenCache

protected transient java.util.HashMap childrenCache

A cache of references to our children

logger

protected transient Logger logger

Constructor Detail

Log

public Log(java.lang.Object name,
           Id location,
           Post post)

Constructs a Log for use in POST

Parameters:

name - Some unique identifier for this log

location - The location of this log in PAST

Method Detail

cache

public boolean cache()

Returns whether or not this log should be cached

Returns:

Whether or not this log should be cached

getLocation

public Id getLocation()

Returns:

The location of this Log in PAST.

getName

public java.lang.Object getName()

Returns:

The name of this Log.

setName

public void setName(java.lang.Object name,
                    Continuation command)

Sets the name of this log. If this log has a parent, it MUST be removed and re-added to the parent for this change to work. Otherwise, BAD BAD BAD things will happen. You've been warned.

Parameters:

name - The new name

command - The command to run once done

setPost

public void setPost(Post post)

Sets the current local Post service.

Parameters:

post - The current local Post service

sync

protected void sync(Continuation command)

Helper method to sync this log object on the network. Once this method is finished, it will call the command.receiveResult() method with the current log as the argument, or it may call receiveExcception if an exception occurred.

Parameters:

command - The command to run once done

addChildLog

public void addChildLog(Log log,
                        Continuation command)

This method adds a child log to this log, essentially forming a tree of logs. Once this method is finished, it will call the command.receiveResult() method with the new Log (ready to go), or it may call receiveExcception if an exception occurred.

Parameters:

log - The log to add as a child.

command - The command to run once done

removeChildLog

public void removeChildLog(java.lang.Object name,
                           Continuation command)

This method removes a child log from this log. Once this method is finished, it will call the command.receiveResult() method with a Boolean value indicating success, or it may call receiveException if an exception occurred.

Parameters:

log - The log to remove

command - The command to run once done

getChildLogNames

public java.lang.Object[] getChildLogNames()

This method returns an array of the names of all of the current child logs of this log.

Returns:

An array of Objects: the names of the children of this Log

getChildLog

public void getChildLog(java.lang.Object name,
                        Continuation command)

This method returns a the specific child log of this log, given the child log's name.

Parameters:

name - The name of the log to return.

command - The command to run once done.

addLogEntry

public void addLogEntry(LogEntry entry,
                        Continuation command)

This method appends an entry into the user's log, and updates the pointer to the top of the log to reflect the new object. This method returns a LogEntryReference which is a pointer to the LogEntry in PAST. Note that this method reinserts this Log into PAST in order to reflect the addition. Once this method is finished, it will call the command.receiveResult() method with a LogEntryReference for the new entry, or it may call receiveExcception if an exception occurred.

Parameters:

entry - The log entry to append to the log.

command - The command to run once done

getTopEntryReference

public LogEntryReference getTopEntryReference()

Returns the reference to the most recent log entry

Returns:

The most recent log entry reference

getTopEntry

public void getTopEntry(Continuation command)

This method returns a reference to the most recent entry in the log, which can then be used to walk down the log.

getRealTopEntry

protected final void getRealTopEntry(Continuation command)

Internal method to get the *actual* top entry

getLogEntryReferences

public void getLogEntryReferences(java.util.Set set,
                                  LogEntry entry,
                                  Continuation command)

This method returns a list of all the handles stored in the folder or any subfolders. Returns a PastContentHandle[] containing all of the handles in to the provided continatuion.

buildSignedReference

public SignedReference buildSignedReference(Id location)

Builds a LogReference object to this log, given a location. Used by the StorageService when storing the log.

Specified by:

buildSignedReference in interface PostData

Parameters:

location - The location of this object.

Returns:

A LogReference to this object

buildContentHashReference

public ContentHashReference buildContentHashReference(Id[] location,
                                                      byte[][] key)

This method is not supported (you CAN NOT store a log as a content-hash block).

Specified by:

buildContentHashReference in interface PostData

Parameters:

location - The location

key -

Returns:

A pointer to the data

Throws:

java.lang.IllegalArgumentException - Always

buildSecureReference

public SecureReference buildSecureReference(Id location,
                                            byte[] key)

This method is not supported (you CAN NOT store a log as a secure block).

Specified by:

buildSecureReference in interface PostData

Parameters:

location - The location of the data

key - The for the data

Returns:

A pointer to the data

Throws:

java.lang.IllegalArgumentException - Always

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object