Package org.torproject.descriptor

Interface DescriptorReader

  • public interface DescriptorReader
    Descriptor source that reads descriptors from local files and provides an iterator over parsed descriptors.

    This descriptor source is likely the most widely used one, possibly in combination with DescriptorCollector to synchronize descriptors from the CollecTor service.

    Reading descriptors is done in a batch which starts after setting any configuration options and initiating the read process.

    Code sample:

    
 DescriptorReader descriptorReader =
     DescriptorSourceFactory.createDescriptorReader();
 // Read descriptors from local directory called in/.
 for (Descriptor descriptor :
     descriptorReader.readDescriptors(new File("in")) {
   // Only process network status consensuses, ignore the rest.
   if ((descriptor instanceof RelayNetworkStatusConsensus)) {
     RelayNetworkStatusConsensus consensus =
         (RelayNetworkStatusConsensus) descriptor;
     processConsensus(consensus);
   }
 }
    Since:
    1.0.0

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.SortedMap<java.lang.String,​java.lang.Long> getExcludedFiles()
      Return files and last modified timestamps of files that exist in the input directory or directories, but that have been excluded from parsing, because they haven't changed since they were last read.
      java.util.SortedMap<java.lang.String,​java.lang.Long> getParsedFiles()
      Return files and last modified timestamps of files that exist in the input directory or directories and that have been parsed.
      java.lang.Iterable<Descriptor> readDescriptors​(java.io.File... descriptorFiles)
      Read descriptors from the given descriptor file(s) and return the parsed descriptors.
      void saveHistoryFile​(java.io.File historyFile)
      Save a history file with file names and last modified timestamps of descriptor files that exist in the input directory or directories and that have either been parsed or excluded from parsing.
      void setExcludedFiles​(java.util.SortedMap<java.lang.String,​java.lang.Long> excludedFiles)
      Exclude files if they haven't changed since the corresponding last modified timestamps.
      void setHistoryFile​(java.io.File historyFile)
      Set a history file to load before reading descriptors and exclude descriptor files that haven't changed since they have last been read.
      void setMaxDescriptorsInQueue​(int maxDescriptorsInQueue)
      Don't keep more than this number of descriptors in the queue (default: 100).

    • Method Detail

      • setHistoryFile

        void setHistoryFile​(java.io.File historyFile)
        Set a history file to load before reading descriptors and exclude descriptor files that haven't changed since they have last been read.

        Lines in the history file contain the last modified time in milliseconds since the epoch and the absolute path of a file, separated by a space.

        Since:
        1.6.0

      • saveHistoryFile

        void saveHistoryFile​(java.io.File historyFile)
        Save a history file with file names and last modified timestamps of descriptor files that exist in the input directory or directories and that have either been parsed or excluded from parsing.

        Lines in the history file contain the last modified time in milliseconds since the epoch and the absolute path of a file, separated by a space.

        Since:
        1.6.0

      • setExcludedFiles

        void setExcludedFiles​(java.util.SortedMap<java.lang.String,​java.lang.Long> excludedFiles)
        Exclude files if they haven't changed since the corresponding last modified timestamps.

        Can be used instead of (or in addition to) a history file.

        Since:
        1.0.0

      • getExcludedFiles

        java.util.SortedMap<java.lang.String,​java.lang.Long> getExcludedFiles()
        Return files and last modified timestamps of files that exist in the input directory or directories, but that have been excluded from parsing, because they haven't changed since they were last read.

        Can be used instead of (or in addition to) a history file when combined with the set of parsed files.

        Since:
        1.0.0

      • getParsedFiles

        java.util.SortedMap<java.lang.String,​java.lang.Long> getParsedFiles()
        Return files and last modified timestamps of files that exist in the input directory or directories and that have been parsed.

        Can be used instead of (or in addition to) a history file when combined with the set of excluded files.

        Since:
        1.0.0

      • setMaxDescriptorsInQueue

        void setMaxDescriptorsInQueue​(int maxDescriptorsInQueue)
        Don't keep more than this number of descriptors in the queue (default: 100).
        Parameters:
        maxDescriptorsInQueue - Maximum number of descriptors in the queue.
        Since:
        1.9.0

      • readDescriptors

        java.lang.Iterable<Descriptor> readDescriptors​(java.io.File... descriptorFiles)
        Read descriptors from the given descriptor file(s) and return the parsed descriptors.

        Whenever the reader runs out of descriptors and expects to provide more shortly after, it blocks the caller. This method can only be run once.

        Parameters:
        descriptorFiles - One or more directories, tarballs, or files containing descriptors.
        Returns:
        Parsed descriptors.
        Since:
        1.9.0