net.named_data.jndn.util

Class SegmentFetcher

java.lang.Object

net.named_data.jndn.util.SegmentFetcher

All Implemented Interfaces:

OnData, OnTimeout, OnDataValidationFailed

public class SegmentFetcher
extends Object
implements OnData, OnDataValidationFailed, OnTimeout

SegmentFetcher is a utility class to fetch the latest version of segmented data. SegmentFetcher assumes that the data is named /{prefix}/{version}/{segment}, where: - {prefix} is the specified name prefix, - {version} is an unknown version that needs to be discovered, and - {segment} is a segment number. (The number of segments is unknown and is controlled by the `FinalBlockId` field in at least the last Data packet. The following logic is implemented in SegmentFetcher: 1. Express the first Interest to discover the version: Interest: /{prefix}?ChildSelector=1&MustBeFresh=true 2. Infer the latest version of the Data: {version} = Data.getName().get(-2) 3. If the segment number in the retrieved packet == 0, go to step 5. 4. Send an Interest for segment 0: Interest: /{prefix}/{version}/{segment=0} 5. Keep sending Interests for the next segment while the retrieved Data does not have a FinalBlockId or the FinalBlockId != Data.getName().get(-1). Interest: /{prefix}/{version}/{segment=(N+1))} 6. 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. 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 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

Methods

Modifier and Type	Method and Description
static void	fetch(Face face, Interest baseInterest, KeyChain validatorKeyChain, 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) Initiate segment fetching.
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	onTimeout(Interest interest) If the interest times out according to the interest lifetime, onTimeout is called.
void	onVerified(Data data, Interest originalInterest)

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.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 - An Interest for the initial segment of the requested data, where baseInterest.getName() has the name prefix. This interest may include a custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include selectors "ChildSelector=1" and "MustBeFresh=true" which will be turned off in subsequent Interests.

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,
         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 - An Interest for the initial segment of the requested data, where baseInterest.getName() has the name prefix. This interest may include a custom InterestLifetime and selectors that will propagate to all subsequent Interests. The only exception is that the initial Interest will be forced to include selectors "ChildSelector=1" and "MustBeFresh=true" which will be turned off in subsequent Interests.

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.

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.

onVerified

public void onVerified(Data data,
              Interest originalInterest)

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.

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.