org.ccnx.ccn.profiles.nameenum.EnumeratedNameList Class Reference

Blocking and background interface to name enumeration. More...

List of all members.

Classes

class  NewChildrenByThread

Public Member Functions

 EnumeratedNameList (ContentName namePrefix, CCNHandle handle) throws IOException
 Creates an EnumeratedNameList object.
 EnumeratedNameList (ContentName namePrefix, boolean startEnumerating, CCNHandle handle) throws IOException
ContentName getName ()
 Method to return the ContentName used for enumeration.
synchronized void stopEnumerating ()
 Cancels ongoing name enumeration.
synchronized void startEnumerating () throws IOException
 Starts enumeration, if we're not enumerating already.
boolean isEnumerating ()
boolean hasEnumerated ()
void shutdown ()
 Shutdown anybody waiting for children on this list.
SortedSet< ContentNamegetNewData (boolean threadPoolContext, long timeout)
 Interface to retrieve only new data from enumeration responses as it arrives.
SortedSet< ContentNamegetNewData ()
 Block and wait as long as it takes for new data to appear.
SortedSet< ContentNamegetNewData (long timeout)
 Block and wait for timeout or until new data appears.
SortedSet< ContentNamegetNewDataThreadPool (long timeout)
 Block and wait for timeout or until new data appears.
SortedSet< ContentNamegetChildren ()
 Returns single-component ContentName objects containing the name components of the children.
boolean hasNewData ()
 Returns true if the prefix has new names that have not been handled by the calling application.
boolean hasChildren ()
 Returns true if we have received any responses listing available child names.
int childCount ()
 Returns the number of children we have, or 0 if we have none.
boolean hasChild (byte[] childComponent)
 Returns true if we know the prefix has a child matching the given name component.
boolean hasChild (String childName)
 Returns whether a child is present in the list of known children.
boolean waitForNewChildren (boolean threadPoolContext, long timeout)
 Wait for new children to arrive.
void waitForNewChildren ()
 Wait for new children to arrive.
boolean waitForNewChildren (long timeout)
 Wait for new children to arrive.
boolean waitForNewChildrenThreadPool (long timeout)
 Wait for new children to arrive in thread pool context.
void waitForChildren (long timeout)
 Waits until there is any data at all.
void waitForChildren ()
 Wait (block) for initial data to arrive, possibly forever.
void waitForNoUpdates (long timeout)
 Wait for new children to arrive until there is a period of length timeout during which no new child arrives.
void waitForNoUpdatesOrResult (long timeout)
 Wait for new children to arrive until there is a period of length timeout during which no new child arrives, or the method hasResult() returns true.
boolean hasResult ()
 Subclasses should override this test to answer true if waiters should break out of a waitForNoUpdatesOrResult loop.
void clearResult ()
 Reset whatever state hasResult tests.
ContentName getLatestVersionChildName ()
 If some or all of the children of this name are versions, returns the latest version among them.
int handleNameEnumerator (ContentName prefix, ArrayList< ContentName > names)
 Handle responses from CCNNameEnumerator that give us a list of single-component child names.
byte[] getLatestVersionChildNameComponent ()
 Returns the latest version available under this prefix as a byte array.
CCNTime getLatestVersionChildTime ()
 Returns the latest version available under this prefix as a CCNTime object.

Static Public Member Functions

static ContentName getLatestVersionName (ContentName name, CCNHandle handle) throws IOException
 A static method that performs a one-shot call that returns the complete name of the latest version of content with the given prefix.
static EnumeratedNameList exists (ContentName childName, ContentName prefixKnownToExist, CCNHandle handle) throws IOException
 Static method that iterates down the namespace starting with the supplied prefix as a ContentName (prefixKnownToExist) to a specific child (childName).

Protected Member Functions

void processNewChildren (SortedSet< ContentName > newChildren)
 Method to allow subclasses to do post-processing on incoming names before handing them to customers.

Protected Attributes

ContentName _namePrefix
CCNNameEnumerator _enumerator
BasicNameEnumeratorListener callback
SortedSet< ContentName_children = new TreeSet<ContentName>()
Map< Long, NewChildrenByThread > _newChildrenByThread = new TreeMap<Long, NewChildrenByThread>()
Object _childLock = new Object()
CCNTime _lastUpdate = null
boolean _enumerating = false
boolean _shutdown = false
boolean _hasEnumerated = false
 Keep track of whether we've ever done enumeration, so we can start it automatically if someone asks us for something not in our cache.

Detailed Description

Blocking and background interface to name enumeration.

This allows a caller to specify a prefix under which to enumerate available children, and name enumeration to proceed in the background for as long as desired, providing updates whenever new data is published. Currently implemented as a wrapper around CCNNameEnumerator, will likely directly aggregate name enumeration responses in the future.

See also:
CCNNameEnumerator
BasicNameEnumeratorListener

Constructor & Destructor Documentation

org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.EnumeratedNameList ( ContentName  namePrefix,
CCNHandle  handle 
) throws IOException

Creates an EnumeratedNameList object.

This constructor creates a new EnumeratedNameList object that will begin enumerating the children of the specified prefix. The new EnumeratedNameList will use the CCNHandle passed in to the constructor, or create a new one using CCNHandle.open() if it is null.

Parameters:
namePrefix the ContentName whose children we wish to list.
handle the CCNHandle object for sending interests and receiving content object responses.

Member Function Documentation

void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.clearResult (  ) 

Reset whatever state hasResult tests.

Overridden by subclasses, default does nothing.

static EnumeratedNameList org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.exists ( ContentName  childName,
ContentName  prefixKnownToExist,
CCNHandle  handle 
) throws IOException [static]

Static method that iterates down the namespace starting with the supplied prefix as a ContentName (prefixKnownToExist) to a specific child (childName).

The method returns null if the name does not exist in a limited time iteration. If the child is found, this method returns the EnumeratedNameList object for the parent of the desired child in the namespace. The current implementation may time out before the desired name is found. Additionally, the current implementation does not loop on an enumeration attempt, so a child may be missed if it is not included in the first enumeration response.

TODO Add loop to enumerate under a name multiple times to avoid missing a child name TODO Handle timeouts better to avoid missing children. (Note: We could modify the name enumeration protocol to return empty responses if we query for an unknown name, but that adds semantic complications.)

Parameters:
childName ContentName for the child we are looking for under (does not have to be directly under) a given prefix.
prefixKnownToExist ContentName prefix to enumerate to look for a given child.
handle CCNHandle for sending and receiving interests and content objects.
Returns:
EnumeratedNameList Returns the parent EnumeratedNameList for the desired child, if one is found. Returns null if the child is not found.
Exceptions:
IOException 
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getChildren (  ) 

Returns single-component ContentName objects containing the name components of the children.

Returns:
SortedSet<ContentName> Returns the array of single-component content name children that have been retrieved so far, or null if no responses have yet been received. The latter may indicate either that no children of this prefix are known to any responders, or that they have not had time to respond.
ContentName org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionChildName (  ) 

If some or all of the children of this name are versions, returns the latest version among them.

Returns:
ContentName The latest version component
byte [] org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionChildNameComponent (  ) 

Returns the latest version available under this prefix as a byte array.

Returns:
byte[] Latest child version as byte array
CCNTime org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionChildTime (  ) 

Returns the latest version available under this prefix as a CCNTime object.

Returns:
CCNTime Latest child version as CCNTime
static ContentName org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionName ( ContentName  name,
CCNHandle  handle 
) throws IOException [static]

A static method that performs a one-shot call that returns the complete name of the latest version of content with the given prefix.

An alternative route to finding the name of the latest version of a piece of content, rather than using methods in the VersioningProfile to retrieve an arbitrary block of content under that version. Useful when the data under a version is complex in structure.

Parameters:
name ContentName to find the latest version of
handle CCNHandle to use for enumeration
Returns:
ContentName The name supplied to the call with the latest version added.
Exceptions:
IOException 
ContentName org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getName (  ) 

Method to return the ContentName used for enumeration.

Returns:
ContentName returns the prefix under which we are enumerating children.
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getNewData ( long  timeout  ) 

Block and wait for timeout or until new data appears.

See getNewData(boolean, long).

Parameters:
timeout in ms
Returns:
SortedSet<ContentName> Returns the array of single-component content name children that are new to us, or null if we reached the timeout before new data arrived
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getNewData (  ) 

Block and wait as long as it takes for new data to appear.

See getNewData(boolean, long).

Returns:
SortedSet<ContentName> Returns the array of single-component content name children that are new to us. Waits forever if no new data appears
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getNewData ( boolean  threadPoolContext,
long  timeout 
)

Interface to retrieve only new data from enumeration responses as it arrives.

This method blocks and waits for data, but grabs the new data for processing. In threadPoolContext it will in effect remove the data from every other listener who is listening in threadPoolContext, in effect handing the new children to the first consumer to wake up and make the other ones go around again. There is currently no support for more than one simultaneous thread pool.

Parameters:
threadPoolContext Are we getting data in threadPoolContext? (described above).
timeout maximum amount of time to wait, 0 to wait forever.
Returns:
SortedSet<ContentName> Returns the array of single-component content name children that are new to us, or null if we reached the timeout before new data arrived
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getNewDataThreadPool ( long  timeout  ) 

Block and wait for timeout or until new data appears.

See getNewData(boolean, long). Different from getNewData in that new data is shared among all threads accessing this instance of EnumeratedNameList. So if another thread gets the data first, we won't get it.

Parameters:
timeout in ms
Returns:
SortedSet<ContentName> Returns the array of single-component content name children that are new to the list instance if we got it first, or null if we reached the timeout before new data arrived
int org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.handleNameEnumerator ( ContentName  prefix,
ArrayList< ContentName names 
)

Handle responses from CCNNameEnumerator that give us a list of single-component child names.

Filter out the names new to us, add them to our list of known children, postprocess them with processNewChildren(SortedSet<ContentName>), and signal waiters if we have new data.

Parameters:
prefix Prefix used for name enumeration.
names The list of names returned in this name enumeration response.
Returns:
int

Implements org.ccnx.ccn.profiles.nameenum.BasicNameEnumeratorListener.

boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.hasChild ( String  childName  ) 

Returns whether a child is present in the list of known children.

Parameters:
childName String version of a child name to look for
Returns:
boolean Returns true if the name is present in the list of known children.
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.hasChild ( byte[]  childComponent  ) 

Returns true if we know the prefix has a child matching the given name component.

Parameters:
childComponent name component to check for in the stored child names.
Returns:
true if that child is in our list of known children
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.hasChildren (  ) 

Returns true if we have received any responses listing available child names.

If no names have yet been received, this may mean either that responses have not had time to arrive, or there are know children known to available responders.

Returns:
true if we have child names received from enumeration responses
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.hasNewData (  ) 

Returns true if the prefix has new names that have not been handled by the calling application.

Returns:
true if there are new children available to process
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.hasResult (  ) 

Subclasses should override this test to answer true if waiters should break out of a waitForNoUpdatesOrResult loop.

Note that results must be cleared manually using clearResult. Default behavior always returns false. Subclasses probably want to set a variable in processNewChildren that will be read here.

Reimplemented in org.ccnx.ccn.io.content.KeyDirectory.

void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.processNewChildren ( SortedSet< ContentName newChildren  )  [protected]

Method to allow subclasses to do post-processing on incoming names before handing them to customers.

Note that the set handed in here is not the set that will be handed out; only the name objects are the same.

Parameters:
newChildren SortedSet of children available for processing
Returns:
void

Reimplemented in org.ccnx.ccn.io.content.KeyDirectory.

synchronized void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.startEnumerating (  )  throws IOException

Starts enumeration, if we're not enumerating already.

Exceptions:
IOException 
synchronized void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.stopEnumerating (  ) 

Cancels ongoing name enumeration.

Previously-accumulated information about children of this name are still stored and available for use.

Returns:
void
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForChildren (  ) 

Wait (block) for initial data to arrive, possibly forever.

See waitForData(long).

Returns:
void
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForChildren ( long  timeout  ) 

Waits until there is any data at all.

Right now, waits for the first response containing actual children, not just a name enumeration response. That means it could block forever if no children exist in a repository or there are not any applications responding to name enumeration requests. Once we have an initial set of children, this method returns immediately.

Parameters:
timeout Maximum amount of time to wait, if 0, waits forever.
Returns:
void
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildren ( long  timeout  ) 

Wait for new children to arrive.

Parameters:
timeout Maximum amount of time to wait, if 0, waits forever.
Returns:
a boolean value that indicates whether new data was found.
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildren (  ) 

Wait for new children to arrive.

This method does not have a timeout and will wait forever.

Returns:
void
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildren ( boolean  threadPoolContext,
long  timeout 
)

Wait for new children to arrive.

Parameters:
timeout Maximum time to wait for new data.
threadPoolContext Are we waiting in threadPoolContext (i.e. other threads can grab children first) See getNewData(boolean, long).
Returns:
a boolean value that indicates whether new data was found.
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildrenThreadPool ( long  timeout  ) 

Wait for new children to arrive in thread pool context.

See notes about this above.

Parameters:
timeout Maximum amount of time to wait, if 0, waits forever.
Returns:
a boolean value that indicates whether new data was found.
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNoUpdates ( long  timeout  ) 

Wait for new children to arrive until there is a period of length timeout during which no new child arrives.

Parameters:
timeout The maximum amount of time to wait between consecutive children arrivals.
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNoUpdatesOrResult ( long  timeout  ) 

Wait for new children to arrive until there is a period of length timeout during which no new child arrives, or the method hasResult() returns true.

The expectation is that a subclass will monitor incoming updates in its processNewChildren() override method, and in that method, set some sort of flag that will be tested by hasResult(). Note that this method does not currently stop enumeration -- enumeration results will continue to accumulate in the background (and request interests will continue to be sent); callers must call stopEnumerating() to actually terminate enumeration.


Member Data Documentation

Keep track of whether we've ever done enumeration, so we can start it automatically if someone asks us for something not in our cache.

This lets us relax the requirement that callers pre-enumerate just in case. Can't use hasChildren; there might not be any children but we might have tried enumeration already.


The documentation for this class was generated from the following file:
Generated on Fri May 13 16:27:47 2011 for Content-Centric Networking in Java by  doxygen 1.6.3