org.ccnx.ccn.impl.CCNFlowControl Class Reference

This class implements an input buffer for interests and an output buffer for content objects. More...

List of all members.

Classes

class  UnmatchedInterest

Public Types

enum  Shape { STREAM = ("STREAM") }
enum  SaveType { RAW = ("RAW"), REPOSITORY = ("REPOSITORY"), LOCALREPOSITORY = ("LOCALREPOSITORY") }

Public Member Functions

 CCNFlowControl (ContentName name, CCNHandle handle) throws IOException
 CCNFlowControl (String name, CCNHandle handle) throws MalformedContentNameStringException, IOException
 CCNFlowControl (CCNHandle handle) throws IOException
 CCNFlowControl (ContentName name, Interest outstandingInterest, CCNHandle handle) throws IOException
 Filter handler constructor -- an Interest has already come in, and we are writing a stream in response.
void addNameSpace (ContentName name) throws IOException
 Add a new namespace to the controller.
void addNameSpace (String name) throws MalformedContentNameStringException, IOException
 Convenience method.
void addNameSpace (ContentName name, Interest outstandingInterest) throws IOException
 Filter handler method, add a namespace and respond to an existing Interest.
void startWrite (String name, Shape shape) throws MalformedContentNameStringException, IOException
 Convenience method.
void startWrite (ContentName name, Shape shape) throws IOException
 This is used to indicate that it should start a write for a stream with this name, and should do any stream-specific setup.
void removeNameSpace (ContentName name)
 Remove a namespace from those we are listening for interests within.
void removeAllNamespaces ()
 Stop attending to all namespaces.
void close ()
 Helper method to clean up and close.
ContentName getNameSpace (ContentName childName)
 Test if this flow controller is currently serving a particular namespace.
void put (ArrayList< ContentObject > cos) throws IOException
 Add multiple content objects to this flow controller.
void put (ContentObject[] cos) throws IOException
 Add multiple content objects to this flow controller.
void put (ContentName name, ArrayList< ContentObject > cos) throws IOException
 Add namespace and multiple content at the same time.
ContentObject put (ContentName name, ContentObject co) throws IOException
 Add namespace and content at the same time.
ContentObject put (ContentObject co) throws IOException
 Add a content object to this flow controller.
void handleInterests (ArrayList< Interest > interests)
 Match incoming interests with data in the buffer.
boolean handleInterest (Interest i)
 Match an incoming interest with data in the buffer.
void afterPutAction (ContentObject co) throws IOException
 Allow override of action after a ContentObject is sent to ccnd.
void beforeClose () throws IOException
 Allow subclasses to override behavior before a flush.
void afterClose () throws IOException
 Allow subclasses to override behavior after a flush.
void setTimeout (int timeout)
 Set the time to wait for buffer to drain on close.
int getTimeout ()
 Get the current waiting time for the buffer to drain.
void shutdown () throws IOException
 Shutdown operation of this flow controller -- wait for all current data to clear, and unregister all outstanding interests.
CCNHandle getHandle ()
 Gets the CCNHandle used by this controller.
void clearUnmatchedInterests ()
 Remove any currently buffered unmatched interests.
void logUnmatchedInterests (String logMessage)
 Debugging function to log unmatched interests.
void enable ()
 Re-enable disabled buffering.
void setCapacity (int value)
 Change the capacity for the maximum amount of data to buffer before causing putters to block.
void setMaximumCapacity ()
 Set the capacity to the maximum possible value, Integer.MAX_VALUE.
void setInterestCapacity (int value)
 Change the maximum number of unmatched interests to buffer.
int getCapacity ()
 What is the total capacity of this flow controller?
int size ()
 Get the number of objects this flow controller is currently holding.
int availableCapacity ()
 Get the amount of remaining space available in this flow controller's buffer.
void remove (ContentObject co)
 Remove a ContentObject from the set buffered by this flow controller, either because we're done with it, or because we don't want to buffer it anymore.
void clear ()
 Remove all the held objects from this buffer.
void disable ()
 Disable buffering.
SaveType saveType ()
 Help users determine what type of flow controller this is.

Protected Member Functions

void waitForPutDrain () throws IOException
 Implements a wait until all outstanding data has been drained from the flow controller.

Protected Attributes

CCNHandle _handle = null
int _timeout = SystemConfiguration.FC_TIMEOUT
int _capacity = DEFAULT_CAPACITY
long _nOut = 0
TreeMap< ContentName,
ContentObject
_holdingArea = new TreeMap<ContentName, ContentObject>()
InterestTable< UnmatchedInterest > _unmatchedInterests = new InterestTable<UnmatchedInterest>()
HashSet< ContentName_filteredNames = new HashSet<ContentName>()

Static Protected Attributes

static final int DEFAULT_CAPACITY = CCNSegmenter.HOLD_COUNT + 1
static final int DEFAULT_INTEREST_CAPACITY = 40
static final int PURGE = 4000

Detailed Description

This class implements an input buffer for interests and an output buffer for content objects.

ccnd will not accept data (content objects) except in response to an interest. This class allows data sources such as output streams to generate content objects speculatively, and buffers them until interests arrive from ccnd. Equally when interests come in from ccnd before the content has been generated this class will buffer the interests until the content is generated.

Implements a capacity limit in the holding buffer. If the buffer consumption reaches the specified capacity, any subsequent put will block until there is more room in the buffer. Note that this means that the buffer may hold as many objects as the capacity value, and the object held by any later blocked put is extra, meaning the total number of objects waiting to be sent is not bounded by the capacity alone. Currently this is only per "flow controller". There is nothing to stop multiple streams writing to the repo for instance to independently all fill their buffers and cause a lot of memory to be used.

Also implements a limited capacity for held interests.

The buffer emptying policy in "afterPutAction" can be overridden by subclasses to implement a different way of draining the buffer. This is used by the repo client to allow objects to remain in the buffer until they are acked.


Constructor & Destructor Documentation

org.ccnx.ccn.impl.CCNFlowControl.CCNFlowControl ( ContentName  name,
CCNHandle  handle 
) throws IOException
Parameters:
name automatically handles this namespace
handle CCNHandle - created if null
Exceptions:
IOException if handle can't be created
org.ccnx.ccn.impl.CCNFlowControl.CCNFlowControl ( String  name,
CCNHandle  handle 
) throws MalformedContentNameStringException, IOException
Parameters:
name automatically handles this namespace
handle CCNHandle - created if null
Exceptions:
MalformedContentNameStringException if namespace is malformed
IOException if handle can't be created
org.ccnx.ccn.impl.CCNFlowControl.CCNFlowControl ( CCNHandle  handle  )  throws IOException
Parameters:
handle CCNHandle - created if null
Exceptions:
IOException if handle can't be created
org.ccnx.ccn.impl.CCNFlowControl.CCNFlowControl ( ContentName  name,
Interest  outstandingInterest,
CCNHandle  handle 
) throws IOException

Filter handler constructor -- an Interest has already come in, and we are writing a stream in response.

So we can write out the first matching block that we get as soon as we get it (in response to this preexisting interest). Caller has the responsibilty to ensure that this Interest is only handed to one CCNFlowControl to emit a block.

Parameters:
name an initial namespace to handle
outstandingInterest an Interest we have already received; the flow controller will immediately emit the first matching block
handle the handle to use. May need to be the same handle that the Interest was received on.

Member Function Documentation

void org.ccnx.ccn.impl.CCNFlowControl.addNameSpace ( ContentName  name,
Interest  outstandingInterest 
) throws IOException

Filter handler method, add a namespace and respond to an existing Interest.

Exceptions:
IOException 
void org.ccnx.ccn.impl.CCNFlowControl.addNameSpace ( String  name  )  throws MalformedContentNameStringException, IOException

Convenience method.

See also:
addNameSpace(ContentName)
Parameters:
name Namespace to be added in string form.
void org.ccnx.ccn.impl.CCNFlowControl.addNameSpace ( ContentName  name  )  throws IOException

Add a new namespace to the controller.

The controller will register a filter with ccnd to receive interests in this namespace.

Parameters:
name 
Exceptions:
IOException 
void org.ccnx.ccn.impl.CCNFlowControl.afterClose (  )  throws IOException

Allow subclasses to override behavior after a flush.

Exceptions:
IOException 

Reimplemented in org.ccnx.ccn.impl.CCNFlowServer, org.ccnx.ccn.impl.repo.RepositoryFlowControl, and org.ccnx.ccn.impl.repo.RepositoryInternalFlowControl.

void org.ccnx.ccn.impl.CCNFlowControl.afterPutAction ( ContentObject  co  )  throws IOException

Allow override of action after a ContentObject is sent to ccnd.

NOTE: Don't need to sync on holding area because this is only called within holding area sync NOTE: Any subclass overriding this method must either make sure to call it eventually (in a _holdingArea sync) or understand the use of _nOut and update it appropriately.

Parameters:
co ContentObject to remove from flow controller.
Exceptions:
IOException may be thrown by overriding subclasses

Reimplemented in org.ccnx.ccn.impl.CCNFlowServer.

int org.ccnx.ccn.impl.CCNFlowControl.availableCapacity (  ) 

Get the amount of remaining space available in this flow controller's buffer.

Returns:
the number of additional objects that can currently be written to this controller
void org.ccnx.ccn.impl.CCNFlowControl.beforeClose (  )  throws IOException

Allow subclasses to override behavior before a flush.

Exceptions:
IOException 
void org.ccnx.ccn.impl.CCNFlowControl.disable (  ) 

Disable buffering.

Warning - calling this risks packet drops. It should only be used for tests or other special circumstances in which you "know what you are doing".

void org.ccnx.ccn.impl.CCNFlowControl.enable (  ) 

Re-enable disabled buffering.

Buffering is enabled by default.

int org.ccnx.ccn.impl.CCNFlowControl.getCapacity (  ) 

What is the total capacity of this flow controller?

Returns:
the total capacity of this flow controller; in other words the number of segments that can be written to it before writes will block
CCNHandle org.ccnx.ccn.impl.CCNFlowControl.getHandle (  ) 

Gets the CCNHandle used by this controller.

Returns:
a CCNHandle
ContentName org.ccnx.ccn.impl.CCNFlowControl.getNameSpace ( ContentName  childName  ) 

Test if this flow controller is currently serving a particular namespace.

Parameters:
childName ContentName of test space
Returns:
The actual namespace the flow controller is using if it does serve the child namespace. null otherwise.
int org.ccnx.ccn.impl.CCNFlowControl.getTimeout (  ) 

Get the current waiting time for the buffer to drain.

Returns:
timeout in milliseconds
boolean org.ccnx.ccn.impl.CCNFlowControl.handleInterest ( Interest  i  ) 

Match an incoming interest with data in the buffer.

If the interest doesn't match it is buffered awaiting potential later incoming data which may match it. This method returns 0 if the interest was null.

Implements org.ccnx.ccn.CCNFilterListener.

void org.ccnx.ccn.impl.CCNFlowControl.handleInterests ( ArrayList< Interest interests  ) 

Match incoming interests with data in the buffer.

If the interest doesn't match it is buffered awaiting potential later incoming data which may match it.

Note that this method is used for testing only, since the interest callback only takes one interest

ContentObject org.ccnx.ccn.impl.CCNFlowControl.put ( ContentObject  co  )  throws IOException

Add a content object to this flow controller.

It won't be sent to ccnd immediately unless a currently waiting interest matches it.

Parameters:
co ContentObject to put
Returns:
the ContentObject put
Exceptions:
IOException if the put fails

Reimplemented in org.ccnx.ccn.impl.repo.RepositoryInternalFlowControl.

ContentObject org.ccnx.ccn.impl.CCNFlowControl.put ( ContentName  name,
ContentObject  co 
) throws IOException

Add namespace and content at the same time.

See also:
addNameSpace(ContentName)
put(ContentObject)
Parameters:
name ContentName of namespace
co ContentObject
Returns:
the ContentObject put
Exceptions:
IOException if the put fails
void org.ccnx.ccn.impl.CCNFlowControl.put ( ContentName  name,
ArrayList< ContentObject cos 
) throws IOException

Add namespace and multiple content at the same time.

See also:
addNameSpace(ContentName)
put(ArrayList)
Parameters:
name ContentName of namespace
cos ArrayList of ContentObjects
Exceptions:
IOException if the put fails
void org.ccnx.ccn.impl.CCNFlowControl.put ( ContentObject[]  cos  )  throws IOException

Add multiple content objects to this flow controller.

See also:
put(ContentObject)
Parameters:
cos Array of ContentObjects
Exceptions:
IOException if the put fails
void org.ccnx.ccn.impl.CCNFlowControl.put ( ArrayList< ContentObject cos  )  throws IOException

Add multiple content objects to this flow controller.

See also:
put(ContentObject)
Parameters:
cos ArrayList of ContentObjects to put
Exceptions:
IOException if the put fails
void org.ccnx.ccn.impl.CCNFlowControl.remove ( ContentObject  co  ) 

Remove a ContentObject from the set buffered by this flow controller, either because we're done with it, or because we don't want to buffer it anymore.

Need a way to get the CO to remove; might want a remove(ContentName) or something like it.

void org.ccnx.ccn.impl.CCNFlowControl.removeNameSpace ( ContentName  name  ) 

Remove a namespace from those we are listening for interests within.

For now we don't have any way to remove a part of a registered namespace from buffering so we only allow removal of a namespace if it actually matches something that was registered

Parameters:
name 
void org.ccnx.ccn.impl.CCNFlowControl.setCapacity ( int  value  ) 

Change the capacity for the maximum amount of data to buffer before causing putters to block.

The capacity value is the number of content objects that will be buffered.

Parameters:
value number of content objects.
void org.ccnx.ccn.impl.CCNFlowControl.setInterestCapacity ( int  value  ) 

Change the maximum number of unmatched interests to buffer.

Parameters:
value number of interests
void org.ccnx.ccn.impl.CCNFlowControl.setTimeout ( int  timeout  ) 

Set the time to wait for buffer to drain on close.

Parameters:
timeout timeout in milliseconds
void org.ccnx.ccn.impl.CCNFlowControl.shutdown (  )  throws IOException

Shutdown operation of this flow controller -- wait for all current data to clear, and unregister all outstanding interests.

Do *not* shut down the handle; we might not own it.

Exceptions:
IOException if buffer doesn't drain within timeout
int org.ccnx.ccn.impl.CCNFlowControl.size (  ) 

Get the number of objects this flow controller is currently holding.

Returns:
the number of objects (segments) in the buffer
void org.ccnx.ccn.impl.CCNFlowControl.startWrite ( ContentName  name,
Shape  shape 
) throws IOException

This is used to indicate that it should start a write for a stream with this name, and should do any stream-specific setup.

Parameters:
name 
shape currently unused and may be deprecated in the future. Can only be Shape.STREAM
Exceptions:
MalformedContentNameStringException if name is malformed
IOException used by subclasses

Reimplemented in org.ccnx.ccn.impl.repo.RepositoryFlowControl.

void org.ccnx.ccn.impl.CCNFlowControl.startWrite ( String  name,
Shape  shape 
) throws MalformedContentNameStringException, IOException

Convenience method.

See also:
startWrite(ContentName, Shape)
Exceptions:
MalformedContentNameStringException if name is malformed
void org.ccnx.ccn.impl.CCNFlowControl.waitForPutDrain (  )  throws IOException [protected]

Implements a wait until all outstanding data has been drained from the flow controller.

This is required on close to ensure that all data is actually sent to ccnd.

Exceptions:
IOException if the data has not been drained after a reasonable period

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