[tor-commits] [onionoo/master] Resolve all remaining Javadoc-related checkstyle issues.

commit c51516bd5044b4b59c24c3cfe6bddc8d9882e018 Author: Karsten Loesing karsten.loesing@gmx.net Date: Tue Jul 19 10:11:02 2016 +0200

Resolve all remaining Javadoc-related checkstyle issues.

Resolve very few of these warnings by suppressing them, in particular getters and setters that happen to contain more than 2 lines of code, because we should either document all or none of them.

Implements more of #19613. --- build.xml | 13 ++++++++++++ .../java/org/torproject/onionoo/cron/Main.java | 3 +++ .../torproject/onionoo/docs/BandwidthStatus.java | 2 ++ .../torproject/onionoo/docs/ClientsHistory.java | 12 +++++++++++ .../org/torproject/onionoo/docs/ClientsStatus.java | 6 ++++++ .../torproject/onionoo/docs/DateTimeHelper.java | 6 ++++++ .../torproject/onionoo/docs/DetailsDocument.java | 8 ++++++++ .../org/torproject/onionoo/docs/DetailsStatus.java | 3 +++ .../org/torproject/onionoo/docs/DocumentStore.java | 13 ++++++++++++ .../onionoo/docs/DocumentStoreFactory.java | 5 +++++ .../org/torproject/onionoo/docs/NodeStatus.java | 23 ++++++++++++++++++++++ .../torproject/onionoo/docs/SummaryDocument.java | 13 ++++++++++++ .../org/torproject/onionoo/docs/UpdateStatus.java | 2 ++ .../org/torproject/onionoo/docs/UptimeHistory.java | 12 +++++++++++ .../org/torproject/onionoo/docs/UptimeStatus.java | 6 ++++++ .../org/torproject/onionoo/docs/WeightsStatus.java | 6 ++++++ .../org/torproject/onionoo/server/NodeIndexer.java | 12 +++++++++++ .../onionoo/server/NodeIndexerFactory.java | 5 +++++ .../onionoo/server/PerformanceMetrics.java | 6 ++++++ .../torproject/onionoo/server/RequestHandler.java | 4 ++++ .../torproject/onionoo/server/ResourceServlet.java | 6 ++++++ .../org/torproject/onionoo/server/ServerMain.java | 1 + .../onionoo/updater/BandwidthStatusUpdater.java | 6 ++++++ .../onionoo/updater/ClientsStatusUpdater.java | 6 ++++++ .../onionoo/updater/DescriptorSource.java | 10 ++++++++++ .../onionoo/updater/DescriptorSourceFactory.java | 5 +++++ .../torproject/onionoo/updater/LookupService.java | 5 +++++ .../onionoo/updater/NodeDetailsStatusUpdater.java | 6 ++++++ .../onionoo/updater/RdnsLookupRequest.java | 1 + .../onionoo/updater/RdnsLookupWorker.java | 1 + .../onionoo/updater/ReverseDomainNameResolver.java | 9 +++++++++ .../onionoo/updater/StatusUpdateRunner.java | 4 ++++ .../onionoo/updater/UptimeStatusUpdater.java | 6 ++++++ .../onionoo/updater/WeightsStatusUpdater.java | 6 ++++++ .../torproject/onionoo/util/FormattingUtils.java | 5 +++++ .../org/torproject/onionoo/util/TimeFactory.java | 5 +++++ .../onionoo/writer/BandwidthDocumentWriter.java | 2 ++ .../onionoo/writer/ClientsDocumentWriter.java | 2 ++ .../onionoo/writer/DetailsDocumentWriter.java | 2 ++ .../onionoo/writer/DocumentWriterRunner.java | 4 ++++ .../onionoo/writer/SummaryDocumentWriter.java | 2 ++ .../onionoo/writer/UptimeDocumentWriter.java | 2 ++ .../onionoo/writer/WeightsDocumentWriter.java | 2 ++ src/test/resources/metrics_checks.xml | 2 ++ 44 files changed, 260 insertions(+)

diff --git a/build.xml b/build.xml index 1688207..f7f6bc0 100644 --- a/build.xml +++ b/build.xml @@ -10,6 +10,7 @@ <property name="classes" value="classes"/> <property name="testresources" value="src/test/resources/"/> <property name="dist" value="dist"/> + <property name="docs" value="${generated}/javadoc/"/> <property name="libs" value="lib"/> <property name="config" value="etc"/> <property name="webxmlfile" value="${config}/web.xml"/> @@ -85,6 +86,7 @@ <copy file="${contextxmltemplate}" tofile="${contextxml}"/> <copy file="${webxmltemplate}" tofile="${webxml}"/> <mkdir dir="${classes}"/> + <mkdir dir="${docs}"/> <mkdir dir="${dist}"/> <mkdir dir="${generated}"/> </target> @@ -111,6 +113,17 @@ </javac> </target>

+ <target name="docs" depends="init"> + <javadoc destdir="${docs}" + footer="&amp;copy; 2016 The Tor Project" + doctitle="Onionoo Documentation" + use="true" + windowtitle="Onionoo Documentation"> + <classpath refid="classpath"/> + <fileset dir="${javasources}/" includes="**/*.java" /> + </javadoc> + </target> + <target name="test" depends="compile"> <javac destdir="${classes}" srcdir="${tests}" diff --git a/src/main/java/org/torproject/onionoo/cron/Main.java b/src/main/java/org/torproject/onionoo/cron/Main.java index 4a57f66..04b6955 100644 --- a/src/main/java/org/torproject/onionoo/cron/Main.java +++ b/src/main/java/org/torproject/onionoo/cron/Main.java @@ -28,6 +28,8 @@ public class Main implements Runnable {

private Logger log = LoggerFactory.getLogger(Main.class);

+ /** Executes a single update run or partial update run, or initiates + * hourly executions, depending on the given command-line arguments. */ public static void main(String[] args) { Main main = new Main(); main.parseArgsOrExit(args); @@ -121,6 +123,7 @@ public class Main implements Runnable { TimeUnit.MINUTES); }

+ @Override public void run() { this.acquireLockOrExit(); this.initialize(); diff --git a/src/main/java/org/torproject/onionoo/docs/BandwidthStatus.java b/src/main/java/org/torproject/onionoo/docs/BandwidthStatus.java index 65d4cf5..ac7085f 100644 --- a/src/main/java/org/torproject/onionoo/docs/BandwidthStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/BandwidthStatus.java @@ -51,6 +51,7 @@ public class BandwidthStatus extends Document { return this.readHistory; }

+ @Override public void setFromDocumentString(String documentString) { try (Scanner s = new Scanner(documentString)) { while (s.hasNextLine()) { @@ -170,6 +171,7 @@ public class BandwidthStatus extends Document { } }

+ @Override public String toDocumentString() { StringBuilder sb = new StringBuilder(); for (long[] v : writeHistory.values()) { diff --git a/src/main/java/org/torproject/onionoo/docs/ClientsHistory.java b/src/main/java/org/torproject/onionoo/docs/ClientsHistory.java index 0f4c148..e99c3ef 100644 --- a/src/main/java/org/torproject/onionoo/docs/ClientsHistory.java +++ b/src/main/java/org/torproject/onionoo/docs/ClientsHistory.java @@ -51,6 +51,9 @@ public class ClientsHistory implements Comparable<ClientsHistory> { return this.responsesByVersion; }

+ /** Instantiates a new clients history object with given interval start + * and end, total responses, and responses by country, transport, and + * version. */ public ClientsHistory(long startMillis, long endMillis, double totalResponses, SortedMap<String, Double> responsesByCountry, @@ -64,6 +67,8 @@ public class ClientsHistory implements Comparable<ClientsHistory> { this.responsesByVersion = responsesByVersion; }

+ /** Instantiates a new clients history object from the given string that + * may have been produced by {@link #toString()}. */ public static ClientsHistory fromString( String responseHistoryString) { String[] parts = responseHistoryString.split(" ", 8); @@ -133,6 +138,7 @@ public class ClientsHistory implements Comparable<ClientsHistory> { return responses; }

+ @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append(DateTimeHelper.format(startMillis)); @@ -154,6 +160,9 @@ public class ClientsHistory implements Comparable<ClientsHistory> { } }

+ /** Adds responses from another clients history object to this one by + * summing up response numbers and extending interval start and/or + * end. */ public void addResponses(ClientsHistory other) { this.totalResponses += other.totalResponses; this.addResponsesByCategory(this.responsesByCountry, @@ -183,16 +192,19 @@ public class ClientsHistory implements Comparable<ClientsHistory> { } }

+ @Override public int compareTo(ClientsHistory other) { return this.startMillis < other.startMillis ? -1 : this.startMillis > other.startMillis ? 1 : 0; }

+ @Override public boolean equals(Object other) { return other instanceof ClientsHistory && this.startMillis == ((ClientsHistory) other).startMillis; }

+ @Override public int hashCode() { return (int) this.startMillis; } diff --git a/src/main/java/org/torproject/onionoo/docs/ClientsStatus.java b/src/main/java/org/torproject/onionoo/docs/ClientsStatus.java index 4ef998e..45466ae 100644 --- a/src/main/java/org/torproject/onionoo/docs/ClientsStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/ClientsStatus.java @@ -38,6 +38,7 @@ public class ClientsStatus extends Document { return this.history; }

+ @Override public void setFromDocumentString(String documentString) { try (Scanner s = new Scanner(documentString)) { while (s.hasNextLine()) { @@ -53,6 +54,8 @@ public class ClientsStatus extends Document { } }

+ /** Adds all given clients history objects that don't overlap with + * existing clients history objects. */ public void addToHistory(SortedSet<ClientsHistory> newIntervals) { for (ClientsHistory interval : newIntervals) { if ((this.history.headSet(interval).isEmpty() @@ -67,6 +70,8 @@ public class ClientsStatus extends Document { } }

+ /** Compresses the history of clients objects by merging adjacent + * intervals, depending on how far back in the past they lie. */ public void compressHistory() { SortedSet<ClientsHistory> uncompressedHistory = new TreeSet<ClientsHistory>(this.history); @@ -107,6 +112,7 @@ public class ClientsStatus extends Document { } }

+ @Override public String toDocumentString() { StringBuilder sb = new StringBuilder(); for (ClientsHistory interval : this.history) { diff --git a/src/main/java/org/torproject/onionoo/docs/DateTimeHelper.java b/src/main/java/org/torproject/onionoo/docs/DateTimeHelper.java index 4e422e9..1dc40c3 100644 --- a/src/main/java/org/torproject/onionoo/docs/DateTimeHelper.java +++ b/src/main/java/org/torproject/onionoo/docs/DateTimeHelper.java @@ -109,6 +109,9 @@ public class DateTimeHelper { return format(millis, ISO_DATETIME_FORMAT); }

+ /** Parses the given string using the given format and return the time + * in milliseconds since the epoch or {@link #NO_TIME_AVAILABLE} if the + * string cannot be parsed. */ public static long parse(String string, String format) { if (null == string) { log.warn("Date String was null."); @@ -122,6 +125,9 @@ public class DateTimeHelper { } }

+ /** Parses the given string using {@link #ISO_DATETIME_FORMAT} as format + * and return the time in milliseconds since the epoch or + * {@link #NO_TIME_AVAILABLE} if the string cannot be parsed. */ public static long parse(String string) { return parse(string, ISO_DATETIME_FORMAT); } diff --git a/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java b/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java index 8ffb358..85c0154 100644 --- a/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java +++ b/src/main/java/org/torproject/onionoo/docs/DetailsDocument.java @@ -377,6 +377,8 @@ public class DetailsDocument extends Document {

private Float consensus_weight_fraction;

+ /** Sets the consensus weight fraction to the given value, but only if + * that value is neither null nor negative. */ public void setConsensusWeightFraction(Float consensusWeightFraction) { if (consensusWeightFraction == null || consensusWeightFraction >= 0.0) { @@ -390,6 +392,8 @@ public class DetailsDocument extends Document {

private Float guard_probability;

+ /** Sets the guard probability to the given value, but only if that + * value is neither null nor negative. */ public void setGuardProbability(Float guardProbability) { if (guardProbability == null || guardProbability >= 0.0) { this.guard_probability = guardProbability; @@ -402,6 +406,8 @@ public class DetailsDocument extends Document {

private Float middle_probability;

+ /** Sets the middle probability to the given value, but only if that + * value is neither null nor negative. */ public void setMiddleProbability(Float middleProbability) { if (middleProbability == null || middleProbability >= 0.0) { this.middle_probability = middleProbability; @@ -414,6 +420,8 @@ public class DetailsDocument extends Document {

private Float exit_probability;

+ /** Sets the exit probability to the given value, but only if that + * value is neither null nor negative. */ public void setExitProbability(Float exitProbability) { if (exitProbability == null || exitProbability >= 0.0) { this.exit_probability = exitProbability; diff --git a/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java b/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java index dcc6fcb..1a3c05d 100644 --- a/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/DetailsStatus.java @@ -250,6 +250,9 @@ public class DetailsStatus extends Document { this.or_addresses_and_ports; }

+ /** Returns all addresses used for the onion-routing protocol which + * includes the primary address and all additionally configured + * onion-routing addresses. */ public SortedSet<String> getOrAddresses() { SortedSet<String> orAddresses = new TreeSet<String>(); if (this.address != null) { diff --git a/src/main/java/org/torproject/onionoo/docs/DocumentStore.java b/src/main/java/org/torproject/onionoo/docs/DocumentStore.java index 600115c..42c75aa 100644 --- a/src/main/java/org/torproject/onionoo/docs/DocumentStore.java +++ b/src/main/java/org/torproject/onionoo/docs/DocumentStore.java @@ -97,6 +97,8 @@ public class DocumentStore { return this.list(documentType, 0L); }

+ /** Returns all fingerprints of documents of the given type that have + * been updated after the given time in milliseconds since the epoch. */ public <T extends Document> SortedSet<String> list( Class<T> documentType, long updatedAfter) { if (documentType.equals(NodeStatus.class)) { @@ -258,6 +260,8 @@ public class DocumentStore { return this.store(document, null); }

+ /** Stores the given document using the given fingerprint as + * identifier. */ public <T extends Document> boolean store(T document, String fingerprint) { if (document instanceof NodeStatus) { @@ -372,6 +376,8 @@ public class DocumentStore { return this.retrieve(documentType, parse, null); }

+ /** Retrieves the document with given type and identified by the given + * fingerprint, and either parses it or returns it unparsed. */ public <T extends Document> T retrieve(Class<T> documentType, boolean parse, String fingerprint) { if (documentType.equals(NodeStatus.class)) { @@ -576,6 +582,8 @@ public class DocumentStore { return this.remove(documentType, null); }

+ /** Removes the document with given type and identified by the given + * fingerprint. */ public <T extends Document> boolean remove(Class<T> documentType, String fingerprint) { if (documentType.equals(NodeStatus.class)) { @@ -681,6 +689,8 @@ public class DocumentStore { return documentFile; }

+ /** Writes cached node statuses, cached summary documents, and then the + * update file to disk. */ public void flushDocumentCache() { /* Write cached node statuses to disk, and write update file * containing current time. It's important to write the update file @@ -698,6 +708,8 @@ public class DocumentStore { } }

+ /** Invalidates the document cache, so that it will be freshly populated + * during the next execution. */ public void invalidateDocumentCache() { this.cachedNodeStatuses = null; this.cachedSummaryDocuments = null; @@ -810,6 +822,7 @@ public class DocumentStore { this.store(updateStatus); }

+ /** Returns a string with statistics on document storage operations. */ public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber(listOperations) diff --git a/src/main/java/org/torproject/onionoo/docs/DocumentStoreFactory.java b/src/main/java/org/torproject/onionoo/docs/DocumentStoreFactory.java index 3fa28fc..455a27f 100644 --- a/src/main/java/org/torproject/onionoo/docs/DocumentStoreFactory.java +++ b/src/main/java/org/torproject/onionoo/docs/DocumentStoreFactory.java @@ -7,10 +7,15 @@ public class DocumentStoreFactory {

private static DocumentStore documentStoreInstance;

+ /** Sets a custom singleton document store instance that will be + * returned by {@link #getDocumentStore()} rather than creating an + * instance upon first invocation. */ public static void setDocumentStore(DocumentStore documentStore) { documentStoreInstance = documentStore; }

+ /** Returns the singleton document store instance that gets created upon + * first invocation of this method. */ public static DocumentStore getDocumentStore() { if (documentStoreInstance == null) { documentStoreInstance = new DocumentStore(); diff --git a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java index 630171b..afdd6c6 100644 --- a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java @@ -29,6 +29,9 @@ public class NodeStatus extends Document {

private String contact;

+ /** Sets the contact to a lower-cased variant of the given string with + * all non-printable characters outside of ASCII code 32 (space) to 126 + * (dash) replaced with spaces. */ public void setContact(String contact) { if (contact == null) { this.contact = null; @@ -130,6 +133,9 @@ public class NodeStatus extends Document { : this.orAddressesAndPorts; }

+ /** Returns all addresses used for the onion-routing protocol which + * includes the primary address and all additionally configured + * onion-routing addresses. */ public SortedSet<String> getOrAddresses() { SortedSet<String> orAddresses = new TreeSet<String>(); if (this.address != null) { @@ -195,6 +201,7 @@ public class NodeStatus extends Document {

private BitSet relayFlags;

+ @SuppressWarnings("checkstyle:javadocmethod") public void setRelayFlags(SortedSet<String> relayFlags) { BitSet newRelayFlags = new BitSet(relayFlagIndexes.size()); for (String relayFlag : relayFlags) { @@ -207,6 +214,7 @@ public class NodeStatus extends Document { this.relayFlags = newRelayFlags; }

+ @SuppressWarnings("checkstyle:javadocmethod") public SortedSet<String> getRelayFlags() { SortedSet<String> result = new TreeSet<String>(); if (this.relayFlags != null) { @@ -255,6 +263,9 @@ public class NodeStatus extends Document { return new TreeMap<Long, Set<String>>(this.lastAddresses); }

+ /** Adds addresses and ports together with the time in milliseconds + * since the epoch when they were last seen to the history of last seen + * addresses and ports. */ public void addLastAddresses(long lastSeenMillis, String address, int orPort, int dirPort, SortedSet<String> orAddressesAndPorts) { Set<String> addressesAndPorts = new HashSet<String>(); @@ -270,6 +281,8 @@ public class NodeStatus extends Document { } }

+ /** Returns the time in milliseconds since the epoch when addresses or + * ports were last changed. */ public long getLastChangedOrAddressOrPort() { long lastChangedAddressesMillis = -1L; if (this.lastAddresses != null) { @@ -369,6 +382,9 @@ public class NodeStatus extends Document { return stringArrayToSortedSet(this.extendedFamily); }

+ /** Returns the alleged family consisting of all relays in this relay's + * declared family that are not in a mutual family relationship with + * this relay. */ public SortedSet<String> getAllegedFamily() { SortedSet<String> allegedFamily = new TreeSet<String>( stringArrayToSortedSet(this.declaredFamily)); @@ -376,6 +392,9 @@ public class NodeStatus extends Document { return allegedFamily; }

+ /** Returns the indirect family consisting of all relays that can be + * reached via mutual family relationships except for those that can be + * reached directly via such a relationship. */ public SortedSet<String> getIndirectFamily() { SortedSet<String> indirectFamily = new TreeSet<String>( stringArrayToSortedSet(this.extendedFamily)); @@ -385,10 +404,13 @@ public class NodeStatus extends Document {

/* Constructor and (de-)serialization methods: */

+ /** Instantiates a new node status object from the given fingerprint. */ public NodeStatus(String fingerprint) { this.fingerprint = fingerprint; }

+ /** Instantiates a new node status object from the given string that may + * have been produced by {@link #toString()}. */ public static NodeStatus fromString(String documentString) { try { String[] parts = documentString.trim().split("\t"); @@ -529,6 +551,7 @@ public class NodeStatus extends Document { } }

+ @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append(this.isRelay ? "r" : "b"); diff --git a/src/main/java/org/torproject/onionoo/docs/SummaryDocument.java b/src/main/java/org/torproject/onionoo/docs/SummaryDocument.java index cebcf5e..6a520c8 100644 --- a/src/main/java/org/torproject/onionoo/docs/SummaryDocument.java +++ b/src/main/java/org/torproject/onionoo/docs/SummaryDocument.java @@ -30,6 +30,9 @@ public class SummaryDocument extends Document {

private String f;

+ /** Sets the fingerprint to the given 40 hex characters and clears + * SHA1-hashed and base64 fingerprints, so that they are re-computed at + * next request. */ public void setFingerprint(String fingerprint) { if (fingerprint != null) { Pattern fingerprintPattern = Pattern.compile("^[0-9a-fA-F]{40}$"); @@ -49,6 +52,8 @@ public class SummaryDocument extends Document {

private transient String hashedFingerprint = null;

+ /** Returns the SHA1-hashed fingerprint, or <code>null</code> if no + * fingerprint is set. */ public String getHashedFingerprint() { if (this.hashedFingerprint == null && this.f != null) { try { @@ -63,6 +68,8 @@ public class SummaryDocument extends Document {

private transient String base64Fingerprint = null;

+ /** Returns the base64-encoded fingerprint, or <code>null</code> if no + * fingerprint is set. */ public String getBase64Fingerprint() { if (this.base64Fingerprint == null && this.f != null) { try { @@ -77,6 +84,9 @@ public class SummaryDocument extends Document {

private transient String[] fingerprintSortedHexBlocks = null;

+ /** Returns a sorted array containing blocks of 4 upper-case hex + * characters from the fingerprint, or <code>null</code> if no + * fingerprint is set. */ public String[] getFingerprintSortedHexBlocks() { if (this.fingerprintSortedHexBlocks == null && this.f != null) { String fingerprint = this.f.toUpperCase(); @@ -94,6 +104,7 @@ public class SummaryDocument extends Document {

private String n;

+ @SuppressWarnings("checkstyle:javadocmethod") public void setNickname(String nickname) { if (nickname == null || nickname.equals("Unnamed")) { this.n = null; @@ -219,6 +230,7 @@ public class SummaryDocument extends Document {

private String c;

+ @SuppressWarnings("checkstyle:javadocmethod") public void setContact(String contact) { if (contact != null && contact.length() == 0) { this.c = null; @@ -257,6 +269,7 @@ public class SummaryDocument extends Document {

/* The familyFingerprints parameter can go away after September 8, 2015. * See above. */ + /** Instantiates a summary document with all given properties. */ public SummaryDocument(boolean isRelay, String nickname, String fingerprint, List<String> addresses, long lastSeenMillis, boolean running, SortedSet<String> relayFlags, long consensusWeight, diff --git a/src/main/java/org/torproject/onionoo/docs/UpdateStatus.java b/src/main/java/org/torproject/onionoo/docs/UpdateStatus.java index 07d5d20..4223337 100644 --- a/src/main/java/org/torproject/onionoo/docs/UpdateStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/UpdateStatus.java @@ -20,6 +20,7 @@ public class UpdateStatus extends Document { return this.updatedMillis; }

+ @Override public void setFromDocumentString(String documentString) { try { this.updatedMillis = Long.parseLong(documentString.trim()); @@ -30,6 +31,7 @@ public class UpdateStatus extends Document { } }

+ @Override public String toDocumentString() { return String.valueOf(this.updatedMillis); } diff --git a/src/main/java/org/torproject/onionoo/docs/UptimeHistory.java b/src/main/java/org/torproject/onionoo/docs/UptimeHistory.java index 6f1cb2e..3cd0a0e 100644 --- a/src/main/java/org/torproject/onionoo/docs/UptimeHistory.java +++ b/src/main/java/org/torproject/onionoo/docs/UptimeHistory.java @@ -38,6 +38,8 @@ public class UptimeHistory implements Comparable<UptimeHistory> { return this.flags; }

+ /** Instantiates a new uptime history object for a relay or bridge with + * the given interval start, uptime hours, and relay flags. */ UptimeHistory(boolean relay, long startMillis, int uptimeHours, SortedSet<String> flags) { this.relay = relay; @@ -46,6 +48,8 @@ public class UptimeHistory implements Comparable<UptimeHistory> { this.flags = flags; }

+ /** Instantiates a new uptime history object from the given string that + * may have been produced by {@link #toString()}. */ public static UptimeHistory fromString(String uptimeHistoryString) { String[] parts = uptimeHistoryString.split(" ", -1); if (parts.length < 3) { @@ -87,6 +91,7 @@ public class UptimeHistory implements Comparable<UptimeHistory> { return new UptimeHistory(relay, startMillis, uptimeHours, flags); }

+ @Override public String toString() { StringBuilder sb = new StringBuilder(); sb.append(this.relay ? (this.flags == null ? "r" : "R") : "b"); @@ -101,6 +106,10 @@ public class UptimeHistory implements Comparable<UptimeHistory> { return sb.toString(); }

+ /** Adds uptime hours from another uptime history object, which is + * assumed to either start right after this one or which ends right + * before it, and sets the interval start to the earlier interval + * start. */ public void addUptime(UptimeHistory other) { this.uptimeHours += other.uptimeHours; if (this.startMillis > other.startMillis) { @@ -108,6 +117,7 @@ public class UptimeHistory implements Comparable<UptimeHistory> { } }

+ @Override public int compareTo(UptimeHistory other) { if (this.relay && !other.relay) { return -1; @@ -118,12 +128,14 @@ public class UptimeHistory implements Comparable<UptimeHistory> { : this.startMillis > other.startMillis ? 1 : 0; }

+ @Override public boolean equals(Object other) { return other instanceof UptimeHistory && this.relay == ((UptimeHistory) other).relay && this.startMillis == ((UptimeHistory) other).startMillis; }

+ @Override public int hashCode() { return (int) this.startMillis + (this.relay ? 1 : 0); } diff --git a/src/main/java/org/torproject/onionoo/docs/UptimeStatus.java b/src/main/java/org/torproject/onionoo/docs/UptimeStatus.java index ce3a4d1..b725acc 100644 --- a/src/main/java/org/torproject/onionoo/docs/UptimeStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/UptimeStatus.java @@ -40,6 +40,7 @@ public class UptimeStatus extends Document { return this.bridgeHistory; }

+ @Override public void setFromDocumentString(String documentString) { try (Scanner s = new Scanner(documentString)) { while (s.hasNextLine()) { @@ -59,6 +60,8 @@ public class UptimeStatus extends Document { } }

+ /** Adds all given uptime history objects that don't overlap with + * existing uptime history objects. */ public void addToHistory(boolean relay, long startMillis, SortedSet<String> flags) { SortedSet<UptimeHistory> history = relay ? this.relayHistory @@ -105,6 +108,8 @@ public class UptimeStatus extends Document { this.isDirty = true; }

+ /** Compresses the history of uptime objects by merging adjacent + * intervals. */ public void compressHistory() { this.compressHistory(this.relayHistory); this.compressHistory(this.bridgeHistory); @@ -137,6 +142,7 @@ public class UptimeStatus extends Document { } }

+ @Override public String toDocumentString() { StringBuilder sb = new StringBuilder(); for (UptimeHistory interval : this.relayHistory) { diff --git a/src/main/java/org/torproject/onionoo/docs/WeightsStatus.java b/src/main/java/org/torproject/onionoo/docs/WeightsStatus.java index 47eaed9..efb7c25 100644 --- a/src/main/java/org/torproject/onionoo/docs/WeightsStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/WeightsStatus.java @@ -46,6 +46,7 @@ public class WeightsStatus extends Document { return this.history; }

+ @Override public void setFromDocumentString(String documentString) { try (Scanner s = new Scanner(documentString)) { while (s.hasNextLine()) { @@ -90,6 +91,8 @@ public class WeightsStatus extends Document { } }

+ /** Adds all given weights history objects that don't overlap with + * existing weights history objects. */ public void addToHistory(long validAfterMillis, long freshUntilMillis, double[] weights) { long[] interval = new long[] { validAfterMillis, freshUntilMillis }; @@ -104,6 +107,8 @@ public class WeightsStatus extends Document { } }

+ /** Compresses the history of weights objects by merging adjacent + * intervals, depending on how far back in the past they lie. */ public void compressHistory() { SortedMap<long[], double[]> uncompressedHistory = new TreeMap<long[], double[]>(this.history); @@ -176,6 +181,7 @@ public class WeightsStatus extends Document { } }

+ @Override public String toDocumentString() { StringBuilder sb = new StringBuilder(); for (Map.Entry<long[], double[]> e : history.entrySet()) { diff --git a/src/main/java/org/torproject/onionoo/server/NodeIndexer.java b/src/main/java/org/torproject/onionoo/server/NodeIndexer.java index 30a6f0e..93b5af7 100644 --- a/src/main/java/org/torproject/onionoo/server/NodeIndexer.java +++ b/src/main/java/org/torproject/onionoo/server/NodeIndexer.java @@ -34,6 +34,7 @@ public class NodeIndexer implements ServletContextListener, Runnable { private static final Logger log = LoggerFactory.getLogger( NodeIndexer.class);

+ @Override public void contextInitialized(ServletContextEvent contextEvent) { ServletContext servletContext = contextEvent.getServletContext(); File outDir = new File(servletContext.getInitParameter("outDir")); @@ -50,6 +51,7 @@ public class NodeIndexer implements ServletContextListener, Runnable { this.startIndexing(); }

+ @Override public void contextDestroyed(ServletContextEvent contextEvent) { this.stopIndexing(); } @@ -60,6 +62,9 @@ public class NodeIndexer implements ServletContextListener, Runnable {

private Thread nodeIndexerThread = null;

+ /** Returns the creation time of the last known node index in + * milliseconds since the epoch, or <code>-1</code> if no node index + * could be retrieved within <code>timeoutMillis</code> milliseconds. */ public synchronized long getLastIndexed(long timeoutMillis) { if (this.lastIndexed == -1L && this.nodeIndexerThread != null && timeoutMillis > 0L) { @@ -71,6 +76,8 @@ public class NodeIndexer implements ServletContextListener, Runnable { return this.lastIndexed; }

+ /** Returns the last known node index, or null if no node index could be + * retrieved within <code>timeoutMillis</code> milliseconds. */ public synchronized NodeIndex getLatestNodeIndex(long timeoutMillis) { if (this.latestNodeIndex == null && this.nodeIndexerThread != null && timeoutMillis > 0L) { @@ -82,6 +89,8 @@ public class NodeIndexer implements ServletContextListener, Runnable { return this.latestNodeIndex; }

+ /** Start reading the node index into memory periodically in a + * background thread. */ public synchronized void startIndexing() { if (this.nodeIndexerThread == null) { this.nodeIndexerThread = new Thread(this); @@ -94,6 +103,7 @@ public class NodeIndexer implements ServletContextListener, Runnable {

private static final long ONE_DAY = 24L * 60L * ONE_MINUTE;

+ @Override public void run() { while (this.nodeIndexerThread != null) { this.indexNodeStatuses(); @@ -104,6 +114,8 @@ public class NodeIndexer implements ServletContextListener, Runnable { } }

+ /** Stop the background process that is periodically reading the node + * index. */ public synchronized void stopIndexing() { Thread indexerThread = this.nodeIndexerThread; this.nodeIndexerThread = null; diff --git a/src/main/java/org/torproject/onionoo/server/NodeIndexerFactory.java b/src/main/java/org/torproject/onionoo/server/NodeIndexerFactory.java index 1dfa859..b938c9e 100644 --- a/src/main/java/org/torproject/onionoo/server/NodeIndexerFactory.java +++ b/src/main/java/org/torproject/onionoo/server/NodeIndexerFactory.java @@ -7,10 +7,15 @@ public class NodeIndexerFactory {

private static NodeIndexer nodeIndexerInstance;

+ /** Sets a custom singleton node indexer instance that will be returned + * by {@link #getNodeIndexer()} rather than creating an instance upon + * first invocation. */ public static void setNodeIndexer(NodeIndexer nodeIndexer) { nodeIndexerInstance = nodeIndexer; }

+ /** Returns the singleton node indexer instance that gets created upon + * first invocation of this method. */ public static NodeIndexer getNodeIndexer() { if (nodeIndexerInstance == null) { nodeIndexerInstance = new NodeIndexer(); diff --git a/src/main/java/org/torproject/onionoo/server/PerformanceMetrics.java b/src/main/java/org/torproject/onionoo/server/PerformanceMetrics.java index a12e5c7..7adad76 100644 --- a/src/main/java/org/torproject/onionoo/server/PerformanceMetrics.java +++ b/src/main/java/org/torproject/onionoo/server/PerformanceMetrics.java @@ -30,6 +30,7 @@ class Counter { this.value++; }

+ @Override public String toString() { return String.valueOf(this.value); } @@ -52,6 +53,7 @@ class MostFrequentString { } }

+ @Override public String toString() { SortedMap<Integer, SortedSet<String>> sortedFrequencies = new TreeMap<Integer, SortedSet<String>>( @@ -98,6 +100,7 @@ class IntegerDistribution { logValues[64 - Long.numberOfLeadingZeros(value)]++; }

+ @Override public String toString() { StringBuilder sb = new StringBuilder(); int totalValues = 0; @@ -172,6 +175,9 @@ public class PerformanceMetrics { private static IntegerDistribution buildResponseMillis = new IntegerDistribution();

+ /** Collects aggregate statistics on a given request for periodic + * request statistics, and logs requests taking longer than expected to + * process. */ public static void logStatistics(long receivedRequestMillis, String resourceType, Collection<String> parameterKeys, long parsedRequestMillis, int relayDocumentsWritten, diff --git a/src/main/java/org/torproject/onionoo/server/RequestHandler.java b/src/main/java/org/torproject/onionoo/server/RequestHandler.java index 85a6ff1..eaa4fe2 100644 --- a/src/main/java/org/torproject/onionoo/server/RequestHandler.java +++ b/src/main/java/org/torproject/onionoo/server/RequestHandler.java @@ -111,6 +111,7 @@ public class RequestHandler {

private int[] firstSeenDays;

+ @SuppressWarnings("checkstyle:javadocmethod") public void setFirstSeenDays(int[] firstSeenDays) { this.firstSeenDays = new int[firstSeenDays.length]; System.arraycopy(firstSeenDays, 0, this.firstSeenDays, 0, @@ -119,6 +120,7 @@ public class RequestHandler {

private int[] lastSeenDays;

+ @SuppressWarnings("checkstyle:javadocmethod") public void setLastSeenDays(int[] lastSeenDays) { this.lastSeenDays = new int[lastSeenDays.length]; System.arraycopy(lastSeenDays, 0, this.lastSeenDays, 0, @@ -137,6 +139,8 @@ public class RequestHandler { private Map<String, SummaryDocument> filteredBridges = new HashMap<String, SummaryDocument>();

+ /** Handles this request by filtering by all given parameters and then + * possibly ordering, offsetting, and limiting results. */ public void handleRequest() { this.filteredRelays.putAll( this.nodeIndex.getRelayFingerprintSummaryLines()); diff --git a/src/main/java/org/torproject/onionoo/server/ResourceServlet.java b/src/main/java/org/torproject/onionoo/server/ResourceServlet.java index 4fd38b7..5b3ab69 100644 --- a/src/main/java/org/torproject/onionoo/server/ResourceServlet.java +++ b/src/main/java/org/torproject/onionoo/server/ResourceServlet.java @@ -31,6 +31,7 @@ public class ResourceServlet extends HttpServlet { private boolean maintenanceMode = false;

/* Called by servlet container, not by test class. */ + @Override public void init(ServletConfig config) throws ServletException { super.init(config); this.maintenanceMode = config.getInitParameter("maintenance") != null @@ -39,6 +40,7 @@ public class ResourceServlet extends HttpServlet {

private static final long INDEX_WAITING_TIME = 10L * 1000L;

+ @Override public long getLastModified(HttpServletRequest request) { if (this.maintenanceMode) { return super.getLastModified(request); @@ -48,6 +50,7 @@ public class ResourceServlet extends HttpServlet { } }

+ @Override public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { HttpServletRequestWrapper requestWrapper = @@ -72,6 +75,9 @@ public class ResourceServlet extends HttpServlet { new HashSet<String>(Arrays.asList(("search,fingerprint,order,limit," + "offset,fields").split(",")));

+ /** Handles the HTTP GET request in the wrapped <code>request</code> by + * writing an HTTP GET response to the likewise <code>response</code>, + * both of which are wrapped to facilitate testing. */ public void doGet(HttpServletRequestWrapper request, HttpServletResponseWrapper response) throws IOException {

diff --git a/src/main/java/org/torproject/onionoo/server/ServerMain.java b/src/main/java/org/torproject/onionoo/server/ServerMain.java index 22e315b..fd4dc90 100644 --- a/src/main/java/org/torproject/onionoo/server/ServerMain.java +++ b/src/main/java/org/torproject/onionoo/server/ServerMain.java @@ -14,6 +14,7 @@ public class ServerMain { private static final Logger log = LoggerFactory.getLogger( ServerMain.class);

+ /** Starts the web server listening for incoming client connections. */ public static void main(String[] args) { try { Resource onionooXml = Resource.newSystemResource("jetty.xml"); diff --git a/src/main/java/org/torproject/onionoo/updater/BandwidthStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/BandwidthStatusUpdater.java index 1c0c181..3aa3dd1 100644 --- a/src/main/java/org/torproject/onionoo/updater/BandwidthStatusUpdater.java +++ b/src/main/java/org/torproject/onionoo/updater/BandwidthStatusUpdater.java @@ -16,6 +16,9 @@ public class BandwidthStatusUpdater implements DescriptorListener,

private DocumentStore documentStore;

+ /** Initializes a new status updater, obtains references to all relevant + * singleton instances, and registers as listener at the (singleton) + * descriptor source. */ public BandwidthStatusUpdater() { this.descriptorSource = DescriptorSourceFactory.getDescriptorSource(); this.documentStore = DocumentStoreFactory.getDocumentStore(); @@ -29,12 +32,14 @@ public class BandwidthStatusUpdater implements DescriptorListener, DescriptorType.BRIDGE_EXTRA_INFOS); }

+ @Override public void processDescriptor(Descriptor descriptor, boolean relay) { if (descriptor instanceof ExtraInfoDescriptor) { this.parseDescriptor((ExtraInfoDescriptor) descriptor); } }

+ @Override public void updateStatuses() { /* Status files are already updated while processing descriptors. */ } @@ -59,6 +64,7 @@ public class BandwidthStatusUpdater implements DescriptorListener, } }

+ @Override public String getStatsString() { /* TODO Add statistics string. */ return null; diff --git a/src/main/java/org/torproject/onionoo/updater/ClientsStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/ClientsStatusUpdater.java index 492b67b..28b8ea7 100644 --- a/src/main/java/org/torproject/onionoo/updater/ClientsStatusUpdater.java +++ b/src/main/java/org/torproject/onionoo/updater/ClientsStatusUpdater.java @@ -43,6 +43,9 @@ public class ClientsStatusUpdater implements DescriptorListener,

private DocumentStore documentStore;

+ /** Initializes a new status updater, obtains references to all relevant + * singleton instances, and registers as listener at the (singleton) + * descriptor source. */ public ClientsStatusUpdater() { this.descriptorSource = DescriptorSourceFactory.getDescriptorSource(); this.documentStore = DocumentStoreFactory.getDocumentStore(); @@ -54,6 +57,7 @@ public class ClientsStatusUpdater implements DescriptorListener, DescriptorType.BRIDGE_EXTRA_INFOS); }

+ @Override public void processDescriptor(Descriptor descriptor, boolean relay) { if (descriptor instanceof ExtraInfoDescriptor && !relay) { this.processBridgeExtraInfoDescriptor( @@ -143,6 +147,7 @@ public class ClientsStatusUpdater implements DescriptorListener, return weightedResponses; }

+ @Override public void updateStatuses() { for (Map.Entry<String, SortedSet<ClientsHistory>> e : this.newResponses.entrySet()) { @@ -161,6 +166,7 @@ public class ClientsStatusUpdater implements DescriptorListener, } }

+ @Override public String getStatsString() { int newIntervals = 0; for (SortedSet<ClientsHistory> hist : this.newResponses.values()) { diff --git a/src/main/java/org/torproject/onionoo/updater/DescriptorSource.java b/src/main/java/org/torproject/onionoo/updater/DescriptorSource.java index b9d07b4..176a17c 100644 --- a/src/main/java/org/torproject/onionoo/updater/DescriptorSource.java +++ b/src/main/java/org/torproject/onionoo/updater/DescriptorSource.java @@ -32,6 +32,7 @@ public class DescriptorSource {

private DescriptorQueue archiveDescriptorQueue;

+ /** Instantiates a new descriptor source. */ public DescriptorSource() { this.descriptorQueues = new ArrayList<DescriptorQueue>(); this.descriptorListeners = @@ -53,6 +54,7 @@ public class DescriptorSource { private Map<DescriptorType, Set<DescriptorListener>> descriptorListeners;

+ /** Registers a descriptor listener for a given descriptor type. */ public void registerDescriptorListener(DescriptorListener listener, DescriptorType descriptorType) { if (!this.descriptorListeners.containsKey(descriptorType)) { @@ -62,6 +64,7 @@ public class DescriptorSource { this.descriptorListeners.get(descriptorType).add(listener); }

+ /** Downloads descriptors from CollecTor. */ public void downloadDescriptors() { for (DescriptorType descriptorType : DescriptorType.values()) { log.info("Loading: " + descriptorType); @@ -87,6 +90,8 @@ public class DescriptorSource { this.deletedLocalFiles += descriptorDownloader.deleteOldLocalFiles(); }

+ /** Reads archived and recent descriptors from disk and feeds them into + * any registered listeners. */ public void readDescriptors() { this.readArchivedDescriptors(); log.debug("Reading recent " + DescriptorType.RELAY_SERVER_DESCRIPTORS @@ -154,6 +159,8 @@ public class DescriptorSource { } }

+ /** Reads archived descriptors from disk and feeds them into any + * registered listeners. */ public void readArchivedDescriptors() { if (!this.inArchiveDir.exists()) { return; @@ -208,6 +215,7 @@ public class DescriptorSource { log.info("Read archived descriptors"); }

+ /** Writes parse histories for recent descriptors to disk. */ public void writeHistoryFiles() { log.debug("Writing parse histories for recent descriptors..."); for (DescriptorQueue descriptorQueue : this.descriptorQueues) { @@ -215,6 +223,8 @@ public class DescriptorSource { } }

+ /** Returns a string with statistics on the number of processed + * descriptors during the current execution. */ public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + this.localFilesBefore + " recent descriptor files " diff --git a/src/main/java/org/torproject/onionoo/updater/DescriptorSourceFactory.java b/src/main/java/org/torproject/onionoo/updater/DescriptorSourceFactory.java index 65c5622..4974488 100644 --- a/src/main/java/org/torproject/onionoo/updater/DescriptorSourceFactory.java +++ b/src/main/java/org/torproject/onionoo/updater/DescriptorSourceFactory.java @@ -7,11 +7,16 @@ public class DescriptorSourceFactory {

private static DescriptorSource descriptorSourceInstance;

+ /** Sets a custom singleton descriptor source instance that will be + * returned by {@link #getDescriptorSource()} rather than creating an + * instance upon first invocation. */ public static void setDescriptorSource( DescriptorSource descriptorSource) { descriptorSourceInstance = descriptorSource; }

+ /** Returns the singleton descriptor source instance that gets created + * upon first invocation of this method. */ public static DescriptorSource getDescriptorSource() { if (descriptorSourceInstance == null) { descriptorSourceInstance = new DescriptorSource(); diff --git a/src/main/java/org/torproject/onionoo/updater/LookupService.java b/src/main/java/org/torproject/onionoo/updater/LookupService.java index 85d56e8..2b0993f 100644 --- a/src/main/java/org/torproject/onionoo/updater/LookupService.java +++ b/src/main/java/org/torproject/onionoo/updater/LookupService.java @@ -97,6 +97,9 @@ public class LookupService { return addressNumber; }

+ /** Looks up address strings in the configured + * <code>GeoLite2-City-*.csv</code> and <code>GeoIPASNum2.csv</code> + * files and returns all lookup results. */ public SortedMap<String, LookupResult> lookup( SortedSet<String> addressStrings) {

@@ -363,6 +366,8 @@ public class LookupService {

private int addressesResolved = 0;

+ /** Returns a string with the number of addresses looked up and + * resolved. */ public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java index 9bceaa1..d873072 100644 --- a/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java +++ b/src/main/java/org/torproject/onionoo/updater/NodeDetailsStatusUpdater.java @@ -95,6 +95,9 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,

private int bridgeStatusesProcessed = 0;

+ /** Initializes a new status updater, obtains references to all relevant + * singleton instances, and registers as listener at the (singleton) + * descriptor source. */ public NodeDetailsStatusUpdater( ReverseDomainNameResolver reverseDomainNameResolver, LookupService lookupService) { @@ -125,6 +128,7 @@ public class NodeDetailsStatusUpdater implements DescriptorListener,

private SortedSet<String> updatedNodes = new TreeSet<String>();

+ @Override public void processDescriptor(Descriptor descriptor, boolean relay) { if (descriptor instanceof ServerDescriptor && relay) { this.processRelayServerDescriptor((ServerDescriptor) descriptor); @@ -385,6 +389,7 @@ public class NodeDetailsStatusUpdater implements DescriptorListener, this.bridgeStatusesProcessed++; }

+ @Override public void updateStatuses() { this.readNodeStatuses(); log.info("Read node statuses"); @@ -927,6 +932,7 @@ public class NodeDetailsStatusUpdater implements DescriptorListener, } }

+ @Override public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/updater/RdnsLookupRequest.java b/src/main/java/org/torproject/onionoo/updater/RdnsLookupRequest.java index e2ee5e1..75ad315 100644 --- a/src/main/java/org/torproject/onionoo/updater/RdnsLookupRequest.java +++ b/src/main/java/org/torproject/onionoo/updater/RdnsLookupRequest.java @@ -28,6 +28,7 @@ class RdnsLookupRequest extends Thread { this.address = address; }

+ @Override public void run() { this.lookupStartedMillis = this.reverseDomainNameResolver.time.currentTimeMillis(); diff --git a/src/main/java/org/torproject/onionoo/updater/RdnsLookupWorker.java b/src/main/java/org/torproject/onionoo/updater/RdnsLookupWorker.java index 0c48be5..165507b 100644 --- a/src/main/java/org/torproject/onionoo/updater/RdnsLookupWorker.java +++ b/src/main/java/org/torproject/onionoo/updater/RdnsLookupWorker.java @@ -11,6 +11,7 @@ class RdnsLookupWorker extends Thread { this.reverseDomainNameResolver = reverseDomainNameResolver; }

+ @Override public void run() { while (this.reverseDomainNameResolver.time.currentTimeMillis() - ReverseDomainNameResolver.RDNS_LOOKUP_MAX_DURATION_MILLIS diff --git a/src/main/java/org/torproject/onionoo/updater/ReverseDomainNameResolver.java b/src/main/java/org/torproject/onionoo/updater/ReverseDomainNameResolver.java index 0f3caad..3214c74 100644 --- a/src/main/java/org/torproject/onionoo/updater/ReverseDomainNameResolver.java +++ b/src/main/java/org/torproject/onionoo/updater/ReverseDomainNameResolver.java @@ -48,6 +48,8 @@ public class ReverseDomainNameResolver { this.addressLastLookupTimes = addressLastLookupTimes; }

+ /** Starts reverse domain name lookups in one or more background + * threads and returns immediately. */ public void startReverseDomainNameLookups() { this.startedRdnsLookups = this.time.currentTimeMillis(); this.rdnsLookupJobs = new HashSet<String>(); @@ -69,6 +71,8 @@ public class ReverseDomainNameResolver { } }

+ /** Joins all background threads performing reverse domain name lookups + * and returns as soon as they have all finished. */ public void finishReverseDomainNameLookups() { for (RdnsLookupWorker rdnsLookupWorker : this.rdnsLookupWorkers) { try { @@ -80,16 +84,21 @@ public class ReverseDomainNameResolver { } }

+ /** Returns reverse domain name lookup results. */ public Map<String, String> getLookupResults() { synchronized (this.rdnsLookupResults) { return new HashMap<String, String>(this.rdnsLookupResults); } }

+ /** Returns the time in milliseconds since the epoch when reverse domain + * lookups have been started. */ public long getLookupStartMillis() { return this.startedRdnsLookups; }

+ /** Returns a string with the number of performed reverse domain name + * lookups and some simple statistics on lookup time. */ public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/updater/StatusUpdateRunner.java b/src/main/java/org/torproject/onionoo/updater/StatusUpdateRunner.java index 2ba8401..7aa1a5e 100644 --- a/src/main/java/org/torproject/onionoo/updater/StatusUpdateRunner.java +++ b/src/main/java/org/torproject/onionoo/updater/StatusUpdateRunner.java @@ -19,6 +19,8 @@ public class StatusUpdateRunner {

private StatusUpdater[] statusUpdaters;

+ /** Instantiates a new status update runner with newly created instances + * of all known status updater implementations. */ public StatusUpdateRunner() { this.ls = new LookupService(new File("geoip")); this.rdnr = new ReverseDomainNameResolver(); @@ -32,6 +34,7 @@ public class StatusUpdateRunner { usu }; }

+ /** Lets each configured status updater update its status files. */ public void updateStatuses() { for (StatusUpdater su : this.statusUpdaters) { log.debug("Begin update of " + su.getClass().getSimpleName()); @@ -41,6 +44,7 @@ public class StatusUpdateRunner { } }

+ /** Logs statistics of all configured status updaters. */ public void logStatistics() { for (StatusUpdater su : this.statusUpdaters) { String statsString = su.getStatsString(); diff --git a/src/main/java/org/torproject/onionoo/updater/UptimeStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/UptimeStatusUpdater.java index f2d7dc1..d4951b7 100644 --- a/src/main/java/org/torproject/onionoo/updater/UptimeStatusUpdater.java +++ b/src/main/java/org/torproject/onionoo/updater/UptimeStatusUpdater.java @@ -28,6 +28,9 @@ public class UptimeStatusUpdater implements DescriptorListener,

private DocumentStore documentStore;

+ /** Initializes a new status updater, obtains references to all relevant + * singleton instances, and registers as listener at the (singleton) + * descriptor source. */ public UptimeStatusUpdater() { this.descriptorSource = DescriptorSourceFactory.getDescriptorSource(); this.documentStore = DocumentStoreFactory.getDocumentStore(); @@ -41,6 +44,7 @@ public class UptimeStatusUpdater implements DescriptorListener, DescriptorType.BRIDGE_STATUSES); }

+ @Override public void processDescriptor(Descriptor descriptor, boolean relay) { if (descriptor instanceof RelayNetworkStatusConsensus) { this.processRelayNetworkStatusConsensus( @@ -132,6 +136,7 @@ public class UptimeStatusUpdater implements DescriptorListener, } }

+ @Override public void updateStatuses() { for (Map.Entry<String, SortedMap<Long, Flags>> e : this.newRunningRelays.entrySet()) { @@ -179,6 +184,7 @@ public class UptimeStatusUpdater implements DescriptorListener, } }

+ @Override public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/updater/WeightsStatusUpdater.java b/src/main/java/org/torproject/onionoo/updater/WeightsStatusUpdater.java index 14e425b..2442a00 100644 --- a/src/main/java/org/torproject/onionoo/updater/WeightsStatusUpdater.java +++ b/src/main/java/org/torproject/onionoo/updater/WeightsStatusUpdater.java @@ -24,6 +24,9 @@ public class WeightsStatusUpdater implements DescriptorListener,

private DocumentStore documentStore;

+ /** Initializes a new status updater, obtains references to all relevant + * singleton instances, and registers as listener at the (singleton) + * descriptor source. */ public WeightsStatusUpdater() { this.descriptorSource = DescriptorSourceFactory.getDescriptorSource(); this.documentStore = DocumentStoreFactory.getDocumentStore(); @@ -35,6 +38,7 @@ public class WeightsStatusUpdater implements DescriptorListener, DescriptorType.RELAY_CONSENSUSES); }

+ @Override public void processDescriptor(Descriptor descriptor, boolean relay) { if (descriptor instanceof RelayNetworkStatusConsensus) { this.processRelayNetworkConsensus( @@ -42,6 +46,7 @@ public class WeightsStatusUpdater implements DescriptorListener, } }

+ @Override public void updateStatuses() { /* Nothing to do. */ } @@ -193,6 +198,7 @@ public class WeightsStatusUpdater implements DescriptorListener, return pathSelectionProbabilities; }

+ @Override public String getStatsString() { /* TODO Add statistics string. */ return null; diff --git a/src/main/java/org/torproject/onionoo/util/FormattingUtils.java b/src/main/java/org/torproject/onionoo/util/FormattingUtils.java index 36fb838..fd83cf8 100644 --- a/src/main/java/org/torproject/onionoo/util/FormattingUtils.java +++ b/src/main/java/org/torproject/onionoo/util/FormattingUtils.java @@ -12,11 +12,14 @@ public class FormattingUtils {

private static final long ONE_MINUTE = 60L * ONE_SECOND;

+ /** Formats the given number of milliseconds using the format + * <code>"${minutes}:${seconds}.{milliseconds} minutes"</code>. */ public static String formatMillis(long millis) { return String.format("%02d:%02d.%03d minutes", millis / ONE_MINUTE, (millis % ONE_MINUTE) / ONE_SECOND, millis % ONE_SECOND); }

+ /** Formats the given number of bytes as B, KiB, MiB, GiB, etc. */ public static String formatBytes(long bytes) { if (bytes < 1024) { return bytes + " B"; @@ -27,6 +30,8 @@ public class FormattingUtils { } }

+ /** Formats the given decimal number with a comma as thousands + * separator. */ public static String formatDecimalNumber(long decimalNumber) { return String.format("%,d", decimalNumber); } diff --git a/src/main/java/org/torproject/onionoo/util/TimeFactory.java b/src/main/java/org/torproject/onionoo/util/TimeFactory.java index e3067a4..608b595 100644 --- a/src/main/java/org/torproject/onionoo/util/TimeFactory.java +++ b/src/main/java/org/torproject/onionoo/util/TimeFactory.java @@ -7,10 +7,15 @@ public class TimeFactory {

private static Time timeInstance;

+ /** Sets a custom singleton time instance that will be returned by + * {@link #getTime} rather than creating an instance upon first + * invocation. */ public static void setTime(Time time) { timeInstance = time; }

+ /** Returns the singleton node indexer instance that gets created upon + * first invocation of this method. */ public static Time getTime() { if (timeInstance == null) { timeInstance = new Time(); diff --git a/src/main/java/org/torproject/onionoo/writer/BandwidthDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/BandwidthDocumentWriter.java index a844f7a..7238c1b 100644 --- a/src/main/java/org/torproject/onionoo/writer/BandwidthDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/BandwidthDocumentWriter.java @@ -36,6 +36,7 @@ public class BandwidthDocumentWriter implements DocumentWriter { this.now = TimeFactory.getTime().currentTimeMillis(); }

+ @Override public void writeDocuments() { UpdateStatus updateStatus = this.documentStore.retrieve( UpdateStatus.class, true); @@ -196,6 +197,7 @@ public class BandwidthDocumentWriter implements DocumentWriter { return graphs; }

+ @Override public String getStatsString() { /* TODO Add statistics string. */ return null; diff --git a/src/main/java/org/torproject/onionoo/writer/ClientsDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/ClientsDocumentWriter.java index 6cbd2e0..00389d0 100644 --- a/src/main/java/org/torproject/onionoo/writer/ClientsDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/ClientsDocumentWriter.java @@ -64,6 +64,7 @@ public class ClientsDocumentWriter implements DocumentWriter {

private int writtenDocuments = 0;

+ @Override public void writeDocuments() { UpdateStatus updateStatus = this.documentStore.retrieve( UpdateStatus.class, true); @@ -286,6 +287,7 @@ public class ClientsDocumentWriter implements DocumentWriter { } }

+ @Override public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java index 44c675f..c167152 100644 --- a/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/DetailsDocumentWriter.java @@ -31,6 +31,7 @@ public class DetailsDocumentWriter implements DocumentWriter { this.documentStore = DocumentStoreFactory.getDocumentStore(); }

+ @Override public void writeDocuments() { UpdateStatus updateStatus = this.documentStore.retrieve( UpdateStatus.class, true); @@ -186,6 +187,7 @@ public class DetailsDocumentWriter implements DocumentWriter { this.documentStore.store(detailsDocument, fingerprint); }

+ @Override public String getStatsString() { /* TODO Add statistics string. */ return null; diff --git a/src/main/java/org/torproject/onionoo/writer/DocumentWriterRunner.java b/src/main/java/org/torproject/onionoo/writer/DocumentWriterRunner.java index 4809ed9..d9d1c47 100644 --- a/src/main/java/org/torproject/onionoo/writer/DocumentWriterRunner.java +++ b/src/main/java/org/torproject/onionoo/writer/DocumentWriterRunner.java @@ -13,6 +13,8 @@ public class DocumentWriterRunner {

private DocumentWriter[] documentWriters;

+ /** Instantiates a new document writer runner with newly created + * instances of all known document writer implementations. */ public DocumentWriterRunner() { SummaryDocumentWriter sdw = new SummaryDocumentWriter(); DetailsDocumentWriter ddw = new DetailsDocumentWriter(); @@ -24,6 +26,7 @@ public class DocumentWriterRunner { udw }; }

+ /** Lets each configured document writer write its documents. */ public void writeDocuments() { for (DocumentWriter dw : this.documentWriters) { log.debug("Writing " + dw.getClass().getSimpleName()); @@ -31,6 +34,7 @@ public class DocumentWriterRunner { } }

+ /** Logs statistics of all configured document writers. */ public void logStatistics() { for (DocumentWriter dw : this.documentWriters) { String statsString = dw.getStatsString(); diff --git a/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java index f0d7fe0..f941ee3 100644 --- a/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/SummaryDocumentWriter.java @@ -32,6 +32,7 @@ public class SummaryDocumentWriter implements DocumentWriter {

private int deletedDocuments = 0;

+ @Override public void writeDocuments() { long relaysLastValidAfterMillis = -1L; long bridgesLastPublishedMillis = -1L; @@ -101,6 +102,7 @@ public class SummaryDocumentWriter implements DocumentWriter { log.info("Wrote summary document files"); }

+ @Override public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/writer/UptimeDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/UptimeDocumentWriter.java index e93627b..502c351 100644 --- a/src/main/java/org/torproject/onionoo/writer/UptimeDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/UptimeDocumentWriter.java @@ -40,6 +40,7 @@ public class UptimeDocumentWriter implements DocumentWriter { this.now = TimeFactory.getTime().currentTimeMillis(); }

+ @Override public void writeDocuments() { UptimeStatus uptimeStatus = this.documentStore.retrieve( UptimeStatus.class, true); @@ -318,6 +319,7 @@ public class UptimeDocumentWriter implements DocumentWriter { } }

+ @Override public String getStatsString() { StringBuilder sb = new StringBuilder(); sb.append(" " + FormattingUtils.formatDecimalNumber( diff --git a/src/main/java/org/torproject/onionoo/writer/WeightsDocumentWriter.java b/src/main/java/org/torproject/onionoo/writer/WeightsDocumentWriter.java index cabe964..326fbda 100644 --- a/src/main/java/org/torproject/onionoo/writer/WeightsDocumentWriter.java +++ b/src/main/java/org/torproject/onionoo/writer/WeightsDocumentWriter.java @@ -36,6 +36,7 @@ public class WeightsDocumentWriter implements DocumentWriter { this.now = TimeFactory.getTime().currentTimeMillis(); }

+ @Override public void writeDocuments() { UpdateStatus updateStatus = this.documentStore.retrieve( UpdateStatus.class, true); @@ -210,6 +211,7 @@ public class WeightsDocumentWriter implements DocumentWriter { } }

+ @Override public String getStatsString() { /* TODO Add statistics string. */ return null; diff --git a/src/test/resources/metrics_checks.xml b/src/test/resources/metrics_checks.xml index 0777894..a4af08a 100644 --- a/src/test/resources/metrics_checks.xml +++ b/src/test/resources/metrics_checks.xml @@ -34,6 +34,7 @@ <property name="eachLine" value="true"/> </module>

+ <module name="SuppressWarningsFilter" /> <module name="TreeWalker"> <module name="OuterTypeFilename"/> <module name="IllegalTokenText"> @@ -213,5 +214,6 @@ <property name="exceptionVariableName" value="expected"/> </module> <module name="CommentsIndentation"/> + <module name="SuppressWarningsHolder" /> </module> </module>