commit 02f3d0ce5661ee4552b1076b7c6b3bb0fef0353c Author: Iain R. Learmonth <irl@fsfe.org> Date: Tue Aug 14 14:15:03 2018 +0100 Adds JavaDoc for NodeStatus class --- .../org/torproject/onionoo/docs/NodeStatus.java | 63 +++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java index b2b6c8e..c0c6adf 100644 --- a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java +++ b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java @@ -23,6 +23,58 @@ import java.util.TreeMap; import java.util.TreeSet; import java.util.stream.Collectors; +/** + * NodeStatus documents contain persistent state for data about relays. These + * are read by the hourly updater and then updated with new details where there + * are relevant descriptors, consensuses or other documents available. + * + * <p>At the end of each run of the hourly updater, these documents are + * concatenated and written to a single file in <code>status/summary</code>. + * Each line contains a single document. + * + * <p>A new NodeStatus can be created from a string using the + * {@link #fromString(String)} static method. To create a serialization, the + * {@link #toString()} method can be used. + * + * <p>The lines are formed of tab-separated values. There must be at least + * 23 fields present in the document. Additional fields may be present but + * are not required for the document to be valid. A summary of the encoding + * can be found here: + * + * <ol start="0"> + * <li>"r" or "b" to represent a relay or a bridge</li> + * <li>Nickname</li> + * <li>ASCII representation of hex-encoded fingerprint</li> + * <li>OR Addresses<li> + * <li>Last seen (date portion)</li> + * <li>Last seen (time portion)</li> + * <li>OR Port</li> + * <li>Dir Port</li> + * <li>Relay Flags</li> + * <li>Consensus Weight</li> + * <li>Country Code</li> + * <li>Blank field (previously used for host name)</li> + * <li>Last reverse DNS lookup time (milliseconds)</li> + * <li>Default policy</li> + * <li>Port list</li> + * <li>First seen (date portion)</li> + * <li>First seen (time portion)</li> + * <li>Last address change (date portion)</li> + * <li>Last address change (time portion)</li> + * <li>AS Number</li> + * <li>Contact</li> + * <li>Recommended version (boolean)</li> + * <li>Family</li> + * <li>Version</li> + * <li>Blank field (previously used for host name)</li> + * <li>Version status</li> + * <li>AS Name</li> + * <li>Verified and unverified host names</li> + * </ol> + * + * <p>This list only provides a summary, individual fields can have + * complex encodings with nested lists. + */ public class NodeStatus extends Document { private static final Logger log = LoggerFactory.getLogger( @@ -489,7 +541,14 @@ public class NodeStatus extends Document { } /** Instantiates a new node status object from the given string that may - * have been produced by {@link #toString()}. */ + * have been produced by {@link #toString()}. A document that has been + * written by a previous version of Onionoo that did not include all the + * currently supported fields will still be accepted, but will contain + * the new fields if serialized again using {@link #toString()}. A + * document that has been generated by a newer version of Onionoo that + * contains new fields will be accepted, but those new fields will be + * ignored and the data discarded if serialized again using + * {@link #toString()}. */ public static NodeStatus fromString(String documentString) { try { String[] parts = documentString.trim().split("\t"); @@ -648,6 +707,8 @@ public class NodeStatus extends Document { } } + /** Generates a String serialization of the node status object that could + * be used by {@link #fromString(String)} to recreate this object. */ @Override public String toString() { StringBuilder sb = new StringBuilder();