public interface DescriptorReader
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);
}
}
Modifier and Type | Method and Description |
---|---|
void |
addDirectory(java.io.File directory)
Deprecated.
Replaced with a parameter in
readDescriptors(File...) ,
which ignores any directories added via this deprecated method. |
void |
addTarball(java.io.File tarball)
Deprecated.
Replaced with a parameter in
readDescriptors(File...) ,
which ignores any tarballs added via this deprecated method. |
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.util.Iterator<DescriptorFile> |
readDescriptors()
Deprecated.
Replaced with
readDescriptors(File...) . |
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 |
setExcludeFiles(java.io.File historyFile)
Deprecated.
Replaced by
setHistoryFile(File) and
saveHistoryFile(File) which let the application explicitly
tell us when it's done processing read descriptors. |
void |
setFailUnrecognizedDescriptorLines()
Deprecated.
Removed in an attempt to simplify the interface. Applications
that must fail descriptors with unrecognized lines can instead check
whether
Descriptor.getUnrecognizedLines() returns any lines. |
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 |
setMaxDescriptorFilesInQueue(int max)
Deprecated.
Replaced with
setMaxDescriptorsInQueue(int) . |
void |
setMaxDescriptorsInQueue(int maxDescriptorsInQueue)
Don't keep more than this number of descriptors in the queue (default:
100).
|
void addDirectory(java.io.File directory)
readDescriptors(File...)
,
which ignores any directories added via this deprecated method.void addTarball(java.io.File tarball)
readDescriptors(File...)
,
which ignores any tarballs added via this deprecated method.void setExcludeFiles(java.io.File historyFile)
setHistoryFile(File)
and
saveHistoryFile(File)
which let the application explicitly
tell us when it's done processing read descriptors.Add a new line for each descriptor that is read in this execution and remove lines for files that don't exist anymore.
Lines in the history file contain the last modified time in milliseconds since the epoch and the absolute path of a file.
void setHistoryFile(java.io.File historyFile)
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.
void saveHistoryFile(java.io.File historyFile)
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.
void setExcludedFiles(java.util.SortedMap<java.lang.String,java.lang.Long> excludedFiles)
Can be used instead of (or in addition to) a history file.
java.util.SortedMap<java.lang.String,java.lang.Long> getExcludedFiles()
Can be used instead of (or in addition to) a history file when combined with the set of parsed files.
java.util.SortedMap<java.lang.String,java.lang.Long> getParsedFiles()
Can be used instead of (or in addition to) a history file when combined with the set of excluded files.
void setFailUnrecognizedDescriptorLines()
Descriptor.getUnrecognizedLines()
returns any lines.This option is not set by default, because the Tor specifications allow for new lines to be added that shall be ignored by older Tor versions. But some applications may want to handle unrecognized descriptor lines explicitly.
void setMaxDescriptorFilesInQueue(int max)
setMaxDescriptorsInQueue(int)
.The default is 100, but if descriptor files contain hundreds or even thousands of descriptors, that default may be too high.
void setMaxDescriptorsInQueue(int maxDescriptorsInQueue)
maxDescriptorsInQueue
- Maximum number of descriptors in the queue.java.util.Iterator<DescriptorFile> readDescriptors()
readDescriptors(File...)
.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.
java.lang.Iterable<Descriptor> readDescriptors(java.io.File... descriptorFiles)
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.
descriptorFiles
- One or more directories, tarballs, or files
containing descriptors.