org.ccnx.ccn.CCNHandle Class Reference

The core class encapsulating a Java interface to the CCN network. More...

List of all members.

Public Member Functions

CCNNetworkManager getNetworkManager ()
 Retrieve this handle's network manager.
KeyManager keyManager ()
 Change the KeyManager this CCNHandle is using.
PublisherPublicKeyDigest getDefaultPublisher ()
 Get the publisher ID of the default public key we use to sign content.
ContentObject get (ContentName name, long timeout) throws IOException
 Helper method wrapped around CCNBase.get(Interest, long).
ContentObject get (ContentName name, PublisherPublicKeyDigest publisher, long timeout) throws IOException
 Helper method wrapped around CCNBase.get(Interest, long).
ContentObject get (Interest interest, long timeout) throws IOException
 Get a single piece of content from CCN.
ContentObject put (ContentObject co) throws IOException
 Put a single content object into the network.
void registerFilter (ContentName filter, CCNFilterListener callbackListener) throws IOException
 Register a standing interest filter with callback to receive any matching interests seen.
void unregisterFilter (ContentName filter, CCNFilterListener callbackListener)
 Unregister a standing interest filter.
void expressInterest (Interest interest, CCNInterestListener listener) throws IOException
 Query, or express an interest in particular content.
void cancelInterest (Interest interest, CCNInterestListener listener)
 Cancel this interest.
void close ()
 Shutdown the handle and its associated resources.
ContentVerifier defaultVerifier ()
 Provide a default verification implementation for users that do not want to alter the standard verification process.

Static Public Member Functions

static CCNHandle open () throws ConfigurationException, IOException
 Create a new CCNHandle, opening a new connection to the CCN network.
static CCNHandle open (KeyManager keyManager) throws IOException
 Create a new CCNHandle, opening a new connection to the CCN network, and specifying the KeyManager it should use.
static CCNHandle getHandle ()
 Returns a static CCNHandle that is made available as a default.

Protected Member Functions

 CCNHandle (KeyManager keyManager) throws IOException
 Create a CCNHandle using the specified KeyManager.
 CCNHandle () throws ConfigurationException, IOException
 Create a CCNHandle using the default KeyManager for this user.
 CCNHandle (boolean useNetwork)
 For testing only.
String formatMessage (String message)

Static Protected Member Functions

static synchronized CCNHandle create () throws ConfigurationException, IOException
 Internal synchronized creation method.

Protected Attributes

final KeyManager _keyManager
final int _handleId
final String _handleIdString
final CCNNetworkManager _networkManager
 A CCNNetworkManager embodies a connection to ccnd.
final Object _openLock = new Object()
boolean _isOpen = false

Static Protected Attributes

static CCNHandle _handle = null
static final AtomicInteger _handleIdCount = new AtomicInteger(0)

Detailed Description

The core class encapsulating a Java interface to the CCN network.

It implements the CCNBase core methods for reading and writing to CCN, using an encapsulated CCNNetworkManager to interface with the local CCN agent. It encapsulates a KeyManager to interface with the user's collection of signing and verification keys. A typical application may have one CCNHandle or many; each encapsulates a single connection to the local CCN agent.

Once a handle is closed, it cannot be used anymore. It will throw an IOException in those cases.


Constructor & Destructor Documentation

org.ccnx.ccn.CCNHandle.CCNHandle ( KeyManager  keyManager  )  throws IOException [protected]

Create a CCNHandle using the specified KeyManager.

Parameters:
keyManager the KeyManager to use. cannot be null.
Exceptions:
IOException 
org.ccnx.ccn.CCNHandle.CCNHandle (  )  throws ConfigurationException, IOException [protected]

Create a CCNHandle using the default KeyManager for this user.

Exceptions:
ConfigurationException if there is an issue in the user or system configuration which we cannot overcome without outside intervention. See the error message for details.
IOException if we encounter an error reading system, configuration, or keystore data that we expect to be well-formed.

Member Function Documentation

void org.ccnx.ccn.CCNHandle.cancelInterest ( Interest  interest,
CCNInterestListener  listener 
)

Cancel this interest.

Parameters:
interest 
listener Used to distinguish the same interest requested by more than one listener.

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.profiles.versioning.VersioningHelper.SinkHandle.

static synchronized CCNHandle org.ccnx.ccn.CCNHandle.create (  )  throws ConfigurationException, IOException [static, protected]

Internal synchronized creation method.

Returns:
a new CCNHandle
Exceptions:
ConfigurationException if there is an issue in the user or system configuration which we cannot overcome without outside intervention. See the error message for details.
IOException if we encounter an error reading system, configuration, or keystore data that we expect to be well-formed.
ContentVerifier org.ccnx.ccn.CCNHandle.defaultVerifier (  ) 

Provide a default verification implementation for users that do not want to alter the standard verification process.

Returns:
a basic ContentVerifier that simply verifies that a piece of content was correctly signed by the key it claims to have been published by, implying no semantics about the "trustworthiness" of that content or its publisher
void org.ccnx.ccn.CCNHandle.expressInterest ( Interest  interest,
CCNInterestListener  listener 
) throws IOException

Query, or express an interest in particular content.

This request is sent out over the CCN to other nodes. On any results, the callbackListener if given, is notified. Results may also be cached in a local repository for later retrieval by get(). Get and expressInterest could be implemented as a single function that might return some content immediately and others by callback; we separate the two for now to simplify the interface.

Pass it on to the CCNInterestManager to forward to the network. Also express it to the repositories we manage, particularly the primary. Each might generate their own CCNQueryDescriptor, so we need to group them together.

Parameters:
interest 
listener 

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.profiles.versioning.VersioningHelper.SinkHandle.

ContentObject org.ccnx.ccn.CCNHandle.get ( Interest  interest,
long  timeout 
) throws IOException

Get a single piece of content from CCN.

This is a blocking get, it will return when matching content is found or it times out, whichever comes first.

Parameters:
interest 
timeout 
Returns:
the content object
Exceptions:
IOException 

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.CCNLibraryTestHarness.

ContentObject org.ccnx.ccn.CCNHandle.get ( ContentName  name,
PublisherPublicKeyDigest  publisher,
long  timeout 
) throws IOException

Helper method wrapped around CCNBase.get(Interest, long).

Parameters:
name name to query for
publisher the desired publisher for the content
timeout timeout for get
Returns:
the object retrieved, or null if timed out
Exceptions:
IOException on error
See also:
CCNBase.get(Interest, long)
ContentObject org.ccnx.ccn.CCNHandle.get ( ContentName  name,
long  timeout 
) throws IOException

Helper method wrapped around CCNBase.get(Interest, long).

Parameters:
name name to query for
timeout timeout for get
Returns:
the object retrieved, or null if timed out
Exceptions:
IOException on error
See also:
CCNBase.get(Interest, long)

Reimplemented in org.ccnx.ccn.test.CCNLibraryTestHarness.

PublisherPublicKeyDigest org.ccnx.ccn.CCNHandle.getDefaultPublisher (  ) 

Get the publisher ID of the default public key we use to sign content.

Returns:
our default publisher ID
static CCNHandle org.ccnx.ccn.CCNHandle.getHandle (  )  [static]

Returns a static CCNHandle that is made available as a default.

Returns:
the shared static CCNHandle
CCNNetworkManager org.ccnx.ccn.CCNHandle.getNetworkManager (  ) 

Retrieve this handle's network manager.

Should only be called by low-level methods seeking direct access to the network.

If the handle is closed, this will return null.

Returns:
the CCN network manager
KeyManager org.ccnx.ccn.CCNHandle.keyManager (  ) 

Change the KeyManager this CCNHandle is using.

Parameters:
keyManager the new KeyManager to use Return the KeyManager we are using.
Returns:
our current KeyManager
static CCNHandle org.ccnx.ccn.CCNHandle.open ( KeyManager  keyManager  )  throws IOException [static]

Create a new CCNHandle, opening a new connection to the CCN network, and specifying the KeyManager it should use.

Particularly useful in testing, to run as if you were a different "user", with a different collection of keys.

Parameters:
keyManager the KeyManager to use
Returns:
the CCNHandle
Exceptions:
IOException 

Reimplemented in org.ccnx.ccn.test.profiles.versioning.VersioningHelper.SinkHandle.

static CCNHandle org.ccnx.ccn.CCNHandle.open (  )  throws ConfigurationException, IOException [static]

Create a new CCNHandle, opening a new connection to the CCN network.

Returns:
the CCNHandle
Exceptions:
ConfigurationException if there is an issue in the user or system configuration which we cannot overcome without outside intervention. See the error message for details.
IOException if we encounter an error reading system, configuration, or keystore data that we expect to be well-formed.
ContentObject org.ccnx.ccn.CCNHandle.put ( ContentObject  co  )  throws IOException

Put a single content object into the network.

This is a low-level put, and typically should only be called by a flow controller, in response to a received Interest. Attempting to write to ccnd without having first received a corresponding Interest violates flow balance, and the content will be dropped.

Parameters:
co the content object to write. This should be complete and well-formed -- signed and so on.
Returns:
the object that was put if successful, otherwise null.
Exceptions:
IOException 

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.CCNLibraryTestHarness.

void org.ccnx.ccn.CCNHandle.registerFilter ( ContentName  filter,
CCNFilterListener  callbackListener 
) throws IOException

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

Parameters:
filter 
callbackListener 

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.CCNLibraryTestHarness.

void org.ccnx.ccn.CCNHandle.unregisterFilter ( ContentName  filter,
CCNFilterListener  callbackListener 
)

Unregister a standing interest filter.

Parameters:
filter 
callbackListener 
Exceptions:
IOException if handle is closed

Implements org.ccnx.ccn.CCNBase.

Reimplemented in org.ccnx.ccn.test.CCNLibraryTestHarness.


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