net.named_data.jndn.sync

Class ChronoSync2013

java.lang.Object

net.named_data.jndn.sync.ChronoSync2013

All Implemented Interfaces:

OnData, OnInterestCallback, OnTimeout

public class ChronoSync2013
extends Object
implements OnInterestCallback, OnData, OnTimeout

ChronoSync2013 implements the NDN ChronoSync protocol as described in the 2013 paper "Let's ChronoSync: Decentralized Dataset State Synchronization in Named Data Networking". http://named-data.net/publications/chronosync .

Note:

The support for ChronoSync is experimental and the API is not finalized. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/chrono-sync2013.html .

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ChronoSync2013.OnInitialized
static interface	ChronoSync2013.OnReceivedSyncState
static class	ChronoSync2013.PrefixAndSessionNo A PrefixAndSessionNo holds a user's data prefix and session number (used to return a list from getProducerPrefixes).
static class	ChronoSync2013.SyncState A SyncState holds the values of a sync state message which is passed to the onReceivedSyncState callback which was given to the ChronoSyn2013 constructor.

Constructor Summary

Constructors

Constructor and Description
ChronoSync2013(ChronoSync2013.OnReceivedSyncState onReceivedSyncState, ChronoSync2013.OnInitialized onInitialized, Name applicationDataPrefix, Name applicationBroadcastPrefix, long sessionNo, Face face, KeyChain keyChain, Name certificateName, double syncLifetime, OnRegisterFailed onRegisterFailed) Create a new ChronoSync2013 to communicate using the given face.

Method Summary

Modifier and Type	Method and Description
List<ChronoSync2013.PrefixAndSessionNo>	getProducerPrefixes() Get a copy of the current list of producer data prefixes, and the associated session number.
long	getProducerSequenceNo(String dataPrefix, long sessionNo) Get the current sequence number in the digest tree for the given producer dataPrefix and sessionNo.
long	getSequenceNo() Get the sequence number of the latest data published by this application instance.
void	onData(Interest interest, Data data) When a matching data packet is received, onData is called.
void	onInterest(Name prefix, Interest interest, Face face, long interestFilterId, InterestFilter filter) Process the sync interest from the applicationBroadcastPrefix.
void	onTimeout(Interest interest) If the interest times out according to the interest lifetime, onTimeout is called.
void	publishNextSequenceNo() Increment the sequence number, create a sync message with the new sequence number and publish a data packet where the name is the applicationBroadcastPrefix + the root digest of the current digest tree.
void	publishNextSequenceNo(Blob applicationInfo) Increment the sequence number, create a sync message with the new sequence number and publish a data packet where the name is the applicationBroadcastPrefix + the root digest of the current digest tree.
void	shutdown() Unregister callbacks so that this does not respond to interests anymore.

Methods inherited from class java.lang.Object

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

Constructor Detail

ChronoSync2013

public ChronoSync2013(ChronoSync2013.OnReceivedSyncState onReceivedSyncState,
                      ChronoSync2013.OnInitialized onInitialized,
                      Name applicationDataPrefix,
                      Name applicationBroadcastPrefix,
                      long sessionNo,
                      Face face,
                      KeyChain keyChain,
                      Name certificateName,
                      double syncLifetime,
                      OnRegisterFailed onRegisterFailed)
               throws IOException,
                      SecurityException

Create a new ChronoSync2013 to communicate using the given face. Initialize the digest log with a digest of "00" and and empty content. Register the applicationBroadcastPrefix to receive interests for sync state messages and express an interest for the initial root digest "00".

Parameters:

onReceivedSyncState - When ChronoSync receives a sync state message, this calls onReceivedSyncState.onReceivedSyncState(syncStates, isRecovery) where syncStates is the list of SyncState messages and isRecovery is true if this is the initial list of SyncState messages or from a recovery interest. (For example, if isRecovery is true, a chat application would not want to re-display all the associated chat messages.) The callback should send interests to fetch the application data for the sequence numbers in the sync state. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onInitialized - This calls onInitialized.onInitialized() when the first sync data is received (or the interest times out because there are no other publishers yet). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

applicationDataPrefix - The prefix used by this application instance for application data. For example, "/my/local/prefix/ndnchat4/0K4wChff2v". This is used when sending a sync message for a new sequence number. In the sync message, this uses applicationDataPrefix.toUri().

applicationBroadcastPrefix - The broadcast name prefix including the application name. For example, "/ndn/broadcast/ChronoChat-0.3/ndnchat1". This makes a copy of the name.

sessionNo - The session number used with the applicationDataPrefix in sync state messages.

face - The Face for calling registerPrefix and expressInterest. The Face object must remain valid for the life of this ChronoSync2013 object.

keyChain - To sign a data packet containing a sync state message, this calls keyChain.sign(data, certificateName).

certificateName - The certificate name of the key to use for signing a data packet containing a sync state message.

syncLifetime - The interest lifetime in milliseconds for sending sync interests.

onRegisterFailed - If failed to register the prefix to receive interests for the applicationBroadcastPrefix, this calls onRegisterFailed.onRegisterFailed(applicationBroadcastPrefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Throws:

IOException

SecurityException

Note:

Your application must call processEvents. Since processEvents modifies the internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as this constructor (which also modifies the data structures).

Method Detail

getProducerPrefixes

public final List<ChronoSync2013.PrefixAndSessionNo> getProducerPrefixes()

Get a copy of the current list of producer data prefixes, and the associated session number. You can use these in getProducerSequenceNo(). This includes the prefix for this user.

Returns:

A copy of the list of each producer prefix and session number.

getProducerSequenceNo

public final long getProducerSequenceNo(String dataPrefix,
                                        long sessionNo)

Get the current sequence number in the digest tree for the given producer dataPrefix and sessionNo.

Parameters:

dataPrefix - The producer data prefix as a Name URI string.

sessionNo - The producer session number.

Returns:

The current producer sequence number, or -1 if the producer namePrefix and sessionNo are not in the digest tree.

publishNextSequenceNo

public final void publishNextSequenceNo(Blob applicationInfo)
                                 throws IOException,
                                        SecurityException

Increment the sequence number, create a sync message with the new sequence number and publish a data packet where the name is the applicationBroadcastPrefix + the root digest of the current digest tree. Then add the sync message to the digest tree and digest log which creates a new root digest. Finally, express an interest for the next sync update with the name applicationBroadcastPrefix + the new root digest. After this, your application should publish the content for the new sequence number. You can get the new sequence number with getSequenceNo().

Parameters:

applicationInfo - (optional) This appends applicationInfo to the content of the sync messages. This same info is provided to the receiving application in the SyncState state object provided to the onReceivedSyncState callback.

Throws:

IOException

SecurityException

Note:

Your application must call processEvents. Since processEvents modifies the internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as publishNextSequenceNo() (which also modifies the data structures).

publishNextSequenceNo

public final void publishNextSequenceNo()
                                 throws IOException,
                                        SecurityException

Increment the sequence number, create a sync message with the new sequence number and publish a data packet where the name is the applicationBroadcastPrefix + the root digest of the current digest tree. Then add the sync message to the digest tree and digest log which creates a new root digest. Finally, express an interest for the next sync update with the name applicationBroadcastPrefix + the new root digest. After this, your application should publish the content for the new sequence number. You can get the new sequence number with getSequenceNo().

Throws:

IOException

SecurityException

Note:

Your application must call processEvents. Since processEvents modifies the internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as publishNextSequenceNo() (which also modifies the data structures).

getSequenceNo

public final long getSequenceNo()

Get the sequence number of the latest data published by this application instance.

Returns:

The sequence number.

shutdown

public final void shutdown()

Unregister callbacks so that this does not respond to interests anymore. If you will discard this ChronoSync2013 object while your application is still running, you should call shutdown() first. After calling this, you should not call publishNextSequenceNo() again since the behavior will be undefined.

Note:

Because this modifies internal ChronoSync data structures, your application should make sure that it calls processEvents in the same thread as shutdown() (which also modifies the data structures).

onInterest

public final void onInterest(Name prefix,
                             Interest interest,
                             Face face,
                             long interestFilterId,
                             InterestFilter filter)

Process the sync interest from the applicationBroadcastPrefix. If we can't satisfy the interest, add it to the pending interest table in the contentCache_ so that a future call to add may satisfy it. (Do not call this. It is only public to implement the interface.)

Specified by:

onInterest in interface OnInterestCallback

Parameters:

prefix - The Name prefix given to registerPrefix or setInterestFilter (or directly to the InterestFilter constructor). NOTE: You must not change the prefix object - if you need to change it then make a copy.

interest - The received interest.

face - You should call face.putData to supply a Data packet which satisfies the Interest.

interestFilterId - The interest filter ID which can be used with Face.unsetInterestFilter.

filter - The InterestFilter given to registerPrefix or setInterestFilter, or the InterestFilter created from the Name prefix. The first argument, prefix, is provided for convenience and is the same as filter.getPrefix(). NOTE: You must not change the filter object - if you need to change it then make a copy.

onData

public final void onData(Interest interest,
                         Data data)

Description copied from interface: OnData

When a matching data packet is received, onData is called.

Specified by:

onData in interface OnData

Parameters:

interest - The interest given to Face.expressInterest. NOTE: You must not change the interest object - if you need to change it then make a copy.

data - The received Data object.

onTimeout

public void onTimeout(Interest interest)

Description copied from interface: OnTimeout

If the interest times out according to the interest lifetime, onTimeout is called.

Specified by:

onTimeout in interface OnTimeout

Parameters:

interest - The interest given to expressInterest.