Config editor: adding javadoc for config editor core (#821)

* adding javadoc for config editor core

* adding more comments

* fixes based on the review

* fixing typos

Author: mariannovotny

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/AuthorisationProvider.java

@@ -1,11 +1,25 @@
 package uk.co.gresearch.siembol.configeditor.common;
-
+/**
+ * An object for providing authorisation for Siembol services
+ *
+ * <p>This interface is for providing authorisation for a Siembol service.
+ * It decides whether the user is allowed to access a service under its role.
+ *
+ * @author  Marian Novotny
+ *
+ */
 public interface AuthorisationProvider {
     enum AuthorisationResult {
         UNDEFINED,
         ALLOWED,
         FORBIDDEN,
     }
 
+    /**
+     * Gets authorisation decision for a user and a service
+     * @param user a user info object
+     * @param serviceName the name of teh service
+     * @return the authorisation result
+     */
     AuthorisationResult getUserAuthorisation(UserInfo user, String serviceName);
 }

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigEditorUtils.java

@@ -16,7 +16,13 @@
 import java.io.*;
 import java.lang.invoke.MethodHandles;
 import java.util.*;
-
+/**
+ * A class with static helper methods for config editor
+ *
+ * <p>This class exposes static helper methods for config editor.
+ *
+ * @author  Marian Novotny
+ */
 public class ConfigEditorUtils {
     private static final Logger LOG = LoggerFactory
             .getLogger(MethodHandles.lookup().lookupClass());

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigImporter.java

@@ -1,9 +1,37 @@
 package uk.co.gresearch.siembol.configeditor.common;
 
 import uk.co.gresearch.siembol.configeditor.model.ConfigEditorResult;
-
+/**
+ * An object for importing configurations
+ *
+ * <p>This interface is for providing functionality for importing open standard configuration into Siembol.
+ * Moreover, it validates attributes and provides importer attributes schema.
+ *
+ * @author  Marian Novotny
+ *
+ */
 public interface ConfigImporter {
+    /**
+     * Gets a json schema for importer attributes
+     * @return config editor result with json schema
+     */
     ConfigEditorResult getImporterAttributesSchema();
+
+    /**
+     * Validates importer attributes
+     * @param attributes a json string with importer attributes
+     * @return config editor result with OK status code if the attributes are valid, otherwise
+     *         the result with ERROR status.
+     */
     ConfigEditorResult validateImporterAttributes(String attributes);
+
+    /**
+     * Imports open standard configuration into Siembol syntax
+     * @param user a user info object
+     * @param importerAttributes a json string with importer attributes
+     * @param configuration configuration for importing into Siembol
+     * @return config editor result with OK status code and the imported config if the import was successful, otherwise
+     *         the result with ERROR status.
+     */
     ConfigEditorResult importConfig(UserInfo user, String importerAttributes, String configuration);
 }

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigInfo.java

@@ -2,7 +2,14 @@
 
 import java.util.Map;
 import java.util.Optional;
-
+/**
+ * An object that represents information about a configuration change
+ *
+ * <p>This class represents information about configuration change such as the name of the configuration,
+ * its version, content etc.
+ *
+ * @author  Marian Novotny
+ */
 public class ConfigInfo {
     private String name;
     private Map<String, Optional<String>> filesContent;

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigInfoType.java

@@ -1,5 +1,13 @@
 package uk.co.gresearch.siembol.configeditor.common;
-
+/**
+ * An enum of configuration types
+ *
+ * @author  Marian Novotny
+ * @see #RULE
+ * @see #CONFIG
+ * @see #TEST_CASE
+ * @see #ADMIN_CONFIG
+ */
 public enum ConfigInfoType {
     RULE("rule", "rules", "Rules"),
     CONFIG("configuration", "configurations", "Configurations"),

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigSchemaService.java

@@ -4,35 +4,82 @@
 import uk.co.gresearch.siembol.configeditor.model.*;
 
 import java.util.ArrayList;
-import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
 import static uk.co.gresearch.siembol.configeditor.model.ConfigEditorResult.StatusCode.OK;
-
+/**
+ * An object for configuration schema service
+ *
+ * <p>This interface is for providing functionality for configuration schema service.
+ * It validates configurations, and provides a json schema.
+ * it provides config importers and testers registered for the service.
+ *
+ * @author  Marian Novotny
+ * @see ConfigTester
+ * @see ConfigImporter
+ *
+ */
 public interface ConfigSchemaService extends HealthCheckable {
     String NOT_IMPLEMENTED_MSG = "Not implemented";
     String SCHEMA_INIT_ERROR = "Error during computing json schema";
 
+    /**
+     * Gets a json schema for configurations
+     * @return a config editor result with a json schema for configurations
+     */
     ConfigEditorResult getSchema();
 
+    /**
+     * Validates a configuration
+     * @param configuration a json string with configuration
+     * @return a config editor result with OK status code if the configuration is valid, otherwise
+     *         the result with ERROR status.
+     */
     ConfigEditorResult validateConfiguration(String configuration);
 
+    /**
+     * Validates configurations
+     * @param configurations a json string with configurations
+     * @return a config editor result with OK status code if the configurations are valid, otherwise
+     *         the result with ERROR status.
+     */
     ConfigEditorResult validateConfigurations(String configurations);
 
+    /**
+     * Gets config importers
+     * @return the map of an importer name string to a config importer object
+     */
     Map<String, ConfigImporter> getConfigImporters();
 
+    /**
+     * Gets config testers
+     * @return a config editor result with config testers registered for the service
+     */
     default ConfigEditorResult getConfigTesters() {
         ConfigEditorAttributes attributes = new ConfigEditorAttributes();
         attributes.setConfigTesters(new ArrayList<>());
         return new ConfigEditorResult(OK, attributes);
     }
 
+    /**
+     * Gets a config tester by name
+     * @return a config tester
+     */
     ConfigTester getConfigTester(String name);
 
+    /**
+     * Checks a health of the service
+     * @return health object with the status
+     * @see Health
+     */
     default Health checkHealth() { return Health.up().build(); }
 
+    /**
+     * Get config importers
+     * @return config editor result with config importers
+     */
     default ConfigEditorResult getImporters() {
         List<ConfigImporterDto> importers = getConfigImporters().entrySet().stream().map(x -> {
             ConfigImporterDto importer = new ConfigImporterDto();
@@ -46,7 +93,19 @@ default ConfigEditorResult getImporters() {
         return new ConfigEditorResult(OK, attributes);
     }
 
-    default ConfigEditorResult importConfig(UserInfo user, String importerName, String importerAttributes, String configToImport) {
+    /**
+     * Imports a config into a service syntax
+     * @param user a user info object
+     * @param importerName the name of the importer
+     * @param importerAttributes a json string with importer attributes
+     * @param configToImport a string with configuration to be imported
+     * @return config editor result with OK status code and the imported config if the import was successful, otherwise
+     *         the result with ERROR status.
+     */
+    default ConfigEditorResult importConfig(UserInfo user,
+                                            String importerName,
+                                            String importerAttributes,
+                                            String configToImport) {
         if (!getConfigImporters().containsKey(importerName)) {
             return  ConfigEditorResult.fromMessage(ConfigEditorResult.StatusCode.BAD_REQUEST,
                     ErrorMessages.UNKNOWN_CONFIG_IMPORTER.getMessage(importerName));
@@ -67,18 +126,38 @@ default ConfigEditorResult importConfig(UserInfo user, String importerName, Stri
         return importResult;
     }
 
+    /**
+     * Gets a json schema for an admin configuration
+     * @return a config editor result with a json schema for an admin configuration
+     */
     default ConfigEditorResult getAdminConfigurationSchema() {
         return ConfigEditorResult.fromMessage(ConfigEditorResult.StatusCode.ERROR, NOT_IMPLEMENTED_MSG);
     }
 
+    /**
+     * Validates an admin configuration
+     * @param configuration a json string with an admin configuration
+     * @return a config editor result with OK status code if the admin configuration is valid, otherwise
+     *         the result with ERROR status.
+     */
     default ConfigEditorResult validateAdminConfiguration(String configuration) {
         return ConfigEditorResult.fromMessage(ConfigEditorResult.StatusCode.ERROR, NOT_IMPLEMENTED_MSG);
     }
 
+    /**
+     * Gets a topology name from an admin configuration
+     * @param configuration a json string with an admin configuration
+     * @return a config editor result with the topology name on success, otherwise
+     *         the result with ERROR status.
+     */
     default ConfigEditorResult getAdminConfigTopologyName(String configuration) {
         return ConfigEditorResult.fromMessage(ConfigEditorResult.StatusCode.ERROR, NOT_IMPLEMENTED_MSG);
     }
 
+    /**
+     * Get a config schema service with enhanced error messages
+     * @return a config schema service with enhanced error messages
+     */
     default ConfigSchemaService withErrorMessage() {
         return new ConfigSchemaServiceWithErrorMessage(this);
     }

config-editor/config-editor-core/src/main/java/uk/co/gresearch/siembol/configeditor/common/ConfigSchemaServiceWithErrorMessage.java

@@ -8,19 +8,34 @@
 
 import java.util.Map;
 import java.util.function.Supplier;
-
+/**
+ * An object for configuration schema service with enhanced error messages
+ *
+ * <p>This class implements ConfigSchemaService interface, and it extends ServiceWithErrorMessage class.
+ * It enriches error messages on error.
+ *
+ * @author  Marian Novotny
+ * @see ServiceWithErrorMessage
+ * @see ConfigSchemaService
+ */
 public class ConfigSchemaServiceWithErrorMessage extends ServiceWithErrorMessage<ConfigSchemaService>
         implements ConfigSchemaService {
 
     public ConfigSchemaServiceWithErrorMessage(ConfigSchemaService service) {
         super(service);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult getSchema() {
         return service.getSchema();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult validateConfiguration(String configuration) {
         Supplier<ConfigEditorResult> fun = () -> service.validateConfiguration(configuration);
@@ -29,6 +44,9 @@ public ConfigEditorResult validateConfiguration(String configuration) {
                 ErrorResolutions.VALIDATION.getResolution());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult validateConfigurations(String configurations) {
         Supplier<ConfigEditorResult> fun = () -> service.validateConfigurations(configurations);
@@ -37,31 +55,49 @@ public ConfigEditorResult validateConfigurations(String configurations) {
                 ErrorResolutions.VALIDATION.getResolution());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Map<String, ConfigImporter> getConfigImporters() {
         return service.getConfigImporters();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult getConfigTesters() {
         return service.getConfigTesters();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigTester getConfigTester(String name) {
         return service.getConfigTester(name);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Health checkHealth() {
         return service.checkHealth();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult getImporters() {
         return service.getImporters();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult importConfig(UserInfo user,
                                            String importerName,
@@ -74,11 +110,17 @@ public ConfigEditorResult importConfig(UserInfo user,
                 ErrorResolutions.GENERIC_BAD_REQUEST.getResolution());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult getAdminConfigurationSchema() {
         return service.getAdminConfigurationSchema();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult validateAdminConfiguration(String configuration) {
         Supplier<ConfigEditorResult> fun = () -> service.validateAdminConfiguration(configuration);
@@ -87,6 +129,9 @@ public ConfigEditorResult validateAdminConfiguration(String configuration) {
                 ErrorResolutions.VALIDATION.getResolution());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public ConfigEditorResult getAdminConfigTopologyName(String configuration) {
         return service.getAdminConfigTopologyName(configuration);