Add tutorial link and examples.

README.md

@@ -89,3 +89,11 @@ jarsigner -verify descriptor-1.0.0.jar
 jarsigner -verify descriptor-1.0.0-sources.jar
 ```
 
+
+Tutorial
+--------
+
+The Metrics website has a tutorial for getting started with metrics-lib:
+
+https://metrics.torproject.org/metrics-lib.html
+

src/main/resources/examples/ConsensusWeightByVersion.java

@@ -0,0 +1,62 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+import java.util.*;
+
+public class ConsensusWeightByVersion {
+  public static void main(String[] args) {
+
+    // Download consensuses.
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors("https://collector.torproject.org", new String[] { "/recent/relay-descriptors/consensuses/" }, 0L, new File("descriptors"), false);
+
+    // Keep local counters for extracted descriptor data.
+    long totalBandwidth = 0L;
+    SortedMap<String, Long> bandwidthByVersion = new TreeMap<>();
+
+    // Read descriptors from disk.
+    DescriptorReader descriptorReader = DescriptorSourceFactory.createDescriptorReader();
+
+    // Add the directory with descriptors to the descriptor reader.
+    descriptorReader.addDirectory(new File("descriptors/recent/relay-descriptors/consensuses"));
+    Iterator<DescriptorFile> descriptorFiles = descriptorReader.readDescriptors();
+    while (descriptorFiles.hasNext()) { // Iterate over all descriptor files found.
+      DescriptorFile descriptorFile = descriptorFiles.next();
+
+      // Now, iterate over the descriptors contained in the file.
+      for (Descriptor descriptor : descriptorFile.getDescriptors()) {
+        if (!(descriptor instanceof RelayNetworkStatusConsensus)) {
+          // We're only interested in consensuses.
+          continue;
+        }
+        RelayNetworkStatusConsensus consensus = (RelayNetworkStatusConsensus) descriptor;
+        for (NetworkStatusEntry entry : consensus.getStatusEntries().values()) {
+          String version = entry.getVersion();
+          if (!version.startsWith("Tor ") || version.length() < 9) {
+            // We're only interested in a.b.c type versions for this example.
+            continue;
+          }
+          // Remove the 'Tor ' prefix and anything starting at the patch level.
+          version = version.substring(4, 9);
+          long bandwidth = entry.getBandwidth();
+          totalBandwidth += bandwidth;
+          if (bandwidthByVersion.containsKey(version)) {
+            bandwidthByVersion.put(version, bandwidth + bandwidthByVersion.get(version));
+          } else {
+            bandwidthByVersion.put(version, bandwidth);
+          }
+        }
+      }
+    }
+
+    // Print out fractions of consensus weight by Tor version.
+    if (totalBandwidth > 0L) {
+      for (Map.Entry<String, Long> e : bandwidthByVersion.entrySet()) {
+        System.out.printf("%s -> %4.1f%%%n", e.getKey(), (100.0 * (double) e.getValue() / (double) totalBandwidth));
+      }
+    }
+  }
+}

src/main/resources/examples/DownloadConsensuses.java

@@ -0,0 +1,25 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+
+public class DownloadConsensuses {
+  public static void main(String[] args) {
+
+    // Download consensuses published in the last 72 hours, which will take up to five minutes and require several hundred MB on the local disk.
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors(
+        // Download from Tor's main CollecTor instance,
+        "https://collector.torproject.org",
+        // include only network status consensuses
+        new String[] { "/recent/relay-descriptors/consensuses/" },
+        // regardless of last-modified time,
+        0L,
+        // write to the local directory called descriptors/,
+        new File("descriptors"),
+        // and don't delete extraneous files that do not exist remotely anymore.
+        false);
+  }
+}

src/main/resources/examples/PluggableTransports.java

@@ -0,0 +1,48 @@
+/* Copyright 2017 The Tor Project
+ * See LICENSE for licensing information */
+
+import org.torproject.descriptor.*;
+
+import java.io.File;
+import java.util.*;
+
+public class PluggableTransports {
+  public static void main(String[] args) {
+
+    DescriptorCollector descriptorCollector = DescriptorSourceFactory.createDescriptorCollector();
+    descriptorCollector.collectDescriptors("https://collector.torproject.org", new String[] { "/recent/bridge-descriptors/extra-infos/" }, 0L, new File("descriptors"), false);
+
+    Set<String> observedFingerprints = new HashSet<>();
+    SortedMap<String, Integer> countedTransports = new TreeMap<>();
+
+    DescriptorReader descriptorReader = DescriptorSourceFactory.createDescriptorReader();
+    descriptorReader.addDirectory(new File("descriptors/recent/bridge-descriptors/extra-infos"));
+    Iterator<DescriptorFile> descriptorFiles = descriptorReader.readDescriptors();
+    while (descriptorFiles.hasNext()) {
+      DescriptorFile descriptorFile = descriptorFiles.next();
+      for (Descriptor descriptor : descriptorFile.getDescriptors()) {
+        if (!(descriptor instanceof BridgeExtraInfoDescriptor)) {
+          continue;
+        }
+        BridgeExtraInfoDescriptor extraInfo = (BridgeExtraInfoDescriptor) descriptor;
+        String fingerprint = extraInfo.getFingerprint();
+        if (observedFingerprints.add(fingerprint)) {
+          for (String transport : extraInfo.getTransports()) {
+            if (countedTransports.containsKey(transport)) {
+              countedTransports.put(transport, 1 + countedTransports.get(transport));
+            } else {
+              countedTransports.put(transport, 1);
+            }
+          }
+        }
+      }
+    }
+
+    if (!observedFingerprints.isEmpty()) {
+      double totalObservedFingerprints = observedFingerprints.size();
+      for (Map.Entry<String, Integer> e : countedTransports.entrySet()) {
+        System.out.printf("%20s -> %4.1f%%%n", e.getKey(), (100.0 * (double) e.getValue() / totalObservedFingerprints));
+      }
+    }
+  }
+}