[tor-commits] [metrics-lib/master] Document all public parts using Javadoc.
karsten at torproject.org
karsten at torproject.org
Tue May 31 18:49:22 UTC 2016
commit 6d05ae95e968806351892b09f7b9653ff82879ed
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date: Fri May 20 11:40:35 2016 +0200
Document all public parts using Javadoc.
Based in parts on very helpful suggestions and feedback by iwakeh.
Implements #16873.
---
CHANGELOG.md | 2 +
build.xml | 18 +
resources/overview.html | 69 +++
.../torproject/descriptor/BandwidthHistory.java | 46 +-
.../descriptor/BridgeExtraInfoDescriptor.java | 20 +-
.../torproject/descriptor/BridgeNetworkStatus.java | 114 +++-
.../descriptor/BridgePoolAssignment.java | 40 +-
.../descriptor/BridgeServerDescriptor.java | 19 +-
src/org/torproject/descriptor/Descriptor.java | 32 +-
.../torproject/descriptor/DescriptorCollector.java | 52 +-
.../descriptor/DescriptorDownloader.java | 205 +++++--
src/org/torproject/descriptor/DescriptorFile.java | 70 ++-
.../descriptor/DescriptorParseException.java | 9 +-
.../torproject/descriptor/DescriptorParser.java | 46 +-
.../torproject/descriptor/DescriptorReader.java | 146 ++++-
.../torproject/descriptor/DescriptorRequest.java | 91 ++-
.../descriptor/DescriptorSourceFactory.java | 128 +++-
src/org/torproject/descriptor/DirSourceEntry.java | 81 ++-
.../descriptor/DirectoryKeyCertificate.java | 98 ++-
.../torproject/descriptor/DirectorySignature.java | 43 +-
src/org/torproject/descriptor/ExitList.java | 76 ++-
src/org/torproject/descriptor/ExitListEntry.java | 48 +-
.../torproject/descriptor/ExtraInfoDescriptor.java | 670 +++++++++++++++------
.../ImplementationNotAccessibleException.java | 10 +-
src/org/torproject/descriptor/Microdescriptor.java | 130 +++-
.../torproject/descriptor/NetworkStatusEntry.java | 169 ++++--
src/org/torproject/descriptor/RelayDirectory.java | 93 ++-
.../descriptor/RelayExtraInfoDescriptor.java | 16 +-
.../torproject/descriptor/RelayNetworkStatus.java | 156 ++++-
.../descriptor/RelayNetworkStatusConsensus.java | 181 +++++-
.../descriptor/RelayNetworkStatusVote.java | 342 +++++++++--
.../descriptor/RelayServerDescriptor.java | 15 +-
.../torproject/descriptor/RouterStatusEntry.java | 43 +-
.../torproject/descriptor/ServerDescriptor.java | 436 ++++++++++----
src/org/torproject/descriptor/TorperfResult.java | 194 ++++--
src/org/torproject/descriptor/package-info.java | 80 +++
36 files changed, 3208 insertions(+), 780 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1b9a75..bfd4755 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,8 @@
implementation classes.
- Actually return the signing key digest in network status votes.
- Parse crypto parts in network status votes.
+ - Document all public parts in org.torproject.descriptor and add
+ an Ant target to generate Javadocs.
* Minor changes
- Include a Torperf results line with more than one unrecognized
diff --git a/build.xml b/build.xml
index f7ef7ca..129c4ed 100644
--- a/build.xml
+++ b/build.xml
@@ -1,7 +1,9 @@
<project default="jar" name="descriptor" basedir=".">
<property name="release.version" value="1.1.0-dev" />
<property name="sources" value="src"/>
+ <property name="resources" value="resources"/>
<property name="classes" value="classes"/>
+ <property name="docs" value="javadoc"/>
<property name="tests" value="test"/>
<property name="libs" value="lib"/>
<property name="jarfile" value="descriptor-${release.version}.jar" />
@@ -25,6 +27,7 @@
<target name="clean" >
<delete includeEmptyDirs="true">
<fileset dir="${classes}" defaultexcludes="false" includes="**" />
+ <fileset dir="${docs}" defaultexcludes="false" includes="**" />
</delete>
<delete file="${jarfile}"/>
<delete file="${jarsourcesfile}"/>
@@ -33,6 +36,7 @@
<target name="init">
<mkdir dir="${classes}"/>
+ <mkdir dir="${docs}"/>
</target>
<target name="compile"
@@ -50,6 +54,20 @@
</javac>
</target>
+ <target name="docs">
+ <javadoc destdir="${docs}"
+ footer="© 2016 The Tor Project"
+ doctitle="DescripTor API Documentation"
+ overview="${basedir}/${resources}/overview.html"
+ use="true"
+ windowtitle="DescripTor API Documentation">
+ <classpath refid="classpath"/>
+ <fileset dir="${sources}">
+ <exclude name="**/impl/**"/>
+ </fileset>
+ </javadoc>
+ </target>
+
<target name="test" depends="compile">
<javac destdir="${classes}"
srcdir="${tests}"
diff --git a/resources/overview.html b/resources/overview.html
new file mode 100644
index 0000000..f5c6b51
--- /dev/null
+++ b/resources/overview.html
@@ -0,0 +1,69 @@
+<html>
+<body>
+<p>DescripTor API, which is provided and supported by Tor's Metrics
+Team, is a library to obtain and process descriptors containing Tor
+network data. It is the main Java tool for processing Tor descriptors
+and provides a standard API consisting of interfaces and a reference
+implementation for all of them.</p>
+
+<p>Most Tor descriptors understood by this library are specified in the
+<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor
+directory protocol, version 3</a> or in the earlier
+<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or
+<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a>
+of that document.
+Other descriptors are specified on the
+<a href="https://collector.torproject.org/">CollecTor website</a>.</p>
+
+<p>The interfaces in
+<a href="./org/torproject/descriptor/package-summary.html">{@code org.torproject.descriptor}</a>
+as well as their implementations in the
+{@code org.torproject.descriptor.impl} package were driven by two main
+goals originating from the primary use case to make Tor network data
+accessible for statistical analysis:</p>
+
+<ul>
+<li><em>Complete coverage:</em> This library is supposed to cover the
+complete range of Tor descriptors made available by the
+<a href="https://collector.torproject.org">CollecTor</a> service.</li>
+<li><em>Runtime and memory efficiency:</em> Processing large amounts of
+descriptors in bulk is supposed to be efficient in terms of runtime and
+required memory.</li>
+</ul>
+
+<p>At the same time the current design and implementation were done with a
+number of non-goals in mind, even though some of these might turn into
+goals in the future:</p>
+
+<p><ul>
+<li><em>Verification:</em> The descriptor parser performs some basic
+verifications of descriptor formats, but no cryptographic verifications.
+It may not even be possible to write a cryptographic verification tool
+using parsed descriptor contents, though this has not been attempted
+yet.</li>
+<li><em>Potentially lossy conversion:</em> Descriptor contents may be
+converted to a format that is easier to process, even if that conversion
+makes it harder or impossible to re-create the original descriptor
+contents from a parsed descriptor.</li>
+<li><em>Generating descriptors:</em> This library does not contain any
+functionality to generate new descriptors for testing or related purposes,
+neither from previously set data nor randomly.</li>
+<li><em>Writing descriptors:</em> This library does not support writing
+descriptors to the file system or a database, both of which are left to
+the application. Stated differently, there are no descriptor sinks that
+would correspond to the provided descriptor sources.</li>
+</ul></p>
+
+<p>Hints about using DescripTor can be found in the
+<a href="./org/torproject/descriptor/package-summary.html#package.description">{@code org.torproject.descriptor} package description</a>.
+</p>
+
+<p>Contact and further information:
+<ul>
+<li><a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Metrics%2Fmetrics-lib">DescripTor Bug Tracker</a></li>
+<li><a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/metrics-team">Metrics Team Mailing List</a></li>
+<li><a href="https://trac.torproject.org/projects/tor/wiki/org/teams/MetricsTeam">Metrics Team Website</a></li>
+</ul>
+</body>
+</html>
+
diff --git a/src/org/torproject/descriptor/BandwidthHistory.java b/src/org/torproject/descriptor/BandwidthHistory.java
index 4431ee2..0be1a53 100644
--- a/src/org/torproject/descriptor/BandwidthHistory.java
+++ b/src/org/torproject/descriptor/BandwidthHistory.java
@@ -1,26 +1,52 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.SortedMap;
-/* Contains the bandwidth history of a relay or bridge. */
+/**
+ * Contains the bandwidth history of a relay or bridge.
+ *
+ * <p>A bandwidth history is not a descriptor type of its own but usually
+ * part of extra-info descriptors ({@link ExtraInfoDescriptor}) or server
+ * descriptors ({@link ServerDescriptor}).</p>
+ *
+ * @since 1.0.0
+ */
public interface BandwidthHistory {
- /* Return the original bandwidth history line as contained in the
- * descriptor, possibly prefixed with "opt ". */
+ /**
+ * Return the original bandwidth history line as contained in the
+ * descriptor, possibly prefixed with {@code "opt "}.
+ *
+ * @since 1.0.0
+ */
public String getLine();
- /* Return the end of the most recent interval in millis. */
+ /**
+ * Return the time in milliseconds since the epoch when the most recent
+ * interval ends.
+ *
+ * @since 1.0.0
+ */
public long getHistoryEndMillis();
- /* Return the interval length in seconds, which is typically 900 seconds
- * or 15 minutes. */
+ /**
+ * Return the interval length in seconds.
+ *
+ * @since 1.0.0
+ */
public long getIntervalLength();
- /* Return the (possibly empty) bandwidth history with map keys being
- * interval ends in millis and map values being number of bytes used in
- * the interval, ordered from oldest to newest interval. */
+ /**
+ * Return the (possibly empty) bandwidth history with map keys being
+ * times in milliseconds since the epoch when intervals end and map
+ * values being number of bytes used in the interval, ordered from
+ * oldest to newest interval.
+ *
+ * @since 1.0.0
+ */
public SortedMap<Long, Long> getBandwidthValues();
}
diff --git a/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java b/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java
index b566283..a3c168d 100644
--- a/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java
+++ b/src/org/torproject/descriptor/BridgeExtraInfoDescriptor.java
@@ -1,8 +1,24 @@
-/* Copyright 2015 The Tor Project
+/* Copyright 2015--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Contains a bridge extra-info descriptor. */
+/**
+ * Contains a sanitized bridge extra-info descriptor.
+ *
+ * <p>Sanitized bridge extra-info descriptors share many contents with
+ * relay extra-info descriptors ({@link RelayExtraInfoDescriptor}), which
+ * is why they share a common
+ * superinterface ({@link ExtraInfoDescriptor}). The main purpose of
+ * having two subinterfaces is being able to distinguish descriptor types
+ * more easily.</p>
+ *
+ * <p>Details about sanitizing bridge extra-info descriptors can be found
+ * <a href="https://collector.torproject.org/#type-bridge-extra-info">here</a>.
+ * </p>
+ *
+ * @since 1.1.0
+ */
public interface BridgeExtraInfoDescriptor extends ExtraInfoDescriptor {
}
diff --git a/src/org/torproject/descriptor/BridgeNetworkStatus.java b/src/org/torproject/descriptor/BridgeNetworkStatus.java
index 1a28ebf..c7458fd 100644
--- a/src/org/torproject/descriptor/BridgeNetworkStatus.java
+++ b/src/org/torproject/descriptor/BridgeNetworkStatus.java
@@ -1,62 +1,128 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.SortedMap;
+/**
+ * Contains a sanitized bridge network status document.
+ *
+ * <p>The bridge directory authority periodically publishes a network
+ * status document with one entry per known bridge in the network
+ * ({@link NetworkStatusEntry}) containing: a hash of its identity key, a
+ * hash of its most recent server descriptor, and a summary of what the
+ * bridge authority believed about its status.</p>
+ *
+ * <p>The main purpose of this document is to get an authoritative list of
+ * running bridges to the bridge distribution service BridgeDB.</p>
+ *
+ * <p>Details about sanitizing bridge network statuses can be found
+ * <a href="https://collector.torproject.org/#type-bridge-network-status">here</a>.
+ * </p>
+ *
+ * @since 1.0.0
+ */
public interface BridgeNetworkStatus extends Descriptor {
- /* Return the published time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the minimum uptime in seconds that this authority requires for
- * assigning the Stable flag, or -1 if the authority doesn't report this
- * value. */
+ /**
+ * Return the minimum uptime in seconds that this authority requires
+ * for assigning the Stable flag, or -1 if the authority doesn't report
+ * this value.
+ *
+ * @since 1.1.0
+ */
public long getStableUptime();
- /* Return the minimum MTBF (mean time between failure) that this
+ /**
+ * Return the minimum MTBF (mean time between failure) that this
* authority requires for assigning the Stable flag, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.1.0
+ */
public long getStableMtbf();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Fast flag, or -1 if the authority doesn't report this
- * value. */
+ * value.
+ *
+ * @since 1.1.0
+ */
public long getFastBandwidth();
- /* Return the minimum WFU (weighted fractional uptime) in percent that
- * this authority requires for assigning the Guard flag, or -1.0 if the
- * authority doesn't report this value. */
+ /**
+ * Return the minimum WFU (weighted fractional uptime) in percent that
+ * this authority requires for assigning the Guard flag, or -1 if the
+ * authority doesn't report this value.
+ *
+ * @since 1.1.0
+ */
public double getGuardWfu();
- /* Return the minimum weighted time in seconds that this authority needs
- * to know about a relay before assigning the Guard flag, or -1 if the
- * authority doesn't report this information. */
+ /**
+ * Return the minimum weighted time in seconds that this authority
+ * needs to know about a relay before assigning the Guard flag, or -1 if
+ * the authority doesn't report this information.
+ *
+ * @since 1.1.0
+ */
public long getGuardTk();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Guard flag if exits can be guards, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.1.0
+ */
public long getGuardBandwidthIncludingExits();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Guard flag if exits can not be guards, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.1.0
+ */
public long getGuardBandwidthExcludingExits();
- /* Return 1 if the authority has measured enough MTBF info to use the
+ /**
+ * Return 1 if the authority has measured enough MTBF info to use the
* MTBF requirement instead of the uptime requirement for assigning the
* Stable flag, 0 if not, or -1 if the authority doesn't report this
- * information. */
+ * information.
+ *
+ * @since 1.1.0
+ */
public int getEnoughMtbfInfo();
- /* Return 1 if the authority has enough measured bandwidths that it'll
+ /**
+ * Return 1 if the authority has enough measured bandwidths that it'll
* ignore the advertised bandwidth claims of routers without measured
* bandwidth, 0 if not, or -1 if the authority doesn't report this
- * information. */
+ * information.
+ *
+ * @since 1.1.0
+ */
public int getIgnoringAdvertisedBws();
- /* Return status entries, one for each contained bridge. */
+ /**
+ * Return status entries for each contained bridge, with map keys being
+ * SHA-1 digests of SHA-1 digest of the bridges' public identity keys,
+ * encoded as 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, NetworkStatusEntry> getStatusEntries();
}
diff --git a/src/org/torproject/descriptor/BridgePoolAssignment.java b/src/org/torproject/descriptor/BridgePoolAssignment.java
index 5186b2b..2de4ee9 100644
--- a/src/org/torproject/descriptor/BridgePoolAssignment.java
+++ b/src/org/torproject/descriptor/BridgePoolAssignment.java
@@ -1,17 +1,47 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.SortedMap;
+/**
+ * Contains a sanitized list of bridges together with the distribution
+ * pools they have been assigned to by the bridge distribution service
+ * BridgeDB.
+ *
+ * <p>BridgeDB receives bridge network statuses
+ * ({@link BridgeNetworkStatus}) from the bridge authority, assigns these
+ * bridges to persistent distribution rings, and hands them out to bridge
+ * users. BridgeDB periodically dumps the list of running bridges with
+ * information about the rings, subrings, and file buckets to which they
+ * are assigned to a local file.</p>
+ *
+ * <p>Details about sanitizing bridge pool assignments can be found
+ * <a href="https://collector.torproject.org/#type-bridge-pool-assignment">here</a>.
+ * </p>
+ *
+ * @since 1.0.0
+ */
public interface BridgePoolAssignment extends Descriptor {
- /* Return the publication time of this bridge pool assignment list. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the entries contained in this bridge pool assignment list with
- * map keys being bridge fingerprints and map values being assignment
- * strings, e.g. "https ring=3 flag=stable". */
+ /**
+ * Return the entries contained in this bridge pool assignment list
+ * with map keys being SHA-1 digests of SHA-1 digest of the bridges'
+ * public identity keys, encoded as 40 upper-case hexadecimal
+ * characters, and map values being assignment strings, e.g.
+ * {@code "https ring=3 flag=stable"}.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, String> getEntries();
}
diff --git a/src/org/torproject/descriptor/BridgeServerDescriptor.java b/src/org/torproject/descriptor/BridgeServerDescriptor.java
index 15b618a..7d4503f 100644
--- a/src/org/torproject/descriptor/BridgeServerDescriptor.java
+++ b/src/org/torproject/descriptor/BridgeServerDescriptor.java
@@ -1,8 +1,23 @@
-/* Copyright 2015 The Tor Project
+/* Copyright 2015--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Contains a bridge server descriptor. */
+/**
+ * Contains a sanitized bridge server descriptor.
+ *
+ * <p>Sanitized bridge server descriptors share many contents with relay
+ * server descriptors ({@link RelayServerDescriptor}), which is why they
+ * share a common superinterface ({@link ServerDescriptor}). The main
+ * purpose of having two subinterfaces is being able to distinguish
+ * descriptor types more easily.</p>
+ *
+ * <p>Details about sanitizing bridge server descriptors can be found
+ * <a href="https://collector.torproject.org/#type-bridge-server-descriptor">here</a>.
+ * </p>
+ *
+ * @since 1.1.0
+ */
public interface BridgeServerDescriptor extends ServerDescriptor {
}
diff --git a/src/org/torproject/descriptor/Descriptor.java b/src/org/torproject/descriptor/Descriptor.java
index 267caf1..7cad109 100644
--- a/src/org/torproject/descriptor/Descriptor.java
+++ b/src/org/torproject/descriptor/Descriptor.java
@@ -1,21 +1,39 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-/* Store meta-data about how a descriptor was downloaded or read from
- * disk. */
+/**
+ * Superinterface for any descriptor with access to generic information
+ * about the descriptor.
+ *
+ * @since 1.0.0
+ */
public interface Descriptor {
- /* Return the raw descriptor bytes. */
+ /**
+ * Return the raw descriptor bytes.
+ *
+ * @since 1.0.0
+ */
public byte[] getRawDescriptorBytes();
- /* Return the (possibly empty) list of annotations. */
+ /**
+ * Return the (possibly empty) list of annotations in the format
+ * {@code "@key( value)*"}.
+ *
+ * @since 1.0.0
+ */
public List<String> getAnnotations();
- /* Return any unrecognized lines when parsing this descriptor, or an
- * empty list if there were no unrecognized lines. */
+ /**
+ * Return any unrecognized lines when parsing this descriptor, or an
+ * empty list if there were no unrecognized lines.
+ *
+ * @since 1.0.0
+ */
public List<String> getUnrecognizedLines();
}
diff --git a/src/org/torproject/descriptor/DescriptorCollector.java b/src/org/torproject/descriptor/DescriptorCollector.java
index 18e594d..b1027dc 100644
--- a/src/org/torproject/descriptor/DescriptorCollector.java
+++ b/src/org/torproject/descriptor/DescriptorCollector.java
@@ -1,12 +1,39 @@
-/* Copyright 2015 The Tor Project
+/* Copyright 2015--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.io.File;
-/** Fetch descriptors from the CollecTor service available at
- * https://collector.torproject.org/ and store them to a local
- * directory. */
+/**
+ * Descriptor source that synchronizes descriptors from the CollecTor
+ * service to a given local directory.
+ *
+ * <p>This type is not a descriptor source in the proper sense, because it
+ * does not produce descriptors by itself. But it often creates the
+ * prerequisites for reading descriptors from disk using
+ * {@link DescriptorReader}.</p>
+ *
+ * <p>Code sample:</p>
+ * <pre>{@code
+ * DescriptorCollector descriptorCollector =
+ * DescriptorSourceFactory.createDescriptorCollector();
+ * descriptorCollector.collectDescriptors(
+ * // Download from Tor's main CollecTor instance,
+ * "https://collector.torproject.org",
+ * // include network status consensuses and relay server descriptors
+ * new String[] { "/recent/relay-descriptors/consensuses/",
+ * "/recent/relay-descriptors/server-descriptors/" },
+ * // regardless of last-modified time,
+ * 0L,
+ * // write to the local directory called in/,
+ * new File("in"),
+ * // and delete extraneous files that do not exist remotely anymore.
+ * true);
+ * }</pre>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorCollector {
/**
@@ -15,17 +42,18 @@ public interface DescriptorCollector {
* anymore.
*
* @param collecTorBaseUrl CollecTor base URL without trailing slash,
- * e.g., "https://collector.torproject.org".
+ * e.g., {@code "https://collector.torproject.org"}
* @param remoteDirectories Remote directories to collect descriptors
- * from, e.g., "/recent/relay-descriptors/server-descriptors/". Only
- * files in this directory will be collected, no files in its sub
- * directories.
+ * from, e.g.,
+ * {@code "/recent/relay-descriptors/server-descriptors/"}, without
+ * processing subdirectories unless they are explicitly listed
* @param minLastModified Minimum last-modified time in milliseconds of
- * files to be collected. Set to 0 for collecting all files.
- * @param localDirectory Directory where collected files will be
- * written.
+ * files to be collected, or 0 for collecting all files
+ * @param localDirectory Directory where collected files will be written
* @param deleteExtraneousLocalFiles Whether to delete all local files
- * that do not exist remotely anymore.
+ * that do not exist remotely anymore
+ *
+ * @since 1.0.0
*/
public void collectDescriptors(String collecTorBaseUrl,
String[] remoteDirectories, long minLastModified,
diff --git a/src/org/torproject/descriptor/DescriptorDownloader.java b/src/org/torproject/descriptor/DescriptorDownloader.java
index 1fc68a0..f0b1101 100644
--- a/src/org/torproject/descriptor/DescriptorDownloader.java
+++ b/src/org/torproject/descriptor/DescriptorDownloader.java
@@ -1,109 +1,198 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.Iterator;
import java.util.Set;
-/* Download relay descriptors from directory mirrors or authorities. */
+/**
+ * Descriptor source that downloads relay descriptors from directory
+ * authorities or mirrors.
+ *
+ * <p>Downloading descriptors is done in a batch which starts after
+ * setting any configuration options and initiating the download
+ * process.</p>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorDownloader {
- /* Add a directory authority to download descriptors from. A directory
- * authority is only required for downloading network status vote and
- * will be used when no directory mirrors are available. */
+ /**
+ * Add a directory authority to download descriptors from, which is
+ * only required for downloading network status votes and will be used
+ * when no directory mirrors are available.
+ *
+ * @since 1.0.0
+ */
public void addDirectoryAuthority(String nickname, String ip,
int dirPort);
- /* Add a directory mirror to download descriptors from. Directory
- * mirrors are preferred when downloading descriptors, except for
- * network status votes which are only available on directory
- * authorities. */
+ /**
+ * Add a directory mirror to download descriptors from, which is
+ * preferred for downloading descriptors, except for network status
+ * votes which are only available on directory authorities.
+ *
+ * @since 1.0.0
+ */
public void addDirectoryMirror(String nickname, String ip, int dirPort);
- /* Include the current network status consensus in the downloads. */
+ /**
+ * Include the current network status consensus in the downloads.
+ *
+ * @since 1.0.0
+ */
public void setIncludeCurrentConsensus();
- /* Include the current network status consensus in the downloads, and
- * attempt to download it from all directory authorities. The primary
- * purpose of doing this is to compare different consensuses and
- * download characteristics to each other. Typically, downloading from
- * a single directory mirror or authority is sufficient. */
+ /**
+ * Include the current network status consensus in the downloads, and
+ * attempt to download it from all directory authorities.
+ *
+ * <p>The primary purpose of doing this is to compare different
+ * consensuses and download characteristics to each other. Typically,
+ * downloading from a single directory mirror or authority is
+ * sufficient.</p>
+ *
+ * @since 1.0.0
+ */
public void setIncludeCurrentConsensusFromAllDirectoryAuthorities();
- /* Include the current network status votes referenced from a previously
- * downloaded consensus in the downloads. This requires downloading the
- * current consensus from at least one directory mirror or authority. */
+ /**
+ * Include the current network status votes referenced from a
+ * previously downloaded consensus in the downloads, which requires
+ * downloading the current consensus from at least one directory mirror
+ * or authority.
+ *
+ * @since 1.0.0
+ */
public void setIncludeCurrentReferencedVotes();
- /* Include the current network status vote published by the given
- * directory authority in the downloads. This requires downloading from
- * at least one directory authority. */
+ /**
+ * Include the current network status vote published by the given
+ * directory authority in the downloads, which requires downloading from
+ * at least one directory authority.
+ *
+ * @since 1.0.0
+ */
public void setIncludeCurrentVote(String fingerprint);
- /* Include the current network status votes published by the given
- * directory authorities in the downloads. This requires downloading
- * from at least one directory authority. */
+ /**
+ * Include the current network status votes published by the given
+ * directory authorities in the downloads, which requires downloading
+ * from at least one directory authority.
+ *
+ * @since 1.0.0
+ */
public void setIncludeCurrentVotes(Set<String> fingerprints);
- /* Include all server descriptors referenced from a previously
- * downloaded network status consensus in the downloads. */
+ /**
+ * Include all server descriptors referenced from a previously
+ * downloaded network status consensus in the downloads.
+ *
+ * @since 1.0.0
+ */
public void setIncludeReferencedServerDescriptors();
- /* Exclude the server descriptor with the given identifier from the
+ /**
+ * Exclude the server descriptor with the given identifier from the
* downloads even if it's referenced from a consensus and we're supposed
- * to download all referenced server descriptors. */
+ * to download all referenced server descriptors.
+ *
+ * @since 1.0.0
+ */
public void setExcludeServerDescriptor(String identifier);
- /* Exclude the server descriptors with the given identifiers from the
+ /**
+ * Exclude the server descriptors with the given identifiers from the
* downloads even if they are referenced from a consensus and we're
- * supposed to download all referenced server descriptors. */
+ * supposed to download all referenced server descriptors.
+ *
+ * @since 1.0.0
+ */
public void setExcludeServerDescriptors(Set<String> identifier);
- /* Include all extra-info descriptors referenced from previously
- * downloaded server descriptors in the downloads. */
+ /**
+ * Include all extra-info descriptors referenced from previously
+ * downloaded server descriptors in the downloads.
+ *
+ * @since 1.0.0
+ */
public void setIncludeReferencedExtraInfoDescriptors();
- /* Exclude the extra-info descriptor with the given identifier from the
+ /**
+ * Exclude the extra-info descriptor with the given identifier from the
* downloads even if it's referenced from a server descriptor and we're
- * supposed to download all referenced extra-info descriptors. */
+ * supposed to download all referenced extra-info descriptors.
+ *
+ * @since 1.0.0
+ */
public void setExcludeExtraInfoDescriptor(String identifier);
- /* Exclude the extra-info descriptors with the given identifiers from
+ /**
+ * Exclude the extra-info descriptors with the given identifiers from
* the downloads even if they are referenced from server descriptors
* and we're supposed to download all referenced extra-info
- * descriptors. */
+ * descriptors.
+ *
+ * @since 1.0.0
+ */
public void setExcludeExtraInfoDescriptors(Set<String> identifiers);
- /* Define a connect timeout for a single request. If a timeout expires,
- * no further requests will be sent to the directory authority or
- * mirror. Setting this value to 0 disables the connect timeout.
- * Default value is 1 minute (60 * 1000). */
+ /**
+ * Define a connect timeout for a single request.
+ *
+ * <p>If a timeout expires, no further requests will be sent to the
+ * directory authority or mirror. Setting this value to 0 disables the
+ * connect timeout. Default value is 1 minute (60 * 1000).</p>
+ *
+ * @since 1.0.0
+ */
public void setConnectTimeout(long connectTimeoutMillis);
- /* Define a read timeout for a single request. If a timeout expires,
- * no further requests will be sent to the directory authority or
- * mirror. Setting this value to 0 disables the read timeout.
- * Default value is 1 minute (60 * 1000). */
+ /**
+ * Define a read timeout for a single request.
+ *
+ * <p>If a timeout expires, no further requests will be sent to the
+ * directory authority or mirror. Setting this value to 0 disables the
+ * read timeout. Default value is 1 minute (60 * 1000).</p>
+ *
+ * @since 1.0.0
+ */
public void setReadTimeout(long readTimeoutMillis);
- /* Define a global timeout for all requests. Once this timeout expires,
- * all running requests are aborted and no further requests are made.
- * Setting this value to 0 disables the global timeout. Default is 1
- * hour (60 * 60 * 1000). */
+ /**
+ * Define a global timeout for all requests.
+ *
+ * <p>Once this timeout expires, all running requests are aborted and no
+ * further requests are made. Setting this value to 0 disables the
+ * global timeout. Default is 1 hour (60 * 60 * 1000).</p>
+ *
+ * @since 1.0.0
+ */
public void setGlobalTimeout(long globalTimeoutMillis);
- /* Fail descriptor parsing when encountering an unrecognized line. This
- * 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. */
+ /**
+ * Fail descriptor parsing when encountering an unrecognized line.
+ *
+ * <p>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.</p>
+ *
+ * @since 1.0.0
+ */
public void setFailUnrecognizedDescriptorLines();
- /* Download the previously configured relay descriptors and make them
- * available via the returned blocking iterator. Whenever the
- * downloader runs out of descriptors and expects to provide more
- * shortly after, it blocks the caller. This method can only be run
- * once. */
+ /**
+ * Download the previously configured relay descriptors and make them
+ * available via the returned blocking iterator.
+ *
+ * <p>Whenever the downloader runs out of descriptors and expects to
+ * provide more shortly after, it blocks the caller. This method can
+ * only be run once.</p>
+ *
+ * @since 1.0.0
+ */
public Iterator<DescriptorRequest> downloadDescriptors();
}
diff --git a/src/org/torproject/descriptor/DescriptorFile.java b/src/org/torproject/descriptor/DescriptorFile.java
index ec012ca..417d7f9 100644
--- a/src/org/torproject/descriptor/DescriptorFile.java
+++ b/src/org/torproject/descriptor/DescriptorFile.java
@@ -1,39 +1,77 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.io.File;
import java.util.List;
-/* Store meta-data about a descriptor file and a list of the contained
- * descriptors. */
+/**
+ * Container for descriptors read from a file.
+ *
+ * <p>When the {@link DescriptorReader} reads descriptors from local files
+ * it provides an iterator over these containers which in turn contain
+ * references to classes implementing the {@link Descriptor} interface.
+ * This container also stores potentially useful meta-data about the
+ * descriptor file.</p>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorFile {
- /* Return the directory where this descriptor file was contained, or
- * null if the file was contained in a tarball. */
+ /**
+ * Return the directory where this descriptor file was contained, or
+ * null if the file was contained in a tarball.
+ *
+ * @since 1.0.0
+ */
public File getDirectory();
- /* Return the tarball where this descriptor file was contained, or null
- * if the file was not contained in a tarball. */
+ /**
+ * Return the tarball where this descriptor file was contained, or null
+ * if the file was not contained in a tarball.
+ *
+ * @since 1.0.0
+ */
public File getTarball();
- /* Return the descriptor file itself, or null if the descriptor file was
- * contained in a tarball. */
+ /**
+ * Return the descriptor file itself, or null if the descriptor file
+ * was contained in a tarball.
+ *
+ * @since 1.0.0
+ */
public File getFile();
- /* Return the descriptor file name, which is either the absolute path of
- * the file on disk, or the tar file entry name. */
+ /**
+ * Return the descriptor file name, which is either the absolute path
+ * of the file on disk, or the tar file entry name.
+ *
+ * @since 1.0.0
+ */
public String getFileName();
- /* Return the time in millis when the descriptor file on disk was last
- * modified. */
+ /**
+ * Return the time in milliseconds since the epoch when the descriptor
+ * file on disk was last modified.
+ *
+ * @since 1.0.0
+ */
public long getLastModified();
- /* Return the descriptors contained in the descriptor file. */
+ /**
+ * Return the descriptors contained in the descriptor file.
+ *
+ * @since 1.0.0
+ */
public List<Descriptor> getDescriptors();
- /* Return the first exception that was thrown when reading this file or
- * parsing its content, or null if no exception was thrown. */
+ /**
+ * Return the first exception that was thrown when reading this file or
+ * parsing its content, or null if no exception was thrown.
+ *
+ * @since 1.0.0
+ */
public Exception getException();
}
diff --git a/src/org/torproject/descriptor/DescriptorParseException.java b/src/org/torproject/descriptor/DescriptorParseException.java
index ff5707d..309d3f7 100644
--- a/src/org/torproject/descriptor/DescriptorParseException.java
+++ b/src/org/torproject/descriptor/DescriptorParseException.java
@@ -1,7 +1,14 @@
-/* Copyright 2014--2015 The Tor Project
+/* Copyright 2014--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
+/**
+ * Thrown if raw descriptor contents cannot be parsed to one or more
+ * {@link Descriptor} instances, according to descriptor specifications.
+ *
+ * @since 1.0.0
+ */
@SuppressWarnings("deprecation")
public class DescriptorParseException
extends org.torproject.descriptor.impl.DescriptorParseException {
diff --git a/src/org/torproject/descriptor/DescriptorParser.java b/src/org/torproject/descriptor/DescriptorParser.java
index 7c59cea..680b8b2 100644
--- a/src/org/torproject/descriptor/DescriptorParser.java
+++ b/src/org/torproject/descriptor/DescriptorParser.java
@@ -1,25 +1,47 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-
-/* Parse descriptors that are already in memory instead of using the
- * descriptor reader or downloader. */
+/**
+ * Descriptor source that parses descriptors from raw descriptor contents.
+ *
+ * <p>Unlike most of the other descriptor sources this descriptor source
+ * does not operate in a batch-processing mode. It takes the raw
+ * descriptor contents of one or more descriptors, parses them, and
+ * returns a list of descriptors.</p>
+ *
+ * <p>This descriptor source is internally used by other descriptor
+ * sources but can also be used directly by applications that obtain
+ * raw descriptor contents via other means than one of the existing
+ * descriptor sources.</p>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorParser {
- /* Fail descriptor parsing when encountering an unrecognized line. This
- * 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. */
+ /**
+ * Fail descriptor parsing when encountering an unrecognized line.
+ *
+ * <p>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.</p>
+ *
+ * @since 1.0.0
+ */
public void setFailUnrecognizedDescriptorLines(
boolean failUnrecognizedDescriptorLines);
- /* Parse descriptors in the given byte array, possibly parsing the
- * publication time from the file name (depending on the descriptor
- * type). */
+ /**
+ * Parse descriptors in the given byte array, possibly parsing the
+ * publication time from the file name, depending on the descriptor
+ * type.
+ *
+ * @since 1.0.0
+ */
public List<Descriptor> parseDescriptors(byte[] rawDescriptorBytes,
String fileName) throws DescriptorParseException;
}
diff --git a/src/org/torproject/descriptor/DescriptorReader.java b/src/org/torproject/descriptor/DescriptorReader.java
index 0e2fe27..771755e 100644
--- a/src/org/torproject/descriptor/DescriptorReader.java
+++ b/src/org/torproject/descriptor/DescriptorReader.java
@@ -1,63 +1,143 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.io.File;
import java.util.Iterator;
import java.util.SortedMap;
-/* Read descriptors from one or more local directories. */
+/**
+ * Descriptor source that reads descriptors from local files and provides
+ * an iterator over parsed descriptors.
+ *
+ * <p>This descriptor source is likely the most widely used one, possibly
+ * in combination with {@link DescriptorCollector} to synchronize
+ * descriptors from the CollecTor service.</p>
+ *
+ * <p>Reading descriptors is done in a batch which starts after setting
+ * any configuration options and initiating the read process.</p>
+ *
+ * <p>Code sample:</p>
+ * <pre>{@code
+ * DescriptorReader descriptorReader =
+ * DescriptorSourceFactory.createDescriptorReader();
+ * // Read descriptors from local directory called in/.
+ * descriptorReader.addDirectory(new File("in"));
+ * Iterator<DescriptorFile> descriptorFiles =
+ * descriptorReader.readDescriptors();
+ * while (descriptorFiles.hasNext()) {
+ * DescriptorFile descriptorFile = descriptorFiles.next();
+ * for (Descriptor descriptor : descriptorFile.getDescriptors()) {
+ * if ((descriptor instanceof RelayNetworkStatusConsensus)) {
+ * // Only process network status consensuses, ignore the rest.
+ * RelayNetworkStatusConsensus consensus =
+ * (RelayNetworkStatusConsensus) descriptor;
+ * processConsensus(consensus);
+ * }
+ * }
+ * }}</pre>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorReader {
- /* Add a local directory to read descriptor files or tarballs containing
- * descriptor files from. */
+ /**
+ * Add a local directory to read descriptors from, which may contain
+ * descriptor files or tarballs containing descriptor files.
+ *
+ * @since 1.0.0
+ */
public void addDirectory(File directory);
- /* Add an uncompressed or bz2-compressed tarball to read descriptors
- * from. */
+ /**
+ * Add a tarball to read descriptors from, which may be uncompressed,
+ * bz2-compressed, or xz-compressed.
+ *
+ * @since 1.0.0
+ */
public void addTarball(File tarball);
- /* Exclude files that are contained in the given history file and that
- * haven't changed since they were last read. Add reads from the
- * current run to the history file. Remove files that don't exist
- * anymore from the history file. Lines in the history file contain the
- * last modified timestamp and the absolute path of a file. */
+ /**
+ * Exclude files that are listed in the given history file and that
+ * haven't changed since they have last been read.
+ *
+ * <p>Add a new line for each descriptor that is read in this execution
+ * and remove lines for files that don't exist anymore.</p>
+ *
+ * <p>Lines in the history file contain the last modified time in
+ * milliseconds since the epoch and the absolute path of a file.</p>
+ *
+ * @since 1.0.0
+ */
public void setExcludeFiles(File historyFile);
- /* 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. */
+ /**
+ * Exclude files if they haven't changed since the corresponding last
+ * modified timestamps.
+ *
+ * <p>Can be used instead of (or in addition to) a history file.</p>
+ *
+ * @since 1.0.0
+ */
public void setExcludedFiles(SortedMap<String, Long> excludedFiles);
- /* Return files and lost modified timestamps of files that exist in the
+ /**
+ * 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. */
+ *
+ * <p>Can be used instead of (or in addition to) a history file when
+ * combined with the set of parsed files.</p>
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Long> getExcludedFiles();
- /* 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. */
+ /**
+ * Return files and last modified timestamps of files that exist in the
+ * input directory or directories and that have been parsed.
+ *
+ * <p>Can be used instead of (or in addition to) a history file when
+ * combined with the set of excluded files.</p>
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Long> getParsedFiles();
- /* Fail descriptor parsing when encountering an unrecognized line. This
- * 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. */
+ /**
+ * Fail descriptor parsing when encountering an unrecognized line.
+ *
+ * <p>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.</p>
+ *
+ * @since 1.0.0
+ */
public void setFailUnrecognizedDescriptorLines();
- /* Don't keep more than this number of parsed descriptor files in the
- * queue. The default is 100, but if descriptor files contain hundreds
- * or even thousands of descriptors, that default may be too high. */
+ /**
+ * Don't keep more than this number of parsed descriptor files in the
+ * queue.
+ *
+ * <p>The default is 100, but if descriptor files contain hundreds or
+ * even thousands of descriptors, that default may be too high.</p>
+ *
+ * @since 1.0.0
+ */
public void setMaxDescriptorFilesInQueue(int max);
- /* Read the previously configured descriptors and make them available
- * via the returned blocking iterator. 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. */
+ /**
+ * Read the previously configured descriptors and make them available
+ * via the returned blocking iterator.
+ *
+ * <p>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.</p>
+ *
+ * @since 1.0.0
+ */
public Iterator<DescriptorFile> readDescriptors();
}
diff --git a/src/org/torproject/descriptor/DescriptorRequest.java b/src/org/torproject/descriptor/DescriptorRequest.java
index 067cd1b..c36c0c0 100644
--- a/src/org/torproject/descriptor/DescriptorRequest.java
+++ b/src/org/torproject/descriptor/DescriptorRequest.java
@@ -1,47 +1,100 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-/* Store meta-data about a descriptor request and a list of the returned
- * descriptors. */
+/**
+ * Container for descriptors downloaded from a directory authority or
+ * mirror.
+ *
+ * <p>When the {@link DescriptorDownloader} downloads descriptors from
+ * directory authorities or mirrors it provides an iterator over these
+ * containers which in turn contain references to classes implementing the
+ * {@link Descriptor} interface. This container also stores potentially
+ * useful meta-data about the descriptor request.</p>
+ *
+ * @since 1.0.0
+ */
public interface DescriptorRequest {
- /* Return the request URL that was used in this request. */
+ /**
+ * Return the request URL that was used in this request.
+ *
+ * @since 1.0.0
+ */
public String getRequestUrl();
- /* Return the nickname of the directory mirror or authority as
- * previously configured. */
+ /**
+ * Return the nickname of the directory mirror or authority as
+ * previously configured.
+ *
+ * @since 1.0.0
+ */
public String getDirectoryNickname();
- /* Return the first exception that was thrown when making this request
- * or parsing the response, or null if no exception was thrown. */
+ /**
+ * Return the first exception that was thrown when making this request
+ * or parsing the response, or null if no exception was thrown.
+ *
+ * @since 1.0.0
+ */
public Exception getException();
- /* Return the response code that the directory mirror or authority
- * returned. */
+ /**
+ * Return the response code that the directory mirror or authority
+ * returned.
+ *
+ * @since 1.0.0
+ */
public int getResponseCode();
- /* Return the time in millis when this request was started. */
+ /**
+ * Return the time in milliseconds since the epoch when this request
+ * was started.
+ *
+ * @since 1.0.0
+ */
public long getRequestStart();
- /* Return the time in millis when this request ended. */
+ /**
+ * Return the time in milliseconds since the epoch when this request
+ * ended.
+ *
+ * @since 1.0.0
+ */
public long getRequestEnd();
- /* Return whether this request ended, because the connect timeout has
- * expired. */
+ /**
+ * Return whether this request ended, because the connect timeout has
+ * expired.
+ *
+ * @since 1.0.0
+ */
public boolean connectTimeoutHasExpired();
- /* Return whether this request ended, because the read timeout has
- * expired. */
+ /**
+ * Return whether this request ended, because the read timeout has
+ * expired.
+ *
+ * @since 1.0.0
+ */
public boolean readTimeoutHasExpired();
- /* Return whether this request ended, because the global timeout for all
- * requests has expired. */
+ /**
+ * Return whether this request ended, because the global timeout for
+ * all requests has expired.
+ *
+ * @since 1.0.0
+ */
public boolean globalTimeoutHasExpired();
- /* Return the descriptors contained in the reply. */
+ /**
+ * Return the descriptors contained in the reply.
+ *
+ * @since 1.0.0
+ */
public List<Descriptor> getDescriptors();
}
diff --git a/src/org/torproject/descriptor/DescriptorSourceFactory.java b/src/org/torproject/descriptor/DescriptorSourceFactory.java
index 728c3eb..af13f39 100644
--- a/src/org/torproject/descriptor/DescriptorSourceFactory.java
+++ b/src/org/torproject/descriptor/DescriptorSourceFactory.java
@@ -1,49 +1,151 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Create descriptor source instances. */
+/**
+ * Factory for descriptor sources which in turn produce descriptors.
+ *
+ * <p>Descriptor sources are the only producers of classes implementing
+ * the {@link Descriptor} superinterface. There exist descriptor sources
+ * for obtaining remote descriptor data ({@link DescriptorDownloader} and
+ * {@link DescriptorCollector}) and descriptor sources for processing
+ * local descriptor data ({@link DescriptorReader} and
+ * {@link DescriptorParser}).</p>
+ *
+ * <p>By default, this factory returns implementations from the library's
+ * own impl package. This may be overridden by setting Java properties,
+ * though most users will simply use the default implementations.</p>
+ *
+ * <p>These properties can be used for setting the implementation:</p>
+ * <ul>
+ * <li>{@code descriptor.collector}</li>
+ * <li>{@code descriptor.downloader}</li>
+ * <li>{@code descriptor.parser}</li>
+ * <li>{@code descriptor.reader}</li>
+ * </ul>
+ *
+ * <p>Assuming the classpath contains the special implementation
+ * referenced, your application classes as well as a descriptor API jar
+ * the following is an example for using a different implementation of the
+ * descriptor downloader:</p>
+ *
+ * <p><code>
+ * java -Ddescriptor.downloader=my.special.descriptorimpl.Downloader my.app.Mainclass
+ * </code></p>
+ *
+ * @since 1.0.0
+ */
public final class DescriptorSourceFactory {
- /* default implementations */
- public final static String LOADER_DEFAULT =
+ /**
+ * Default implementation of the {@link DescriptorDownloader}
+ * descriptor source.
+ *
+ * @since 1.0.0
+ */
+ public final static String DOWNLOADER_DEFAULT =
"org.torproject.descriptor.impl.DescriptorDownloaderImpl";
+
+ /**
+ * Default implementation of the {@link DescriptorParser} descriptor
+ * source.
+ *
+ * @since 1.0.0
+ */
public final static String PARSER_DEFAULT =
"org.torproject.descriptor.impl.DescriptorParserImpl";
+
+ /**
+ * Default implementation of the {@link DescriptorReader} descriptor
+ * source.
+ *
+ * @since 1.0.0
+ */
public final static String READER_DEFAULT =
"org.torproject.descriptor.impl.DescriptorReaderImpl";
+
+ /**
+ * Default implementation of the {@link DescriptorCollector} descriptor
+ * source.
+ *
+ * @since 1.0.0
+ */
public final static String COLLECTOR_DEFAULT =
"org.torproject.descriptor.impl.DescriptorCollectorImpl";
- /* property names */
+ /**
+ * Property name for overriding the implementation of the
+ * {@link DescriptorParser} descriptor source, which is by default set
+ * to the class in {@link #PARSER_DEFAULT}.
+ *
+ * @since 1.0.0
+ */
public final static String PARSER_PROPERTY = "descriptor.parser";
+
+ /**
+ * Property name for overriding the implementation of the
+ * {@link DescriptorReader} descriptor source, which is by default set
+ * to the class in {@link #READER_DEFAULT}.
+ *
+ * @since 1.0.0
+ */
public final static String READER_PROPERTY = "descriptor.reader";
- public final static String LOADER_PROPERTY = "descriptor.downloader";
+
+ /**
+ * Property name for overriding the implementation of the
+ * {@link DescriptorDownloader} descriptor source, which is by default
+ * set to the class in {@link #DOWNLOADER_DEFAULT}.
+ *
+ * @since 1.0.0
+ */
+ public final static String DOWNLOADER_PROPERTY =
+ "descriptor.downloader";
+
+ /**
+ * Property name for overriding the implementation of the
+ * {@link DescriptorCollector} descriptor source, which is by default
+ * set to the class in {@link #COLLECTOR_DEFAULT}.
+ *
+ * @since 1.0.0
+ */
public final static String COLLECTOR_PROPERTY = "descriptor.collector";
/**
- * Create a descriptor parser.
+ * Create a new {@link DescriptorParser} by instantiating the class in
+ * {@link #PARSER_PROPERTY}.
+ *
+ * @since 1.0.0
*/
public final static DescriptorParser createDescriptorParser() {
return (DescriptorParser) retrieve(PARSER_PROPERTY);
}
/**
- * Create a descriptor reader.
+ * Create a new {@link DescriptorReader} by instantiating the class in
+ * {@link #READER_PROPERTY}.
+ *
+ * @since 1.0.0
*/
public final static DescriptorReader createDescriptorReader() {
return (DescriptorReader) retrieve(READER_PROPERTY);
}
/**
- * Create a descriptor downloader.
+ * Create a new {@link DescriptorDownloader} by instantiating the class
+ * in {@link #DOWNLOADER_PROPERTY}.
+ *
+ * @since 1.0.0
*/
public final static DescriptorDownloader createDescriptorDownloader() {
- return (DescriptorDownloader) retrieve(LOADER_PROPERTY);
+ return (DescriptorDownloader) retrieve(DOWNLOADER_PROPERTY);
}
/**
- * Create a descriptor collector.
+ * Create a new {@link DescriptorCollector} by instantiating the class
+ * in {@link #COLLECTOR_PROPERTY}.
+ *
+ * @since 1.0.0
*/
public final static DescriptorCollector createDescriptorCollector() {
return (DescriptorCollector) retrieve(COLLECTOR_PROPERTY);
@@ -57,8 +159,8 @@ public final class DescriptorSourceFactory {
case PARSER_PROPERTY:
clazzName = System.getProperty(type, PARSER_DEFAULT);
break;
- case LOADER_PROPERTY:
- clazzName = System.getProperty(type, LOADER_DEFAULT);
+ case DOWNLOADER_PROPERTY:
+ clazzName = System.getProperty(type, DOWNLOADER_DEFAULT);
break;
case READER_PROPERTY:
clazzName = System.getProperty(type, READER_DEFAULT);
diff --git a/src/org/torproject/descriptor/DirSourceEntry.java b/src/org/torproject/descriptor/DirSourceEntry.java
index da898d0..96d81ee 100644
--- a/src/org/torproject/descriptor/DirSourceEntry.java
+++ b/src/org/torproject/descriptor/DirSourceEntry.java
@@ -1,37 +1,96 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
+/**
+ * Contains details about an authority and its vote that contributed to a
+ * consensus.
+ *
+ * <p>A directory source entry is not a descriptor type of its own but is
+ * part of a network status consensus
+ * ({@link RelayNetworkStatusConsensus}).</p>
+ *
+ * @since 1.0.0
+ */
public interface DirSourceEntry {
- /* Return the raw dir-source bytes. */
+ /**
+ * Return the raw directory source entry bytes.
+ *
+ * @since 1.0.0
+ */
public byte[] getDirSourceEntryBytes();
- /* Return the directory nickname. */
+ /**
+ * Return the authority's nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the identity fingerprint. */
+ /**
+ * Return a SHA-1 digest of the authority's long-term authority
+ * identity key used for the version 3 directory protocol, encoded as
+ * 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getIdentity();
- /* Return the hostname. */
+ /**
+ * Return the authority's hostname.
+ *
+ * @since 1.2.0
+ */
public String getHostname();
- /* Return the IP address. */
+ /**
+ * Return the authority's primary IPv4 address in dotted-quad format.
+ *
+ * @since 1.0.0
+ */
public String getIp();
- /* Return the DirPort. */
+ /**
+ * Return the TCP port where this authority accepts directory-related
+ * HTTP connections.
+ *
+ * @since 1.0.0
+ */
public int getDirPort();
- /* Return the ORPort. */
+ /**
+ * Return the TCP port where this authority accepts TLS connections for
+ * the main OR protocol.
+ *
+ * @since 1.0.0
+ */
public int getOrPort();
- /* Return whether the dir-source was created using a legacy key. */
+ /**
+ * Return whether this directory source entry was created using a
+ * legacy key.
+ *
+ * @since 1.0.0
+ */
public boolean isLegacy();
- /* Return the contact line. */
+ /**
+ * Return the contact information for this authority, which may contain
+ * non-ASCII characters.
+ *
+ * @since 1.0.0
+ */
public String getContactLine();
- /* Return the vote digest. */
+ /**
+ * Return the SHA-1 vote digest, encoded as 40 lower-case hexadecimal
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getVoteDigest();
}
diff --git a/src/org/torproject/descriptor/DirectoryKeyCertificate.java b/src/org/torproject/descriptor/DirectoryKeyCertificate.java
index 61986cf..07211ef 100644
--- a/src/org/torproject/descriptor/DirectoryKeyCertificate.java
+++ b/src/org/torproject/descriptor/DirectoryKeyCertificate.java
@@ -1,45 +1,109 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
+/**
+ * Contains a key certificate in the version 3 directory protocol.
+ *
+ * <p>Every directory authority in the version 3 directory protocol uses
+ * two keys: a medium-term signing key, and a long-term authority identity
+ * key. (Authorities also have a relay identity key used in their role as
+ * a relay and by earlier versions of the directory protocol.) The
+ * identity key is used from time to time to sign new key certificates
+ * containing signing keys. The contained signing key is used to sign key
+ * certificates and status documents.</p>
+ *
+ * @since 1.0.0
+ */
public interface DirectoryKeyCertificate extends Descriptor {
- /* Return the directory key certificate version. */
+ /**
+ * Return the version of this descriptor, which must be 3 or higher.
+ *
+ * @since 1.0.0
+ */
public int getDirKeyCertificateVersion();
- /* Return the IP address, or null if the certificate does not contain an
- * address. */
+ /**
+ * Return the authority's primary IPv4 address in dotted-quad format,
+ * or null if the certificate does not contain an address.
+ *
+ * @since 1.0.0
+ */
public String getAddress();
- /* Return the directory port, or -1 if the certificate does not contain
- * one. */
+ /**
+ * Return the TCP port where this authority accepts directory-related
+ * HTTP connections, or -1 if the certificate does not contain a port.
+ *
+ * @since 1.0.0
+ */
public int getPort();
- /* Return the directory identity fingerprint. */
+ /**
+ * Return a SHA-1 digest of the authority's long-term authority
+ * identity key used for the version 3 directory protocol, encoded as
+ * 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return the directory identity key. */
+ /**
+ * Return the authority's identity key in PEM format.
+ *
+ * @since 1.0.0
+ */
public String getDirIdentityKey();
- /* Return the directory key certificate publication timestamp. */
+ /**
+ * Return the time in milliseconds since the epoch when the authority's
+ * signing key and this key certificate were generated.
+ *
+ * @since 1.0.0
+ */
public long getDirKeyPublishedMillis();
- /* Return the directory key certificate expiration timestamp. */
+ /**
+ * Return the time in milliseconds since the epoch after which the
+ * authority's signing key is no longer valid.
+ *
+ * @since 1.0.0
+ */
public long getDirKeyExpiresMillis();
- /* Return the directory signing key digest. */
+ /**
+ * Return the authority's signing key in PEM format.
+ *
+ * @since 1.0.0
+ */
public String getDirSigningKey();
- /* Return the signature of the directory identity key made using the
- * directory signing key, or null if the certificate does not contain
- * this signature. */
+ /**
+ * Return the signature of the authority's identity key made using the
+ * authority's signing key, or null if the certificate does not contain
+ * such a signature.
+ *
+ * @since 1.0.0
+ */
public String getDirKeyCrosscert();
- /* Return the certificate signature made using the directory identity
- * key. */
+ /**
+ * Return the certificate signature from the initial item
+ * "dir-key-certificate-version" until the final item
+ * "dir-key-certification", signed with the authority identity key.
+ *
+ * @since 1.0.0
+ */
public String getDirKeyCertification();
- /* Return the calculated certificate digest. */
+ /**
+ * Return the SHA-1 certificate digest, encoded as 40 lower-case
+ * hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getCertificateDigest();
}
diff --git a/src/org/torproject/descriptor/DirectorySignature.java b/src/org/torproject/descriptor/DirectorySignature.java
index ff706ea..8877a4e 100644
--- a/src/org/torproject/descriptor/DirectorySignature.java
+++ b/src/org/torproject/descriptor/DirectorySignature.java
@@ -1,19 +1,52 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
+/**
+ * Contains the signature of a network status consensus or vote.
+ *
+ * <p>A directory signature is not a descriptor type of its own but is
+ * part of a network status consensus
+ * ({@link RelayNetworkStatusConsensus}) or vote
+ * ({@link RelayNetworkStatusVote}).</p>
+ *
+ * @since 1.0.0
+ */
public interface DirectorySignature {
- /* Return the digest algorithm, which is "sha1" by default. */
+ /**
+ * Return the digest algorithm, which is "sha1" by default and which
+ * can be "sha256" or another digest algorithm.
+ *
+ * @since 1.0.0
+ */
public String getAlgorithm();
- /* Return the directory identity fingerprint. */
+ /**
+ * Return the SHA-1 digest of the authority's long-term identity key in
+ * the version 3 directory protocol, encoded as 40 upper-case
+ * hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getIdentity();
- /* Return the directory signing key digest. */
+ /**
+ * Return the SHA-1 digest of the authority's medium-term signing key
+ * in the version 3 directory protocol, encoded as 40 upper-case
+ * hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getSigningKeyDigest();
- /* Return the directory signature made using the signing key. */
+ /**
+ * Return the directory signature string made with the authority's
+ * identity key in the version 3 directory protocol.
+ *
+ * @since 1.0.0
+ */
public String getSignature();
}
diff --git a/src/org/torproject/descriptor/ExitList.java b/src/org/torproject/descriptor/ExitList.java
index c813a6b..2a5cb2e 100644
--- a/src/org/torproject/descriptor/ExitList.java
+++ b/src/org/torproject/descriptor/ExitList.java
@@ -1,42 +1,92 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.Map;
import java.util.Set;
-/* Exit list containing all known exit scan results at a given time. */
+/**
+ * Contains an exit list containing the IP addresses of relays that the
+ * exit list service TorDNSEL found when exiting through them.
+ *
+ * @since 1.0.0
+ */
public interface ExitList extends Descriptor {
+ /**
+ * End-of-line character expected in exit lists.
+ *
+ * @since 1.0.0
+ */
public final static String EOL = "\n";
- /* Exit list entry containing results from a single exit scan. */
+ /**
+ * Exit list entry containing results from a single exit scan.
+ *
+ * @since 1.1.0
+ */
public interface Entry {
- /* Return the scanned relay's fingerprint. */
+ /**
+ * Return the scanned relay's fingerprint, which is a SHA-1 digest of
+ * the relays's public identity key, encoded as 40 upper-case
+ * hexadecimal characters.
+ *
+ * @since 1.1.0
+ */
public String getFingerprint();
- /* Return the publication time of the scanned relay's last known
- * descriptor. */
+ /**
+ * Return the time in milliseconds since the epoch when the scanned
+ * relay's last known descriptor was published.
+ *
+ * @since 1.1.0
+ */
public long getPublishedMillis();
- /* Return the publication time of the network status that this scan
- * was based on. */
+ /**
+ * Return the time in milliseconds since the epoch when the network
+ * status that this scan was based on was published.
+ *
+ * @since 1.1.0
+ */
public long getLastStatusMillis();
- /* Return the IP addresses that were determined in the scan. */
+ /**
+ * Return the IP addresses that were determined in the scan with map
+ * keys being IPv4 addresses in dotted-quad format and map values
+ * being scan times in milliseconds since the epoch.
+ *
+ * @since 1.1.0
+ */
public Map<String, Long> getExitAddresses();
}
- /* Return the download time of the exit list. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was downloaded.
+ *
+ * @since 1.0.0
+ */
public long getDownloadedMillis();
- /* Return the unordered set of exit scan results. */
- /* Use getEntries instead. */
+ /**
+ * Return the unordered set of exit scan results.
+ *
+ * @since 1.0.0
+ * @deprecated The {@link ExitListEntry} type has been deprecated and
+ * superseded by {@link ExitList.Entry} which is returned by
+ * {@link #getEntries()}.
+ */
@Deprecated
public Set<ExitListEntry> getExitListEntries();
- /* Return the unordered set of exit scan results. */
+ /**
+ * Return the unordered set of exit scan results.
+ *
+ * @since 1.1.0
+ */
public Set<ExitList.Entry> getEntries();
}
diff --git a/src/org/torproject/descriptor/ExitListEntry.java b/src/org/torproject/descriptor/ExitListEntry.java
index 7b69483..2a3d79f 100644
--- a/src/org/torproject/descriptor/ExitListEntry.java
+++ b/src/org/torproject/descriptor/ExitListEntry.java
@@ -1,27 +1,55 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Exit list entry containing results from a single exit scan. */
-/* Use org.torproject.descriptor.ExitList.Entry instead. */
+/**
+ * Exit list entry containing results from a single exit scan.
+ *
+ * @since 1.0.0
+ * @deprecated Superseded by {@link ExitList.Entry}.
+ */
@Deprecated
public interface ExitListEntry extends ExitList.Entry {
- /* Return the scanned relay's fingerprint. */
+ /**
+ * Return the scanned relay's fingerprint, which is a SHA-1 digest of
+ * the relays's public identity key, encoded as 40 upper-case
+ * hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return the publication time of the scanned relay's last known
- * descriptor. */
+ /**
+ * Return the time in milliseconds since the epoch when the scanned
+ * relay's last known descriptor was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the publication time of the network status that this scan was
- * based on. */
+ /**
+ * Return the time in milliseconds since the epoch when the network
+ * status that this scan was based on was published.
+ *
+ * @since 1.0.0
+ */
public long getLastStatusMillis();
- /* Return the IP address that was determined in the scan. */
+ /**
+ * Return the IPv4 address in dotted-quad format that was determined in
+ * the scan.
+ *
+ * @since 1.0.0
+ */
public String getExitAddress();
- /* Return the scan time. */
+ /**
+ * Return the scan time in milliseconds since the epoch.
+ *
+ * @since 1.0.0
+ */
public long getScanMillis();
}
diff --git a/src/org/torproject/descriptor/ExtraInfoDescriptor.java b/src/org/torproject/descriptor/ExtraInfoDescriptor.java
index ed0141d..49efbf3 100644
--- a/src/org/torproject/descriptor/ExtraInfoDescriptor.java
+++ b/src/org/torproject/descriptor/ExtraInfoDescriptor.java
@@ -1,322 +1,646 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.Map;
import java.util.SortedMap;
-/* Contains a relay or bridge extra-info descriptor. */
+/**
+ * Contains a relay or sanitized bridge extra-info descriptor.
+ *
+ * <p>Relays publish extra-info descriptors as an addendum to server
+ * descriptors ({@link ServerDescriptor}) to report extraneous information
+ * to the directory authorities that clients do not need to download in
+ * order to function. This information primarily consists of statistics
+ * gathered by the relay about its usage and can take up a lot of
+ * descriptor space. The separation of server descriptors and extra-info
+ * descriptors has become less relevant with the introduction of
+ * microdescriptors ({@link Microdescriptor}) that are derived from server
+ * descriptors by the directory authority and which clients download
+ * instead of server descriptors, but it persists.</p>
+ *
+ * <p>Bridges publish extra-info descriptors to the bridge authority for
+ * the same reason, to include statistics about their usage without
+ * increasing the directory protocol overhead for bridge clients. In this
+ * case, the separation of server descriptors and extra-info descriptors
+ * is slightly more relevant, because there are no microdescriptors for
+ * bridges, so that bridge clients still download server descriptors of
+ * bridges they're using. Another reason is that bridges need to include
+ * information like details of all the transports they support in their
+ * descriptors, and bridge clients using one such transport are not
+ * supposed to learn the details of the other transports.</p>
+ *
+ * <p>It's worth noting that all contents of extra-info descriptors are
+ * written and signed by relays and bridges without a third party
+ * verifying their correctness. The (bridge) directory authorities may
+ * decide to exclude dishonest servers from the network statuses they
+ * produce, but that wouldn't be reflected in extra-info descriptors.</p>
+ *
+ * @since 1.0.0
+ */
public interface ExtraInfoDescriptor extends Descriptor {
- /* Return the descriptor digest that is used to reference this
- * extra-info descriptor in a server descriptor. */
+ /**
+ * Return the SHA-1 descriptor digest, encoded as 40 lower-case (relay
+ * descriptors) or upper-case (bridge descriptors) hexadecimal
+ * characters, that is used to reference this descriptor from a server
+ * descriptor.
+ *
+ * @since 1.0.0
+ */
public String getExtraInfoDigest();
- /* Return the base64-encoded SHA-256 descriptor digest that may be used
- * to reference this extra-info descriptor in a server descriptor. */
+ /**
+ * Return the SHA-256 descriptor digest, encoded as 43 base64
+ * characters without padding characters, that may be used to reference
+ * this descriptor from a server descriptor.
+ *
+ * @since 1.1.0
+ */
public String getExtraInfoDigestSha256();
- /* Return the relay's nickname. */
+ /**
+ * Return the server's nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the relay's fingerprint. */
+ /**
+ * Return a SHA-1 digest of the server's public identity key, encoded
+ * as 40 upper-case hexadecimal characters, that is typically used to
+ * uniquely identify the server.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return the publication time of this descriptor. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * and the corresponding server descriptor were generated.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the read history contained in this descriptor, or null if no
- * read history is contained. */
+ /**
+ * Return the server's history of read bytes, or null if the descriptor
+ * does not contain a bandwidth history; older Tor versions included
+ * bandwidth histories in their server descriptors
+ * ({@link ServerDescriptor#getReadHistory()}).
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getReadHistory();
- /* Return the write history contained in this descriptor, or null if no
- * read history is contained. */
+ /**
+ * Return the server's history of written bytes, or null if the
+ * descriptor does not contain a bandwidth history; older Tor versions
+ * included bandwidth histories in their server descriptors
+ * ({@link ServerDescriptor#getWriteHistory()}).
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getWriteHistory();
- /* Return the SHA1 digest of the GeoIP database used by this relay, or
- * null if no GeoIP database digest is included. */
+ /**
+ * Return a SHA-1 digest of the GeoIP database file used by this server
+ * to resolve client IP addresses to country codes, encoded as 40
+ * upper-case hexadecimal characters, or null if no GeoIP database
+ * digest is included.
+ *
+ * @since 1.0.0
+ */
public String getGeoipDbDigest();
- /* Return the SHA1 digest of the GeoIPv6 database used by this relay, or
- * null if no GeoIPv6 database digest is included. */
+ /**
+ * Return a SHA-1 digest of the GeoIPv6 database file used by this
+ * server to resolve client IP addresses to country codes, encoded as 40
+ * upper-case hexadecimal characters, or null if no GeoIPv6 database
+ * digest is included.
+ *
+ * @since 1.0.0
+ */
public String getGeoip6DbDigest();
- /* Return the end of the included directory request statistics interval,
- * or -1 if no directory request statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * directory request statistics interval ended, or -1 if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getDirreqStatsEndMillis();
- /* Return the interval length of the included directory request
- * statistics in seconds, or -1 if no directory request statistics are
- * included. */
+ /**
+ * Return the interval length of the included directory request
+ * statistics in seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getDirreqStatsIntervalLength();
- /* Return statistics on unique IP addresses requesting v2 network
+ /**
+ * Return statistics on unique IP addresses requesting v2 network
* statuses with map keys being country codes and map values being
* numbers of unique IP addresses rounded up to the nearest multiple of
- * 8, or null if no such statistics are included. */
+ * 8, or null if no such statistics are included (which is the case with
+ * recent Tor versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV2Ips();
- /* Return statistics on unique IP addresses requesting v3 network status
- * consensuses with map keys being country codes and map values being
- * numbers of unique IP addresses rounded up to the nearest multiple of
- * 8, or null if no such statistics are included. */
+ /**
+ * Return statistics on unique IP addresses requesting v3 network
+ * status consensuses of any flavor with map keys being country codes
+ * and map values being numbers of unique IP addresses rounded up to the
+ * nearest multiple of 8, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV3Ips();
- /* Return statistics on directory requests for v2 network statuses with
+ /**
+ * Return statistics on directory requests for v2 network statuses with
* map keys being country codes and map values being request numbers
* rounded up to the nearest multiple of 8, or null if no such
- * statistics are included. */
+ * statistics are included (which is the case with recent Tor
+ * versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV2Reqs();
- /* Return statistics on directory requests for v3 network status
- * consensuses with map keys being country codes and map values being
- * request numbers rounded up to the nearest multiple of 8, or null if
- * no such statistics are included. */
+ /**
+ * Return statistics on directory requests for v3 network status
+ * consensuses of any flavor with map keys being country codes and map
+ * values being request numbers rounded up to the nearest multiple of 8,
+ * or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV3Reqs();
- /* Return the share of requests for v2 network statuses that the
- * directory expects to receive from clients, or -1.0 if no such
- * statistics are included. */
+ /**
+ * Return the share of requests for v2 network statuses that the server
+ * expects to receive from clients, or -1.0 if this share is not
+ * included (which is the case with recent Tor versions).
+ *
+ * @since 1.0.0
+ */
public double getDirreqV2Share();
- /* Return the share of requests for v3 network status consensuses that
- * the directory expects to receive from clients, or -1.0 if no such
- * statistics are included. */
+ /**
+ * Return the share of requests for v3 network status consensuses of
+ * any flavor that the server expects to receive from clients, or -1.0
+ * if this share is not included (which is the case with recent Tor
+ * versions).
+ *
+ * @since 1.0.0
+ */
public double getDirreqV3Share();
- /* Return statistics on directory request responses for v2 network
+ /**
+ * Return statistics on responses to directory requests for v2 network
* statuses with map keys being response strings and map values being
* response numbers rounded up to the nearest multiple of 4, or null if
- * no such statistics are included. */
+ * no such statistics are included (which is the case with recent Tor
+ * versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV2Resp();
- /* Return statistics on directory request responses for v3 network
- * status consensuses with map keys being response strings and map
- * values being response numbers rounded up to the nearest multiple of
- * 4, or null if no such statistics are included. */
+ /**
+ * Return statistics on responses to directory requests for v3 network
+ * status consensuses of any flavor with map keys being response strings
+ * and map values being response numbers rounded up to the nearest
+ * multiple of 4, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV3Resp();
- /* Return statistics on direct directory requests asking for v2 network
- * statuses with map keys being statistic keys and map values being
- * statistic values, or null if no such statistics are included. */
+ /**
+ * Return statistics on directory requests for v2 network statuses to
+ * the server's directory port with map keys being statistic keys and
+ * map values being statistic values like counts or quantiles, or null
+ * if no such statistics are included (which is the case with recent Tor
+ * versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV2DirectDl();
- /* Return statistics on direct directory requests asking for v3 network
- * status consensuses with map keys being statistic keys and map
- * values being statistic values, or null if no such statistics are
- * included. */
+ /**
+ * Return statistics on directory requests for v3 network status
+ * consensuses of any flavor to the server's directory port with map
+ * keys being statistic keys and map values being statistic values like
+ * counts or quantiles, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV3DirectDl();
- /* Return statistics on tunneled directory requests asking for v2
- * network statuses with map keys being statistic keys and map values
- * being statistic values, or null if no such statistics are
- * included. */
+ /**
+ * Return statistics on directory requests for v2 network statuses
+ * tunneled through a circuit with map keys being statistic keys and map
+ * values being statistic values, or null if no such statistics are
+ * included (which is the case with recent Tor versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV2TunneledDl();
- /* Return statistics on tunneled directory requests asking for v3
- * network status consensuses with map keys being statistic keys and map
- * values being statistic values, or null if no such statistics are
- * included. */
+ /**
+ * Return statistics on directory requests for v3 network status
+ * consensuses of any flavor tunneled through a circuit with map keys
+ * being statistic keys and map values being statistic values, or null
+ * if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getDirreqV3TunneledDl();
- /* Return the directory request read history contained in this
- * descriptor, or null if no directory request read history is
- * contained. */
+ /**
+ * Return the directory request read history contained in this
+ * descriptor, or null if no such history is contained.
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getDirreqReadHistory();
- /* Return the directory request write history contained in this
- * descriptor, or null if no directory request write history is
- * contained. */
+ /**
+ * Return the directory request write history contained in this
+ * descriptor, or null if no such history is contained.
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getDirreqWriteHistory();
- /* Return the end of the included entry statistics interval, or -1 if no
- * entry statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * entry statistics interval ended, or -1 if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public long getEntryStatsEndMillis();
- /* Return the interval length of the included entry statistics in
- * seconds, or -1 if no entry statistics are included. */
+ /**
+ * Return the interval length of the included entry statistics in
+ * seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getEntryStatsIntervalLength();
- /* Return statistics on client IP addresses with map keys being country
+ /**
+ * Return statistics on client IP addresses with map keys being country
* codes and map values being the number of unique IP addresses that
* have connected from that country rounded up to the nearest multiple
- * of 8, or null if no entry statistics are included. */
+ * of 8, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getEntryIps();
- /* Return the end of the included cell statistics interval, or -1 if no
- * cell statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * cell statistics interval ended, or -1 if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public long getCellStatsEndMillis();
- /* Return the interval length of the included cell statistics in
- * seconds, or -1 if no cell statistics are included. */
+ /**
+ * Return the interval length of the included cell statistics in
+ * seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getCellStatsIntervalLength();
- /* Return the mean number of processed cells per circuit by circuit
- * deciles. */
+ /**
+ * Return the mean number of processed cells per circuit by circuit
+ * decile starting with the loudest decile at index 0 and the quietest
+ * decile at index 8, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getCellProcessedCells();
- /* Return the mean number of cells contained in circuit queues by
- * circuit deciles. */
+ /**
+ * Return the mean number of cells contained in circuit queues by
+ * circuit decile starting with the loudest decile at index 0 and the
+ * quietest decile at index 8, or null if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public List<Double> getCellQueuedCells();
- /* Return the mean times in milliseconds that cells spend in circuit
- * queues by circuit deciles. */
+ /**
+ * Return the mean times in milliseconds that cells spend in circuit
+ * queues by circuit decile starting with the loudest decile at index 0
+ * and the quietest decile at index 8, or null if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getCellTimeInQueue();
- /* Return the mean number of circuits included in any of the cell
- * statistics deciles, or -1 if no cell statistics are included. */
+ /**
+ * Return the mean number of circuits included in any of the cell
+ * statistics deciles, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public int getCellCircuitsPerDecile();
- /* Return the end of the included statistics interval on bi-directional
- * connection usage, or -1 if no such statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * statistics on bi-directional connection usage ended, or -1 if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getConnBiDirectStatsEndMillis();
- /* Return the interval length of the included statistics on
+ /**
+ * Return the interval length of the included statistics on
* bi-directional connection usage in seconds, or -1 if no such
- * statistics are included. */
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getConnBiDirectStatsIntervalLength();
- /* Return the number of connections on which this relay read and wrote
- * less than 2 KiB/s in a 10-second interval, or -1 if no statistics on
- * bi-directional connection usage are included. */
+ /**
+ * Return the number of connections on which this server read and wrote
+ * less than 2 KiB/s in a 10-second interval, or -1 if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public int getConnBiDirectBelow();
- /* Return the number of connections on which this relay read and wrote
+ /**
+ * Return the number of connections on which this server read and wrote
* at least 2 KiB/s in a 10-second interval and at least 10 times more
- * in read direction than in write direction, or -1 if no statistics on
- * bi-directional connection usage are included. */
+ * in read direction than in write direction, or -1 if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public int getConnBiDirectRead();
- /* Return the number of connections on which this relay read and wrote
+ /**
+ * Return the number of connections on which this server read and wrote
* at least 2 KiB/s in a 10-second interval and at least 10 times more
- * in write direction than in read direction, or -1 if no statistics on
- * bi-directional connection usage are included. */
+ * in write direction than in read direction, or -1 if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public int getConnBiDirectWrite();
- /* Return the number of connections on which this relay read and wrote
+ /**
+ * Return the number of connections on which this server read and wrote
* at least 2 KiB/s in a 10-second interval but not 10 times more in
- * either direction, or -1 if no statistics on bi-directional connection
- * usage are included. */
+ * either direction, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public int getConnBiDirectBoth();
- /* Return the end of the included exit statistics interval, or -1 if no
- * exit statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * exit statistics interval ended, or -1 if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public long getExitStatsEndMillis();
- /* Return the interval length of the included exit statistics in
- * seconds, or -1 if no exit statistics are included. */
+ /**
+ * Return the interval length of the included exit statistics in
+ * seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getExitStatsIntervalLength();
- /* Return statistics on KiB written by port with map keys being ports
- * (or "other") and map values being KiB rounded up to the next full
- * KiB, or null if no exit statistics are included. */
+ /**
+ * Return statistics on KiB written to streams exiting the Tor network
+ * by target TCP port with map keys being string representations of
+ * ports (or {@code "other"}) and map values being KiB rounded up to the
+ * next full KiB, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Long> getExitKibibytesWritten();
- /* Return statistics on KiB read by port with map keys being ports (or
- * "other") and map values being KiB rounded up to the next full KiB, or
- * null if no exit statistics are included. */
+ /**
+ * Return statistics on KiB read from streams exiting the Tor network
+ * by target TCP port with map keys being string representations of
+ * ports (or {@code "other"}) and map values being KiB rounded up to the
+ * next full KiB, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Long> getExitKibibytesRead();
- /* Return statistics on opened exit streams with map keys being ports
- * (or "other") and map values being the number of opened streams,
- * rounded up to the nearest multiple of 4, or null if no exit
- * statistics are included. */
+ /**
+ * Return statistics on opened streams exiting the Tor network by
+ * target TCP port with map keys being string representations of ports
+ * (or {@code "other"}) and map values being the number of opened
+ * streams, rounded up to the nearest multiple of 4, or null if no such
+ * statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Long> getExitStreamsOpened();
- /* Return the start of the included geoip statistics, or -1 if no geoip
- * statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * "geoip" statistics interval started, or -1 if no such statistics are
+ * included (which is the case except for very old Tor versions).
+ *
+ * @since 1.0.0
+ */
public long getGeoipStartTimeMillis();
- /* Return statistics on client IP addresses with map keys being country
- * codes and map values being the number of unique IP addresses that
- * have connected from that country rounded up to the nearest multiple
- * of 8, or null if no geoip statistics are included. */
+ /**
+ * Return statistics on the origin of client IP addresses with map keys
+ * being country codes and map values being the number of unique IP
+ * addresses that have connected from that country between the start of
+ * the statistics interval and the descriptor publication time rounded
+ * up to the nearest multiple of 8, or null if no such statistics are
+ * included (which is the case except for very old Tor versions).
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getGeoipClientOrigins();
- /* Return the end of the included bridge statistics, or -1 if no bridge
- * statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * bridge statistics interval ended, or -1 if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public long getBridgeStatsEndMillis();
- /* Return the interval length of the included bridge statistics in
- * seconds, or -1 if no bridge statistics are included. */
+ /**
+ * Return the interval length of the included bridge statistics in
+ * seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public long getBridgeStatsIntervalLength();
- /* Return statistics on client IP addresses with map keys being country
- * codes and map values being the number of unique IP addresses that
- * have connected from that country rounded up to the nearest multiple
- * of 8, or null if no bridge statistics are included. */
+ /**
+ * Return statistics on bridge client IP addresses by country with map
+ * keys being country codes and map values being the number of unique IP
+ * addresses that have connected from that country rounded up to the
+ * nearest multiple of 8, or null if no such statistics are included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getBridgeIps();
- /* Return statistics on client IP addresses with map keys being protocol
- * family, e.g., "v4" or "v6", and map values being the number of unique
- * IP addresses rounded up to the nearest multiple of 8, or null if no
- * bridge IP version statistics are included. */
+ /**
+ * Return statistics on bridge client IP addresses by IP version with
+ * map keys being protocol families, e.g., {@code "v4"} or {@code "v6"},
+ * and map values being the number of unique IP addresses rounded up to
+ * the nearest multiple of 8, or null if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getBridgeIpVersions();
- /* Return statistics on client IP addresses with map keys being
- * pluggable transport names, e.g., "obfs2" or "obfs3" for known
- * transports, "<OR>" for no transport, or "<??>" for an unknown
- * transport, and map values being the number of unique IP addresses
- * rounded up to the nearest multiple of 8, or null if no bridge IP
- * transport statistics are included. */
+ /**
+ * Return statistics on bridge client IP addresses by transport with
+ * map keys being pluggable transport names, e.g., {@code "obfs2"} or
+ * {@code "obfs3"} for known transports, {@code "<OR>"} for the default
+ * onion routing protocol, or {@code "<??>"} for an unknown transport,
+ * and map values being the number of unique IP addresses rounded up to
+ * the nearest multiple of 8, or null if no such statistics are
+ * included.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getBridgeIpTransports();
- /* Return the (possibly empty) list of transports supported by this
- * bridge. */
+ /**
+ * Return the (possibly empty) list of pluggable transports supported
+ * by this server.
+ *
+ * @since 1.0.0
+ */
public List<String> getTransports();
- /* Return the end of the included hidden-service statistics, or -1 if no
- * hidden-service statistics are included. */
+ /**
+ * Return the time in milliseconds since the epoch when the included
+ * hidden-service statistics interval ended, or -1 if no such statistics
+ * are included.
+ *
+ * @since 1.1.0
+ */
public long getHidservStatsEndMillis();
- /* Return the interval length of the included hidden-service statistics
- * in seconds, or -1 if no hidden-service statistics are included. */
+ /**
+ * Return the interval length of the included hidden-service statistics
+ * in seconds, or -1 if no such statistics are included.
+ *
+ * @since 1.1.0
+ */
public long getHidservStatsIntervalLength();
- /* Return the approximate number of RELAY cells seen in either direction
- * on a circuit after receiving and successfully processing a
- * RENDEZVOUS1 cell, or null if no hidden-service statistics are
- * included. */
+ /**
+ * Return the approximate number of RELAY cells seen in either
+ * direction on a circuit after receiving and successfully processing a
+ * RENDEZVOUS1 cell, or null if no such statistics are included.
+ *
+ * @since 1.1.0
+ */
public Double getHidservRendRelayedCells();
- /* Return the obfuscation parameters applied to the original measurement
- * value of RELAY cells seen in either direction on a circuit after
- * receiving and successfully processing a RENDEZVOUS1 cell, or null if
- * no hidden-service statistics are included.. */
+ /**
+ * Return the obfuscation parameters applied to the original
+ * measurement value of RELAY cells seen in either direction on a
+ * circuit after receiving and successfully processing a RENDEZVOUS1
+ * cell, or null if no such statistics are included.
+ *
+ * @since 1.1.0
+ */
public Map<String, Double> getHidservRendRelayedCellsParameters();
- /* Return the approximate number of unique hidden-service identities
+ /**
+ * Return the approximate number of unique hidden-service identities
* seen in descriptors published to and accepted by this hidden-service
- * directory, or null if no hidden-service statistics are included. */
+ * directory, or null if no such statistics are included.
+ *
+ * @since 1.1.0
+ */
public Double getHidservDirOnionsSeen();
- /* Return the obfuscation parameters applied to the original measurement
- * value of unique hidden-service identities seen in descriptors
- * published to and accepted by this hidden-service directory, or null
- * if no hidden-service statistics are included. */
+ /**
+ * Return the obfuscation parameters applied to the original
+ * measurement value of unique hidden-service identities seen in
+ * descriptors published to and accepted by this hidden-service
+ * directory, or null if no such statistics are included.
+ *
+ * @since 1.1.0
+ */
public Map<String, Double> getHidservDirOnionsSeenParameters();
- /* Return the signature of the PKCS1-padded extra-info descriptor
- * digest, or null if the descriptor doesn't contain a signature (which
- * is the case in sanitized bridge descriptors). */
+ /**
+ * Return the RSA-1024 signature of the PKCS1-padded descriptor digest,
+ * taken from the beginning of the router line through the newline after
+ * the router-signature line, or null if the descriptor doesn't contain
+ * a signature (which is the case in sanitized bridge descriptors).
+ *
+ * @since 1.1.0
+ */
public String getRouterSignature();
- /* Return the base64-encoded Ed25519 certificate, or null if the
- * descriptor doesn't contain one. */
+ /**
+ * Return the Ed25519 certificate in PEM format, or null if the
+ * descriptor doesn't contain one.
+ *
+ * @since 1.1.0
+ */
public String getIdentityEd25519();
- /* Return the base64-encoded Ed25519 master key, which may either be
- * parsed from the optional "master-key-ed25519" line or derived from
- * the (likewise optional) Ed25519 certificate following the
- * "identity-ed25519" line, or null if the descriptor contains neither
- * Ed25519 master key nor Ed25519 certificate. */
+ /**
+ * Return the Ed25519 master key, encoded as 43 base64 characters
+ * without padding characters, which was either parsed from the optional
+ * {@code "master-key-ed25519"} line or derived from the (likewise
+ * optional) Ed25519 certificate following the
+ * {@code "identity-ed25519"} line, or null if the descriptor contains
+ * neither Ed25519 master key nor Ed25519 certificate.
+ *
+ * @since 1.1.0
+ */
public String getMasterKeyEd25519();
- /* Return the base64-encoded Ed25519 signature of a SHA-256 digest of
- * the entire descriptor, from the first character up to and including
- * the first space after the "router-sig-ed25519" string, prefixed with
- * the string "Tor router descriptor signature v1". */
+ /**
+ * Return the Ed25519 signature of the SHA-256 digest of the entire
+ * descriptor, encoded as 86 base64 characters without padding
+ * characters, from the first character up to and including the first
+ * space after the {@code "router-sig-ed25519"} string, prefixed with
+ * the string {@code "Tor router descriptor signature v1"}.
+ *
+ * @since 1.1.0
+ */
public String getRouterSignatureEd25519();
}
diff --git a/src/org/torproject/descriptor/ImplementationNotAccessibleException.java b/src/org/torproject/descriptor/ImplementationNotAccessibleException.java
index fda3e24..c54e48f 100644
--- a/src/org/torproject/descriptor/ImplementationNotAccessibleException.java
+++ b/src/org/torproject/descriptor/ImplementationNotAccessibleException.java
@@ -1,7 +1,15 @@
-/* Copyright 2014--2015 The Tor Project
+/* Copyright 2014--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
+/**
+ * Thrown if a descriptor source implementation class cannot be found,
+ * instantiated, or accessed.
+ *
+ * @see DescriptorSourceFactory
+ * @since 1.0.0
+ */
@SuppressWarnings("serial")
public class ImplementationNotAccessibleException
extends RuntimeException {
diff --git a/src/org/torproject/descriptor/Microdescriptor.java b/src/org/torproject/descriptor/Microdescriptor.java
index 3cebeb6..f19b7df 100644
--- a/src/org/torproject/descriptor/Microdescriptor.java
+++ b/src/org/torproject/descriptor/Microdescriptor.java
@@ -1,57 +1,135 @@
-/* Copyright 2014--2015 The Tor Project
+/* Copyright 2014--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-/* Contains a relay microdescriptor. */
+/**
+ * Contains a relay microdescriptor.
+ *
+ * <p>A microdescriptor is a stripped-down version of a relay server
+ * descriptor ({@link RelayServerDescriptor}) generated by the directory
+ * authorities by extracting and/or transforming relay server descriptor
+ * contents following strict rules without adding the authority's opinion
+ * about the relay. Microdescriptors are referenced from microdescriptor
+ * consensuses ({@link RelayNetworkStatusConsensus}) and downloaded by
+ * clients to make path-selection decisions and to build circuits.
+ * Microdescriptors contain only the most relevant parts that clients care
+ * about. Microdescriptors are expected to be relatively static and only
+ * change about once per week.</p>
+ *
+ * @since 1.0.0
+ */
public interface Microdescriptor extends Descriptor {
- /* Return the descriptor digest that is used to reference this
- * microdescriptor in a network status. */
+ /**
+ * Return the SHA-256 descriptor digest, encoded as 43 base64
+ * characters without padding characters, that is used to reference this
+ * descriptor from a vote or microdescriptor consensus.
+ *
+ * @since 1.0.0
+ */
public String getMicrodescriptorDigest();
- /* Return the onion key in PEM format. */
+ /**
+ * Return the RSA-1024 public key in PEM format used to encrypt CREATE
+ * cells for this server, or null if the descriptor doesn't contain an
+ * onion key.
+ *
+ * @since 1.0.0
+ */
public String getOnionKey();
- /* Return the ntor onion key base64 string with padding omitted, or null
- * if the microdescriptor didn't contain an ntor onion key line. */
+ /**
+ * Return the curve25519 public key, encoded as 43 base64 characters
+ * without padding characters, that is used for the ntor circuit
+ * extended handshake, or null if the descriptor didn't contain an
+ * ntor-onion-key line.
+ *
+ * @since 1.0.0
+ */
public String getNtorOnionKey();
- /* Return the relay's additional OR addresses and ports contained in
- * or-address lines, or an empty list if the microdescriptor doesn't
- * contain such lines. */
+ /**
+ * Return IP addresses and TCP ports where this server accepts TLS
+ * connections for the main OR protocol, or an empty list if the server
+ * does not support additional addresses or ports; entries are given in
+ * the order as they are listed in the descriptor; IPv4 addresses are
+ * given in dotted-quad format, IPv6 addresses use the colon-separated
+ * hexadecimal format surrounded by square brackets, and TCP ports are
+ * separated from the IP address using a colon.
+ *
+ * @since 1.0.0
+ */
public List<String> getOrAddresses();
- /* Return nicknames, ($-prefixed) fingerprints, $fingerprint=nickname,
- * or $fingerprint~nickname tuples contained in the family line of this
- * relay, or null if the descriptor does not contain a family line. */
+ /**
+ * Return nicknames, $-prefixed identity fingerprints, or tuples of the
+ * format {@code $fingerprint=nickname} or {@code $fingerprint~nickname}
+ * of servers contained in this server's family, or null if the
+ * descriptor does not contain a family line.
+ *
+ * @since 1.0.0
+ */
public List<String> getFamilyEntries();
- /* Return the default policy of the port summary or null if the
- * microdescriptor didn't contain a port summary line. */
+ /**
+ * Return the default policy, {@code "accept"} or {@code "reject"}, of
+ * the IPv4 port summary, or null if the descriptor didn't contain an
+ * IPv4 exit-policy summary line which is equivalent to rejecting all
+ * streams to IPv4 targets.
+ *
+ * @since 1.0.0
+ */
public String getDefaultPolicy();
- /* Return the port list of the port summary or null if the
- * microdescriptor didn't contain a port summary line. */
+ /**
+ * Return the port list of the IPv4 exit-policy summary, or null if the
+ * descriptor didn't contain an IPv4 exit-policy summary line which is
+ * equivalent to rejecting all streams to IPv4 targets.
+ *
+ * @since 1.0.0
+ */
public String getPortList();
- /* Return the default policy of the IPv6 port summary or null if the
- * microdescriptor didn't contain an IPv6 port summary line. */
+ /**
+ * Return the default policy, {@code "accept"} or {@code "reject"}, of
+ * the IPv6 port summary, or null if the descriptor didn't contain an
+ * IPv6 exit-policy summary line which is equivalent to rejecting all
+ * streams to IPv6 targets.
+ *
+ * @since 1.0.0
+ */
public String getIpv6DefaultPolicy();
- /* Return the port list of the IPv6 port summary or null if the
- * microdescriptor didn't contain an IPv6 port summary line. */
+ /**
+ * Return the port list of the IPv6 exit-policy summary, or null if the
+ * descriptor didn't contain an IPv6 exit-policy summary line which is
+ * equivalent to rejecting all streams to IPv6 targets.
+ *
+ * @since 1.0.0
+ */
public String getIpv6PortList();
- /* Return the optional, base64-encoded RSA-1024 identity that is only
+ /**
+ * Return a SHA-1 digest of the server's RSA-1024 identity key, encoded
+ * as 27 base64 characters without padding characters, that is only
* included to prevent collisions between microdescriptors, or null if
- * no such identity is included. */
+ * no such digest is included.
+ *
+ * @since 1.1.0
+ */
public String getRsa1024Identity();
- /* Return the optional, base64-encoded Ed25519 identity that is only
- * included to prevent collisions between microdescriptors, or null if
- * no such identity is included. */
+ /**
+ * Return a SHA-256 digest of the server's Ed25519 identity key,
+ * encoded as 43 base64 characters without padding characters, that is
+ * only included to prevent collisions between microdescriptors, or null
+ * if no such digest is included.
+ *
+ * @since 1.1.0
+ */
public String getEd25519Identity();
}
diff --git a/src/org/torproject/descriptor/NetworkStatusEntry.java b/src/org/torproject/descriptor/NetworkStatusEntry.java
index 584f07b..43b3175 100644
--- a/src/org/torproject/descriptor/NetworkStatusEntry.java
+++ b/src/org/torproject/descriptor/NetworkStatusEntry.java
@@ -1,84 +1,177 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.Set;
import java.util.SortedSet;
-/* Status entry contained in a network status with version 2 or higher or
- * in a bridge network status. */
+/**
+ * Contains an entry in a network status in the version 2 or 3 directory
+ * protocol or in a bridge network status.
+ *
+ * <p>A network status entry is not a descriptor type of its own but is
+ * part of a network status in the version 2 directory protocol
+ * ({@link RelayNetworkStatus}), a vote ({@link RelayNetworkStatusVote})
+ * or flavored/unflavored consensus (@link RelayNetworkStatusConsensus})
+ * in the version 3 directory protocol, or a bridge network status
+ * ({@link BridgeNetworkStatus}). Entries in signed directories in the
+ * version 1 directory protocol are represented by router status entries
+ * ({@link RouterStatusEntry}).</p>
+ *
+ * @since 1.0.0
+ */
public interface NetworkStatusEntry {
- /* Return the raw status entry bytes. */
+ /**
+ * Return the raw network status entry bytes.
+ *
+ * @since 1.0.0
+ */
public byte[] getStatusEntryBytes();
- /* Return the relay nickname. */
+ /**
+ * Return the server nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the relay fingerprint. */
+ /**
+ * Return a SHA-1 digest of the server's identity key, encoded as 40
+ * upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return the descriptor identity or null if the containing status is a
- * microdesc consensus. */
+ /**
+ * Return the SHA-1 digest of the server descriptor, or null if the
+ * containing network status does not contain server descriptor
+ * references, like a microdesc consensus.
+ *
+ * @since 1.0.0
+ */
public String getDescriptor();
- /* Return the publication timestamp. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the IP address. */
+ /**
+ * Return the server's primary IPv4 address in dotted-quad format.
+ *
+ * @since 1.0.0
+ */
public String getAddress();
- /* Return the ORPort. */
+ /**
+ * Return the TCP port where this server accepts TLS connections for
+ * the main OR protocol.
+ *
+ * @since 1.0.0
+ */
public int getOrPort();
- /* Return the DirPort. */
+ /**
+ * Return the TCP port where this server accepts directory-related HTTP
+ * connections.
+ *
+ * @since 1.0.0
+ */
public int getDirPort();
- /* Return the (possibly empty) set of microdescriptor digest(s) if the
- * containing status is a vote or microdesc consensus, or null
- * otherwise. */
+ /**
+ * Return the (possibly empty) set of microdescriptor digests if the
+ * containing network status is a vote or microdesc consensus, or null
+ * otherwise.
+ *
+ * @since 1.0.0
+ */
public Set<String> getMicrodescriptorDigests();
- /* Return the relay's additional OR addresses and ports contained in
- * or-address lines, or an empty list if the network status doesn't
- * contain such lines. */
+ /**
+ * Return additional IP addresses and TCP ports where this server
+ * accepts TLS connections for the main OR protocol, or an empty list if
+ * the network status doesn't contain any such additional addresses and
+ * ports.
+ *
+ * @since 1.0.0
+ */
public List<String> getOrAddresses();
- /* Return the relay flags or null if the status entry didn't contain any
- * relay flags. */
+ /**
+ * Return the relay flags assigned to this server, or null if the
+ * status entry didn't contain any relay flags.
+ *
+ * @since 1.0.0
+ */
public SortedSet<String> getFlags();
- /* Return the Tor software version or null if the status entry didn't
- * contain a version line. */
+ /**
+ * Return the Tor software version, or null if the status entry didn't
+ * contain version information.
+ *
+ * @since 1.0.0
+ */
public String getVersion();
- /* Return the bandwidth weight or -1L if the status entry didn't
- * contain a bandwidth line. */
+ /**
+ * Return the bandwidth weight of this server or -1 if the status entry
+ * didn't contain a bandwidth line.
+ *
+ * @since 1.0.0
+ */
public long getBandwidth();
- /* Return the measured bandwidth or -1L if the status entry didn't
- * contain a bandwidth line or didn't contain a Measured= keyword in its
- * bandwidth line. */
+ /**
+ * Return the measured bandwidth or -1 if the status entry either
+ * didn't contain bandwidth information or didn't contain an indication
+ * that this information is based on measured bandwidth.
+ *
+ * @since 1.0.0
+ */
public long getMeasured();
- /* Return whether the status entry contained an Unmeasured=1 entry in
- * its bandwidth line, meaning that the bandwidth authorities didn't
- * measure this relay yet. Only included in consensuses using method
- * 17 or higher. */
+ /**
+ * Return whether the status entry is yet unmeasured by the bandwidth
+ * authorities; only included in consensuses using method 17 or higher.
+ *
+ * @since 1.0.0
+ */
public boolean getUnmeasured();
- /* Return the default policy of the port summary or null if the status
- * entry didn't contain a port summary line. */
+ /**
+ * Return the default policy of the port summary, which can be either
+ * {@code "accept"} or {@code "reject"}, or null if the status entry
+ * didn't contain an exit policy summary.
+ *
+ * @since 1.0.0
+ */
public String getDefaultPolicy();
- /* Return the port list of the port summary or null if the status entry
- * didn't contain a port summary line. */
+ /**
+ * Return the list of ports or port intervals of the exit port summary,
+ * or null if the status entry didn't contain an exit policy summary.
+ *
+ * @since 1.0.0
+ */
public String getPortList();
- /* Return the relay's base64-encoded Ed25519 master key, "none" if the
- * relay doesn't have an Ed25519 identity, or null if the status entry
- * didn't contain this information. Only included in votes. */
+ /**
+ * Return the server's Ed25519 master key, encoded as 43 base64
+ * characters without padding characters, "none" if the relay doesn't
+ * have an Ed25519 identity, or null if the status entry didn't contain
+ * this information or if the status is not a vote.
+ *
+ * @since 1.1.0
+ */
public String getMasterKeyEd25519();
}
diff --git a/src/org/torproject/descriptor/RelayDirectory.java b/src/org/torproject/descriptor/RelayDirectory.java
index 209c080..8f3e58b 100644
--- a/src/org/torproject/descriptor/RelayDirectory.java
+++ b/src/org/torproject/descriptor/RelayDirectory.java
@@ -1,41 +1,104 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-/* Contains a v1 signed directory. */
+/**
+ * Contains a signed directory in the version 1 directory protocol.
+ *
+ * <p>Directory authorities in the (long outdated) version 1 of the
+ * directory protocol served signed directory documents containing a list
+ * of signed server descriptors ({@link ServerDescriptor}) along with
+ * short summaries of the status of each server
+ * ({@link RouterStatusEntry}).</p>
+ *
+ * <p>Clients in that version of the directory protocol would fetch this
+ * signed directory to get up-to-date information on the state of the
+ * network and be certain that the list was attested by a trusted
+ * directory authority.</p>
+ *
+ * <p>Signed directories in the version 1 directory protocol have first
+ * been superseded by network status documents in the version 2 directory
+ * protocol ({@link RelayNetworkStatus}) and later by network status
+ * consensuses ({@link RelayNetworkStatusConsensus}) in the version 3
+ * directory protocol.</p>
+ *
+ * @since 1.0.0
+ */
public interface RelayDirectory extends Descriptor {
- /* Return the published time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the directory signing key digest. */
+ /**
+ * Return the RSA-1024 public key in PEM format used by this authority
+ * as long-term identity key and to sign network statuses, or null if
+ * this key is not included in the descriptor header.
+ *
+ * @since 1.0.0
+ */
public String getDirSigningKey();
- /* Return recommended software versions or null if the directory doesn't
- * list recommended software. */
+ /**
+ * Return recommended Tor versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedSoftware();
- /* Return the directory signature. */
+ /**
+ * Return the directory signature string made with the authority's
+ * identity key.
+ *
+ * @since 1.0.0
+ */
public String getDirectorySignature();
- /* Return router status entries, one for each contained relay. */
+ /**
+ * Return router status entries, one for each contained relay.
+ *
+ * @since 1.0.0
+ */
public List<RouterStatusEntry> getRouterStatusEntries();
- /* Return a list of server descriptors contained in the signed
- * directory. */
+ /**
+ * Return a list of server descriptors contained in the signed
+ * directory.
+ *
+ * @since 1.0.0
+ */
public List<ServerDescriptor> getServerDescriptors();
- /* Return a (very likely empty) list of exceptions from parsing the
- * contained server descriptors. */
+ /**
+ * Return a (very likely empty) list of exceptions from parsing the
+ * contained server descriptors.
+ *
+ * @since 1.0.0
+ */
public List<Exception> getServerDescriptorParseExceptions();
- /* Return the directory nickname. */
+ /**
+ * Return the directory nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the directory digest that the directory authority used to sign
- * the directory. */
+ /**
+ * Return the SHA-1 directory digest, encoded as 40 lower-case
+ * hexadecimal characters, that the directory authority used to sign the
+ * directory.
+ *
+ * @since 1.0.0
+ */
public String getDirectoryDigest();
}
diff --git a/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java b/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java
index 01e2716..73f8438 100644
--- a/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java
+++ b/src/org/torproject/descriptor/RelayExtraInfoDescriptor.java
@@ -1,8 +1,20 @@
-/* Copyright 2015 The Tor Project
+/* Copyright 2015--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Contains a relay extra-info descriptor. */
+/**
+ * Contains a relay extra-info descriptor.
+ *
+ * <p>Relay extra-info descriptors share many contents with sanitized
+ * bridge extra-info descriptors ({@link BridgeExtraInfoDescriptor}),
+ * which is why they share a common superinterface
+ * ({@link ExtraInfoDescriptor}). The main purpose of having two
+ * subinterfaces is being able to distinguish descriptor types more
+ * easily.</p>
+ *
+ * @since 1.1.0
+ */
public interface RelayExtraInfoDescriptor extends ExtraInfoDescriptor {
}
diff --git a/src/org/torproject/descriptor/RelayNetworkStatus.java b/src/org/torproject/descriptor/RelayNetworkStatus.java
index acbdb90..db3ddac 100644
--- a/src/org/torproject/descriptor/RelayNetworkStatus.java
+++ b/src/org/torproject/descriptor/RelayNetworkStatus.java
@@ -1,68 +1,176 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.SortedMap;
import java.util.SortedSet;
-/* Contains a v2 network status. */
+/**
+ * Contains a network status document in the version 2 directory protocol.
+ *
+ * <p>Directory authorities in the (outdated) version 2 of the directory
+ * protocol published signed network status documents. Each network
+ * status listed, for every relay in the network
+ * ({@link NetworkStatusEntry}): a hash of its identity key, a hash of its
+ * most recent server descriptor, and a summary of what the authority
+ * believed about its status.</p>
+ *
+ * <p>Clients would download the authorities' network status documents in
+ * turn, and believe statements about routers iff they were attested to by
+ * more than half of the authorities.</p>
+ *
+ * <p>Network status documents in the version 2 directory protocol
+ * supersede signed directories in the version 1 directory protocol
+ * ({@link RelayDirectory}) and have been superseded by network status
+ * consensuses ({@link RelayNetworkStatusConsensus}) in the version 3
+ * directory protocol.</p>
+ *
+ * @since 1.0.0
+ */
public interface RelayNetworkStatus extends Descriptor {
- /* Return the network status version. */
+ /**
+ * Return the document format version of this descriptor which is 2.
+ *
+ * @since 1.0.0
+ */
public int getNetworkStatusVersion();
- /* Return the authority's hostname. */
+ /**
+ * Return the authority's hostname.
+ *
+ * @since 1.0.0
+ */
public String getHostname();
- /* Return the authority's IP address. */
+ /**
+ * Return the authority's primary IPv4 address in dotted-quad format,
+ * or null if the descriptor does not contain an address.
+ *
+ * @since 1.0.0
+ */
public String getAddress();
- /* Return the authority's directory port. */
+ /**
+ * Return the TCP port where this authority accepts directory-related
+ * HTTP connections, or 0 if the authority does not accept such
+ * connections.
+ *
+ * @since 1.0.0
+ */
public int getDirport();
- /* Return the directory's signing key's fingerprint. */
+ /**
+ * Return a SHA-1 digest of the authority's public identity key,
+ * encoded as 40 upper-case hexadecimal characters, which is also used
+ * to sign network statuses.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return the contact line. */
+ /**
+ * Return the contact information for this authority, which may contain
+ * non-ASCII characters.
+ *
+ * @since 1.0.0
+ */
public String getContactLine();
- /* Return the directory signing key digest. */
+ /**
+ * Return the RSA-1024 public key in PEM format used by this authority
+ * as long-term identity key and to sign network statuses.
+ *
+ * @since 1.0.0
+ */
public String getDirSigningKey();
- /* Return recommended server versions or null if the status doesn't
- * contain recommended server versions. */
+ /**
+ * Return recommended Tor versions for server usage, or null if the
+ * authority does not recommend server versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedServerVersions();
- /* Return recommended client versions or null if the status doesn't
- * contain recommended client versions. */
+ /**
+ * Return recommended Tor versions for client usage, or null if the
+ * authority does not recommend client versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedClientVersions();
- /* Return the published time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the set of flags that this directory assigns to relays, or
- * null if the status does not contain a dir-options line. */
+ /**
+ * Return the set of flags that this directory assigns to relays, or
+ * null if the status does not assign such flags.
+ *
+ * @since 1.0.0
+ */
public SortedSet<String> getDirOptions();
- /* Return status entries, one for each contained relay. */
+ /**
+ * Return status entries for each contained server, with map keys being
+ * SHA-1 digests of the servers' public identity keys, encoded as 40
+ * upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, NetworkStatusEntry> getStatusEntries();
- /* Return whether a status entry with the given fingerprint exists. */
+ /**
+ * Return whether a status entry with the given relay fingerprint
+ * (SHA-1 digest of the server's public identity key, encoded as 40
+ * upper-case hexadecimal characters) exists; convenience method for
+ * {@code getStatusEntries().containsKey(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public boolean containsStatusEntry(String fingerprint);
- /* Return a status entry by fingerprint or null if no such status entry
- * exists. */
+ /**
+ * Return a status entry by relay fingerprint (SHA-1 digest of the
+ * server's public identity key, encoded as 40 upper-case hexadecimal
+ * characters), or null if no such status entry exists; convenience
+ * method for {@code getStatusEntries().get(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public NetworkStatusEntry getStatusEntry(String fingerprint);
- /* Return the directory nickname. */
+ /**
+ * Return the authority's nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the directory signature. */
+ /**
+ * Return the directory signature string made with the authority's
+ * identity key.
+ *
+ * @since 1.0.0
+ */
public String getDirectorySignature();
- /* Return the status digest that the directory authority used to sign
- * the network status. */
+ /**
+ * Return the SHA-1 status digest, encoded as 40 lower-case hexadecimal
+ * characters, that the directory authority used to sign the network
+ * status.
+ *
+ * @since 1.0.0
+ */
public String getStatusDigest();
}
diff --git a/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java b/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java
index 0419acc..624f1cc 100644
--- a/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java
+++ b/src/org/torproject/descriptor/RelayNetworkStatusConsensus.java
@@ -1,76 +1,201 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.SortedMap;
import java.util.SortedSet;
-/* Contains a network status consensus. */
+/**
+ * Contains a network status consensus in the version 3 directory protocol.
+ *
+ * <p>Directory authorities in the version 3 of the directory protocol
+ * periodically generate a view of the current descriptors and status for
+ * known relays and send a signed summary of this view to the other
+ * authorities ({@link RelayNetworkStatusVote}). The authorities compute
+ * the result of this vote and sign a network status consensus containing
+ * the result of the vote, which is this document.</p>
+ *
+ * <p>Clients use consensus documents to find out when their list of
+ * relays is out-of-date by looking at the contained network status
+ * entries ({@link NetworkStatusEntry}). If it is, they download any
+ * missing server descriptors ({@link ServerDescriptor}).</p>
+ *
+ * @since 1.0.0
+ */
public interface RelayNetworkStatusConsensus extends Descriptor {
- /* Return the network status version. */
+ /**
+ * Return the document format version of this descriptor which is 3 or
+ * higher.
+ *
+ * @since 1.0.0
+ */
public int getNetworkStatusVersion();
- /* Return the flavor name, or null if this consensus is unflavored. */
+ /**
+ * Return the consensus flavor name, which denotes the variant of the
+ * original, unflavored consensus, encoded as a string of alphanumeric
+ * characters and dashes, or null if this descriptor is the unflavored
+ * consensus.
+ *
+ * @since 1.0.0
+ */
public String getConsensusFlavor();
- /* Return the consensus method. */
+ /**
+ * Return the consensus method number of this descriptor, which is the
+ * highest consensus method supported by more than 2/3 of voting
+ * authorities, or 0 if no consensus method is contained in the
+ * descriptor.
+ *
+ * @since 1.0.0
+ */
public int getConsensusMethod();
- /* Return the valid-after time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch at which this
+ * descriptor became valid.
+ *
+ * @since 1.0.0
+ */
public long getValidAfterMillis();
- /* Return the fresh-until time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch until which this
+ * descriptor is the freshest that is available.
+ *
+ * @since 1.0.0
+ */
public long getFreshUntilMillis();
- /* Return the valid-until time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch until which this
+ * descriptor was valid.
+ *
+ * @since 1.0.0
+ */
public long getValidUntilMillis();
- /* Return the VoteSeconds time in seconds. */
+ /**
+ * Return the number of seconds that the directory authorities will
+ * allow to collect votes from the other authorities when producing the
+ * next consensus.
+ *
+ * @since 1.0.0
+ */
public long getVoteSeconds();
- /* Return the DistSeconds time in seconds. */
+ /**
+ * Return the number of seconds that the directory authorities will
+ * allow to collect signatures from the other authorities when producing
+ * the next consensus.
+ *
+ * @since 1.0.0
+ */
public long getDistSeconds();
- /* Return recommended server versions or null if the consensus doesn't
- * contain recommended server versions. */
+ /**
+ * Return recommended Tor versions for server usage, or null if the
+ * consensus does not contain an opinion about server versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedServerVersions();
- /* Return recommended client versions or null if the consensus doesn't
- * contain recommended client versions. */
+ /**
+ * Return recommended Tor versions for client usage, or null if the
+ * consensus does not contain an opinion about client versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedClientVersions();
- /* Return known relay flags. */
+ /**
+ * Return known relay flags in this descriptor that were contained in
+ * enough votes for this consensus to be an authoritative opinion for
+ * these relay flags.
+ *
+ * @since 1.0.0
+ */
public SortedSet<String> getKnownFlags();
- /* Return consensus parameters or null if the consensus doesn't contain
- * consensus parameters. */
+ /**
+ * Return consensus parameters contained in this descriptor with map
+ * keys being case-sensitive parameter identifiers and map values being
+ * parameter values, or null if the consensus doesn't contain consensus
+ * parameters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getConsensusParams();
- /* Return dir-source entries representing the directories of which
- * votes are contained in this consensus. */
+ /**
+ * Return directory source entries for each directory authority that
+ * contributed to the consensus, with map keys being SHA-1 digests of
+ * the authorities' identity keys in the version 3 directory protocol,
+ * encoded as 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, DirSourceEntry> getDirSourceEntries();
- /* Return status entries, one for each contained relay. */
+ /**
+ * Return status entries for each contained server, with map keys being
+ * SHA-1 digests of the servers' public identity keys, encoded as 40
+ * upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, NetworkStatusEntry> getStatusEntries();
- /* Return whether a status entry with the given fingerprint exists. */
+ /**
+ * Return whether a status entry with the given relay fingerprint
+ * (SHA-1 digest of the server's public identity key, encoded as 40
+ * upper-case hexadecimal characters) exists; convenience method for
+ * {@code getStatusEntries().containsKey(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public boolean containsStatusEntry(String fingerprint);
- /* Return a status entry by fingerprint or null if no such status entry
- * exists. */
+ /**
+ * Return a status entry by relay fingerprint (SHA-1 digest of the
+ * server's public identity key, encoded as 40 upper-case hexadecimal
+ * characters), or null if no such status entry exists; convenience
+ * method for {@code getStatusEntries().get(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public NetworkStatusEntry getStatusEntry(String fingerprint);
- /* Return directory signatures. */
+ /**
+ * Return directory signatures of this consensus, with map keys being
+ * SHA-1 digests of the authorities' identity keys in the version 3
+ * directory protocol, encoded as 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, DirectorySignature> getDirectorySignatures();
- /* Return bandwidth weights or null if the consensus doesn't contain
- * bandwidth weights. */
+ /**
+ * Return optional weights to be applied to router bandwidths during
+ * path selection with map keys being case-sensitive weight identifiers
+ * and map values being weight values, or null if the consensus doesn't
+ * contain such weights.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getBandwidthWeights();
- /* Return the consensus digest that directory authorities use to sign
- * the consensus. */
+ /**
+ * Return the SHA-1 digest of this consensus, encoded as 40 upper-case
+ * hexadecimal characters that directory authorities use to sign the
+ * consensus.
+ *
+ * @since 1.0.0
+ */
public String getConsensusDigest();
}
diff --git a/src/org/torproject/descriptor/RelayNetworkStatusVote.java b/src/org/torproject/descriptor/RelayNetworkStatusVote.java
index f4fad2a..5e0c7cd 100644
--- a/src/org/torproject/descriptor/RelayNetworkStatusVote.java
+++ b/src/org/torproject/descriptor/RelayNetworkStatusVote.java
@@ -1,147 +1,379 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.SortedMap;
import java.util.SortedSet;
-/* Contains a network status vote. */
+/**
+ * Contains a network status vote in the version 3 directory protocol.
+ *
+ * <p>Directory authorities in the version 3 of the directory protocol
+ * periodically generate a view of the current descriptors and status for
+ * known relays and send a signed summary of this view to the other
+ * authorities, which is this document. The authorities compute the
+ * result of this vote and sign a network status consensus containing the
+ * result of the vote ({@link RelayNetworkStatusConsensus}).</p>
+ *
+ * @since 1.0.0
+ */
public interface RelayNetworkStatusVote extends Descriptor {
- /* Return the network status version. */
+ /**
+ * Return the document format version of this descriptor which is 3 or
+ * higher.
+ *
+ * @since 1.0.0
+ */
public int getNetworkStatusVersion();
- /* Return the consensus method. */
+ /**
+ * Return the list of consensus method numbers supported by this
+ * authority, or null if the descriptor doesn't say so, which would mean
+ * that only method 1 is supported.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getConsensusMethods();
- /* Return the publication time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * was published.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the valid-after time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch at which the
+ * consensus is supposed to become valid.
+ *
+ * @since 1.0.0
+ */
public long getValidAfterMillis();
- /* Return the fresh-until time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch until which the
+ * consensus is supposed to be the freshest that is available.
+ *
+ * @since 1.0.0
+ */
public long getFreshUntilMillis();
- /* Return the valid-until time in milliseconds. */
+ /**
+ * Return the time in milliseconds since the epoch until which the
+ * consensus is supposed to be valid.
+ *
+ * @since 1.0.0
+ */
public long getValidUntilMillis();
- /* Return the VoteSeconds time in seconds. */
+ /**
+ * Return the number of seconds that the directory authorities will
+ * allow to collect votes from the other authorities when producing the
+ * next consensus.
+ *
+ * @since 1.0.0
+ */
public long getVoteSeconds();
- /* Return the DistSeconds time in seconds. */
+ /**
+ * Return the number of seconds that the directory authorities will
+ * allow to collect signatures from the other authorities when producing
+ * the next consensus.
+ *
+ * @since 1.0.0
+ */
public long getDistSeconds();
- /* Return recommended server versions or null if the authority doesn't
- * recommend server versions. */
+ /**
+ * Return recommended Tor versions for server usage, or null if the
+ * authority does not recommend server versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedServerVersions();
- /* Return recommended client versions or null if the authority doesn't
- * recommend server versions. */
+ /**
+ * Return recommended Tor versions for client usage, or null if the
+ * authority does not recommend client versions.
+ *
+ * @since 1.0.0
+ */
public List<String> getRecommendedClientVersions();
- /* Return known relay flags. */
+ /**
+ * Return known relay flags by this authority.
+ *
+ * @since 1.0.0
+ */
public SortedSet<String> getKnownFlags();
- /* Return the minimum uptime in seconds that this authority requires for
- * assigning the Stable flag, or -1 if the authority doesn't report this
- * value. */
+ /**
+ * Return the minimum uptime in seconds that this authority requires
+ * for assigning the Stable flag, or -1 if the authority doesn't report
+ * this value.
+ *
+ * @since 1.0.0
+ */
public long getStableUptime();
- /* Return the minimum MTBF (mean time between failure) that this
+ /**
+ * Return the minimum MTBF (mean time between failure) that this
* authority requires for assigning the Stable flag, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.0.0
+ */
public long getStableMtbf();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Fast flag, or -1 if the authority doesn't report this
- * value. */
+ * value.
+ *
+ * @since 1.0.0
+ */
public long getFastBandwidth();
- /* Return the minimum WFU (weighted fractional uptime) in percent that
- * this authority requires for assigning the Guard flag, or -1.0 if the
- * authority doesn't report this value. */
+ /**
+ * Return the minimum WFU (weighted fractional uptime) in percent that
+ * this authority requires for assigning the Guard flag, or -1 if the
+ * authority doesn't report this value.
+ *
+ * @since 1.0.0
+ */
public double getGuardWfu();
- /* Return the minimum weighted time in seconds that this authority needs
- * to know about a relay before assigning the Guard flag, or -1 if the
- * authority doesn't report this information. */
+ /**
+ * Return the minimum weighted time in seconds that this authority
+ * needs to know about a relay before assigning the Guard flag, or -1 if
+ * the authority doesn't report this information.
+ *
+ * @since 1.0.0
+ */
public long getGuardTk();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Guard flag if exits can be guards, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.0.0
+ */
public long getGuardBandwidthIncludingExits();
- /* Return the minimum bandwidth that this authority requires for
+ /**
+ * Return the minimum bandwidth that this authority requires for
* assigning the Guard flag if exits can not be guards, or -1 if the
- * authority doesn't report this value. */
+ * authority doesn't report this value.
+ *
+ * @since 1.0.0
+ */
public long getGuardBandwidthExcludingExits();
- /* Return 1 if the authority has measured enough MTBF info to use the
+ /**
+ * Return 1 if the authority has measured enough MTBF info to use the
* MTBF requirement instead of the uptime requirement for assigning the
* Stable flag, 0 if not, or -1 if the authority doesn't report this
- * information. */
+ * information.
+ *
+ * @since 1.0.0
+ */
public int getEnoughMtbfInfo();
- /* Return 1 if the authority has enough measured bandwidths that it'll
+ /**
+ * Return 1 if the authority has enough measured bandwidths that it'll
* ignore the advertised bandwidth claims of routers without measured
* bandwidth, 0 if not, or -1 if the authority doesn't report this
- * information. */
+ * information.
+ *
+ * @since 1.1.0
+ */
public int getIgnoringAdvertisedBws();
- /* Return consensus parameters. */
+ /**
+ * Return consensus parameters contained in this descriptor with map
+ * keys being case-sensitive parameter identifiers and map values being
+ * parameter values, or null if the authority doesn't include consensus
+ * parameters in its vote.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, Integer> getConsensusParams();
- /* Return the directory nickname. */
+ /**
+ * Return the authority's nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the directory identity. */
+ /**
+ * Return a SHA-1 digest of the authority's long-term authority
+ * identity key used for the version 3 directory protocol, encoded as
+ * 40 upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getIdentity();
- /* Return the hostname. */
+ /**
+ * Return the authority's hostname.
+ *
+ * @since 1.2.0
+ */
public String getHostname();
- /* Return the IP address. */
+ /**
+ * Return the authority's primary IPv4 address in dotted-quad format,
+ * or null if the descriptor does not contain an address.
+ *
+ * @since 1.0.0
+ */
public String getAddress();
- /* Return the DiRPort. */
+ /**
+ * Return the TCP port where this authority accepts directory-related
+ * HTTP connections, or 0 if the authority does not accept such
+ * connections.
+ *
+ * @since 1.0.0
+ */
public int getDirport();
- /* Return the ORPort. */
+ /**
+ * Return the TCP port where this authority accepts TLS connections for
+ * the main OR protocol, or 0 if the authority does not accept such
+ * connections.
+ *
+ * @since 1.0.0
+ */
public int getOrport();
- /* Return the contact line. */
+ /**
+ * Return the contact information for this authority, which may contain
+ * non-ASCII characters, or null if no contact information is included
+ * in the descriptor.
+ *
+ * @since 1.0.0
+ */
public String getContactLine();
- /* Return the directory key certificate version. */
+ /**
+ * Return the version of the directory key certificate used by this
+ * authority, which must be 3 or higher.
+ *
+ * @since 1.0.0
+ */
public int getDirKeyCertificateVersion();
- /* Return the legacy dir key or null if the directory authority does not
- * use a legacy dir key. */
+ /**
+ * Return the SHA-1 digest for an obsolete authority identity key still
+ * used by this authority to keep older clients working, or null if this
+ * authority does not use such a key.
+ *
+ * @since 1.0.0
+ */
public String getLegacyDirKey();
- /* Return the directory key publication timestamp. */
+ /**
+ * Return the authority's identity key in PEM format.
+ *
+ * @since 1.2.0
+ */
+ public String getDirIdentityKey();
+
+ /**
+ * Return the time in milliseconds since the epoch when the authority's
+ * signing key and corresponding key certificate were generated.
+ *
+ * @since 1.0.0
+ */
public long getDirKeyPublishedMillis();
- /* Return the directory key expiration timestamp. */
+ /**
+ * Return the time in milliseconds since the epoch after which the
+ * authority's signing key is no longer valid.
+ *
+ * @since 1.0.0
+ */
public long getDirKeyExpiresMillis();
- /* Return the signing key digest. */
+ /**
+ * Return the authority's signing key in PEM format.
+ *
+ * @since 1.2.0
+ */
+ public String getDirSigningKey();
+
+ /**
+ * Return the SHA-1 digest of the authority's signing key, encoded as
+ * 40 upper-case hexadecimal characters, or null if this digest cannot
+ * be obtained from the directory signature.
+ *
+ * @since 1.0.0
+ */
public String getSigningKeyDigest();
- /* Return status entries, one for each contained relay. */
+ /**
+ * Return the signature of the authority's identity key made using the
+ * authority's signing key, or null if the vote does not contain such a
+ * signature.
+ *
+ * @since 1.2.0
+ */
+ public String getDirKeyCrosscert();
+
+ /**
+ * Return the certificate signature from the initial item
+ * "dir-key-certificate-version" until the final item
+ * "dir-key-certification", signed with the authority identity key.
+ *
+ * @since 1.2.0
+ */
+ public String getDirKeyCertification();
+
+ /**
+ * Return status entries for each contained server, with map keys being
+ * SHA-1 digests of the servers' public identity keys, encoded as 40
+ * upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, NetworkStatusEntry> getStatusEntries();
- /* Return whether a status entry with the given fingerprint exists. */
+ /**
+ * Return whether a status entry with the given relay fingerprint
+ * (SHA-1 digest of the server's public identity key, encoded as 40
+ * upper-case hexadecimal characters) exists; convenience method for
+ * {@code getStatusEntries().containsKey(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public boolean containsStatusEntry(String fingerprint);
- /* Return a status entry by fingerprint or null if no such status entry
- * exists. */
+ /**
+ * Return a status entry by relay fingerprint (SHA-1 digest of the
+ * server's public identity key, encoded as 40 upper-case hexadecimal
+ * characters), or null if no such status entry exists; convenience
+ * method for {@code getStatusEntries().get(fingerprint)}.
+ *
+ * @since 1.0.0
+ */
public NetworkStatusEntry getStatusEntry(String fingerprint);
- /* Return directory signatures. */
+ /**
+ * Return the directory signature of this vote, with the single map key
+ * being the SHA-1 digest of the authority's identity key in the version
+ * 3 directory protocol, encoded as 40 upper-case hexadecimal
+ * characters.
+ *
+ * @since 1.0.0
+ */
public SortedMap<String, DirectorySignature> getDirectorySignatures();
}
diff --git a/src/org/torproject/descriptor/RelayServerDescriptor.java b/src/org/torproject/descriptor/RelayServerDescriptor.java
index 402ddfc..6ef3140 100644
--- a/src/org/torproject/descriptor/RelayServerDescriptor.java
+++ b/src/org/torproject/descriptor/RelayServerDescriptor.java
@@ -1,8 +1,19 @@
-/* Copyright 2015 The Tor Project
+/* Copyright 2015--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Contains a relay server descriptor. */
+/**
+ * Contains a relay server descriptor.
+ *
+ * <p>Relay server descriptors share many contents with sanitized bridge
+ * server descriptors ({@link BridgeServerDescriptor}), which is why they
+ * share a common superinterface ({@link ServerDescriptor}). The main
+ * purpose of having two subinterfaces is being able to distinguish
+ * descriptor types more easily.</p>
+ *
+ * @since 1.1.0
+ */
public interface RelayServerDescriptor extends ServerDescriptor {
}
diff --git a/src/org/torproject/descriptor/RouterStatusEntry.java b/src/org/torproject/descriptor/RouterStatusEntry.java
index 978e6e1..f9a56db 100644
--- a/src/org/torproject/descriptor/RouterStatusEntry.java
+++ b/src/org/torproject/descriptor/RouterStatusEntry.java
@@ -1,20 +1,51 @@
-/* Copyright 2012--2015 The Tor Project
+/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
-/* Status entry contained in a v1 signed directory. */
+/**
+ * Contains a router status entry contained in a signed directory in the
+ * version 1 directory protocol.
+ *
+ * <p>Directory authorities in the (long outdated) version 1 of the
+ * directory protocol included router status entries with short summaries
+ * of the status of each server in the signed directories they produced
+ * ({@link RelayDirectory}). These entries contained references to server
+ * descriptors published by relays together with the authorities' opinion
+ * on whether relays were verified and live.</p>
+ *
+ * @since 1.0.0
+ */
public interface RouterStatusEntry {
- /* Return the relay nickname, or null if the relay is unverified. */
+ /**
+ * Return the relay nickname consisting of 1 to 19 alphanumeric
+ * characters, or null if the relay is unverified.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the relay fingerprint. */
+ /**
+ * Return a SHA-1 digest of the relay's identity key, encoded as 40
+ * upper-case hexadecimal characters.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return whether the relay is verified. */
+ /**
+ * Return whether the relay is verified.
+ *
+ * @since 1.0.0
+ */
public boolean isVerified();
- /* Return whether the relay is live. */
+ /**
+ * Return whether the relay is live.
+ *
+ * @since 1.0.0
+ */
public boolean isLive();
}
diff --git a/src/org/torproject/descriptor/ServerDescriptor.java b/src/org/torproject/descriptor/ServerDescriptor.java
index 49eaa92..17c7e82 100644
--- a/src/org/torproject/descriptor/ServerDescriptor.java
+++ b/src/org/torproject/descriptor/ServerDescriptor.java
@@ -1,195 +1,427 @@
-/* Copyright 2011--2015 The Tor Project
+/* Copyright 2011--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
-/* Contains a relay or bridge server descriptor. */
+/**
+ * Contains a relay or sanitized bridge server descriptor.
+ *
+ * <p>Relays publish server descriptors to the directory authorities to
+ * register in the network. Server descriptors contain information about
+ * the capabilities of a server, like their exit policy, that clients use
+ * to select servers for their circuits (along with information provided
+ * by directory authorities on reachability, stability, and capacity of
+ * servers). Server descriptors also contain network addresses and
+ * cryptographic material that clients use to build circuits.</p>
+ *
+ * <p>Prior to the introduction of microdescriptors
+ * ({@link Microdescriptor}), the directory authorities included
+ * cryptographic digests of server descriptors in network statuses
+ * ({@link RelayNetworkStatusConsensus}) and clients downloaded all
+ * referenced server descriptors. Nowadays, the directory authorities
+ * derive microdescriptors from server descriptors and reference those
+ * in network statuses, and clients only download microdescriptors instead
+ * of server descriptors.</p>
+ *
+ * <p>Bridges publish server descriptors to the bridge directory
+ * authority, also to announce themselves in the network. The bridge
+ * directory authority compiles a list of available bridges
+ * ({@link BridgeNetworkStatus}) for the bridge distribution service
+ * BridgeDB. There are no microdescriptors for bridges, so that bridge
+ * clients still rely on downloading bridge server descriptors directly
+ * from the bridge they're connecting to.</p>
+ *
+ * <p>It's worth noting that all contents of server descriptors are
+ * written and signed by relays and bridges without a third party
+ * verifying their correctness. The (bridge) directory authorities may
+ * decide to exclude dishonest servers from the network statuses they
+ * produce, but that wouldn't be reflected in server descriptors.</p>
+ *
+ * @since 1.0.0
+ */
public interface ServerDescriptor extends Descriptor {
- /* Return the descriptor digest that is used to reference this server
- * descriptor in a network status. */
+ /**
+ * Return the SHA-1 descriptor digest, encoded as 40 lower-case (relay
+ * descriptors) or upper-case (bridge descriptors) hexadecimal
+ * characters, that is used to reference this descriptor from a network
+ * status descriptor.
+ *
+ * @since 1.0.0
+ */
public String getServerDescriptorDigest();
- /* Return the base64-encoded SHA-256 descriptor digest that may be used
- * to reference this server descriptor in a network status. */
+ /**
+ * Return the SHA-256 descriptor digest, encoded as 43 base64
+ * characters without padding characters, that may be used to reference
+ * this server descriptor from a network status descriptor.
+ *
+ * @since 1.1.0
+ */
public String getServerDescriptorDigestSha256();
- /* Return the relay's nickname. */
+ /**
+ * Return the server's nickname consisting of 1 to 19 alphanumeric
+ * characters.
+ *
+ * @since 1.0.0
+ */
public String getNickname();
- /* Return the relay's IPv4 address in dotted-quad format. */
+ /**
+ * Return the server's primary IPv4 address in dotted-quad format.
+ *
+ * @since 1.0.0
+ */
public String getAddress();
- /* Return the relay's OR port. */
+ /**
+ * Return the TCP port where this server accepts TLS connections for
+ * the main OR protocol, or 0 if the server does not accept such
+ * connections.
+ *
+ * @since 1.0.0
+ */
public int getOrPort();
- /* Return the relay's SOCKS port which should always be 0. */
+ /**
+ * Return the TCP port where this server accepts SOCKS connections,
+ * which is deprecated and should always be 0.
+ *
+ * @since 1.0.0
+ */
public int getSocksPort();
- /* Return the relay's directory port. */
+ /**
+ * Return the TCP port where this server accepts directory-related HTTP
+ * connections, or 0 if the server does not accept such connections.
+ *
+ * @since 1.0.0
+ */
public int getDirPort();
- /* Return the relay's additional OR addresses and ports contained in
- * or-address lines, or an empty list if the descriptor doesn't contain
- * such lines. */
+ /**
+ * Return IP addresses and TCP ports where this server accepts TLS
+ * connections for the main OR protocol, or an empty list if the server
+ * does not support additional addresses or ports; entries are given in
+ * the order as they are listed in the descriptor; IPv4 addresses are
+ * given in dotted-quad format, IPv6 addresses use the colon-separated
+ * hexadecimal format surrounded by square brackets, and TCP ports are
+ * separated from the IP address using a colon.
+ *
+ * @since 1.0.0
+ */
public List<String> getOrAddresses();
- /* Return the average bandwidth in bytes per second that the relay is
- * willing to sustain over long periods. */
+ /**
+ * Return the average bandwidth in bytes per second that the server is
+ * willing to sustain over long periods.
+ *
+ * @since 1.0.0
+ */
public int getBandwidthRate();
- /* Return the burst bandwidth in bytes per second that the relay is
- * willing to sustain in very short intervals. */
+ /**
+ * Return the burst bandwidth in bytes per second that the server is
+ * willing to sustain in very short intervals.
+ *
+ * @since 1.0.0
+ */
public int getBandwidthBurst();
- /* Return the observed bandwidth in bytes per second as an estimate of
- * the capacity that the relay can handle, or -1 if the descriptor
+ /**
+ * Return the observed bandwidth in bytes per second as an estimate of
+ * the capacity that the server can handle, or -1 if the descriptor
* doesn't contain an observed bandwidth value (which is the case for
- * Tor versions 0.0.8 or older). */
+ * Tor 0.0.8 or older).
+ *
+ * @since 1.0.0
+ */
public int getBandwidthObserved();
- /* Return the platform string containing the Tor software version and
- * the operating system, or null if this descriptor does not contain a
- * platform line. */
+ /**
+ * Return a human-readable string describing the Tor software version
+ * and the operating system of this server, which may contain non-ASCII
+ * characters, typically written as {@code "Tor $version on $system"},
+ * or null if this descriptor does not contain a platform line.
+ *
+ * @since 1.0.0
+ */
public String getPlatform();
- /* Return the time when this descriptor and the corresponding extra-info
- * document was generated. */
+ /**
+ * Return the time in milliseconds since the epoch when this descriptor
+ * and the corresponding extra-info descriptor were generated.
+ *
+ * @since 1.0.0
+ */
public long getPublishedMillis();
- /* Return the relay fingerprint, or null if this descriptor does not
- * contain a fingerprint line. */
+ /**
+ * Return a SHA-1 digest of the server's public identity key, encoded
+ * as 40 upper-case hexadecimal characters (without spaces after every 4
+ * characters as opposed to the encoding in the descriptor), that is
+ * typically used to uniquely identify the server, or null if this
+ * descriptor does not contain a fingerprint line.
+ *
+ * @since 1.0.0
+ */
public String getFingerprint();
- /* Return whether the relay was hibernating when this descriptor was
- * published. */
+ /**
+ * Return whether the server was hibernating when this descriptor was
+ * published and should not be used to build circuits.
+ *
+ * @since 1.0.0
+ */
public boolean isHibernating();
- /* Return the number of seconds that this relay has been running (which
- * might even be negative in a few descriptors due to a bug that was
- * fixed in 0.1.2.7-alpha), or null if the descriptor does not contain
- * an uptime line. */
+ /**
+ * Return the number of seconds that the server process has been
+ * running (which might even be negative in a few descriptors due to a
+ * bug that was fixed in Tor 0.1.2.7-alpha), or null if the descriptor
+ * does not contain an uptime line.
+ *
+ * @since 1.0.0
+ */
public Long getUptime();
- /* Return the onion key in PEM format, or null if the descriptor
- * doesn't contain a signing key (which is the case in sanitized bridge
- * descriptors). */
+ /**
+ * Return the RSA-1024 public key in PEM format used to encrypt CREATE
+ * cells for this server, or null if the descriptor doesn't contain an
+ * onion key (which is the case in sanitized bridge descriptors).
+ *
+ * @since 1.0.0
+ */
public String getOnionKey();
- /* Return the signing key in PEM format, or null if the descriptor
- * doesn't contain a signing key (which is the case in sanitized bridge
- * descriptors). */
+ /**
+ * Return the RSA-1024 public key in PEM format used by this server as
+ * long-term identity key, or null if the descriptor doesn't contain a
+ * signing key (which is the case in sanitized bridge descriptors).
+ *
+ * @since 1.0.0
+ */
public String getSigningKey();
- /* Return the relay's exit policy consisting of one or more accept or
- * reject lines. */
+ /**
+ * Return the server's exit policy consisting of one or more accept or
+ * reject rules that the server follows when deciding whether to allow a
+ * new stream to a given IP address and TCP port.
+ *
+ * @since 1.0.0
+ */
public List<String> getExitPolicyLines();
- /* Return the signature of the PKCS1-padded server descriptor digest, or
- * null if the descriptor doesn't contain a signature (which is the case
- * in sanitized bridge descriptors). */
+ /**
+ * Return the RSA-1024 signature of the PKCS1-padded descriptor digest,
+ * taken from the beginning of the router line through the newline after
+ * the router-signature line, or null if the descriptor doesn't contain
+ * a signature (which is the case in sanitized bridge descriptors).
+ *
+ * @since 1.0.0
+ */
public String getRouterSignature();
- /* Return the contact information for this relay, or null if no contact
- * information is included in the descriptor. */
+ /**
+ * Return the contact information for this server, which may contain
+ * non-ASCII characters, or null if no contact information is included
+ * in the descriptor.
+ *
+ * @since 1.0.0
+ */
public String getContact();
- /* Return nicknames, ($-prefixed) fingerprints, $fingerprint=nickname,
- * or $fingerprint~nickname tuples contained in the family line of this
- * relay, or null if the descriptor does not contain a family line. */
+ /**
+ * Return nicknames, $-prefixed identity fingerprints, or tuples of the
+ * format {@code $fingerprint=nickname} or {@code $fingerprint~nickname}
+ * of servers contained in this server's family, or null if the
+ * descriptor does not contain a family line.
+ *
+ * @since 1.0.0
+ */
public List<String> getFamilyEntries();
- /* Return the relay's read history. (Current Tor versions include their
- * bandwidth histories in their extra-info descriptors, not in their
- * server descriptors.) */
+ /**
+ * Return the server's history of read bytes, or null if the descriptor
+ * does not contain a bandwidth history; current Tor versions include
+ * bandwidth histories in their extra-info descriptors
+ * ({@link ExtraInfoDescriptor#getReadHistory()}), not in their server
+ * descriptors.
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getReadHistory();
- /* Return the relay's write history. (Current Tor versions include
- * their bandwidth histories in their extra-info descriptors, not in
- * their server descriptors.) */
+ /**
+ * Return the server's history of written bytes, or null if the
+ * descriptor does not contain a bandwidth history; current Tor versions
+ * include bandwidth histories in their extra-info descriptors
+ * ({@link ExtraInfoDescriptor#getWriteHistory()}), not in their server
+ * descriptors.
+ *
+ * @since 1.0.0
+ */
public BandwidthHistory getWriteHistory();
- /* Return true if the relay uses the enhanced DNS logic, or false if
+ /**
+ * Return true if the server uses the enhanced DNS logic, or false if
* doesn't use it or doesn't include an eventdns line in its
- * descriptor. */
+ * descriptor; current Tor versions should be presumed to have the evdns
+ * backend.
+ *
+ * @since 1.0.0
+ */
public boolean getUsesEnhancedDnsLogic();
- /* Return whether this relay is a directory cache that provides
- * extra-info descriptors. */
+ /**
+ * Return whether this server is a directory cache that provides
+ * extra-info descriptors.
+ *
+ * @since 1.0.0
+ */
public boolean getCachesExtraInfo();
- /* Return the digest of the relay's extra-info descriptor, or null if
- * the relay did not upload a corresponding extra-info descriptor. */
+ /**
+ * Return the SHA-1 digest of the server's extra-info descriptor,
+ * encoded as 40 upper-case hexadecimal characters, or null if the
+ * server did not upload a corresponding extra-info descriptor.
+ *
+ * @since 1.0.0
+ */
public String getExtraInfoDigest();
- /* Return the base64-encoded SHA-256 digest of the extra-info descriptor
- * referenced from this server descriptor, or null if the relay either
- * did not upload a corresponding extra-info descriptor or did not refer
- * to it using a SHA-256 digest. */
+ /**
+ * Return the SHA-256 digest of the server's extra-info descriptor,
+ * encoded as 43 base64 characters without padding characters, or null
+ * if the server either did not upload a corresponding extra-info
+ * descriptor or did not refer to it using a SHA-256 digest.
+ *
+ * @since 1.1.0
+ */
public String getExtraInfoDigestSha256();
- /* Return the hidden service descriptor version(s) that this relay
- * stores and serves, or null if it doesn't store and serve any hidden
- * service descriptors. */
+ /**
+ * Return the list of hidden service descriptor version numbers that
+ * this server stores and serves, or null if it doesn't store and serve
+ * any hidden service descriptors.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getHiddenServiceDirVersions();
- /* Return the list of link protocol versions that this relay
- * supports. */
+ /**
+ * Return the list of link protocol versions that this server
+ * supports.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getLinkProtocolVersions();
- /* Return the list of circuit protocol versions that this relay
- * supports. */
+ /**
+ * Return the list of circuit protocol versions that this server
+ * supports.
+ *
+ * @since 1.0.0
+ */
public List<Integer> getCircuitProtocolVersions();
- /* Return whether this relay allows single-hop circuits to make exit
- * connections. */
+ /**
+ * Return whether this server allows single-hop circuits to make exit
+ * connections.
+ *
+ * @since 1.0.0
+ */
public boolean getAllowSingleHopExits();
- /* Return the default policy of the IPv6 port summary or null if the
- * server descriptor didn't contain an IPv6 port summary line. */
+ /**
+ * Return the default policy, {@code "accept"} or {@code "reject"}, of
+ * the IPv6 port summary, or null if the descriptor didn't contain an
+ * IPv6 exit-policy summary line which is equivalent to rejecting all
+ * streams to IPv6 targets.
+ *
+ * @since 1.0.0
+ */
public String getIpv6DefaultPolicy();
- /* Return the port list of the IPv6 port summary or null if the server
- * descriptor didn't contain an IPv6 port summary line. */
+ /**
+ * Return the port list of the IPv6 exit-policy summary, or null if the
+ * descriptor didn't contain an IPv6 exit-policy summary line which is
+ * equivalent to rejecting all streams to IPv6 targets.
+ *
+ * @since 1.0.0
+ */
public String getIpv6PortList();
- /* Return the ntor onion key base64 string with padding omitted, or null
- * if the server descriptors didn't contain an ntor onion key line. */
+ /**
+ * Return the curve25519 public key, encoded as 43 base64 characters
+ * without padding characters, that is used for the ntor circuit
+ * extended handshake, or null if the descriptor didn't contain an
+ * ntor-onion-key line. */
public String getNtorOnionKey();
- /* Return the base64-encoded Ed25519 certificate, or null if the
- * descriptor doesn't contain one. */
+ /**
+ * Return the Ed25519 certificate in PEM format, or null if the
+ * descriptor doesn't contain one.
+ *
+ * @since 1.1.0
+ */
public String getIdentityEd25519();
- /* Return the base64-encoded Ed25519 master key, which may either be
- * parsed from the optional "master-key-ed25519" line or derived from
- * the (likewise optional) Ed25519 certificate following the
- * "identity-ed25519" line, or null if the descriptor contains neither
- * Ed25519 master key nor Ed25519 certificate. */
+ /**
+ * Return the Ed25519 master key, encoded as 43 base64 characters
+ * without padding characters, which was either parsed from the optional
+ * {@code "master-key-ed25519"} line or derived from the (likewise
+ * optional) Ed25519 certificate following the
+ * {@code "identity-ed25519"} line, or null if the descriptor contains
+ * neither Ed25519 master key nor Ed25519 certificate.
+ *
+ * @since 1.1.0
+ */
public String getMasterKeyEd25519();
- /* Return the base64-encoded Ed25519 signature of a SHA-256 digest of
- * the entire descriptor, from the first character up to and including
- * the first space after the "router-sig-ed25519" string, prefixed with
- * the string "Tor router descriptor signature v1". */
+ /**
+ * Return the Ed25519 signature of the SHA-256 digest of the entire
+ * descriptor, encoded as 86 base64 characters without padding
+ * characters, from the first character up to and including the first
+ * space after the {@code "router-sig-ed25519"} string, prefixed with
+ * the string {@code "Tor router descriptor signature v1"}.
+ *
+ * @since 1.1.0
+ */
public String getRouterSignatureEd25519();
- /* Return an RSA signature, generated using the onion-key, that proves
- * that the party creating the descriptor had control over the secret
- * key corresponding to the onion-key, or null if the descriptor does
- * not contain such a signature. */
+ /**
+ * Return an RSA-1024 signature in PEM format, generated using the
+ * server's onion key, that proves that the party creating the
+ * descriptor had control over the private key corresponding to the
+ * onion key, or null if the descriptor does not contain such a
+ * signature.
+ *
+ * @since 1.1.0
+ */
public String getOnionKeyCrosscert();
- /* Return an Ed25519 signature, generated using the ntor-onion-key, that
- * proves that the party creating the descriptor had control over the
- * secret key corresponding to the ntor-onion-key, or null if the
- * descriptor does not contain such a signature. */
+ /**
+ * Return an Ed25519 signature in PEM format, generated using the
+ * server's ntor onion key, that proves that the party creating the
+ * descriptor had control over the private key corresponding to the ntor
+ * onion key, or null if the descriptor does not contain such a
+ * signature.
+ *
+ * @since 1.1.0
+ */
public String getNtorOnionKeyCrosscert();
- /* Return the sign of the Ed25519 public key corresponding to the ntor
+ /**
+ * Return the sign of the Ed25519 public key corresponding to the ntor
* onion key as 0 or 1, or -1 if the descriptor does not contain this
- * information. */
+ * information.
+ *
+ * @since 1.1.0
+ */
public int getNtorOnionKeyCrosscertSign();
}
diff --git a/src/org/torproject/descriptor/TorperfResult.java b/src/org/torproject/descriptor/TorperfResult.java
index 9c47a61..188200b 100644
--- a/src/org/torproject/descriptor/TorperfResult.java
+++ b/src/org/torproject/descriptor/TorperfResult.java
@@ -1,97 +1,215 @@
/* Copyright 2012--2016 The Tor Project
* See LICENSE for licensing information */
+
package org.torproject.descriptor;
import java.util.List;
import java.util.SortedMap;
+/**
+ * Contains performance measurement results from making simple HTTP
+ * requests over the Tor network.
+ *
+ * <p>The performance measurement service Torperf publishes performance
+ * data from making simple HTTP requests over the Tor network. Torperf
+ * uses a trivial SOCKS client to download files of various sizes over the
+ * Tor network and notes how long substeps take.</p>
+ *
+ * @since 1.0.0
+ */
public interface TorperfResult extends Descriptor {
- /* Return all unrecognized keys together with their values, or null if
- * all keys were recognized. */
+ /**
+ * Return all unrecognized keys together with their values, or null if
+ * all keys were recognized.
+ *
+ * @since 1.2.0
+ */
public SortedMap<String, String> getUnrecognizedKeys();
- /* Return the configured name of the data source. */
+ /**
+ * Return the configured name of the data source.
+ *
+ * @since 1.0.0
+ */
public String getSource();
- /* Return the configured file size in bytes. */
+ /**
+ * Return the configured file size in bytes.
+ *
+ * @since 1.0.0
+ */
public int getFileSize();
- /* Return the time when the connection process starts. */
+ /**
+ * Return the time in milliseconds since the epoch when the connection
+ * process started.
+ *
+ * @since 1.0.0
+ */
public long getStartMillis();
- /* Return the time when the socket was created. */
+ /**
+ * Return the time in milliseconds since the epoch when the socket was
+ * created.
+ *
+ * @since 1.0.0
+ */
public long getSocketMillis();
- /* Return the time when the socket was connected. */
+ /**
+ * Return the time in milliseconds since the epoch when the socket was
+ * connected.
+ *
+ * @since 1.0.0
+ */
public long getConnectMillis();
- /* Return the time when SOCKS 5 authentication methods have been
- * negotiated. */
+ /**
+ * Return the time in milliseconds since the epoch when SOCKS 5
+ * authentication methods have been negotiated.
+ *
+ * @since 1.0.0
+ */
public long getNegotiateMillis();
- /* Return the time when the SOCKS request was sent. */
+ /**
+ * Return the time in milliseconds since the epoch when the SOCKS
+ * request was sent.
+ *
+ * @since 1.0.0
+ */
public long getRequestMillis();
- /* Return the time when the SOCKS response was received. */
+ /**
+ * Return the time in milliseconds since the epoch when the SOCKS
+ * response was received.
+ *
+ * @since 1.0.0
+ */
public long getResponseMillis();
- /* Return the time when the HTTP request was written. */
+ /**
+ * Return the time in milliseconds since the epoch when the HTTP
+ * request was written.
+ *
+ * @since 1.0.0
+ */
public long getDataRequestMillis();
- /* Return the time when the first response was received. */
+ /**
+ * Return the time in milliseconds since the epoch when the first
+ * response was received.
+ *
+ * @since 1.0.0
+ */
public long getDataResponseMillis();
- /* Return the time when the payload was complete. */
+ /**
+ * Return the time in milliseconds since the epoch when the payload was
+ * complete.
+ *
+ * @since 1.0.0
+ */
public long getDataCompleteMillis();
- /* Return the total number of bytes written. */
+ /**
+ * Return the total number of bytes written.
+ *
+ * @since 1.0.0
+ */
public int getWriteBytes();
- /* Return the total number of bytes read. */
+ /**
+ * Return the total number of bytes read.
+ *
+ * @since 1.0.0
+ */
public int getReadBytes();
- /* Return whether the request timed out (as opposed to failing), or null
- * if the torperf line didn't contain that information. */
+ /**
+ * Return whether the request timed out (as opposed to failing), or
+ * null if the torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public Boolean didTimeout();
- /* Return the times when x% of expected bytes were read for
- * 0 <= x <= 100, or null if the torperf line didn't contain that
- * information. */
+ /**
+ * Return the times in milliseconds since the epoch when {@code x%} of
+ * expected bytes were read for {@code 0 <= x <= 100}, or null if the
+ * torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public SortedMap<Integer, Long> getDataPercentiles();
- /* Return the time when the circuit was launched, or -1 if the torperf
- * line didn't contain that information. */
+ /**
+ * Return the time in milliseconds since the epoch when the circuit was
+ * launched, or -1 if the torperf line didn't contain that
+ * information.
+ *
+ * @since 1.0.0
+ */
public long getLaunchMillis();
- /* Return the time when the circuit was used, or -1 if the torperf line
- * didn't contain that information. */
+ /**
+ * Return the time in milliseconds since the epoch when the circuit was
+ * used, or -1 if the torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public long getUsedAtMillis();
- /* Return a list of fingerprints of the relays in the circuit, or null
- * if the torperf line didn't contain that information. */
+ /**
+ * Return a list of fingerprints of the relays in the circuit, or null
+ * if the torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public List<String> getPath();
- /* Return a list of times in millis when circuit hops were built, or
- * null if the torperf line didn't contain that information. */
+ /**
+ * Return a list of times in milliseconds since the epoch when circuit
+ * hops were built, or null if the torperf line didn't contain that
+ * information.
+ *
+ * @since 1.0.0
+ */
public List<Long> getBuildTimes();
- /* Return the circuit build timeout that the Tor client used when
+ /**
+ * Return the circuit build timeout that the Tor client used when
* building this circuit, or -1 if the torperf line didn't contain that
- * information. */
+ * information.
+ *
+ * @since 1.0.0
+ */
public long getTimeout();
- /* Return the circuit build time quantile that the Tor client uses to
- * determine its circuit-build timeout, or -1.0 if the torperf line
- * didn't contain that information. */
+ /**
+ * Return the circuit build time quantile that the Tor client uses to
+ * determine its circuit-build timeout, or -1 if the torperf line
+ * didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public double getQuantile();
- /* Return the identifier of the circuit used for this measurement, or -1
- * if the torperf line didn't contain that information. */
+ /**
+ * Return the identifier of the circuit used for this measurement, or
+ * -1 if the torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public int getCircId();
- /* Return the identifier of the stream used for this measurement, or -1
- * if the torperf line didn't contain that information. */
+ /**
+ * Return the identifier of the stream used for this measurement, or -1
+ * if the torperf line didn't contain that information.
+ *
+ * @since 1.0.0
+ */
public int getUsedBy();
}
diff --git a/src/org/torproject/descriptor/package-info.java b/src/org/torproject/descriptor/package-info.java
new file mode 100644
index 0000000..5b34554
--- /dev/null
+++ b/src/org/torproject/descriptor/package-info.java
@@ -0,0 +1,80 @@
+/* Copyright 2016 The Tor Project
+ * See LICENSE for licensing information */
+
+/**
+ * Interfaces and essential classes for obtaining and processing Tor
+ * descriptors.
+ *
+ * <p>This package contains all relevant interfaces and
+ * classes that an application would need to use this library.
+ * Applications are strongly discouraged from accessing types from the
+ * implementation package ({@code org.torproject.descriptor.impl})
+ * directly, because those may change without prior notice.</p>
+ *
+ * <p>Interfaces and classes in this package can be grouped into
+ * general-purpose types to obtain and process any type of descriptor and
+ * descriptors produced by different components of the Tor network:</p>
+ *
+ * <ol>
+ * <li>General-purpose types comprise
+ * {@link org.torproject.descriptor.DescriptorSourceFactory} which is the
+ * main entry point into using this library. This factory is used to
+ * create the descriptor sources for obtaining remote descriptor data
+ * ({@link org.torproject.descriptor.DescriptorDownloader} and
+ * {@link org.torproject.descriptor.DescriptorCollector}) and descriptor
+ * sources for processing local descriptor data
+ * ({@link org.torproject.descriptor.DescriptorReader} and
+ * {@link org.torproject.descriptor.DescriptorParser}). General-purpose
+ * types also include descriptor containers
+ * ({@link org.torproject.descriptor.DescriptorRequest} and
+ * {@link org.torproject.descriptor.DescriptorFile}) and the
+ * superinterface for all provided descriptors
+ * ({@link org.torproject.descriptor.Descriptor}).</li>
+ *
+ * <li>The first group of descriptors is published by relays and servers
+ * in the Tor network. These interfaces include server descriptors
+ * ({@link org.torproject.descriptor.ServerDescriptor} with subinterfaces
+ * {@link org.torproject.descriptor.RelayServerDescriptor} and
+ * {@link org.torproject.descriptor.BridgeServerDescriptor}), extra-info
+ * descriptors ({@link org.torproject.descriptor.ExtraInfoDescriptor} with
+ * subinterfaces
+ * {@link org.torproject.descriptor.RelayExtraInfoDescriptor} and
+ * {@link org.torproject.descriptor.BridgeExtraInfoDescriptor}),
+ * microdescriptors which are derived from server descriptors by the
+ * directory authorities
+ * ({@link org.torproject.descriptor.Microdescriptor}), and helper types
+ * for parts of the aforementioned descriptors
+ * ({@link org.torproject.descriptor.BandwidthHistory}).</li>
+ *
+ * <li>The second group of descriptors is generated by authoritative
+ * directory servers that form an opinion about relays and bridges in the
+ * Tor network. These include descriptors specified in version 3 of the
+ * directory protocol
+ * ({@link org.torproject.descriptor.RelayNetworkStatusConsensus},
+ * {@link org.torproject.descriptor.RelayNetworkStatusVote},
+ * {@link org.torproject.descriptor.DirectoryKeyCertificate}, and helper
+ * types for descriptor parts
+ * {@link org.torproject.descriptor.DirSourceEntry},
+ * {@link org.torproject.descriptor.NetworkStatusEntry}, and
+ * {@link org.torproject.descriptor.DirectorySignature}), descriptors from
+ * earlier directory protocol version 2
+ * ({@link org.torproject.descriptor.RelayNetworkStatus}) and version 1
+ * ({@link org.torproject.descriptor.RelayDirectory} and
+ * {@link org.torproject.descriptor.RouterStatusEntry}), as well as
+ * descriptors published by the bridge authority and sanitized by the
+ * CollecTor service
+ * ({@link org.torproject.descriptor.BridgeNetworkStatus}).</li>
+ *
+ * <li>The third group of descriptors is created by auxiliary services
+ * connected to the Tor network rather than by the Tor software. This
+ * group comprises descriptors by the bridge distribution service BridgeDB
+ * ({@link org.torproject.descriptor.BridgePoolAssignment}), the exit list
+ * service TorDNSEL ({@link org.torproject.descriptor.ExitList}), and the
+ * performance measurement service Torperf
+ * ({@link org.torproject.descriptor.TorperfResult}).</li>
+ * </ol>
+ *
+ * @since 1.0.0
+ */
+package org.torproject.descriptor;
+
More information about the tor-commits
mailing list