feat: Add javadoc and clean up [DHIS2-18321]

dhis-2/dhis-api/src/main/java/org/hisp/dhis/category/CategoryComboStore.java

@@ -40,5 +40,12 @@
 public interface CategoryComboStore extends IdentifiableObjectStore<CategoryCombo> {
   List<CategoryCombo> getCategoryCombosByDimensionType(DataDimensionType dataDimensionType);
 
+  /**
+   * Retrieve all {@link CategoryCombo}s with {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link CategoryCombo}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *     passed in
+   */
   List<CategoryCombo> getByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/category/CategoryOptionStore.java

@@ -30,6 +30,7 @@
 import java.util.Collection;
 import java.util.List;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 import org.hisp.dhis.common.UID;
 import org.hisp.dhis.user.UserDetails;
@@ -49,5 +50,12 @@ public interface CategoryOptionStore extends IdentifiableObjectStore<CategoryOpt
 
   List<CategoryOption> getDataWriteCategoryOptions(Category category, UserDetails userDetails);
 
-  List<CategoryOption> getByCategoryOptionCombo(Collection<UID> uids);
+  /**
+   * Retrieve all {@link CategoryOption}s with {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link CategoryOption}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *     passed in
+   */
+  List<CategoryOption> getByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/category/CategoryService.java

@@ -30,6 +30,7 @@
 import java.util.Collection;
 import java.util.List;
 import java.util.Set;
+import javax.annotation.Nonnull;
 import org.apache.commons.collections4.SetValuedMap;
 import org.hisp.dhis.common.IdScheme;
 import org.hisp.dhis.common.UID;
@@ -478,15 +479,15 @@ CategoryOptionCombo getCategoryOptionCombo(
    * @return categoryOptionCombos with refs to categoryOptions
    */
   List<CategoryOptionCombo> getCategoryOptionCombosByCategoryOption(
-      Collection<UID> categoryOptions);
+      @Nonnull Collection<UID> categoryOptions);
 
   /**
    * Retrieves all CategoryOptionCombos by {@link UID}.
    *
    * @param uids {@link UID}s to search for
    * @return categoryOptionCombos with refs to {@link UID}s
    */
-  List<CategoryOptionCombo> getCategoryOptionCombosByUid(Collection<UID> uids);
+  List<CategoryOptionCombo> getCategoryOptionCombosByUid(@Nonnull Collection<UID> uids);
 
   // -------------------------------------------------------------------------
   // DataElementOperand

dhis-2/dhis-api/src/main/java/org/hisp/dhis/dataapproval/DataApprovalStore.java

@@ -165,7 +165,18 @@ List<DataApprovalStatus> getDataApprovalStatuses(
       List<DataApprovalLevel> userApprovalLevels,
       Map<Integer, DataApprovalLevel> levelMap);
 
+  /**
+   * Retrieve all {@link DataApproval}s with {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link DataApproval}s with {@link CategoryOptionCombo} {@link UID}s passed in
+   */
   List<DataApproval> getByCategoryOptionCombo(@Nonnull Collection<UID> uid);
 
+  /**
+   * Delete all {@link DataApproval}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   */
   void deleteByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/dataelement/DataElementOperandStore.java

@@ -30,6 +30,7 @@
 import java.util.Collection;
 import java.util.List;
 import javax.annotation.Nonnull;
+import org.hisp.dhis.category.CategoryOptionCombo;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 import org.hisp.dhis.common.UID;
 
@@ -39,7 +40,20 @@
 public interface DataElementOperandStore extends IdentifiableObjectStore<DataElementOperand> {
   String ID = DataElementOperand.class.getName();
 
+  /**
+   * Retrieve all {@link DataElementOperand}s with {@link DataElement}s
+   *
+   * @param dataElements {@link DataElement}s
+   * @return {@link DataElementOperand}s with references to {@link DataElement}s passed in
+   */
   List<DataElementOperand> getByDataElement(Collection<DataElement> dataElements);
 
+  /**
+   * Retrieve all {@link DataElementOperand}s with {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link DataElementOperand}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *     passed in
+   */
   List<DataElementOperand> getByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/dataset/CompleteDataSetRegistrationStore.java

@@ -113,7 +113,19 @@ CompleteDataSetRegistration getCompleteDataSetRegistration(
    */
   int getCompleteDataSetCountLastUpdatedAfter(Date lastUpdated);
 
+  /**
+   * Retrieve all {@link CompleteDataSetRegistration}s with {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link CompleteDataSetRegistration}s with references to {@link CategoryOptionCombo}
+   *     {@link UID}s passed in
+   */
   List<CompleteDataSetRegistration> getAllByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 
+  /**
+   * Delete all {@link CompleteDataSetRegistration}s with references to {@link CategoryOptionCombo}s
+   *
+   * @param cocs {@link CategoryOptionCombo}s
+   */
   void deleteByCategoryOptionCombo(@Nonnull Collection<CategoryOptionCombo> cocs);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/datavalue/DataValueAuditStore.java

@@ -28,6 +28,7 @@
 package org.hisp.dhis.datavalue;
 
 import java.util.List;
+import javax.annotation.Nonnull;
 import org.hisp.dhis.category.CategoryOptionCombo;
 import org.hisp.dhis.dataelement.DataElement;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
@@ -75,7 +76,7 @@ public interface DataValueAuditStore {
    *
    * @param categoryOptionCombo the categoryOptionCombo.
    */
-  void deleteDataValueAudits(CategoryOptionCombo categoryOptionCombo);
+  void deleteDataValueAudits(@Nonnull CategoryOptionCombo categoryOptionCombo);
 
   /**
    * Returns data value audits for the given query.

dhis-2/dhis-api/src/main/java/org/hisp/dhis/datavalue/DataValueStore.java

@@ -94,11 +94,26 @@ public interface DataValueStore {
    */
   void deleteDataValues(DataElement dataElement);
 
+  /**
+   * Deletes all data values for the given data element.
+   *
+   * @param dataElement the dataElement.
+   */
   void deleteDataValues(@Nonnull Collection<DataElement> dataElement);
 
+  /**
+   * Deletes all data values for the given category option combos.
+   *
+   * @param categoryOptionCombos the categoryOptionCombos.
+   */
   void deleteDataValuesByCategoryOptionCombo(
       @Nonnull Collection<CategoryOptionCombo> categoryOptionCombos);
 
+  /**
+   * Deletes all data values for the given attribute option combos.
+   *
+   * @param attributeOptionCombos the attributeOptionCombos.
+   */
   void deleteDataValuesByAttributeOptionCombo(
       @Nonnull Collection<CategoryOptionCombo> attributeOptionCombos);
 
@@ -175,6 +190,12 @@ DataValue getDataValue(
    */
   List<DeflatedDataValue> getDeflatedDataValues(DataExportParams params);
 
+  /**
+   * Retrieve all {@link DataValue}s with references to {@link DataElement}s
+   *
+   * @param dataElements {@link DataElement}s
+   * @return {@link DataValue}s with references to {@link DataElement}s passed in
+   */
   List<DataValue> getAllDataValuesByDataElement(List<DataElement> dataElements);
 
   /**

dhis-2/dhis-api/src/main/java/org/hisp/dhis/minmax/MinMaxDataElementStore.java

@@ -34,6 +34,7 @@
 import org.hisp.dhis.common.GenericStore;
 import org.hisp.dhis.common.UID;
 import org.hisp.dhis.dataelement.DataElement;
+import org.hisp.dhis.datavalue.DataValue;
 import org.hisp.dhis.organisationunit.OrganisationUnit;
 
 /**
@@ -61,5 +62,13 @@ MinMaxDataElement get(
 
   List<MinMaxDataElement> getByDataElement(Collection<DataElement> dataElements);
 
+  /**
+   * Retrieve all {@link MinMaxDataElement}s with references to {@link CategoryOptionCombo} {@link
+   * UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link MinMaxDataElement}s with references to {@link CategoryOptionCombo} {@link UID}
+   *     passed in
+   */
   List<MinMaxDataElement> getByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/predictor/PredictorStore.java

@@ -30,9 +30,11 @@
 import java.util.Collection;
 import java.util.List;
 import javax.annotation.Nonnull;
+import org.hisp.dhis.category.CategoryOptionCombo;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 import org.hisp.dhis.common.UID;
 import org.hisp.dhis.dataelement.DataElement;
+import org.hisp.dhis.minmax.MinMaxDataElement;
 
 /**
  * @author Ken Haase
@@ -47,5 +49,11 @@ public interface PredictorStore extends IdentifiableObjectStore<Predictor> {
   List<Predictor> getAllWithSampleSkipTestContainingDataElement(
       @Nonnull List<String> dataElementUids);
 
+  /**
+   * Retrieve all {@link Predictor}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link Predictor}s with references to {@link CategoryOptionCombo} {@link UID} passed in
+   */
   List<Predictor> getByCategoryOptionCombo(@Nonnull Collection<UID> uids);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/program/EventStore.java

@@ -29,6 +29,7 @@
 
 import java.util.Collection;
 import java.util.List;
+import org.hisp.dhis.category.CategoryOptionCombo;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 import org.hisp.dhis.common.UID;
 
@@ -39,7 +40,18 @@ public interface EventStore extends IdentifiableObjectStore<Event> {
 
   List<Event> getAllWithEventDataValuesRootKeysContainingAnyOf(List<String> searchStrings);
 
+  /**
+   * Retrieve all {@link Event}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   * @return {@link Event}s with references to {@link CategoryOptionCombo} {@link UID} passed in
+   */
   List<Event> getAllByAttributeOptionCombo(Collection<UID> uids);
 
+  /**
+   * Delete all {@link Event}s with references to {@link CategoryOptionCombo} {@link UID}s
+   *
+   * @param uids {@link CategoryOptionCombo} {@link UID}s
+   */
   void deleteAllByAttributeOptionCombo(Collection<UID> uids);
 }

dhis-2/dhis-services/dhis-service-administration/src/main/java/org/hisp/dhis/merge/CommonDataMergeHandler.java

@@ -63,6 +63,14 @@ public class CommonDataMergeHandler {
   private final DataValueStore dataValueStore;
   private final EntityManager entityManager;
 
+  /**
+   * Groups {@link DataValue}s into duplicates & non-duplicates. It uses the duplicate predicate
+   * param value to decide whether the {@link DataValue} is considered a duplicate or not. Once
+   * grouped, they are then passed on to be handled accordingly.
+   *
+   * @param merge {@link DataValueMergeParams} to perform merge
+   * @param <T> {@link BaseIdentifiableObject} type
+   */
   public <T extends BaseIdentifiableObject> void handleDataValues(
       @Nonnull DataValueMergeParams<T> merge) {
     Map<Boolean, List<DataValue>> sourceDuplicateList =
@@ -78,11 +86,11 @@ public <T extends BaseIdentifiableObject> void handleDataValues(
   }
 
   /**
-   * Method to handle merging duplicate {@link DataValue}s. There may be multiple potential {@link
-   * DataValue} duplicates. The {@link DataValue} with the latest `lastUpdated` value is filtered
-   * out, the rest are then deleted at the end of the process (We can only have one of these entries
-   * due to the composite key constraint). The filtered-out {@link DataValue} will be compared with
-   * the target {@link DataValue} lastUpdated date.
+   * Handle merging duplicate {@link DataValue}s. There may be multiple potential {@link DataValue}
+   * duplicates. The {@link DataValue} with the latest `lastUpdated` value is filtered out, the rest
+   * are then deleted at the end of the process (We can only have one of these entries due to the
+   * composite key constraint). The filtered-out {@link DataValue} will be compared with the target
+   * {@link DataValue} lastUpdated date.
    *
    * <p>If the target date is later, no action is required.
    *

dhis-2/dhis-services/dhis-service-administration/src/main/java/org/hisp/dhis/merge/category/optioncombo/DataCategoryOptionComboMergeHandler.java

@@ -48,6 +48,7 @@
 import org.hisp.dhis.common.BaseIdentifiableObject;
 import org.hisp.dhis.common.UID;
 import org.hisp.dhis.dataapproval.DataApproval;
+import org.hisp.dhis.dataapproval.DataApprovalAudit;
 import org.hisp.dhis.dataapproval.DataApprovalAuditStore;
 import org.hisp.dhis.dataapproval.DataApprovalStore;
 import org.hisp.dhis.dataset.CompleteDataSetRegistration;
@@ -58,6 +59,7 @@
 import org.hisp.dhis.datavalue.DataValueStore;
 import org.hisp.dhis.merge.CommonDataMergeHandler;
 import org.hisp.dhis.merge.CommonDataMergeHandler.DataValueMergeParams;
+import org.hisp.dhis.merge.DataMergeStrategy;
 import org.hisp.dhis.merge.MergeRequest;
 import org.hisp.dhis.program.Event;
 import org.hisp.dhis.program.EventStore;
@@ -198,7 +200,10 @@ public void handleDataApprovals(
     }
   }
 
-  /** */
+  /**
+   * Deletes {@link DataApprovalAudit}s if the source {@link CategoryOptionCombo}s are being
+   * deleted. Otherwise, no other action taken.
+   */
   public void handleDataApprovalAudits(
       @Nonnull List<CategoryOptionCombo> sources, @Nonnull MergeRequest mergeRequest) {
     if (mergeRequest.isDeleteSources()) {
@@ -211,7 +216,12 @@ public void handleDataApprovalAudits(
     }
   }
 
-  /** */
+  /**
+   * Deletes {@link Event}s if the {@link DataMergeStrategy}s is {@link DataMergeStrategy#DISCARD}.
+   * Otherwise, reassigns source {@link Event}s attributeOptionCombos to the target {@link
+   * CategoryOptionCombo} if the {@link DataMergeStrategy}s is {@link
+   * DataMergeStrategy#LAST_UPDATED}.
+   */
   public void handleEvents(
       @Nonnull List<CategoryOptionCombo> sources,
       @Nonnull CategoryOptionCombo target,
@@ -228,15 +238,20 @@ public void handleEvents(
     }
   }
 
-  /** */
+  /**
+   * Deletes {@link CompleteDataSetRegistration}s if the {@link DataMergeStrategy}s is {@link
+   * DataMergeStrategy#DISCARD}. Otherwise, if the {@link DataMergeStrategy}s is {@link
+   * DataMergeStrategy#LAST_UPDATED}, it groups source {@link CompleteDataSetRegistration}s into
+   * duplicates and non-duplicates for further processing.
+   */
   public void handleCompleteDataSetRegistrations(
       @Nonnull List<CategoryOptionCombo> sources,
       @Nonnull CategoryOptionCombo target,
       @Nonnull MergeRequest mergeRequest) {
     if (DISCARD == mergeRequest.getDataMergeStrategy()) {
       completeDataSetRegistrationStore.deleteByCategoryOptionCombo(sources);
     } else if (LAST_UPDATED == mergeRequest.getDataMergeStrategy()) {
-      // get DVs from sources
+      // get CDSRs from sources
       List<CompleteDataSetRegistration> sourceCdsr =
           completeDataSetRegistrationStore.getAllByCategoryOptionCombo(
               UID.of(sources.stream().map(BaseIdentifiableObject::getUid).toList()));

dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/category/DefaultCategoryService.java

@@ -701,13 +701,13 @@ public void updateCategoryOptionComboNames() {
 
   @Override
   public List<CategoryOptionCombo> getCategoryOptionCombosByCategoryOption(
-      Collection<UID> categoryOptionsUids) {
+      @Nonnull Collection<UID> categoryOptionsUids) {
     return categoryOptionComboStore.getCategoryOptionCombosByCategoryOption(
         UID.toValueList(categoryOptionsUids));
   }
 
   @Override
-  public List<CategoryOptionCombo> getCategoryOptionCombosByUid(Collection<UID> uids) {
+  public List<CategoryOptionCombo> getCategoryOptionCombosByUid(@Nonnull Collection<UID> uids) {
     return categoryOptionComboStore.getByUid(UID.toValueList(uids));
   }
 

dhis-2/dhis-services/dhis-service-core/src/main/java/org/hisp/dhis/datavalue/hibernate/HibernateDataValueStore.java

@@ -325,10 +325,10 @@ public List<DataValue> getAllDataValuesByAttrOptCombo(@Nonnull Collection<UID> u
     if (uids.isEmpty()) return List.of();
     return getQuery(
             """
-        select dv from DataValue dv
-        join dv.attributeOptionCombo aoc
-        where aoc.uid in :uids
-        """)
+            select dv from DataValue dv
+            join dv.attributeOptionCombo aoc
+            where aoc.uid in :uids
+            """)
         .setParameter("uids", UID.toValueList(uids))
         .getResultList();
   }