From 3f0c8487b9cd3144f5fb07f2d70672574d8c6334 Mon Sep 17 00:00:00 2001 From: anhefti Date: Sat, 8 Jun 2019 20:30:03 +0200 Subject: [PATCH] API doc --- .../sebconfig/SebClientConfigService.java | 2 ++ .../sebconfig/SebConfigCryptor.java | 6 ++--- .../sebconfig/SebConfigEncryptionService.java | 1 + .../sebconfig/SebExamConfigService.java | 24 +++++++++++++++++++ .../sebconfig/XMLValueConverter.java | 19 +++++++++++++++ .../sebconfig/XMLValueConverterService.java | 5 ++++ .../servicelayer/sebconfig/ZipService.java | 13 ++++++++++ 7 files changed, 66 insertions(+), 4 deletions(-) diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebClientConfigService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebClientConfigService.java index ba4f8cae..7d5ebdbf 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebClientConfigService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebClientConfigService.java @@ -60,6 +60,8 @@ public interface SebClientConfigService { Result autoCreateSebClientConfigurationForInstitution(Long institutionId); /** Use this to export a specified SebClientConfiguration within a given OutputStream. + * The SEB Client Configuration is exported in the defined SEB Configuration format + * as described here: https://www.safeexambrowser.org/developer/seb-file-format.html * * @param out OutputStream to write the export to * @param modelId the model identifier of the SebClientConfiguration to export */ diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigCryptor.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigCryptor.java index 25c8f2a1..5003c6fe 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigCryptor.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigCryptor.java @@ -29,8 +29,7 @@ public interface SebConfigCryptor { Set strategies(); /** Encrypt an incoming plain data stream to an outgoing cipher data stream - * - * IMPORTANT: This must run in a separated thread + * This uses Springs @Async annotation to run in a separated thread * * @param output the output stream to write encrypted data to * @param input the input stream to read plain data from @@ -42,8 +41,7 @@ public interface SebConfigCryptor { final SebConfigEncryptionContext context); /** Decrypt an incoming cipher data stream to an outgoing plain text data stream - * - * IMPORTANT: This must run in a separated thread + * This uses Springs @Async annotation to run in a separated thread * * @param output the output stream to write the plain text data to * @param input the input stream to read the cipher text from diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigEncryptionService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigEncryptionService.java index 8b628e7c..8077e231 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigEncryptionService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebConfigEncryptionService.java @@ -16,6 +16,7 @@ import java.util.function.Supplier; import ch.ethz.seb.sebserver.gbl.util.Utils; +/** Used for SEB Configuration encryption and decryption */ public interface SebConfigEncryptionService { /** Types of encryption strategies */ diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebExamConfigService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebExamConfigService.java index d7d0ec3a..19c49477 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebExamConfigService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/SebExamConfigService.java @@ -17,14 +17,38 @@ import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationValue; /** The base interface and service for all SEB Exam Configuration related functionality. */ public interface SebExamConfigService { + /** Validates a given ConfigurationValue by using registered ConfigurationValueValodator + * beans to find a proper validator for the specified ConfigurationValue + * + * @param value The ConfigurationValue to validate + * @throws FieldValidationException on validation exception */ void validate(ConfigurationValue value) throws FieldValidationException; + /** Validates a ConfigurationTableValues container by extracting each value and + * validate each, collecting the error if there are some. + * + * @param tableValue The ConfigurationTableValues container + * @throws FieldValidationException on validation exception */ void validate(ConfigurationTableValues tableValue) throws FieldValidationException; + /** Used to export a specified SEB Exam Configuration as plain XML + * This exports the values of the follow-up configuration defined by a given + * ConfigurationNode (configurationNodeId) + * + * @param out The output stream to write the plain XML text to. + * @param institutionId The identifier of the institution of the requesting user + * @param configurationNodeId the identifier of the ConfigurationNode to export */ void exportPlainXML(OutputStream out, Long institutionId, Long configurationNodeId); + /** Used to export a SEB Exam Configuration within its defined Configuration Exam Mapping. + * either with encryption if defined or as plain text within the SEB Configuration format + * as described here: https://www.safeexambrowser.org/developer/seb-file-format.html + * + * @param out The output stream to write the export data to + * @param configExamMappingId The identifier of the Exam Configuration Mapping */ void exportForExam(OutputStream out, Long configExamMappingId); + /** TODO */ String generateConfigKey(Long configurationNodeId); } diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverter.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverter.java index ae64ed3e..baf8b650 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverter.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverter.java @@ -16,12 +16,31 @@ import ch.ethz.seb.sebserver.gbl.model.sebconfig.AttributeType; import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationAttribute; import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationValue; +/** Defines the interface of a XML converter to be used to convert + * ConfigurationValue for defined ConfigurationAttribute */ public interface XMLValueConverter { + /** Gives a Set of AttributeType's a concrete converter is able to + * handle and convert ConfigurationValue of attributes of given types. + * + * @return a Set of supported AttributeType's of the converter */ Set types(); + /** The name of the Converter. This can be used if a Converter is specific to + * an ConfigurationAttribute and not specific on a type of attribute. + * This must give either the name if a specific ConfigurationAttribute or null/emptyString + * + * @return The name of a specific ConfigurationAttribute the converter works for. */ String name(); + /** Used to convert the a given ConfigurationAttribute / ConfigurationValue + * pair to plain XML text for block of this SEB Configuration attribute. + * + * @param out The output stream to write the plain XML text block to + * @param attribute The ConfigurationAttribute containing all attribute information + * @param value The ConfigurationValue containing the value + * @param xmlValueConverterService + * @throws IOException */ void convertToXML( OutputStream out, ConfigurationAttribute attribute, diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverterService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverterService.java index e9d6b889..0e0ff16b 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverterService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/XMLValueConverterService.java @@ -10,8 +10,13 @@ package ch.ethz.seb.sebserver.webservice.servicelayer.sebconfig; import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationAttribute; +/** Interface of a SEB Exam Configuration XML conversion service */ public interface XMLValueConverterService { + /** Use this to get a XMLValueConverter for a given ConfigurationAttribute. + * + * @param attribute The ConfigurationAttribute instance + * @return a XMLValueConverter for a given ConfigurationAttribute */ XMLValueConverter getXMLConverter(ConfigurationAttribute attribute); } diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ZipService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ZipService.java index 6f12b216..d11a46fe 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ZipService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ZipService.java @@ -15,11 +15,24 @@ import org.springframework.scheduling.annotation.Async; import ch.ethz.seb.sebserver.gbl.async.AsyncServiceSpringConfig; +/** A Zip service that can be used to compress or uncompress a given data stream. */ public interface ZipService { + /** Use this to read uncompressed data from a given input-stream, + * compress this data with gzip and write the compressed data to + * a given output stream. + * + * @param out the OutputStream to write the compressed data to + * @param in the InputStream to read the uncompressed data from */ @Async(AsyncServiceSpringConfig.EXECUTOR_BEAN_NAME) void write(OutputStream out, InputStream in); + /** Use this to read gzip-compressed data from a given input-stream, + * uncompress this data and write the uncompressed data to + * a given output stream. + * + * @param out the OutputStream to write the uncompressed data to + * @param in the InputStream to read the compressed data from */ @Async(AsyncServiceSpringConfig.EXECUTOR_BEAN_NAME) void read(OutputStream out, InputStream in);