Commit 02f3d0ce authored by Iain R. Learmonth's avatar Iain R. Learmonth Committed by Karsten Loesing
Browse files

Adds JavaDoc for NodeStatus class

parent 4b05f840
......@@ -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();
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment