From 45795c2efcdf9141907e60c3348695aac6cbf0d8 Mon Sep 17 00:00:00 2001 From: Vanessa Teague Date: Thu, 28 Mar 2024 11:31:37 +1100 Subject: [PATCH] Improved commenting. --- .../persistence/entity/Contest.java | 35 +++++++++++-------- .../repository/ContestRepository.java | 8 ++--- .../raireservice/request/ContestRequest.java | 4 +-- .../request/GenerateAssertionsRequest.java | 9 +++++ .../request/GetAssertionsRequest.java | 9 ++++- .../request/RequestValidationException.java | 9 +++++ .../repository/ContestRepositoryTests.java | 20 +++++------ 7 files changed, 61 insertions(+), 33 deletions(-) diff --git a/src/main/java/au/org/democracydevelopers/raireservice/persistence/entity/Contest.java b/src/main/java/au/org/democracydevelopers/raireservice/persistence/entity/Contest.java index 06e1b43..4681c6e 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/persistence/entity/Contest.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/persistence/entity/Contest.java @@ -26,7 +26,8 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra /* * A contest class used for reading contest data out of the corla database. * This class omits the fields that are not relevant to input validation - we only care about - * checking whether the request we received makes sense for IRV assertion generation or retrieval. + * checking whether any requests raire-service receives for assertion generation or retrieval make + * sense and are valid. */ @Entity @Table(name = "contest") @@ -47,10 +48,6 @@ public class Contest { @Column(name = "name", nullable = false, updatable = false) private String name; - public String getName() { - return name; - } - /** * Description - should be either IRV or PLURALITY. */ @@ -58,10 +55,6 @@ public String getName() { @Column(name = "description", nullable = false, updatable = false) private String description; - public String getDescription() { - return description; - } - /** * ID of county. */ @@ -69,10 +62,6 @@ public String getDescription() { @Column(name = "county_id", nullable = false, updatable = false) private long countyID; - public long getCountyID() { - return countyID; - } - /** * Version. Used for optimistic locking. */ @@ -80,7 +69,23 @@ public long getCountyID() { @Column(name = "version", nullable = false) private long version; - public long getVersion() { - return version; + /** + * Get the name of the contest. + * @return the name of the contest. + */ + public String getName() { + return name; + } + + /** + * Get the description, either "IRV" or "Plurality". + * @return the description. + */ + public String getDescription() { + return description; + } + + public long getCountyID() { + return countyID; } } \ No newline at end of file diff --git a/src/main/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepository.java b/src/main/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepository.java index b3c2e77..04f92ca 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepository.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepository.java @@ -36,7 +36,7 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra public interface ContestRepository extends JpaRepository { /** - * Select contests by contest name + * Find and return all contests with a given name from the corla database. * Not used except in isAllIRV. * Spring syntactic sugar for the obvious SELECT query. * @param contestName the name of the contest. @@ -45,7 +45,7 @@ public interface ContestRepository extends JpaRepository { List findByName(String contestName); /** - * Find the first contest by name + * Find and return the first contest with a given name from the corla database. * @param contestName the name of the contest. * @return the first of that name, */ @@ -53,7 +53,7 @@ public interface ContestRepository extends JpaRepository { /** - * Select contests by contest ID and county ID. + * Find and return contests by contest ID and county ID. * Contest ID is unique, so at most one result is possible. * @param contestID the ID of the contest * @param countyID the ID of the county @@ -65,9 +65,9 @@ Optional findByContestAndCountyID(@Param("contestID") long contestID, /** * Check whether all the contests of the given name have description 'IRV'. + * Note it does _not_ test for existence - use findFirstByName for that. * @param contestName the name of the contest * @return false if there are any non-IRV descriptions for a contest of that name. - * Note it does _not_ test for existence - use findFirstByName for that. */ default boolean isAllIRV(String contestName) { List contests = findByName(contestName); diff --git a/src/main/java/au/org/democracydevelopers/raireservice/request/ContestRequest.java b/src/main/java/au/org/democracydevelopers/raireservice/request/ContestRequest.java index 572bd42..b60bb84 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/request/ContestRequest.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/request/ContestRequest.java @@ -27,7 +27,7 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra import org.springframework.data.annotation.ReadOnlyProperty; /** - * Request (expected to be json) idenitfying a contest and listing its candidates. + * Request (expected to be json) identifying a contest by name and listing its candidates. * This is an abstract class containing only the core input & validation for contests - * just the contest name and list of candidates, plus basic methods to check that they are * present, non-null and IRV. @@ -66,7 +66,7 @@ public ContestRequest(String contestName, List candidates) { } /** - * Validates the contest request, checking that the contest exists and is an * IRV contest, and + * Validates the contest request, checking that the contest exists and is an IRV contest, and * that the contest request has candidates. Note it does _not_ check whether the candidates are * present in the CVRs. * @param contestRepository the respository for getting Contest objects from the database. diff --git a/src/main/java/au/org/democracydevelopers/raireservice/request/GenerateAssertionsRequest.java b/src/main/java/au/org/democracydevelopers/raireservice/request/GenerateAssertionsRequest.java index 741a809..c88d5e3 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/request/GenerateAssertionsRequest.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/request/GenerateAssertionsRequest.java @@ -27,6 +27,15 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra /** * Request (expected to be json) identifying the contest for which assertions should be generated. * This extends ContestRequest and uses the contest name and candidate list, plus validations, from there. + * A GenerateAssertionsRequest identifies a contest by name along with the candidate list (which + * is necessary for producing the metadata for later visualization). + * TotalAuditableBallots states the total number of ballots in the universe, which may _not_ be the + * same as the number of CVRs that mention the contest. + * TimeLimitSeconds is a limit on the elapsed time that RAIRE has to do assertion generation. + * Validation consists only of checking that the request is reasonable, including calling + * ContestRequest.Validate to check that the contest exists and is all IRV, and that the candidate + * names are reasonable. GenerateAssertionsRequest.Validate then checks that the two numbers, + * totalAuditableBallots and timeLimitSeconds are positive. */ public class GenerateAssertionsRequest extends ContestRequest { diff --git a/src/main/java/au/org/democracydevelopers/raireservice/request/GetAssertionsRequest.java b/src/main/java/au/org/democracydevelopers/raireservice/request/GetAssertionsRequest.java index a12bd25..c06ca4d 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/request/GetAssertionsRequest.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/request/GetAssertionsRequest.java @@ -29,6 +29,13 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra * Request (expected to be json) identifying the contest for which assertions should be retrieved * from the database (expected to be exported as json). * This extends ContestRequest and uses the contest name and candidate list, plus validations, from there. + * A GetAssertionsRequest identifies a contest by name along with the candidate list (which + * is necessary for producing the metadata for later visualization). + * riskLimit states the risk limit for the audit. This is not actually used in raire-service computations, + * but will be output later with the assertion export, so that it can be used in the assertion visualizer. + * Validation consists only of checking that the request is reasonable, including calling + * ContestRequest.Validate to check that the contest exists and is all IRV, and that the candidate + * names are reasonable. GetAssertionsRequest.Validate then checks that the risk limit is non-negative. */ public class GetAssertionsRequest extends ContestRequest { @@ -60,7 +67,7 @@ public GetAssertionsRequest(String contestName, List candidates, BigDeci * Validates the request to retrieve assertions for the contest, checking that the contest exists * and is an IRV contest, that the risk limit has a sensible value, and that there are candidates. * Note it does _not_ check whether the candidates are present in the CVRs. - * @param contestRepository the respository for getting Contest objects from the database. + * @param contestRepository the repository for getting Contest objects from the database. * @throws RequestValidationException if the request is invalid. */ public void Validate(ContestRepository contestRepository) throws RequestValidationException { diff --git a/src/main/java/au/org/democracydevelopers/raireservice/request/RequestValidationException.java b/src/main/java/au/org/democracydevelopers/raireservice/request/RequestValidationException.java index f6271db..1c31ed6 100644 --- a/src/main/java/au/org/democracydevelopers/raireservice/request/RequestValidationException.java +++ b/src/main/java/au/org/democracydevelopers/raireservice/request/RequestValidationException.java @@ -20,6 +20,15 @@ the raire assertion generation engine (https://github.com/DemocracyDevelopers/ra package au.org.democracydevelopers.raireservice.request; +/** + * Exception indicating that a request failed validation. For a ContestRequest (including + * GenerateAssertionsRequest and GetAssertionRequest) this may be because: + * - the contest name is blank, or the candidate list is empty, + * - there is no contest of the requested name in the database, + * - the contest is not an IRV contest, + * - one of the numbers in the request (such as a time limit, risk limit, ballot count) is outside + * the required range. + */ public class RequestValidationException extends Exception { public RequestValidationException(String s) { diff --git a/src/test/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepositoryTests.java b/src/test/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepositoryTests.java index 0220b06..961e108 100644 --- a/src/test/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepositoryTests.java +++ b/src/test/java/au/org/democracydevelopers/raireservice/persistence/repository/ContestRepositoryTests.java @@ -51,7 +51,7 @@ public class ContestRepositoryTests { private static final String ballinaMayoral = "Ballina Mayoral"; /** - * Retrieval of a non-existent contest name retrieves nothing + * Retrieval of a non-existent contest name retrieves nothing. */ @Test @Transactional @@ -61,7 +61,7 @@ void retrieveZeroContests() { } /** - * Retrieval of all of a non-existent contest name retrieves nothing + * Retrieval of all of a non-existent contest name retrieves nothing. */ @Test @Transactional @@ -71,7 +71,7 @@ void retrieveAllZeroContests() { } /** - * Retrieving Ballina Mayoral by name works as expected + * Retrieving Ballina Mayoral by name works as expected. */ @Test @Transactional @@ -82,11 +82,10 @@ void retrieveBallinaMayoral() { assertEquals(ballinaMayoral, ballina.get().getName()); assertEquals("IRV", ballina.get().getDescription()); assertEquals(8L, ballina.get().getCountyID()); - assertEquals(0L, ballina.get().getVersion()); } /** - * Retrieving all matching Ballina Mayoral by name returns one item + * Retrieving all matching Ballina Mayoral by name returns one item. */ @Test @Transactional @@ -96,7 +95,7 @@ void retrieveAllBallinaMayoral() { } /** - * Retrieving all matching "Invalid Mixed Contest" by name returns both items + * Retrieving all matching "Invalid Mixed Contest" by name returns both items. */ @Test @Transactional @@ -116,7 +115,6 @@ void retrievePlurality() { assertEquals("Valid Plurality Contest",plurality.get().getName()); assertEquals("Plurality", plurality.get().getDescription()); assertEquals(10L, plurality.get().getCountyID()); - assertEquals(0L, plurality.get().getVersion()); } /** @@ -162,7 +160,7 @@ void retrieveWronglyByCountyAndContestID2() { } /** - * A single IRV contest is correctly identified as all IRV + * A single IRV contest is correctly identified as all IRV. */ @Test @Transactional @@ -171,7 +169,7 @@ void singleIRVIsAllIRV() { } /** - * A non-existent contest is all IRV + * A non-existent contest is all IRV. */ @Test @Transactional @@ -180,7 +178,7 @@ void multiCountyIRVIsAllIRV() { } /** - * A single Plurality contest is not all IRV + * A single Plurality contest is not all IRV. */ @Test @Transactional @@ -190,7 +188,7 @@ void SinglePluralityIsNotAllIRV() { /** - * A (invalid) mixed contest is not all IRV + * A (invalid) mixed contest is not all IRV. */ @Test @Transactional