net.named_data.jndn.util

Class SegmentFetcher

java.lang.Object

net.named_data.jndn.util.SegmentFetcher

All Implemented Interfaces:

OnData, OnNetworkNack, OnTimeout, OnDataValidationFailed

public class SegmentFetcher
extends Object
implements OnData, OnDataValidationFailed, OnTimeout, OnNetworkNack

SegmentFetcher is a utility class to fetch the latest version of segmented data. SegmentFetcher assumes that segments in the object are named `/{prefix}/{version}/{segment}`, where: - `{prefix}` is the specified prefix, - `{version}` is an unknown version that needs to be discovered, and - `{segment}` is a segment number (the number of segments in the object is unknown until a Data packet containing the `FinalBlockId` field is received). SegmentFetcher implements the following logic: 1. Express an Interest to discover the latest version of the object: Interest: `/{prefix}?ndn.CanBePrefix=true,ndn.MustBeFresh=true` 2. Infer the latest version of the object: `{version} = Data.getName().get(-2)` 3. Keep sending Interests for future segments until an error occurs or the number of segments indicated by the FinalBlockId in a received Data packet is reached. This retrieval will start at segment 1 if segment 0 was received in response to the Interest expressed in step 2; otherwise, retrieval will start at segment 0. By default, congestion control will be used to manage the Interest window size. Interests expressed in this step will follow this Name format: Interest: `/{prefix}/{version}/{segment=(N)}` 4. Call the OnComplete callback with a blob that concatenates the content from all the segmented objects. If an error occurs during the fetching process, the OnError callback is called with a proper error code. The following errors are possible: - `INTEREST_TIMEOUT`: if any of the Interests times out - `DATA_HAS_NO_SEGMENT`: if any of the retrieved Data packets don't have a segment as the last component of the name (not counting the implicit digest) - `SEGMENT_VERIFICATION_FAILED`: if any retrieved segment fails the user-provided VerifySegment callback or KeyChain verifyData. - `IO_ERROR`: for I/O errors when sending an Interest. - 'NACK_ERROR': unknown/unhandled NACK received. In order to validate individual segments, a KeyChain needs to be supplied. If verifyData fails, the fetching process is aborted with SEGMENT_VERIFICATION_FAILED. If data validation is not required, pass (KeyChain)null. Example: Interest interest = new Interest(new Name("/data/prefix")); interest.setInterestLifetimeMilliseconds(1000); SegmentFetcher.fetch (face, interest, 0, new SegmentFetcher.OnComplete() { public void onComplete(Blob content) { ... }}, new SegmentFetcher.OnError() { public void onError(SegmentFetcher.ErrorCode errorCode, String message) { ... }});

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SegmentFetcher.ErrorCode
static interface	SegmentFetcher.OnComplete
static interface	SegmentFetcher.OnError
static class	SegmentFetcher.Options
static interface	SegmentFetcher.VerifySegment

Field Summary

Fields

Modifier and Type	Field and Description
static SegmentFetcher.VerifySegment	DontVerifySegment DontVerifySegment may be used in fetch to skip validation of Data packets.

Method Summary

Modifier and Type	Method and Description
static void	fetch(Face face, Interest baseInterest, KeyChain validatorKeyChain, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError)
static void	fetch(Face face, Interest baseInterest, SegmentFetcher.Options options, KeyChain validatorKeyChain, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError) Initiate segment fetching.
static void	fetch(Face face, Interest baseInterest, SegmentFetcher.Options options, SegmentFetcher.VerifySegment verifySegment, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError) Initiate segment fetching.
static void	fetch(Face face, Interest baseInterest, SegmentFetcher.Options options, Validator validator, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError) Initiate segment fetching.
static void	fetch(Face face, Interest baseInterest, SegmentFetcher.VerifySegment verifySegment, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError)
static void	fetch(Face face, Interest baseInterest, Validator validator, SegmentFetcher.OnComplete onComplete, SegmentFetcher.OnError onError)
boolean	isStopped()
void	onData(Interest originalInterest, Data data) When a matching data packet is received, onData is called.
void	onDataValidationFailed(Data data, String reason) When verifyData fails, onDataValidationFailed is called.
void	onNetworkNack(Interest interest, NetworkNack networkNack) When a network Nack packet is received, onNetworkNack is called.
void	onTimeout(Interest interest) If the interest times out according to the interest lifetime, onTimeout is called.
void	stop() Stop fetching packets and clear the received data.

Methods inherited from class java.lang.Object

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

Field Detail

DontVerifySegment

public static final SegmentFetcher.VerifySegment DontVerifySegment

DontVerifySegment may be used in fetch to skip validation of Data packets.

Method Detail

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         SegmentFetcher.Options options,
                         SegmentFetcher.VerifySegment verifySegment,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

Initiate segment fetching. For more details, see the documentation for the class.

Parameters:

face - This calls face.expressInterest to fetch more segments.

baseInterest - Interest for the initial segment of requested data. This interest may include a custom InterestLifetime and parameters that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include the "CanBePrefix=true" and "MustBeFresh=true" parameters, which will not be included in subsequent interests.

options - A set of options to control the sending and receiving of packets in the AIMD pipelining.

verifySegment - When a Data packet is received this calls verifySegment.verifySegment(data). If it returns false then abort fetching and call onError.onError with ErrorCode.SEGMENT_VERIFICATION_FAILED. If data validation is not required, use DontVerifySegment. 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.

onComplete - When all segments are received, call onComplete.onComplete(content) where content is the concatenation of the content of all the segments. 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.

onError - Call onError.onError(errorCode, message) for timeout or an error processing segments. 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.

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         SegmentFetcher.VerifySegment verifySegment,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         SegmentFetcher.Options options,
                         KeyChain validatorKeyChain,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

Initiate segment fetching. For more details, see the documentation for the class.

Parameters:

face - This calls face.expressInterest to fetch more segments.

baseInterest - Interest for the initial segment of requested data. This interest may include a custom InterestLifetime and parameters that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include the "CanBePrefix=true" and "MustBeFresh=true" parameters, which will not be included in subsequent interests.

options - A set of options to control the sending and receiving of packets in the AIMD pipelining.

validatorKeyChain - When a Data packet is received this calls validatorKeyChain.verifyData(data). If validation fails then abort fetching and call onError with SEGMENT_VERIFICATION_FAILED. This does not make a copy of the KeyChain; the object must remain valid while fetching. If validatorKeyChain is null, this does not validate the data packet.

onComplete - When all segments are received, call onComplete.onComplete(content) where content is the concatenation of the content of all the segments. 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.

onError - Call onError.onError(errorCode, message) for timeout or an error processing segments. 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.

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         KeyChain validatorKeyChain,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         SegmentFetcher.Options options,
                         Validator validator,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

Initiate segment fetching. For more details, see the documentation for the class.

Parameters:

face - This calls face.expressInterest to fetch more segments.

baseInterest - Interest for the initial segment of requested data. This interest may include a custom InterestLifetime and parameters that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include the "CanBePrefix=true" and "MustBeFresh=true" parameters, which will not be included in subsequent interests.

options - A set of options to control the sending and receiving of packets in the AIMD pipelining.

validator - The Validator, the fetcher will use to validate data. The caller must ensure the validator remains valid until either #onComplete or #onError has been signaled.

onComplete - When all segments are received, call onComplete.onComplete(content) where content is the concatenation of the content of all the segments. 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.

onError - Call onError.onError(errorCode, message) for timeout or an error processing segments. 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.

fetch

public static void fetch(Face face,
                         Interest baseInterest,
                         Validator validator,
                         SegmentFetcher.OnComplete onComplete,
                         SegmentFetcher.OnError onError)

onData

public void onData(Interest originalInterest,
                   Data data)

Description copied from interface: OnData

When a matching data packet is received, onData is called.

Specified by:

onData in interface OnData

Parameters:

originalInterest - The interest given to Face.expressInterest. NOTE: You must not change the interest object - if you need to change it then make a copy.

data - The received Data object.

onDataValidationFailed

public void onDataValidationFailed(Data data,
                                   String reason)

Description copied from interface: OnDataValidationFailed

When verifyData fails, onDataValidationFailed is called.

Specified by:

onDataValidationFailed in interface OnDataValidationFailed

Parameters:

data - The data object being verified.

reason - The reason for the failed validation.

onNetworkNack

public void onNetworkNack(Interest interest,
                          NetworkNack networkNack)

Description copied from interface: OnNetworkNack

When a network Nack packet is received, onNetworkNack is called.

Specified by:

onNetworkNack in interface OnNetworkNack

Parameters:

interest - The interest given to Face.expressInterest. NOTE: You must not change the interest object - if you need to change it then make a copy.

networkNack - The received NetworkNack object.

onTimeout

public void onTimeout(Interest interest)

Description copied from interface: OnTimeout

If the interest times out according to the interest lifetime, onTimeout is called.

Specified by:

onTimeout in interface OnTimeout

Parameters:

interest - The interest given to expressInterest.

isStopped

public boolean isStopped()

stop

public void stop()

Stop fetching packets and clear the received data.