org.ccnx.ccn.impl.CCNNetworkManager Class Reference

The low level interface to ccnd. More...

Inheritance diagram for org.ccnx.ccn.impl.CCNNetworkManager:

List of all members.

Public Types

enum  NetworkProtocol { UDP = (17), TCP = (6) }
 Definitions for which network protocol to use. More...
enum  StatsEnum {
  Puts = ("ContentObjects", "The number of put calls"), Gets = ("ContentObjects", "The number of get calls"), WriteInterest = ("calls", "The number of calls to write(Interest)"), WriteObject = ("calls", "The number of calls to write(ContentObject)"),
  WriteErrors = ("count", "Error count for writeInner()"), WriteUnderflows = ("count", "The count of times when the bytes written to the channel < buffer size"), ExpressInterest = ("calls", "The number of calls to expressInterest"), CancelInterest = ("calls", "The number of calls to cancelInterest"),
  DeliverInterest = ("calls", "The number of calls to deliverInterest"), DeliverContent = ("calls", "The number of calls to cancelInterest"), DeliverInterestMatchingFilters = ("calls", "Count of the number of calls to interest handlers"), DeliverContentMatchingInterests = ("calls", "Count of the number of calls to content handlers"),
  DeliverContentFailed = ("calls", "The number of content deliveries that failed"), DeliverInterestFailed = ("calls", "The number of interest deliveries that failed"), InterestHandlerTime = ("nanos", "The average amount of time spent in interest handlers"), ContentHandlerTime = ("nanos", "The average amount of time spent in content handlers"),
  ReceiveObject = ("objects", "Receive count of ContentObjects from channel"), ReceiveInterest = ("interests", "Receive count of Interests from channel"), ReceiveUnknown = ("calls", "Receive count of unknown type from channel"), ReceiveErrors = ("errors", "Number of errors from the channel in run() loop"),
  ContentObjectsIgnored = ("ContentObjects", "The number of ContentObjects that are never handled"), HandleInterest = ("interests", "Number of calls to RepositoryInterestHandler.handleInterest()"), HandleInterestErrors = ("errors", "Errors in handleInterest()"), HandleInterestCommands = ("interests", "Number of command interests to handleInterest()"),
  HandleInterestStartWriteReceived = ("interests", "Number of start writes to handleInterest()"), HandleInterestStartWriteProcessed = ("interests", "Number of start writes processed by handleInterest()"), HandleInterestStartWriteIgnored = ("interests", "Number of start writes ignored in handleInterest()"), HandleInterestStartWriteErrors = ("errors", "Error count in startWrite()"),
  HandleInterestNameEnumReceived = ("interests", "Number of name enums to handleInterest()"), HandleInterestNameEnumProcessed = ("interests", "Number of name enums processed in handleInterest()"), HandleInterestNameEnumIgnored = ("interests", "Number of name enums ignored in handleInterest()"), HandleInterestCheckedWriteReceived = ("interests", "Number of checked write to handleInterest()"),
  HandleInterestCheckedWriteProcessed = ("interests", "Number of checked write processed in handleInterest()"), HandleInterestCheckedWriteIgnored = ("interests", "Number of checked write ignored in handleInterest()"), HandleInterestBulkImportReceived = ("interests", "Number of bulk imports to handleInterest()"), HandleInterestBulkImportProcessed = ("interests", "Number of bulk imports processed in handleInterest()"),
  HandleInterestBulkImportIgnored = ("interests", "Number of bulk imports ignored in handleInterest()"), HandleInterestUncategorized = ("interests", "Number of uncategorized interests to handleInterest()"), HandleInterestDuplicateRequests = ("interests", "Number of duplicate interests to handleInterest()"), HandleInterestWriteSuspended = ("interests", "Number of write suspended interests to handleInterest()"),
  HandleInterestStartWritePolicyHandlers = ("responses", "Number of RepositoryPolicyHandler created for StartWrite"), HandleInterestStartWriteExpressInterest = ("responses", "Number of expressInterests created for StartWrite"), HandleInterestNameEnumResponses = ("responses", "Number of responses sent for Name Enums"), HandleContent = ("objects", "Calls to ResponsitoryDataListener.handleContent()"),
  HandleContentHandleData = ("objects", "Calls to handleData in RepositoryDataListener"), HandleContentExpressInterest = ("interests", "Number of interests expressed in handleContent()"), HandleContentCancelInterest = ("interests", "Number of interests cancelled"), HandleContentExpressInterestErrors = ("errors", "Number of errors expressing interests in handleContent()"),
  Receive = ("ContentObjects", "The number of objects received in handleContent"), ReceiveVersionNumberError = ("Errors", "Errors parsing VersionNumber from content name"), ReceiveReturnInterest = ("interests", "Number of non-null interests returned from receive()"), ReceiveIgnored = ("count", "Count of objects ignored because version was out-of-bounds"),
  ReceiveDuplicates = ("count", "Count of duplicate version numbers received"), ReceiveUnique = ("count", "Count of objects with unique version numbers received"), ReceiveNoPendingInterest = ("Errors", "Received object did not match a pending interest in _interestMap"), Rebuild = ("count", "Calls to rebuild()"),
  RebuileShiftLeft = ("count", "Number of left-shift rebuilds"), RebuildShiftRight = ("count", "Number of right-shift rebuilds"), RebuildCreateLeft = ("count", "Number of create left neighbor rebuilds"), RebuildCreateRight = ("count", "Number of create right neighbor rebuilds"),
  RebuildInsertLeft = ("count", "Number of inserts to left rebuilds"), RebuildInsertRight = ("count", "Number of inserts to right rebuilds"), RebuildRollLeft = ("count", "Number of roll left rebuilds"), RebuildRollRight = ("count", "Number of roll right rebuilds"),
  SendInterest = ("count", "Interests sent (not counting ReceiveReturnInterest)"), CancelInterest = ("count", "Interests cancelled"), SendInterestErrors = ("errors", "Errors calling expressInterest()")
}

Public Member Functions

 CCNNetworkManager (KeyManager keyManager) throws IOException
 The constructor.
void shutdown ()
 Shutdown the connection to ccnd and all threads associated with this network manager.
NetworkProtocol getProtocol ()
 Get the protocol this network manager is using.
void setTap (String pathname) throws IOException
 Turns on writing of all packets to a file for test/debug Overrides any previous setTap or environment/property setting.
PublisherPublicKeyDigest getCCNDId () throws IOException
 Get the CCN Name of the 'ccnd' we're connected to.
KeyManager getKeyManager ()
void setKeyManager (KeyManager manager)
ContentObject put (ContentObject co) throws IOException, InterruptedException
 Write content to ccnd.
ContentObject get (Interest interest, long timeout) throws IOException, InterruptedException
 get content matching an interest from ccnd.
void expressInterest (Object caller, Interest interest, Object handler) throws IOException
 We express interests to the ccnd and register them within the network manager.
void cancelInterest (Object caller, Interest interest, Object handler)
 Cancel this query.
void setInterestFilter (Object caller, ContentName filter, Object handler) throws IOException
 Register a standing interest filter with callback to receive any matching interests seen.
void setInterestFilter (Object caller, ContentName filter, Object callbackHandler, Integer registrationFlags) throws IOException
 Register a standing interest filter with callback to receive any matching interests seen.
ArrayList< ContentNamegetRegisteredPrefixes ()
 Get current list of prefixes that are actually registered on the face associated with this netmanager.
void cancelInterestFilter (Object caller, ContentName filter, Object handler)
 Unregister a standing interest filter.
void write (Interest interest) throws ContentEncodingException
 Write an interest directly to ccnd Don't do this unless you know what you are doing! See CCNHandle.expressInterest for the proper way to output interests to the network.
void run ()
 Reader thread: this thread will handle reading datagrams and perform callbacks after reading complete packets.
void dumpHandlerStackTrace (String message)
 Diagnostic routine to get a handler stack trace in time of suspected problem.
CCNStats getStats ()

Static Public Attributes

static final int DEFAULT_AGENT_PORT = 9695
static final String DEFAULT_AGENT_HOST = "localhost"
static final String PROP_AGENT_PORT = "ccn.agent.port"
static final String PROP_AGENT_HOST = "ccn.agent.host"
static final String PROP_TAP = "ccn.tap"
static final String ENV_TAP = "CCN_TAP"
static final int PERIOD = 2000
static final int MAX_PERIOD = PERIOD * 8
static final String KEEPALIVE_NAME = "/HereIAm"
static final int THREAD_LIFE = 8
static final int MAX_PAYLOAD = 8800
static final boolean DEFAULT_PREFIX_REG = true

Protected Member Functions

void finalize () throws Throwable
RegisteredPrefix getRegisteredPrefix (ContentName prefix)
 Merge prefixes so we only add a new one when it doesn't have a common ancestor already registered.
void write (ContentObject data) throws ContentEncodingException
void deliverInterest (InterestRegistration ireg, Interest interest)
 Internal delivery of interests to pending filter handlers.
void deliverContent (ContentObject co)
 Deliver data to all blocked getters and registered interests.
PublisherPublicKeyDigest fetchCCNDId (CCNNetworkManager mgr, KeyManager keyManager) throws IOException
String formatMessage (String message)

Protected Attributes

final int _managerId
final String _managerIdString
Integer _faceID = null
CCNDIdGetter _getter = null
Thread _thread = null
CCNNetworkChannel _channel = null
boolean _run = true
FileOutputStream _tapStreamOut = null
FileOutputStream _tapStreamIn = null
long _lastHeartbeat = 0
int _port = DEFAULT_AGENT_PORT
String _host = DEFAULT_AGENT_HOST
NetworkProtocol _protocol = SystemConfiguration.AGENT_PROTOCOL
KeyManager _keyManager
InterestTable
< InterestRegistration
_myInterests = new InterestTable<InterestRegistration>()
InterestTable< Filter_myFilters = new InterestTable<Filter>()
boolean _usePrefixReg = DEFAULT_PREFIX_REG
PrefixRegistrationManager _prefixMgr = null
TreeMap< ContentName,
RegisteredPrefix
_registeredPrefixes = new TreeMap<ContentName, RegisteredPrefix>()
Semaphore _registrationChangeInProgress = new Semaphore(1)
Timer _periodicTimer = null
Object _timersSetupLock = new Object()
Boolean _timersSetup = false
boolean _inHandler = false
long _timeForThisHandler
long _currentHandler = 0
long _lastHandler = -1
InterestRegistration _beingDelivered = null
Object _beingDeliveredLock = new Object()
CCNEnumStats< StatsEnum > _stats = new CCNEnumStats<StatsEnum>(StatsEnum.Puts)

Static Protected Attributes

static final AtomicInteger _managerIdCount = new AtomicInteger(0)
static Integer _idSyncer = new Integer(0)
static PublisherPublicKeyDigest _ccndId = null

Classes

class  CallbackHandlerRegistration
 Generic superclass for registration objects that may have a callback handler. More...
class  CCNDIdGetter
class  Filter
 Record of a filter describing portion of namespace for which this application can respond to interests. More...
class  InterestRegistration
 Record of Interest This is the mechanism that calls a user contentHandler when a ContentObject that matches their interest is received by the network manager. More...
class  PeriodicWriter
 Do scheduled interest, registration refreshes, and UDP heartbeats.
class  RegisteredPrefix
 Keep track of prefixes that are actually registered with ccnd (as opposed to Filters used to dispatch interests). More...


Detailed Description

The low level interface to ccnd.

This provides the main data API between the java library and ccnd. Access to ccnd can be either via TCP or UDP. This is controlled by the SystemConfiguration.AGENT_PROTOCOL property and currently defaults to TCP.

The write API is implemented by methods of this class but users should typically access these via the CCNHandle API rather than directly.

The read API is implemented in a thread that continuously reads from ccnd. Whenever the thread reads a complete packet, it calls back a handler or handlers that have been previously setup by users. Since there is only one callback thread, users must take care to avoid slow or blocking processing directly within the callback. This is similar to the restrictions on the event dispatching thread in Swing. The setup of callback handlers should also normally be done via the CCNHandle API.

The class also has a separate timer process which is used to refresh unsatisfied interests and to keep UDP connections alive by sending a heartbeat packet at regular intervals.

The class attempts to notice when a ccnd has died and to reconnect to a ccnd when it is restarted.

It also handles the low level output "tap" functionality - this allows inspection or logging of all the communications with ccnd.


Member Enumeration Documentation

Definitions for which network protocol to use.

This allows overriding the current default.


Constructor & Destructor Documentation

org.ccnx.ccn.impl.CCNNetworkManager.CCNNetworkManager ( KeyManager  keyManager  )  throws IOException

The constructor.

Attempts to connect to a ccnd at the currently specified port number

Exceptions:
IOException if the port is invalid


Member Function Documentation

NetworkProtocol org.ccnx.ccn.impl.CCNNetworkManager.getProtocol (  ) 

Get the protocol this network manager is using.

Returns:
the protocol

void org.ccnx.ccn.impl.CCNNetworkManager.setTap ( String  pathname  )  throws IOException

Turns on writing of all packets to a file for test/debug Overrides any previous setTap or environment/property setting.

Pass null to turn off tap.

Parameters:
pathname name of tap file

PublisherPublicKeyDigest org.ccnx.ccn.impl.CCNNetworkManager.getCCNDId (  )  throws IOException

Get the CCN Name of the 'ccnd' we're connected to.

Returns:
the CCN Name of the 'ccnd' this CCNNetworkManager is connected to.
Exceptions:
IOException 

ContentObject org.ccnx.ccn.impl.CCNNetworkManager.put ( ContentObject  co  )  throws IOException, InterruptedException

Write content to ccnd.

Parameters:
co the content
Returns:
the same content that was passed into the method
TODO - code doesn't actually throw either of these exceptions but need to fix upper level code to compensate when they are removed.
Exceptions:
IOException 
InterruptedException 

ContentObject org.ccnx.ccn.impl.CCNNetworkManager.get ( Interest  interest,
long  timeout 
) throws IOException, InterruptedException

get content matching an interest from ccnd.

Expresses an interest, waits for ccnd to return matching the data, then removes the interest and returns the data to the caller.

Parameters:
interest the interest
timeout time to wait for return in ms
Returns:
ContentObject or null on timeout
Exceptions:
IOException on incorrect interest data
InterruptedException if process is interrupted during wait

void org.ccnx.ccn.impl.CCNNetworkManager.expressInterest ( Object  caller,
Interest  interest,
Object  handler 
) throws IOException

We express interests to the ccnd and register them within the network manager.

Parameters:
caller must not be null
interest the interest
handler handler to callback on receipt of data
Exceptions:
IOException on incorrect interest

void org.ccnx.ccn.impl.CCNNetworkManager.cancelInterest ( Object  caller,
Interest  interest,
Object  handler 
)

Cancel this query.

Parameters:
caller must not be null
interest 
handler 

void org.ccnx.ccn.impl.CCNNetworkManager.setInterestFilter ( Object  caller,
ContentName  filter,
Object  handler 
) throws IOException

Register a standing interest filter with callback to receive any matching interests seen.

Any interests whose prefix completely matches "filter" will be delivered to the handler. Also if this filter matches no currently registered prefixes, register its prefix with ccnd.

Parameters:
caller must not be null
filter ContentName containing prefix of interests to match
handler a CCNInterestHandler
Exceptions:
IOException 

void org.ccnx.ccn.impl.CCNNetworkManager.setInterestFilter ( Object  caller,
ContentName  filter,
Object  callbackHandler,
Integer  registrationFlags 
) throws IOException

Register a standing interest filter with callback to receive any matching interests seen.

Any interests whose prefix completely matches "filter" will be delivered to the handler. Also if this filter matches no currently registered prefixes, register its prefix with ccnd.

Note that this is mismatched with deregistering prefixes. When registering, we wait for the registration to complete before continuing, but when deregistering we don't.

Parameters:
caller must not be null
filter ContentName containing prefix of interests to match
callbackHandler a CCNInterestHandler
registrationFlags to use for this registration.
Exceptions:
IOException <<<<<<< HEAD
TODO - use of "caller" should be reviewed - don't believe this is currently serving serving any useful purpose. ======= >>>>>>> 8ae13f2... refs #100427 test upping netmanager thread priority

ArrayList<ContentName> org.ccnx.ccn.impl.CCNNetworkManager.getRegisteredPrefixes (  ) 

Get current list of prefixes that are actually registered on the face associated with this netmanager.

Returns:
the list of prefixes as an ArrayList of ContentNames

void org.ccnx.ccn.impl.CCNNetworkManager.cancelInterestFilter ( Object  caller,
ContentName  filter,
Object  handler 
)

Unregister a standing interest filter.

If we are the last user of a filter registered with ccnd, we request a deregistration with ccnd but we don't need to wait for it to complete.

Parameters:
caller must not be null
filter currently registered filter
handler the handler registered to it

RegisteredPrefix org.ccnx.ccn.impl.CCNNetworkManager.getRegisteredPrefix ( ContentName  prefix  )  [protected]

Merge prefixes so we only add a new one when it doesn't have a common ancestor already registered.

Must be called with _registeredPrefixes locked

We decided that if we are registering a prefix that already has another prefix that is an descendant of it registered, we won't bother to now deregister that prefix because it would be complicated to do that and doesn't hurt anything.

Notes on efficiency: First of all I'm not sure how important efficiency is in this routine because it may not be too common to have many different prefixes registered. Currently we search all prefixes until we see one that is past the one we want to register before deciding there are none that encapsulate it. There may be a more efficient way to code this that is still correct but I haven't come up with it.

Parameters:
prefix 
Returns:
prefix that incorporates or matches this one or null if none found

void org.ccnx.ccn.impl.CCNNetworkManager.write ( Interest  interest  )  throws ContentEncodingException

Write an interest directly to ccnd Don't do this unless you know what you are doing! See CCNHandle.expressInterest for the proper way to output interests to the network.

Parameters:
interest 
Exceptions:
ContentEncodingException 

void org.ccnx.ccn.impl.CCNNetworkManager.deliverInterest ( InterestRegistration  ireg,
Interest  interest 
) [protected]

Internal delivery of interests to pending filter handlers.

Parameters:
ireg 

void org.ccnx.ccn.impl.CCNNetworkManager.deliverContent ( ContentObject  co  )  [protected]

Deliver data to all blocked getters and registered interests.

Parameters:
co 


The documentation for this class was generated from the following file:

Generated on Thu Feb 16 00:44:51 2012 for Content-Centric Networking in Java by  doxygen 1.5.6