update javadoc

core/src/main/java/gov/hhs/aspr/ms/taskit/core/testsupport/TranslationSpecSupport.java → 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 <T>                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 <T> Set<String> testGetTranslationSpecs(Class<T> translatorClassRef,
             List<TranslationSpec<?, ?>> translationSpecs) throws ClassNotFoundException {
@@ -58,7 +72,7 @@ public static <T> Set<String> testGetTranslationSpecs(Class<T> 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());
                 }
             }

core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/ITranslationSpec.java

@@ -6,9 +6,28 @@
  * Interface for TranslationSpecifications (TranslationSpecs)
  */
 public interface ITranslationSpec {
-    <T extends ITaskitEngine> void init(T taskitEngine);
 
-    <T> T translate(Object object);
+    /**
+     * Initializes the translation spec with the given taskitEngine
+     * 
+     * @param <T>          the type of the taskitEngine
+     * @param taskitEngine the taskitEngine the translationSpec should be
+     *                     initialized with
+     */
+    public <T extends ITaskitEngine> void init(T taskitEngine);
 
-    boolean isInitialized();
+    /**
+     * Given an object, translates it if the translationSpec knows how to translate
+     * it
+     * 
+     * @param <T>    the translated type
+     * @param object the object to translate
+     * @return the translated object
+     */
+    public <T> T translate(Object object);
+
+    /**
+     * @return the initialized flag of this translation spec
+     */
+    public boolean isInitialized();
 }

core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslationSpec.java

@@ -18,36 +18,34 @@ public abstract class TranslationSpec<I, A> 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 <T extends ITaskitEngine> 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.
-     * <p>
-     * It first checks if the object class is exactly equal to either the App or
-     * Input Class and if so, calls the related method
-     * </p>
-     * <p>
-     * It then checks if the the object class is assignable from either the App or
-     * Input Class and if so, calls the related method
-     * </p>
-     * <p>
-     * If no match can be found, an exception is thrown
-     * </p>
-     * 
-     * @param <T> the expected return type after translation/conversion
+     * @implNote The implementation of the
+     *           {@link ITranslationSpec#translate(Object)} method
+     *           <p>
+     *           It first checks if the object class is exactly equal to either the
+     *           App or
+     *           Input Class and if so, calls the related method
+     *           </p>
+     *           <p>
+     *           It then checks if the the object class is assignable from either
+     *           the App or
+     *           Input Class and if so, calls the related method
+     *           </p>
+     *           <p>
+     *           If no match can be found, an exception is thrown
+     *           </p>
      * @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<A> getAppObjectClass();
 
     /**
-     * Returns the class of the input object
+     * @return the class of the input type
      */
     public abstract Class<I> 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);
         }

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<TranslatorContext> initializer;
         private final Set<TranslatorId> 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
          *                           <ul>
          *                           <li>{@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<TranslatorContext> 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
          *                           <ul>
@@ -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,29 +174,32 @@ Consumer<TranslatorContext> 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<TranslatorId> 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);
         this.initialized = true;
     }
 
     /**
-     * Returns the initialized flag of this translator
+     * @return the initialized flag of this translator
      */
     public boolean isInitialized() {
         return this.initialized;

core/src/main/java/gov/hhs/aspr/ms/taskit/core/translation/TranslatorContext.java

@@ -5,25 +5,35 @@
 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
+ * <p>
+ * 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
  */
 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
+     * <p>
+     * see note on this class for the usage of this method
      * 
-     * @param <T> the type of the TaskitEngine
+     * @param <T>      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

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 {
     /**

core/src/test/java/gov/hhs/aspr/ms/taskit/core/testsupport/AT_TranslationSpecSupport.java → 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<TranslationSpec<?, ?>> translationSpecs = new ArrayList<>();
 
         translationSpecs.add(new TestObjectTranslationSpec());
 
-        Set<String> missingSpecs = TranslationSpecSupport.testGetTranslationSpecs(TestObjectTranslator.class, translationSpecs);
+        Set<String> 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()));