net.named_data.jndn.util

Class MemoryContentCache

java.lang.Object

net.named_data.jndn.util.MemoryContentCache

All Implemented Interfaces:

OnInterestCallback

public class MemoryContentCache
extends Object
implements OnInterestCallback

A MemoryContentCache holds a set of Data packets and answers an Interest to return the correct Data packet. The cache is periodically cleaned up to remove each stale Data packet based on its FreshnessPeriod (if it has one).

Note:

This class is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/memory-content-cache.html .

Constructor Summary

Constructors

Constructor and Description
MemoryContentCache(Face face) Create a new MemoryContentCache to use the given Face, with a default cleanupIntervalMilliseconds of 1000.0 milliseconds.
MemoryContentCache(Face face, double cleanupIntervalMilliseconds) Create a new MemoryContentCache to use the given Face.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Data data) Add the Data packet to the cache so that it is available to use to answer interests.
OnInterestCallback	getStorePendingInterest() Return a callback to use for onDataNotFound in registerPrefix which simply calls storePendingInterest() to store the interest that doesn't match a Data packet.
void	onInterest(Name prefix, Interest interest, Face face, long interestFilterId, InterestFilter filter) When an interest is received which matches the interest filter, onInterest is called.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name matches the filter.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnInterestCallback onDataNotFound) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnInterestCallback onDataNotFound, ForwardingFlags flags) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnInterestCallback onDataNotFound, ForwardingFlags flags, WireFormat wireFormat) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnRegisterSuccess onRegisterSuccess) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnRegisterSuccess onRegisterSuccess, OnInterestCallback onDataNotFound) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnRegisterSuccess onRegisterSuccess, OnInterestCallback onDataNotFound, ForwardingFlags flags) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	registerPrefix(Name prefix, OnRegisterFailed onRegisterFailed, OnRegisterSuccess onRegisterSuccess, OnInterestCallback onDataNotFound, ForwardingFlags flags, WireFormat wireFormat) Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	setInterestFilter(InterestFilter filter) Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	setInterestFilter(InterestFilter filter, OnInterestCallback onDataNotFound) Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name matches the filter.
void	setInterestFilter(Name prefix) Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	setInterestFilter(Name prefix, OnInterestCallback onDataNotFound) Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.
void	storePendingInterest(Interest interest, Face face) Store an interest from an OnInterest callback in the internal pending interest table (normally because there is no Data packet available yet to satisfy the interest).
void	unregisterAll() Call Face.unsetInterestFilter and Face.removeRegisteredPrefix for all the prefixes given to the setInterestFilter and registerPrefix method on this MemoryContentCache object so that it will not receive interests any more.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MemoryContentCache

public MemoryContentCache(Face face,
                  double cleanupIntervalMilliseconds)

Create a new MemoryContentCache to use the given Face.

Parameters:

face - The Face to use to call registerPrefix and setInterestFilter, and which will call this object's OnInterest callback.

cleanupIntervalMilliseconds - The interval in milliseconds between each check to clean up stale content in the cache. If this is a large number, then effectively the stale content will not be removed from the cache.

MemoryContentCache

public MemoryContentCache(Face face)

Create a new MemoryContentCache to use the given Face, with a default cleanupIntervalMilliseconds of 1000.0 milliseconds.

Parameters:

face - The Face to use to call registerPrefix and setInterestFilter, and which will call this object's OnInterest callback.

Method Detail

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnRegisterSuccess onRegisterSuccess,
                  OnInterestCallback onDataNotFound,
                  ForwardingFlags flags,
                  WireFormat wireFormat)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onRegisterSuccess - This calls onRegisterSuccess.onRegisterSuccess(prefix, registeredPrefixId) when this receives a success message from the forwarder. If onRegisterSuccess is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

flags - See Face.registerPrefix.

wireFormat - See Face.registerPrefix.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnRegisterSuccess onRegisterSuccess,
                  OnInterestCallback onDataNotFound,
                  ForwardingFlags flags)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onRegisterSuccess - This calls onRegisterSuccess.onRegisterSuccess(prefix, registeredPrefixId) when this receives a success message from the forwarder. If onRegisterSuccess is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onInterest.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it.

flags - See Face.registerPrefix.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnRegisterSuccess onRegisterSuccess,
                  OnInterestCallback onDataNotFound)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. This uses the default WireFormat.getDefaultWireFormat(). Use default ForwardingFlags.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onRegisterSuccess - This calls onRegisterSuccess.onRegisterSuccess(prefix, registeredPrefixId) when this receives a success message from the forwarder. If onRegisterSuccess is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnRegisterSuccess onRegisterSuccess)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. Do not call a callback if a data packet is not found in the cache. This uses the default WireFormat.getDefaultWireFormat(). Use default ForwardingFlags.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onRegisterSuccess - This calls onRegisterSuccess.onRegisterSuccess(prefix, registeredPrefixId) when this receives a success message from the forwarder. If onRegisterSuccess is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnInterestCallback onDataNotFound,
                  ForwardingFlags flags,
                  WireFormat wireFormat)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

flags - See Face.registerPrefix.

wireFormat - See Face.registerPrefix.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnInterestCallback onDataNotFound,
                  ForwardingFlags flags)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it.

flags - See Face.registerPrefix.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed,
                  OnInterestCallback onDataNotFound)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. This uses the default WireFormat.getDefaultWireFormat(). Use default ForwardingFlags.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

registerPrefix

public final void registerPrefix(Name prefix,
                  OnRegisterFailed onRegisterFailed)
                          throws IOException,
                                 SecurityException

Call registerPrefix on the Face given to the constructor so that this MemoryContentCache will answer interests whose name matches the filter. Alternatively, if the Face's registerPrefix has already been called, then you can call this object's setInterestFilter. Do not call a callback if a data packet is not found in the cache. This uses the default WireFormat.getDefaultWireFormat(). Use default ForwardingFlags.

Parameters:

prefix - The Name for the prefix to register. This copies the Name.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Throws:

IOException - For I/O error in sending the registration request.

SecurityException - If signing a command interest for NFD and cannot find the private key for the certificateName.

setInterestFilter

public final void setInterestFilter(InterestFilter filter,
                     OnInterestCallback onDataNotFound)

Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name matches the filter.

Parameters:

filter - The InterestFilter with a prefix and optional regex filter used to match the name of an incoming Interest. This makes a copy of filter.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). Note: If you call setInterestFilter multiple times where filter.getPrefix() is the same, it is undetermined which onDataNotFound will be called. If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

setInterestFilter

public final void setInterestFilter(InterestFilter filter)

Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Do not call a callback if a data packet is not found in the cache.

Parameters:

filter - The InterestFilter with a prefix and optional regex filter used to match the name of an incoming Interest. This makes a copy of filter.

setInterestFilter

public final void setInterestFilter(Name prefix,
                     OnInterestCallback onDataNotFound)

Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix.

Parameters:

prefix - The Name prefix used to match the name of an incoming Interest. This copies the Name.

onDataNotFound - If a data packet for an interest is not found in the cache, this forwards the interest by calling onDataNotFound.onInterest(prefix, interest, face, interestFilterId, filter). Your callback can find the Data packet for the interest and call face.putData(data). Note: If you call setInterestFilter multiple times where filter.getPrefix() is the same, it is undetermined which onDataNotFound will be called. If your callback cannot find the Data packet, it can optionally call storePendingInterest(interest, face) to store the pending interest in this object to be satisfied by a later call to add(data). If you want to automatically store all pending interests, you can simply use getStorePendingInterest() for onDataNotFound. If onDataNotFound is null, this does not use it. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

setInterestFilter

public final void setInterestFilter(Name prefix)

Call setInterestFilter on the Face given to the constructor so that this MemoryContentCache will answer interests whose name has the prefix. Do not call a callback if a data packet is not found in the cache.

Parameters:

prefix - The Name prefix used to match the name of an incoming Interest. This copies the Name.

unregisterAll

public final void unregisterAll()

Call Face.unsetInterestFilter and Face.removeRegisteredPrefix for all the prefixes given to the setInterestFilter and registerPrefix method on this MemoryContentCache object so that it will not receive interests any more. You can call this if you want to "shut down" this MemoryContentCache while your application is still running.

add

public final void add(Data data)

Add the Data packet to the cache so that it is available to use to answer interests. If data.getMetaInfo().getFreshnessPeriod() is not negative, set the staleness time to now plus data.getMetaInfo().getFreshnessPeriod(), which is checked during cleanup to remove stale content. This also checks if cleanupIntervalMilliseconds milliseconds have passed and removes stale content from the cache. After removing stale content, remove timed-out pending interests from storePendingInterest(), then if the added Data packet satisfies any interest, send it through the face and remove the interest from the pending interest table.

Parameters:

data - The Data packet object to put in the cache. This copies the fields from the object.

storePendingInterest

public final void storePendingInterest(Interest interest,
                        Face face)

Store an interest from an OnInterest callback in the internal pending interest table (normally because there is no Data packet available yet to satisfy the interest). add(data) will check if the added Data packet satisfies any pending interest and send it through the face.

Parameters:

interest - The Interest for which we don't have a Data packet yet. You should not modify the interest after calling this.

face - The Face with the connection which received the interest. This comes from the OnInterest callback.

getStorePendingInterest

public final OnInterestCallback getStorePendingInterest()

Return a callback to use for onDataNotFound in registerPrefix which simply calls storePendingInterest() to store the interest that doesn't match a Data packet. add(data) will check if the added Data packet satisfies any pending interest and send it.

Returns:

A callback to use for onDataNotFound in registerPrefix().

onInterest

public final void onInterest(Name prefix,
              Interest interest,
              Face face,
              long interestFilterId,
              InterestFilter filter)

Description copied from interface: OnInterestCallback

When an interest is received which matches the interest filter, onInterest is called.

Specified by:

onInterest in interface OnInterestCallback

Parameters:

prefix - The Name prefix given to registerPrefix or setInterestFilter (or directly to the InterestFilter constructor). NOTE: You must not change the prefix object - if you need to change it then make a copy.

interest - The received interest.

face - You should call face.putData to supply a Data packet which satisfies the Interest.

interestFilterId - The interest filter ID which can be used with Face.unsetInterestFilter.

filter - The InterestFilter given to registerPrefix or setInterestFilter, or the InterestFilter created from the Name prefix. The first argument, prefix, is provided for convenience and is the same as filter.getPrefix(). NOTE: You must not change the filter object - if you need to change it then make a copy.