Blocking and background interface to name enumeration. More...
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< ContentName > | getNewData (boolean threadPoolContext, long timeout) |
Interface to retrieve only new data from enumeration responses as it arrives. | |
SortedSet< ContentName > | getNewData () |
Block and wait as long as it takes for new data to appear. | |
SortedSet< ContentName > | getNewData (long timeout) |
Block and wait for timeout or until new data appears. | |
SortedSet< ContentName > | getNewDataThreadPool (long timeout) |
Block and wait for timeout or until new data appears. | |
SortedSet< ContentName > | getChildren () |
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. |
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.
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.
namePrefix | the ContentName whose children we wish to list. | |
handle | the CCNHandle object for sending interests and receiving content object responses. |
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.)
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. |
IOException |
SortedSet<ContentName> org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getChildren | ( | ) |
Returns single-component ContentName objects containing the name components of the children.
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.
byte [] org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionChildNameComponent | ( | ) |
Returns the latest version available under this prefix as a byte array.
CCNTime org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getLatestVersionChildTime | ( | ) |
Returns the latest version available under this prefix as a CCNTime object.
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.
name | ContentName to find the latest version of | |
handle | CCNHandle to use for enumeration |
IOException |
ContentName org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.getName | ( | ) |
Method to return the ContentName used for enumeration.
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).
timeout | in ms |
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).
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.
threadPoolContext | Are we getting data in threadPoolContext? (described above). | |
timeout | maximum amount of time to wait, 0 to wait forever. |
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.
timeout | in ms |
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.
prefix | Prefix used for name enumeration. | |
names | The list of names returned in this name enumeration response. |
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.
childName | String version of a child name to look for |
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.
childComponent | name component to check for in the stored child names. |
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.
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.
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.
newChildren | SortedSet of children available for processing |
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.
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.
void org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForChildren | ( | ) |
Wait (block) for initial data to arrive, possibly forever.
See waitForData(long).
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.
timeout | Maximum amount of time to wait, if 0, waits forever. |
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildren | ( | long | timeout | ) |
Wait for new children to arrive.
timeout | Maximum amount of time to wait, if 0, waits forever. |
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.
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList.waitForNewChildren | ( | boolean | threadPoolContext, | |
long | timeout | |||
) |
Wait for new children to arrive.
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). |
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.
timeout | Maximum amount of time to wait, if 0, waits forever. |
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.
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.
boolean org.ccnx.ccn.profiles.nameenum.EnumeratedNameList._hasEnumerated = false [protected] |
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.