• Home
• net.named-data
• jndn-android-with-async-io
• 0.16
• source code
• SegmentFetcher.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

net.named_data.jndn.util.SegmentFetcher Maven / Gradle / Ivy

/**
 * Copyright (C) 2015-2017 Regents of the University of California.
 * @author: Jeff Thompson 
 * @author: From ndn-cxx util/segment-fetcher https://github.com/named-data/ndn-cxx
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see .
 * A copy of the GNU Lesser General Public License is in the file COPYING.
 */

package net.named_data.jndn.util;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.ArrayList;
import java.util.logging.Level;
import java.util.logging.Logger;
import net.named_data.jndn.Data;
import net.named_data.jndn.Face;
import net.named_data.jndn.Interest;
import net.named_data.jndn.Name;
import net.named_data.jndn.OnData;
import net.named_data.jndn.OnTimeout;
import net.named_data.jndn.encoding.EncodingException;
import net.named_data.jndn.security.KeyChain;
import net.named_data.jndn.security.OnVerified;
import net.named_data.jndn.security.OnDataValidationFailed;

/**
 * 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) {
 *            ...
 *          }});
 */
public class SegmentFetcher implements OnData, OnDataValidationFailed, OnTimeout {
  public enum ErrorCode {
    INTEREST_TIMEOUT,
    DATA_HAS_NO_SEGMENT,
    SEGMENT_VERIFICATION_FAILED,
    IO_ERROR
  }

  public interface OnComplete {
    void onComplete(Blob content);
  }

  public interface VerifySegment {
    boolean verifySegment(Data data);
  }

  public interface OnError {
    void onError(ErrorCode errorCode, String message);
  }

  /**
   * DontVerifySegment may be used in fetch to skip validation of Data packets.
   */
  public static final VerifySegment DontVerifySegment = new VerifySegment() {
   public boolean verifySegment(Data data) {
     return true;
   }};

  /**
   * Initiate segment fetching. For more details, see the documentation for
   * the class.
   * @param face This calls face.expressInterest to fetch more segments.
   * @param 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.
   * @param 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.
   * @param 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.
   * @param 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.
   */
  public static void
  fetch
    (Face face, Interest baseInterest, VerifySegment verifySegment,
     OnComplete onComplete, OnError onError)
  {
    new SegmentFetcher(face, null, verifySegment, onComplete, onError)
      .fetchFirstSegment(baseInterest);
  }

  /**
   * Initiate segment fetching. For more details, see the documentation for
   * the class.
   * @param face This calls face.expressInterest to fetch more segments.
   * @param 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.
   * @param 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.
   * @param 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.
   * @param 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.
   */
  public static void
  fetch
    (Face face, Interest baseInterest, KeyChain validatorKeyChain,
     OnComplete onComplete, OnError onError)
  {
    new SegmentFetcher
      (face, validatorKeyChain, DontVerifySegment, onComplete, onError)
      .fetchFirstSegment(baseInterest);
  }

  /**
   * Create a new SegmentFetcher to use the Face. See the static fetch method
   * for details. If validatorKeyChain is not null, use it and ignore
   * verifySegment. After creating the SegmentFetcher, call fetchFirstSegment.
   * @param face This calls face.expressInterest to fetch more segments.
   * @param validatorKeyChain If this is not null, use its verifyData instead of
   * the verifySegment callback.
   * @param 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.
   * @param onComplete When all segments are received, call
   * onComplete.onComplete(content) where content is the concatenation of the
   * content of all the segments.
   * @param onError Call onError.onError(errorCode, message) for timeout or an
   * error processing segments.
   */
  private SegmentFetcher
    (Face face, KeyChain validatorKeyChain, VerifySegment verifySegment,
     OnComplete onComplete, OnError onError)
  {
    face_ = face;
    validatorKeyChain_ = validatorKeyChain;
    verifySegment_ = verifySegment;
    onComplete_ = onComplete;
    onError_ = onError;
  }

  private void
  fetchFirstSegment(Interest baseInterest)
  {
    Interest interest = new Interest(baseInterest);
    interest.setChildSelector(1);
    interest.setMustBeFresh(true);

    try {
      face_.expressInterest(interest, this, this);
    } catch (IOException ex) {
      try {
        onError_.onError
          (ErrorCode.IO_ERROR, "I/O error fetching the first segment " + ex);
      } catch (Throwable exception) {
        logger_.log(Level.SEVERE, "Error in onError", exception);
      }
    }
  }

  private void
  fetchNextSegment(Interest originalInterest, Name dataName, long segment)
  {
    // Start with the original Interest to preserve any special selectors.
    Interest interest = new Interest(originalInterest);
    // Changing a field clears the nonce so that the library will generate a new one.
    interest.setChildSelector(0);
    interest.setMustBeFresh(false);
    interest.setName(dataName.getPrefix(-1).appendSegment(segment));
    try {
      face_.expressInterest(interest, this, this);
    } catch (IOException ex) {
      try {
        onError_.onError
          (ErrorCode.IO_ERROR, "I/O error fetching the next segment " + ex);
      } catch (Throwable exception) {
        logger_.log(Level.SEVERE, "Error in onError", exception);
      }
    }
  }

  public void
  onData(final Interest originalInterest, Data data)
  {
    if (validatorKeyChain_ != null) {
      try {
        final SegmentFetcher thisSegmentFetcher = this;
        validatorKeyChain_.verifyData
          (data,
           new OnVerified() {
             public void onVerified(Data localData) {
               thisSegmentFetcher.onVerified(localData, originalInterest);
             }
           },
           this);
      } catch (Throwable ex) {
        try {
          onError_.onError
            (ErrorCode.SEGMENT_VERIFICATION_FAILED,
             "Error in KeyChain.verifyData " + ex.getMessage());
        } catch (Throwable ex2) {
          logger_.log(Level.SEVERE, "Error in onError", ex2);
        }
      }
    }
    else {
      boolean verified = false;
      try {
        verified = verifySegment_.verifySegment(data);
      } catch (Throwable ex) {
        logger_.log(Level.SEVERE, "Error in verifySegment", ex);
      }
      if (!verified) {
        try {
          onError_.onError
            (ErrorCode.SEGMENT_VERIFICATION_FAILED, "Segment verification failed");
        } catch (Throwable ex) {
          logger_.log(Level.SEVERE, "Error in onError", ex);
        }
        return;
      }

      onVerified(data, originalInterest);
    }
  }

  public void
  onVerified(Data data, Interest originalInterest)
  {
    if (!endsWithSegmentNumber(data.getName())) {
      // We don't expect a name without a segment number.  Treat it as a bad packet.
      try {
        onError_.onError
          (ErrorCode.DATA_HAS_NO_SEGMENT,
           "Got an unexpected packet without a segment number: " + data.getName().toUri());
      } catch (Throwable ex) {
        logger_.log(Level.SEVERE, "Error in onError", ex);
      }
    }
    else {
      long currentSegment;
      try {
        currentSegment = data.getName().get(-1).toSegment();
      }
      catch (EncodingException ex) {
        try {
          onError_.onError
            (ErrorCode.DATA_HAS_NO_SEGMENT,
             "Error decoding the name segment number " +
             data.getName().get(-1).toEscapedString() + ": " + ex);
        } catch (Throwable exception) {
          logger_.log(Level.SEVERE, "Error in onError", exception);
        }
        return;
      }

      long expectedSegmentNumber = contentParts_.size();
      if (currentSegment != expectedSegmentNumber) {
        // Try again to get the expected segment.  This also includes the case
        //   where the first segment is not segment 0.
        fetchNextSegment(originalInterest, data.getName(), expectedSegmentNumber);
      }
      else {
        // Save the content and check if we are finished.
        contentParts_.add(data.getContent());

        if (data.getMetaInfo().getFinalBlockId().getValue().size() > 0) {
          long finalSegmentNumber;
          try {
            finalSegmentNumber = data.getMetaInfo().getFinalBlockId().toSegment();
          }
          catch (EncodingException ex) {
            try {
              onError_.onError
                (ErrorCode.DATA_HAS_NO_SEGMENT,
                 "Error decoding the FinalBlockId segment number " +
                 data.getMetaInfo().getFinalBlockId().toEscapedString() + ": " + ex);
            } catch (Throwable exception) {
              logger_.log(Level.SEVERE, "Error in onError", exception);
            }
            return;
          }

          if (currentSegment == finalSegmentNumber) {
            // We are finished.

            // Get the total size and concatenate to get content.
            int totalSize = 0;
            for (int i = 0; i < contentParts_.size(); ++i)
              totalSize += ((Blob)contentParts_.get(i)).size();
            ByteBuffer content = ByteBuffer.allocate(totalSize);
            for (int i = 0; i < contentParts_.size(); ++i)
              content.put(((Blob)contentParts_.get(i)).buf());
            content.flip();

            try {
              onComplete_.onComplete(new Blob(content, false));
            } catch (Throwable ex) {
              logger_.log(Level.SEVERE, "Error in onComplete", ex);
            }
            return;
          }
        }

        // Fetch the next segment.
        fetchNextSegment(originalInterest, data.getName(), expectedSegmentNumber + 1);
      }
    }
  }

  public void
  onDataValidationFailed(Data data, String reason)
  {
    try {
      onError_.onError
        (ErrorCode.SEGMENT_VERIFICATION_FAILED,
         "Segment verification failed for " + data.getName().toUri() +
         " . Reason: " + reason);
    } catch (Throwable ex) {
      logger_.log(Level.SEVERE, "Error in onError", ex);
    }
  }

  public void
  onTimeout(Interest interest)
  {
    try {
      onError_.onError
        (ErrorCode.INTEREST_TIMEOUT,
         "Time out for interest " + interest.getName().toUri());
    } catch (Throwable ex) {
      logger_.log(Level.SEVERE, "Error in onError", ex);
    }
  }

  /**
   * Check if the last component in the name is a segment number.
   * @param name The name to check.
   * @return True if the name ends with a segment number, otherwise false.
   */
  private static boolean
  endsWithSegmentNumber(Name name)
  {
    return name.size() >= 1 && name.get(-1).isSegment();
  }

  // Use a non-template ArrayList so it works with older Java compilers.
  private final ArrayList contentParts_ = new ArrayList(); // of Blob
  private final Face face_;
  private final KeyChain validatorKeyChain_;
  private final VerifySegment verifySegment_;
  private final OnComplete onComplete_;
  private final OnError onError_;
  private static final Logger logger_ = Logger.getLogger(SegmentFetcher.class.getName());
}