From 2b56928e9ace0f93dc4167d1adb15542656db6c3 Mon Sep 17 00:00:00 2001 From: Hai Brenner Date: Mon, 4 Jul 2016 11:54:36 +0300 Subject: [PATCH] added some JavaDoc comments and documentation --- .../SimpleListCategoriesSelector.java | 10 +++-- .../voting/encryptor/VBCryptoManager.java | 1 + .../voting/encryptor/VBCryptoManagerImpl.java | 4 +- .../output/AsyncRunnableOutputDevice.java | 42 ++++++++++++++----- .../voting/output/BallotOutputDevice.java | 5 ++- .../voting/output/NetworkVirtualPrinter.java | 23 +++++++--- .../output/SystemConsoleOutputDevice.java | 27 ++++++++---- .../outputcommands/AuditOutputCommand.java | 2 +- .../outputcommands/CancelOutputCommand.java | 2 +- .../outputcommands/CastOutputCommand.java | 2 +- .../outputcommands/CommitOutputCommand.java | 2 +- .../output/outputcommands/OutputCommand.java | 4 +- 12 files changed, 90 insertions(+), 34 deletions(-) diff --git a/voting-booth/src/main/java/meerkat/voting/controller/selector/SimpleListCategoriesSelector.java b/voting-booth/src/main/java/meerkat/voting/controller/selector/SimpleListCategoriesSelector.java index 7f2af87..b39fede 100644 --- a/voting-booth/src/main/java/meerkat/voting/controller/selector/SimpleListCategoriesSelector.java +++ b/voting-booth/src/main/java/meerkat/voting/controller/selector/SimpleListCategoriesSelector.java @@ -69,7 +69,7 @@ public class SimpleListCategoriesSelector implements QuestionSelector { assertDataValid(); } - /* + /** * asserts that the selection data does not contain a question index which is beyond the length of * the ballot race questions array. Otherwise, throws an IndexOutOfBoundsException */ @@ -130,9 +130,11 @@ public class SimpleListCategoriesSelector implements QuestionSelector { return isSelected; } - /* + /** * Verifies that the ballot answer is of length 1. (We do not yet handle multi-choice questions in the channel choice round). * Otherwise, throws an exception. + * @param ballotAnswer + * @param questionNumber the number of the question (needed only for error message strings) */ private void assertAnswerLengthIsOne (BallotAnswer ballotAnswer, int questionNumber) { if (ballotAnswer.getAnswerCount() != 1) { @@ -157,8 +159,10 @@ public class SimpleListCategoriesSelector implements QuestionSelector { return selectedQuestions; } - /* + /** * copies a List of Integers into an int[] array of same length + * @param l a list of Integers + * @return an array of ints */ private int[] listToIntArray(List l) { int[] res = new int[l.size()]; diff --git a/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManager.java b/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManager.java index d5216e4..04416f3 100644 --- a/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManager.java +++ b/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManager.java @@ -7,6 +7,7 @@ import java.security.SignatureException; /** * An interface for the encryptor component of the voting booth + * It handles both the encryption and the digital signature */ public interface VBCryptoManager { /** diff --git a/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManagerImpl.java b/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManagerImpl.java index 2bc9729..83fb8b0 100644 --- a/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManagerImpl.java +++ b/voting-booth/src/main/java/meerkat/voting/encryptor/VBCryptoManagerImpl.java @@ -11,13 +11,13 @@ import java.security.SignatureException; import java.util.Random; /** - * Created by hai on 07/06/16. + * A basic implementation of the VBCryptoManager interface */ public class VBCryptoManagerImpl implements VBCryptoManager { protected final static Logger logger = LoggerFactory.getLogger(VBCryptoManagerImpl.class); - private final Random random; + private final Random random; //TODO: Random object should be more cryptographycally secure private final Encryption encryption; private final DigitalSignature digitalSignature; diff --git a/voting-booth/src/main/java/meerkat/voting/output/AsyncRunnableOutputDevice.java b/voting-booth/src/main/java/meerkat/voting/output/AsyncRunnableOutputDevice.java index d4620bb..88dde5b 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/AsyncRunnableOutputDevice.java +++ b/voting-booth/src/main/java/meerkat/voting/output/AsyncRunnableOutputDevice.java @@ -12,7 +12,9 @@ import org.slf4j.LoggerFactory; import java.util.concurrent.LinkedBlockingQueue; /** - * Created by hai on 27/06/16. + * This is a base class for simple OutputDevices which run asynchronously (as a separate thread). + * The methods of the BallotOutputDevice simply register a matching OutputCommand in the instance's queue + * The Runnable.run method simply takes the next registered command and calls the matching (abstract) method */ public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, Runnable { @@ -52,16 +54,10 @@ public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, R queue.clear(); } - - abstract void doCommitToBallot(CommitOutputCommand command); - - abstract void doAudit(AuditOutputCommand command); - - abstract void doCastBallot(CastOutputCommand command); - - abstract void doCancel(CancelOutputCommand command); - - + /** + * chooses the next method to run according to the type of the given OutputCommand + * @param command any valid OutputCommand + */ private void handleSingleCommand(OutputCommand command) { if (command instanceof CommitOutputCommand) { doCommitToBallot((CommitOutputCommand)command); @@ -111,4 +107,28 @@ public abstract class AsyncRunnableOutputDevice implements BallotOutputDevice, R } + /** + * This method should be filled by an extending class. It should have the details of how to commit to a ballot + * @param command + */ + abstract void doCommitToBallot(CommitOutputCommand command); + + /** + * This method should be filled by an extending class. It should have the details of how to audit the ballot + * @param command + */ + abstract void doAudit(AuditOutputCommand command); + + /** + * This method should be filled by an extending class. It should have the details of how to cast the ballot + * @param command + */ + abstract void doCastBallot(CastOutputCommand command); + + /** + * This method should be filled by an extending class. It should have the details of how to cancel the ballot output + * @param command + */ + abstract void doCancel(CancelOutputCommand command); + } diff --git a/voting-booth/src/main/java/meerkat/voting/output/BallotOutputDevice.java b/voting-booth/src/main/java/meerkat/voting/output/BallotOutputDevice.java index 97fa7ed..3909ce3 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/BallotOutputDevice.java +++ b/voting-booth/src/main/java/meerkat/voting/output/BallotOutputDevice.java @@ -20,7 +20,7 @@ public interface BallotOutputDevice { /** * Voter chose 'audit'. Output the ballot secrets to prove correctness of the encryption. - * @param ballotSecrets - the secrtes of the encryption + * @param ballotSecrets - the secrets of the encryption * @param callback - a callback object which expects no return value */ public void audit(BallotSecrets ballotSecrets, FutureCallback callback); @@ -37,5 +37,8 @@ public interface BallotOutputDevice { */ public void cancelBallot(FutureCallback callback); + /** + * A method for shutting down the Output Device + */ public void callShutDown(); } diff --git a/voting-booth/src/main/java/meerkat/voting/output/NetworkVirtualPrinter.java b/voting-booth/src/main/java/meerkat/voting/output/NetworkVirtualPrinter.java index f65959f..05be623 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/NetworkVirtualPrinter.java +++ b/voting-booth/src/main/java/meerkat/voting/output/NetworkVirtualPrinter.java @@ -20,20 +20,17 @@ import java.io.IOException; import static meerkat.pollingstation.PollingStationConstants.POLLING_STATION_WEB_SCANNER_SCAN_PATH; /** - * Created by hai on 27/06/16. + * A ballot output device for the network. It simply sends details over the wire */ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice { - private Logger logger; + private static final Logger logger = LoggerFactory.getLogger(NetworkVirtualPrinter.class); private SignedEncryptedBallot signedEncryptedBallot; private final WebTarget successfulPrintTarget; public NetworkVirtualPrinter(String address) { super(); - - logger = LoggerFactory.getLogger(NetworkVirtualPrinter.class); logger.info("A NetworkVirtualPrinter is constructed"); - Client client = ClientBuilder.newClient(); client.register(ProtobufMessageBodyReader.class); client.register(ProtobufMessageBodyWriter.class); @@ -41,6 +38,12 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice { } + /** + * The NetworkVirtualPrinter actually does nothing for committing. + * It simply keeps the ballot details for later. + * When the voter chooses to Cast the ballot, these details are sent over the wire. + * @param command a CommitOutputCommand with the signed encryption of the ballot + */ public void doCommitToBallot(CommitOutputCommand command) { logger.debug("entered method doCommitToBallot"); signedEncryptedBallot = command.getSignedEncryptedBallot(); @@ -48,6 +51,9 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice { } + /** + * The NetworkVirtualPrinter actually does nothing for auditing. + */ public void doAudit(AuditOutputCommand command) { logger.debug("entered method doAudit"); signedEncryptedBallot = null; @@ -55,6 +61,10 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice { } + /** + * This is where the magic happens. The signed encrypted ballot is transmitted over the wire + * @param command + */ public void doCastBallot(CastOutputCommand command) { logger.debug("entered method doCastBallot"); ScannedData scannedData = ScannedData.newBuilder() @@ -75,6 +85,9 @@ public class NetworkVirtualPrinter extends AsyncRunnableOutputDevice { } + /** + * The NetworkVirtualPrinter actually does nothing for canceling. + */ public void doCancel(CancelOutputCommand command) { logger.debug("entered method doCancel"); signedEncryptedBallot = null; diff --git a/voting-booth/src/main/java/meerkat/voting/output/SystemConsoleOutputDevice.java b/voting-booth/src/main/java/meerkat/voting/output/SystemConsoleOutputDevice.java index 62bebe3..c07d8df 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/SystemConsoleOutputDevice.java +++ b/voting-booth/src/main/java/meerkat/voting/output/SystemConsoleOutputDevice.java @@ -13,17 +13,18 @@ import org.slf4j.LoggerFactory; */ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice { - private Logger logger; + private static final Logger logger = LoggerFactory.getLogger(SystemConsoleOutputDevice.class);; public SystemConsoleOutputDevice () { super(); - logger = LoggerFactory.getLogger(SystemConsoleOutputDevice.class); logger.info("A SystemConsoleOutputDevice is constructed"); } - - - + /** + * Committing to the ballot. + * Simply prints to the output stream all the details in the CommitOutputCommand. + * @param command details to commit to, and the callback to call when finished + */ public void doCommitToBallot(CommitOutputCommand command) { logger.debug("entered method doCommitToBallot"); PlaintextBallot plaintextBallot = command.getPlaintext(); @@ -43,16 +44,24 @@ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice { } + /** + * auditing the ballot. + * prints to the output stream the ballot secrets (the encryption randomness and its proof of random generation) + * @param command An auditing command with the callback to finally call + */ public void doAudit(AuditOutputCommand command) { logger.debug("entered method doAudit"); System.out.println("Auditing"); BallotSecrets ballotSecrets = command.getBallotSecrets(); - printEncryptionRandomness (ballotSecrets.getEncryptionRandomness()); + printEncryptionRandomness(ballotSecrets.getEncryptionRandomness()); printRandomnessGenerationProof (ballotSecrets.getProof()); command.getCallback().onSuccess(null); } - + /** + * Casting the ballot (actually does nothing new) + * @param command + */ public void doCastBallot(CastOutputCommand command) { logger.debug("entered method doCastBallot"); System.out.println("Ballot finalized for casting!"); @@ -60,6 +69,10 @@ public class SystemConsoleOutputDevice extends AsyncRunnableOutputDevice { } + /** + * Canceling the ballot (actually does nothing new) + * @param command + */ public void doCancel(CancelOutputCommand command) { logger.debug("entered method doCancel"); System.out.println("Ballot cancelled!"); diff --git a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/AuditOutputCommand.java b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/AuditOutputCommand.java index 2722326..564fb06 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/AuditOutputCommand.java +++ b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/AuditOutputCommand.java @@ -4,7 +4,7 @@ import meerkat.protobuf.Voting.*; import meerkat.voting.controller.callbacks.ControllerCallback; /** - * Created by hai on 15/06/16. + * This OutputCommand supplies the necessary details for outputting Audit information */ public class AuditOutputCommand extends OutputCommand { diff --git a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CancelOutputCommand.java b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CancelOutputCommand.java index 0c360d2..26a0388 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CancelOutputCommand.java +++ b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CancelOutputCommand.java @@ -3,7 +3,7 @@ package meerkat.voting.output.outputcommands; import meerkat.voting.controller.callbacks.ControllerCallback; /** - * Created by hai on 15/06/16. + * This OutputCommand signals the output-device that it should Cancel the rest of the ballot output */ public class CancelOutputCommand extends OutputCommand { diff --git a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CastOutputCommand.java b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CastOutputCommand.java index af7ed30..a89eb1b 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CastOutputCommand.java +++ b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CastOutputCommand.java @@ -3,7 +3,7 @@ package meerkat.voting.output.outputcommands; import meerkat.voting.controller.callbacks.ControllerCallback; /** - * Created by hai on 15/06/16. + * This OutputCommand signals the output-device that the voter wishes to Cast the ballot */ public class CastOutputCommand extends OutputCommand { diff --git a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CommitOutputCommand.java b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CommitOutputCommand.java index dcd52f6..a3bd9ac 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CommitOutputCommand.java +++ b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/CommitOutputCommand.java @@ -4,7 +4,7 @@ import meerkat.protobuf.Voting.*; import meerkat.voting.controller.callbacks.ControllerCallback; /** - * Created by hai on 15/06/16. + * This OutputCommand supplies the necessary details for outputting a commit to the ballot */ public class CommitOutputCommand extends OutputCommand { diff --git a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/OutputCommand.java b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/OutputCommand.java index 8a7c322..7085380 100644 --- a/voting-booth/src/main/java/meerkat/voting/output/outputcommands/OutputCommand.java +++ b/voting-booth/src/main/java/meerkat/voting/output/outputcommands/OutputCommand.java @@ -2,7 +2,9 @@ package meerkat.voting.output.outputcommands; import meerkat.voting.controller.callbacks.ControllerCallback; -//TODO: make this class generic +/** + * Base class for the commands to put in the output-device queue + */ public abstract class OutputCommand { protected final ControllerCallback callback;