Commit 04e17004 authored by Hiro's avatar Hiro 🏄
Browse files

Improve javadoc for ExtraInfoDescriptor classes.

Remove javadoc warnings at build time and improve
overall code documentation.
parent 668788a9
......@@ -3,9 +3,7 @@
package org.torproject.descriptor.impl;
import org.torproject.descriptor.BandwidthHistory;
import org.torproject.descriptor.DescriptorParseException;
import org.torproject.descriptor.ExtraInfoDescriptor;
import org.torproject.descriptor.*;
import java.io.File;
import java.util.ArrayList;
......@@ -20,14 +18,47 @@ import java.util.Set;
import java.util.SortedMap;
import java.util.TreeMap;
/**
* Contains logic to work with extra-info descriptor files.
*
* The extra-info document format is defined in the dir-spec
* document.
*
* @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
*
* Descriptor keys are defined and their occurency is checked to
* make sure the descriptor file format is valid.
*
* Descriptor lines are parsed and their values can be accessed through the
* defined methods.
*
* When metrics library learns how to parse a new line for extra-info
* descriptor files all its fields, from the dir-spec document, are parsed in
* this class.
*
* The new key is added to {@link Key} and its occurence is checked in
* {@link ExtraInfoDescriptorImpl} constructor.
*
* @since 1.0.0
*/
public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
implements ExtraInfoDescriptor {
private static final long serialVersionUID = -4720810362228341775L;
/**
* Define keys that MUST occur exactly one time in every
* instance of the document type.
*/
private Set<Key> exactlyOnceKeys = EnumSet.of(
Key.EXTRA_INFO, Key.PUBLISHED);
/**
* Define keys that MAY occur zero or one times in any instance of the
* document type, but MUST NOT occur more than once.
*/
private static final Set<Key> atMostOnceKeys = EnumSet.of(
Key.IDENTITY_ED25519, Key.MASTER_KEY_ED25519, Key.READ_HISTORY,
Key.WRITE_HISTORY, Key.DIRREQ_READ_HISTORY, Key.DIRREQ_WRITE_HISTORY,
......@@ -41,6 +72,11 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
super(descriptorBytes, offsetAndLimit, descriptorFile, false);
this.parseDescriptorBytes();
this.checkExactlyOnceKeys(exactlyOnceKeys);
/**
* When a key is added to {@link Key} it needs to be added here too.
* Either directly or to the methods that check the occurrence of the key.
*/
Set<Key> dirreqStatsKeys = EnumSet.of(
Key.DIRREQ_STATS_END, Key.DIRREQ_V2_IPS, Key.DIRREQ_V3_IPS,
Key.DIRREQ_V2_REQS, Key.DIRREQ_V3_REQS, Key.DIRREQ_V2_SHARE,
......@@ -74,6 +110,13 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
this.clearParsedKeys();
}
/**
* Parse the descriptor file.
*
* @throws DescriptorParseException if any of the desriptor lines
* is not valid.
*
*/
private void parseDescriptorBytes() throws DescriptorParseException {
Scanner scanner = this.newScanner().useDelimiter(NL);
Key nextCrypto = Key.EMPTY;
......
......@@ -3,6 +3,17 @@ package org.torproject.descriptor.impl;
import java.util.HashMap;
import java.util.Map;
/**
* Define keys from descriptor document files
*
* The extra-info document format is defined in the dir-spec
* document.
*
* @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
*
* Occurence of each key is checked in the respective implementation class.
*/
public enum Key {
EMPTY("the-empty-key"),
......
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