From f5d63109cc2b4fd16db97b11a2d86c91a2ede3ac Mon Sep 17 00:00:00 2001 From: bischoffz Date: Mon, 8 Jul 2024 23:52:07 -0400 Subject: [PATCH] update javadoc --- ...upport.java => TranslatorTestSupport.java} | 22 +++++-- .../core/translation/ITranslationSpec.java | 25 +++++++- .../core/translation/TranslationSpec.java | 63 ++++++++++--------- .../taskit/core/translation/Translator.java | 34 +++++++--- .../core/translation/TranslatorContext.java | 22 +++++-- .../taskit/core/translation/TranslatorId.java | 2 +- ...ort.java => AT_TranslatorTestSupport.java} | 8 +-- 7 files changed, 122 insertions(+), 54 deletions(-) rename core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/{TranslationSpecSupport.java => TranslatorTestSupport.java} (79%) rename core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/{AT_TranslationSpecSupport.java => AT_TranslatorTestSupport.java} (69%) diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslationSpecSupport.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslatorTestSupport.java similarity index 79% rename from core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslationSpecSupport.java rename to core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslatorTestSupport.java index 2d1d3a8..cde530d 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslationSpecSupport.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslatorTestSupport.java @@ -10,15 +10,29 @@ import gov.hhs.aspr.ms.taskit.core.translation.TranslationSpec; import gov.hhs.aspr.ms.util.resourcehelper.ResourceHelper; -public class TranslationSpecSupport { +/** + * Class to help test Translators and their internal list of translation specs + */ +public class TranslatorTestSupport { - private TranslationSpecSupport() {} - /* + private TranslatorTestSupport() { + } + + /** * This method is to ensure that every translationSpec that is supposed to be * tied to a Translator is defined in its list of translationSpecs. If a * translationSpec is added and not subsequently added to the list in the * Translator, then this test will fail and provide the name of the missing * TranslationSpec + * + * @param the type of the translator + * @param translatorClassRef the classRef of the translator + * @param translationSpecs the list of translation specs defined in the + * translator + * @return a set containing any missing translationSpecs defined in the + * translation.spec package for which the translator is located + * @throws ClassNotFoundException if the class loader cannot load a class + * */ public static Set testGetTranslationSpecs(Class translatorClassRef, List> translationSpecs) throws ClassNotFoundException { @@ -58,7 +72,7 @@ public static Set testGetTranslationSpecs(Class translatorClassRe className = packageName + "." + className.substring(0, className.length() - 6); Class classRef = classLoader.loadClass(className); - if(!translationSpecClasses.contains(classRef)) { + if (!translationSpecClasses.contains(classRef)) { missingTranslationSpecs.add(classRef.getSimpleName()); } } diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/ITranslationSpec.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/ITranslationSpec.java index cc32058..4f64ec2 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/ITranslationSpec.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/ITranslationSpec.java @@ -6,9 +6,28 @@ * Interface for TranslationSpecifications (TranslationSpecs) */ public interface ITranslationSpec { - void init(T taskitEngine); - T translate(Object object); + /** + * Initializes the translation spec with the given taskitEngine + * + * @param the type of the taskitEngine + * @param taskitEngine the taskitEngine the translationSpec should be + * initialized with + */ + public void init(T taskitEngine); - boolean isInitialized(); + /** + * Given an object, translates it if the translationSpec knows how to translate + * it + * + * @param the translated type + * @param object the object to translate + * @return the translated object + */ + public T translate(Object object); + + /** + * @return the initialized flag of this translation spec + */ + public boolean isInitialized(); } diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslationSpec.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslationSpec.java index f02c6cb..d9d0666 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslationSpec.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslationSpec.java @@ -18,36 +18,34 @@ public abstract class TranslationSpec implements ITranslationSpec { private boolean initialized = false; /** - * Initializes this translationSpec. All child TranslationSpecs must call - * super() otherwise there will be an exception throw in the TaskitEngine + * @implNote All child TranslationSpecs must call + * super() otherwise there will be an exception throw in the + * TaskitEngine */ public void init(T taskitEngine) { this.initialized = true; } - /** - * Returns the initialization state of this TranslationSpec - */ public boolean isInitialized() { return this.initialized; } /** - * The implementation of the {@link ITranslationSpec#translate(Object)} method - * Given the object, determines which method should be called. - *

- * It first checks if the object class is exactly equal to either the App or - * Input Class and if so, calls the related method - *

- *

- * It then checks if the the object class is assignable from either the App or - * Input Class and if so, calls the related method - *

- *

- * If no match can be found, an exception is thrown - *

- * - * @param the expected return type after translation/conversion + * @implNote The implementation of the + * {@link ITranslationSpec#translate(Object)} method + *

+ * It first checks if the object class is exactly equal to either the + * App or + * Input Class and if so, calls the related method + *

+ *

+ * It then checks if the the object class is assignable from either + * the App or + * Input Class and if so, calls the related method + *

+ *

+ * If no match can be found, an exception is thrown + *

* @throws ContractException {@linkplain TaskitCoreError#UNKNOWN_OBJECT} if * no match can be found between the passed in object * and the given appClass and InputClass @@ -84,15 +82,14 @@ public int hashCode() { @Override public boolean equals(Object obj) { - // if same object, then equal if (this == obj) { return true; } - // if obj is null, not equal + if (obj == null) { return false; } - // if obj is not an instance of TranslationSpec, not equal + if (!(obj instanceof TranslationSpec)) { return false; } @@ -115,26 +112,36 @@ public boolean equals(Object obj) { } /** - * Given an inputObject, translates it to it's appObject equivalent + * Translates the given object to its corresponding app type + * + * @param inputObject the input object to translate + * @return the translated object */ protected abstract A translateInputObject(I inputObject); /** - * Given an appObject, translates it to it's inputObject equivalent + * Translates the given object to its corresponding input type + * + * @param appObject the app object to translate + * @return the translated object */ protected abstract I translateAppObject(A appObject); /** - * Returns the class of the app object + * @return the class of the app type */ public abstract Class getAppObjectClass(); /** - * Returns the class of the input object + * @return the class of the input type */ public abstract Class getInputObjectClass(); - void checkInit() { + /* + * checks the initialized flag on this translation spec and throws an exception + * if it has not been initialized + */ + private void checkInit() { if (!this.initialized) { throw new ContractException(TaskitCoreError.UNINITIALIZED_TRANSLATION_SPEC); } diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/Translator.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/Translator.java index 92c0ef2..8ae54b2 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/Translator.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/Translator.java @@ -22,7 +22,7 @@ private Translator(Data data) { this.data = data; } - final static class Data { + private final static class Data { private TranslatorId translatorId; private Consumer initializer; private final Set dependencies = new LinkedHashSet<>(); @@ -52,6 +52,9 @@ public boolean equals(Object obj) { } + /** + * Builder for the Translator + */ public final static class Builder { private Data data; @@ -71,6 +74,8 @@ private void validate() { /** * Builds the Translator * + * @return the built translator + * * @throws ContractException *
    *
  • {@linkplain TaskitCoreError#NULL_TRANSLATOR_ID} @@ -86,8 +91,10 @@ public Translator build() { } /** - * Sets the translatorId + * Sets the translatorId for this Translator * + * @param translatorId the translatorId to set + * @return the builder instance * @throws ContractException {@linkplain TaskitCoreError#NULL_TRANSLATOR_ID} * if the translatorId is null */ @@ -102,8 +109,10 @@ public Builder setTranslatorId(TranslatorId translatorId) { } /** - * Sets the initialization callback for the translator + * Sets the initialization consumer for this translator * + * @param initConsumer the consumer to use for initialization + * @return the builder instance * @throws ContractException {@linkplain TaskitCoreError#NULL_INIT_CONSUMER} * if the initConsumer is null */ @@ -118,7 +127,11 @@ public Builder setInitializer(Consumer initConsumer) { } /** - * Adds the given TranslatorId as a dependency for this Translator + * Adds a dependency for this Translator + * + * @param dependency the translatorId of the translator this translator should + * depend on + * @return the builder instance * * @throws ContractException *
      @@ -146,6 +159,8 @@ public Builder addDependency(TranslatorId dependency) { /** * Creates a new Builder for a Translator + * + * @return a new Builder for a Translator */ public static Builder builder() { return new Builder(new Data()); @@ -159,21 +174,24 @@ Consumer getInitializer() { } /** - * Returns the TranslatorId + * @return the TranslatorId for this Translator */ public TranslatorId getTranslatorId() { return this.data.translatorId; } /** - * Returns the set of Dependencies + * @return the set of dependencies for this Translator */ public Set getTranslatorDependencies() { return this.data.dependencies; } /** - * sets the initialized flag on this translator to true + * Initializes this translator using its initialization consumer + * + * @param translatorContext the translator context to pass to the initialization + * consumer */ public void initialize(TranslatorContext translatorContext) { this.data.initializer.accept(translatorContext); @@ -181,7 +199,7 @@ public void initialize(TranslatorContext translatorContext) { } /** - * Returns the initialized flag of this translator + * @return the initialized flag of this translator */ public boolean isInitialized() { return this.initialized; diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorContext.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorContext.java index 410bdee..0912733 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorContext.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorContext.java @@ -5,10 +5,11 @@ import gov.hhs.aspr.ms.util.errors.ContractException; /** - * Context that is used by {@link Translator}s - * - * Note: This class exists because the subclassed TaskitEngine may have - * different build methods than the abstract one, preventing the associated + * Context that is used by {@link Translator}s for initialization + *

      + * Note: This class exists because the TaskitEngine instance used by a + * Translator may have + * different build methods, preventing the associated * consumer that this context is used in from just being a consumer of a * ITaskitEngineBuilder */ @@ -16,14 +17,23 @@ public final class TranslatorContext { private final ITaskitEngineBuilder builder; + /** + * Constructor for the Translator Context + * + * @param builder the builder of the TaskitEngine + */ public TranslatorContext(ITaskitEngineBuilder builder) { this.builder = builder; } /** - * Returns an instance of the TaskitEngine Builder + * Gets the taskit engine builder for this context + *

      + * see note on this class for the usage of this method * - * @param the type of the TaskitEngine + * @param the type of the TaskitEngine + * @param classRef the classRef of the TaskitEngine type + * @return the taskitEngineBuilder * @throws ContractException {@linkplain TaskitCoreError#INVALID_TASKIT_ENGINE_BUILDER_CLASS_REF} * if the given classRef does not match the class or * the taskitEngineBuilder is null diff --git a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorId.java b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorId.java index f8e0111..dd03bdc 100644 --- a/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorId.java +++ b/core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorId.java @@ -1,7 +1,7 @@ package gov.hhs.aspr.ms.taskit.core.translation; /** - * Used as a {@link Translator} identifier + * a {@link Translator} identifier */ public interface TranslatorId { /** diff --git a/core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslationSpecSupport.java b/core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslatorTestSupport.java similarity index 69% rename from core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslationSpecSupport.java rename to core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslatorTestSupport.java index 2748ae1..dc9fd04 100644 --- a/core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslationSpecSupport.java +++ b/core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslatorTestSupport.java @@ -13,20 +13,20 @@ import gov.hhs.aspr.ms.taskit.core.translation.TranslationSpec; import gov.hhs.aspr.ms.util.annotations.UnitTestMethod; -public class AT_TranslationSpecSupport { +public class AT_TranslatorTestSupport { @Test - @UnitTestMethod(target = TranslationSpecSupport.class, name = "testGetTranslationSpecs", args = {Class.class, List.class}) + @UnitTestMethod(target = TranslatorTestSupport.class, name = "testGetTranslationSpecs", args = {Class.class, List.class}) public void testTestGetTranslationSpecs() throws ClassNotFoundException { List> translationSpecs = new ArrayList<>(); translationSpecs.add(new TestObjectTranslationSpec()); - Set missingSpecs = TranslationSpecSupport.testGetTranslationSpecs(TestObjectTranslator.class, translationSpecs); + Set missingSpecs = TranslatorTestSupport.testGetTranslationSpecs(TestObjectTranslator.class, translationSpecs); assertTrue(missingSpecs.isEmpty()); - missingSpecs = TranslationSpecSupport.testGetTranslationSpecs(TestObjectTranslator.class, new ArrayList<>()); + missingSpecs = TranslatorTestSupport.testGetTranslationSpecs(TestObjectTranslator.class, new ArrayList<>()); assertTrue(missingSpecs.size() == 1); assertTrue(missingSpecs.contains(TestObjectTranslationSpec.class.getSimpleName()));