net.named_data.jndn

Class Face

java.lang.Object

net.named_data.jndn.Face

public class Face
extends Object

The Face class provides the main methods for NDN communication.

Constructor Summary

Constructors

Constructor and Description
Face() Create a new Face for communication with an NDN hub at "localhost" using the default port 6363 and the default TcpTransport.
Face(String host) Create a new Face for communication with an NDN hub at host using the default port 6363 and the default TcpTransport.
Face(String host, int port) Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.
Face(Transport transport, Transport.ConnectionInfo connectionInfo) Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.

Method Summary

Methods

Modifier and Type	Method and Description
long	expressInterest(Interest interest, OnData onData) Send the Interest through the transport, read the entire response and call onData(interest, data).
long	expressInterest(Interest interest, OnData onData, OnTimeout onTimeout) Send the Interest through the transport, read the entire response and call onData(interest, data).
long	expressInterest(Interest interest, OnData onData, OnTimeout onTimeout, WireFormat wireFormat) Send the Interest through the transport, read the entire response and call onData(interest, data).
long	expressInterest(Interest interest, OnData onData, WireFormat wireFormat) Send the Interest through the transport, read the entire response and call onData(interest, data).
long	expressInterest(Name name, Interest interestTemplate, OnData onData) Encode name as an Interest.
long	expressInterest(Name name, Interest interestTemplate, OnData onData, OnTimeout onTimeout) Encode name as an Interest.
long	expressInterest(Name name, Interest interestTemplate, OnData onData, OnTimeout onTimeout, WireFormat wireFormat) Encode name as an Interest.
long	expressInterest(Name name, Interest interestTemplate, OnData onData, WireFormat wireFormat) Encode name as an Interest.
long	expressInterest(Name name, OnData onData) Encode name as an Interest.
long	expressInterest(Name name, OnData onData, OnTimeout onTimeout) Encode name as an Interest.
long	expressInterest(Name name, OnData onData, OnTimeout onTimeout, WireFormat wireFormat) Encode name as an Interest.
long	expressInterest(Name name, OnData onData, WireFormat wireFormat) Encode name as an Interest.
static int	getMaxNdnPacketSize() Get the practical limit of the size of a network-layer packet.
boolean	isLocal() Check if the face is local based on the current connection through the Transport; some Transport may cause network IO (e.g.
void	makeCommandInterest(Interest interest) Append a timestamp component and a random value component to interest's name.
void	makeCommandInterest(Interest interest, WireFormat wireFormat) Append a timestamp component and a random value component to interest's name.
void	processEvents() Process any packets to receive and call callbacks such as onData, onInterest or onTimeout.
void	putData(Data data) The OnInterestCallback calls this to put a Data packet which satisfies an Interest.
void	putData(Data data, WireFormat wireFormat) The OnInterestCallback calls this to put a Data packet which satisfies an Interest.
long	registerPrefix(Name prefix, OnInterestCallback onInterest, OnRegisterFailed onRegisterFailed) Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
long	registerPrefix(Name prefix, OnInterestCallback onInterest, OnRegisterFailed onRegisterFailed, ForwardingFlags flags) Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
long	registerPrefix(Name prefix, OnInterestCallback onInterest, OnRegisterFailed onRegisterFailed, ForwardingFlags flags, WireFormat wireFormat) Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
long	registerPrefix(Name prefix, OnInterestCallback onInterest, OnRegisterFailed onRegisterFailed, WireFormat wireFormat) Register prefix with the connected NDN hub and call onInterest when a matching interest is received.
long	registerPrefix(Name prefix, OnInterest onInterest, OnRegisterFailed onRegisterFailed) Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).
long	registerPrefix(Name prefix, OnInterest onInterest, OnRegisterFailed onRegisterFailed, ForwardingFlags flags) Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).
long	registerPrefix(Name prefix, OnInterest onInterest, OnRegisterFailed onRegisterFailed, ForwardingFlags flags, WireFormat wireFormat) Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).
long	registerPrefix(Name prefix, OnInterest onInterest, OnRegisterFailed onRegisterFailed, WireFormat wireFormat) Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).
void	removePendingInterest(long pendingInterestId) Remove the pending interest entry with the pendingInterestId from the pending interest table.
void	removeRegisteredPrefix(long registeredPrefixId) Remove the registered prefix entry with the registeredPrefixId from the registered prefix table.
void	send(Blob encoding) Send the encoded packet out through the face.
void	send(ByteBuffer encoding) Send the encoded packet out through the face.
void	setCommandCertificateName(Name certificateName) Set the certificate name used to sign command interest (e.g.
void	setCommandSigningInfo(KeyChain keyChain, Name certificateName) Set the KeyChain and certificate name used to sign command interests (e.g.
long	setInterestFilter(InterestFilter filter, OnInterestCallback onInterest) Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest.
long	setInterestFilter(Name prefix, OnInterestCallback onInterest) Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest.
void	shutdown() Shut down and disconnect this Face.
void	unsetInterestFilter(long interestFilterId) Remove the interest filter entry which has the interestFilterId from the interest filter table.

Methods inherited from class java.lang.Object

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

Constructor Detail

Face

public Face(Transport transport,
    Transport.ConnectionInfo connectionInfo)

Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.

Parameters:

transport - A Transport object used for communication.

connectionInfo - A Transport.ConnectionInfo to be used to connect to the transport.

Face

public Face(String host,
    int port)

Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.

Parameters:

host - The host of the NDN hub.

port - The port of the NDN hub.

Face

public Face(String host)

Create a new Face for communication with an NDN hub at host using the default port 6363 and the default TcpTransport.

Parameters:

host - The host of the NDN hub.

Face

public Face()

Create a new Face for communication with an NDN hub at "localhost" using the default port 6363 and the default TcpTransport.

Method Detail

expressInterest

public long expressInterest(Interest interest,
                   OnData onData,
                   OnTimeout onTimeout,
                   WireFormat wireFormat)
                     throws IOException

Send the Interest through the transport, read the entire response and call onData(interest, data).

Parameters:

interest - The Interest to send. This copies the Interest.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Interest interest,
                   OnData onData,
                   OnTimeout onTimeout)
                     throws IOException

Send the Interest through the transport, read the entire response and call onData(interest, data). This uses the default WireFormat.getDefaultWireFormat().

Parameters:

interest - The Interest to send. This copies the Interest.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Interest interest,
                   OnData onData,
                   WireFormat wireFormat)
                     throws IOException

Send the Interest through the transport, read the entire response and call onData(interest, data). Ignore if the interest times out.

Parameters:

interest - The Interest to send. This copies the Interest.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Interest interest,
                   OnData onData)
                     throws IOException

Send the Interest through the transport, read the entire response and call onData(interest, data). Ignore if the interest times out. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

interest - The Interest to send. This copies the Interest.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   Interest interestTemplate,
                   OnData onData,
                   OnTimeout onTimeout,
                   WireFormat wireFormat)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data).

Parameters:

name - A Name for the interest. This copies the Name.

interestTemplate - If not null, copy interest selectors from the template. This does not keep a pointer to the Interest object.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   OnData onData,
                   OnTimeout onTimeout,
                   WireFormat wireFormat)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Use a default interest lifetime.

Parameters:

name - A Name for the interest. This copies the Name.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   Interest interestTemplate,
                   OnData onData,
                   WireFormat wireFormat)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Ignore if the interest times out.

Parameters:

name - A Name for the interest. This copies the Name.

interestTemplate - If not null, copy interest selectors from the template. This does not keep a pointer to the Interest object.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   Interest interestTemplate,
                   OnData onData,
                   OnTimeout onTimeout)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). This uses the default WireFormat.getDefaultWireFormat().

Parameters:

name - A Name for the interest. This copies the Name.

interestTemplate - If not null, copy interest selectors from the template. This does not keep a pointer to the Interest object.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   Interest interestTemplate,
                   OnData onData)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Ignore if the interest times out. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

name - A Name for the interest. This copies the Name.

interestTemplate - If not null, copy interest selectors from the template. This does not keep a pointer to the Interest object.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   OnData onData,
                   OnTimeout onTimeout)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Use a default interest lifetime. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

name - A Name for the interest. This copies the Name.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

onTimeout - If the interest times out according to the interest lifetime, this calls onTimeout.onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is null, this does not use it.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   OnData onData,
                   WireFormat wireFormat)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Use a default interest lifetime. Ignore if the interest times out.

Parameters:

name - A Name for the interest. This copies the Name.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

wireFormat - A WireFormat object used to encode the message.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

expressInterest

public long expressInterest(Name name,
                   OnData onData)
                     throws IOException

Encode name as an Interest. If interestTemplate is not null, use its interest selectors. Send the interest through the transport, read the entire response and call onData(interest, data). Use a default interest lifetime. Ignore if the interest times out. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

name - A Name for the interest. This copies the Name.

onData - When a matching data packet is received, this calls onData.onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. NOTE: You must not change the interest object - if you need to change it then make a copy.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throws:

IOException - For I/O error in sending the interest.

Error - If the encoded interest size exceeds getMaxNdnPacketSize().

removePendingInterest

public void removePendingInterest(long pendingInterestId)

Remove the pending interest entry with the pendingInterestId from the pending interest table. This does not affect another pending interest with a different pendingInterestId, even if it has the same interest name. If there is no entry with the pendingInterestId, do nothing.

Parameters:

pendingInterestId - The ID returned from expressInterest.

setCommandSigningInfo

public void setCommandSigningInfo(KeyChain keyChain,
                         Name certificateName)

Set the KeyChain and certificate name used to sign command interests (e.g. for registerPrefix).

Parameters:

keyChain - The KeyChain object for signing interests, which must remain valid for the life of this Face. You must create the KeyChain object and pass it in. You can create a default KeyChain for your system with the default KeyChain constructor.

certificateName - The certificate name for signing interests. This makes a copy of the Name. You can get the default certificate name with keyChain.getDefaultCertificateName() .

setCommandCertificateName

public void setCommandCertificateName(Name certificateName)

Set the certificate name used to sign command interest (e.g. for registerPrefix), using the KeyChain that was set with setCommandSigningInfo.

Parameters:

certificateName - The certificate name for signing interest. This makes a copy of the Name.

makeCommandInterest

public void makeCommandInterest(Interest interest,
                       WireFormat wireFormat)
                         throws SecurityException

Append a timestamp component and a random value component to interest's name. Then use the keyChain and certificateName from setCommandSigningInfo to sign the interest. If the interest lifetime is not set, this sets it.

Parameters:

interest - The interest whose name is appended with components.

wireFormat - A WireFormat object used to encode the SignatureInfo and to encode the interest name for signing.

Throws:

SecurityException - If cannot find the private key for the certificateName.

Note:

This method is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/face.html#face-makecommandinterest-method .

makeCommandInterest

public void makeCommandInterest(Interest interest)
                         throws SecurityException

Append a timestamp component and a random value component to interest's name. Then use the keyChain and certificateName from setCommandSigningInfo to sign the interest. If the interest lifetime is not set, this sets it. Use the default WireFormat to encode the SignatureInfo and to encode the interest name for signing.

Parameters:

interest - The interest whose name is appended with components.

Throws:

SecurityException - If cannot find the private key for the certificateName.

Note:

This method is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/face.html#face-makecommandinterest-method .

registerPrefix

public long registerPrefix(Name prefix,
                  OnInterestCallback onInterest,
                  OnRegisterFailed onRegisterFailed,
                  ForwardingFlags flags,
                  WireFormat wireFormat)
                    throws IOException,
                           SecurityException

Register prefix with the connected NDN hub and call onInterest when a matching interest is received. If you have not called setCommandSigningInfo, this assumes you are connecting to NDNx. If you have called setCommandSigningInfo, this first sends an NFD registration request, and if that times out then this sends an NDNx registration request. If you need to register a prefix with NFD, you must first call setCommandSigningInfo.

Parameters:

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

onInterest - (optional) If not null, this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter). The onInterest callback should supply the Data with face.putData(). NOTE: You must not change the prefix or filter objects - if you need to change them then make a copy. If onInterest is null, it is ignored and you must call setInterestFilter.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix).

flags - The flags for finer control of which interests are forwarded to the application.

wireFormat - A WireFormat object used to encode the message.

Returns:

The registered prefix ID which can be used with removeRegisteredPrefix.

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 long registerPrefix(Name prefix,
                  OnInterestCallback onInterest,
                  OnRegisterFailed onRegisterFailed,
                  ForwardingFlags flags)
                    throws IOException,
                           SecurityException

Register prefix with the connected NDN hub and call onInterest when a matching interest is received. This uses the default WireFormat.getDefaultWireFormat().

Parameters:

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

onInterest - (optional) If not null, this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter). The onInterest callback should supply the Data with face.putData(). NOTE: You must not change the prefix or filter objects - if you need to change them then make a copy. If onInterest is null, it is ignored and you must call setInterestFilter.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix).

flags - The flags for finer control of which interests are forwarded to the application.

Returns:

The registered prefix ID which can be used with removeRegisteredPrefix.

Throws:

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

SecurityException

registerPrefix

public long registerPrefix(Name prefix,
                  OnInterestCallback onInterest,
                  OnRegisterFailed onRegisterFailed,
                  WireFormat wireFormat)
                    throws IOException,
                           SecurityException

Register prefix with the connected NDN hub and call onInterest when a matching interest is received. Use default ForwardingFlags.

Parameters:

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

onInterest - (optional) If not null, this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter). The onInterest callback should supply the Data with face.putData(). NOTE: You must not change the prefix or filter objects - if you need to change them then make a copy. If onInterest is null, it is ignored and you must call setInterestFilter.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix).

wireFormat - A WireFormat object used to encode the message.

Returns:

The registered prefix ID which can be used with removeRegisteredPrefix.

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 long registerPrefix(Name prefix,
                  OnInterestCallback onInterest,
                  OnRegisterFailed onRegisterFailed)
                    throws IOException,
                           SecurityException

Register prefix with the connected NDN hub and call onInterest when a matching interest is received. This uses the default WireFormat.getDefaultWireFormat(). Use default ForwardingFlags.

Parameters:

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

onInterest - (optional) If not null, this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter). The onInterest callback should supply the Data with face.putData(). NOTE: You must not change the prefix or filter objects - if you need to change them then make a copy. If onInterest is null, it is ignored and you must call setInterestFilter.

onRegisterFailed - If register prefix fails for any reason, this calls onRegisterFailed.onRegisterFailed(prefix).

Returns:

The registered prefix ID which can be used with removeRegisteredPrefix.

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 long registerPrefix(Name prefix,
                  OnInterest onInterest,
                  OnRegisterFailed onRegisterFailed,
                  ForwardingFlags flags,
                  WireFormat wireFormat)
                    throws IOException,
                           SecurityException

Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).

Throws:

IOException

SecurityException

registerPrefix

public long registerPrefix(Name prefix,
                  OnInterest onInterest,
                  OnRegisterFailed onRegisterFailed,
                  ForwardingFlags flags)
                    throws IOException,
                           SecurityException

Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).

Throws:

IOException

SecurityException

registerPrefix

public long registerPrefix(Name prefix,
                  OnInterest onInterest,
                  OnRegisterFailed onRegisterFailed,
                  WireFormat wireFormat)
                    throws IOException,
                           SecurityException

Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).

Throws:

IOException

SecurityException

registerPrefix

public long registerPrefix(Name prefix,
                  OnInterest onInterest,
                  OnRegisterFailed onRegisterFailed)
                    throws IOException,
                           SecurityException

Deprecated. Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).

Throws:

IOException

SecurityException

removeRegisteredPrefix

public void removeRegisteredPrefix(long registeredPrefixId)

Remove the registered prefix entry with the registeredPrefixId from the registered prefix table. This does not affect another registered prefix with a different registeredPrefixId, even if it has the same prefix name. If an interest filter was automatically created by registerPrefix, also remove it. If there is no entry with the registeredPrefixId, do nothing.

Parameters:

registeredPrefixId - The ID returned from registerPrefix.

setInterestFilter

public long setInterestFilter(InterestFilter filter,
                     OnInterestCallback onInterest)

Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest. This method only modifies the library's local callback table and does not register the prefix with the forwarder. It will always succeed. To register a prefix with the forwarder, use registerPrefix.

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.

onInterest - When an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter).

Returns:

The interest filter ID which can be used with unsetInterestFilter.

setInterestFilter

public long setInterestFilter(Name prefix,
                     OnInterestCallback onInterest)

Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest. This method only modifies the library's local callback table and does not register the prefix with the forwarder. It will always succeed. To register a prefix with the forwarder, use registerPrefix.

Parameters:

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

onInterest - This creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest.onInterest(prefix, interest, face, interestFilterId, filter).

Returns:

The interest filter ID which can be used with unsetInterestFilter.

unsetInterestFilter

public void unsetInterestFilter(long interestFilterId)

Remove the interest filter entry which has the interestFilterId from the interest filter table. This does not affect another interest filter with a different interestFilterId, even if it has the same prefix name. If there is no entry with the interestFilterId, do nothing.

Parameters:

interestFilterId - The ID returned from setInterestFilter.

putData

public void putData(Data data,
           WireFormat wireFormat)
             throws IOException

The OnInterestCallback calls this to put a Data packet which satisfies an Interest.

Parameters:

data - The Data packet which satisfies the interest.

wireFormat - A WireFormat object used to encode the Data packet.

Throws:

Error - If the encoded Data packet size exceeds getMaxNdnPacketSize().

IOException

putData

public void putData(Data data)
             throws IOException

The OnInterestCallback calls this to put a Data packet which satisfies an Interest. This uses the default WireFormat.getDefaultWireFormat() to encode data.

Parameters:

data - The Data packet which satisfies the interest.

Throws:

Error - If the encoded Data packet size exceeds getMaxNdnPacketSize().

IOException

send

public void send(Blob encoding)
          throws IOException

Send the encoded packet out through the face.

Parameters:

encoding - The blob with the the encoded packet to send.

Throws:

Error - If the encoded packet size exceeds getMaxNdnPacketSize().

IOException

send

public void send(ByteBuffer encoding)
          throws IOException

Send the encoded packet out through the face.

Parameters:

encoding - The array of bytes for the encoded packet to send. This reads from position() to limit(), but does not change the position.

Throws:

Error - If the encoded packet size exceeds getMaxNdnPacketSize().

IOException

processEvents

public void processEvents()
                   throws IOException,
                          EncodingException

Process any packets to receive and call callbacks such as onData, onInterest or onTimeout. This returns immediately if there is no data to receive. This blocks while calling the callbacks. You should repeatedly call this from an event loop, with calls to sleep as needed so that the loop doesn’t use 100% of the CPU. Since processEvents modifies the pending interest table, your application should make sure that it calls processEvents in the same thread as expressInterest (which also modifies the pending interest table). This may throw an exception for reading data or in the callback for processing the data. If you call this from an main event loop, you may want to catch and log/disregard all exceptions.

Throws:

IOException

EncodingException

isLocal

public boolean isLocal()
                throws IOException

Check if the face is local based on the current connection through the Transport; some Transport may cause network IO (e.g. an IP host name lookup).

Returns:

True if the face is local, false if not.

Throws:

IOException

Note:

This is an experimental feature. This API may change in the future.

shutdown

public void shutdown()

Shut down and disconnect this Face.

getMaxNdnPacketSize

public static int getMaxNdnPacketSize()

Get the practical limit of the size of a network-layer packet. If a packet is larger than this, the library or application MAY drop it.

Returns:

The maximum NDN packet size.