Add unit tests and improve javadoc comments.

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/pom.xml

@@ -149,6 +149,15 @@
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
                 <version>${jacoco.version}</version>
+                <configuration>
+                    <excludes>
+                        <exclude>org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/constant/*.class</exclude>
+                        <exclude>org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/exception/*.class</exclude>
+                        <exclude>org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/internal/*.class</exclude>
+                        <exclude>org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/strategy/AggregationStrategy.class</exclude>
+                        <exclude>org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/OrgResourceResolverService.class</exclude>
+                    </excludes>
+                </configuration>
                 <executions>
                     <execution>
                         <id>default-prepare-agent</id>
@@ -187,7 +196,7 @@
                                         <limit implementation="org.jacoco.report.check.Limit">
                                             <counter>COMPLEXITY</counter>
                                             <value>COVEREDRATIO</value>
-                                            <!--<minimum>0.60</minimum>-->
+                                            <minimum>0.60</minimum>
                                         </limit>
                                     </limits>
                                 </rule>

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/OrgResourceResolverService.java

@@ -26,35 +26,49 @@
 import java.util.function.Function;
 
 /**
- * Service interface for organization resource resolver.
+ * Provides a service interface to retrieve resources from an organization's hierarchy.
+ * Supports traversal of both organization and application hierarchies using customizable
+ * resource retrieval and aggregation strategies.
+ * <p>
+ * The service is designed for extensibility, allowing clients to define their own retrieval logic
+ * and aggregation mechanisms via functional interfaces and strategy patterns.
  */
 public interface OrgResourceResolverService {
 
     /**
-     * Get resources from the organization hierarchy.
+     * Retrieves resources by traversing the hierarchy of a given organization.
      *
-     * @param organizationId      Organization ID.
-     * @param resourceRetriever   Function to retrieve the resource.
-     * @param aggregationStrategy Aggregation strategy.
-     * @param <T>                 Type of the resource.
-     * @return Resolved resources.
-     * @throws OrgResourceHierarchyTraverseException If an error occurs while retrieving the resources.
+     * @param organizationId      The unique identifier of the organization.
+     * @param resourceRetriever   A function that defines how to fetch a resource for a given organization ID.
+     *                            The function must return an {@link Optional<T>} containing the resource if found,
+     *                            or an empty {@link Optional<T>} if not.
+     * @param aggregationStrategy A strategy defining how to aggregate resources retrieved from
+     *                            different levels of the hierarchy.
+     * @param <T>                 The type of the resource being retrieved and aggregated.
+     * @return An aggregated resource of type <T> obtained from the organization hierarchy.
+     * @throws OrgResourceHierarchyTraverseException If any errors occur during resource retrieval
+     *                                               or aggregation.
      */
     <T> T getResourcesFromOrgHierarchy(String organizationId,
                                        Function<String, Optional<T>> resourceRetriever,
                                        AggregationStrategy<T> aggregationStrategy)
             throws OrgResourceHierarchyTraverseException;
 
     /**
-     * Get resources from the organization and application hierarchy.
+     * Retrieves resources by traversing the hierarchy of a given organization and application.
      *
-     * @param organizationId      Organization ID.
-     * @param applicationId       Application ID.
-     * @param resourceRetriever   Function to retrieve the resource.
-     * @param aggregationStrategy Aggregation strategy.
-     * @param <T>                 Type of the resource.
-     * @return Resolved resources.
-     * @throws OrgResourceHierarchyTraverseException If an error occurs while retrieving the resources.
+     * @param organizationId      The unique identifier of the organization. Must not be null.
+     * @param applicationId       The unique identifier of the application within the organization. Must not be null.
+     * @param resourceRetriever   A bi-function that defines how to fetch a resource based on the
+     *                            organization and application IDs. The function must return an
+     *                            {@link Optional<T>} containing the resource if found,
+     *                            or an empty {@link Optional<T>} if not.
+     * @param aggregationStrategy A strategy defining how to aggregate resources retrieved from
+     *                            different levels of the hierarchy.
+     * @param <T>                 The type of the resource being retrieved and aggregated.
+     * @return An aggregated resource of type <T> obtained from the organization and application hierarchy.
+     * @throws OrgResourceHierarchyTraverseException If any errors occur during resource retrieval
+     *                                               or aggregation.
      */
     <T> T getResourcesFromOrgHierarchy(String organizationId, String applicationId,
                                        BiFunction<String, String, Optional<T>> resourceRetriever,

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/OrgResourceResolverServiceImpl.java

@@ -22,7 +22,7 @@
 import org.wso2.carbon.identity.application.common.IdentityApplicationManagementException;
 import org.wso2.carbon.identity.application.mgt.ApplicationManagementService;
 import org.wso2.carbon.identity.organization.management.service.OrganizationManager;
-import org.wso2.carbon.identity.organization.management.service.exception.OrganizationManagementException;
+import org.wso2.carbon.identity.organization.management.service.exception.OrganizationManagementServerException;
 import org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.constant.OrgResourceHierarchyTraverseConstants;
 import org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.exception.OrgResourceHierarchyTraverseException;
 import org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.internal.OrgResourceHierarchyTraverseServiceDataHolder;
@@ -37,7 +37,8 @@
 import java.util.function.Function;
 
 /**
- * Implementation of the OrgResourceResolverService.
+ * Implementation of the OrgResourceResolverService interface, responsible for resolving resources within the
+ * given organization/ application hierarchy.
  */
 public class OrgResourceResolverServiceImpl implements OrgResourceResolverService {
 
@@ -53,7 +54,7 @@ public <T> T getResourcesFromOrgHierarchy(String organizationId, Function<String
             }
 
             return aggregationStrategy.aggregate(organizationIds, resourceRetriever);
-        } catch (OrganizationManagementException e) {
+        } catch (OrganizationManagementServerException e) {
             throw OrgResourceHierarchyTraverseUtil.handleServerException(
                     OrgResourceHierarchyTraverseConstants.ErrorMessages
                             .ERROR_CODE_SERVER_ERROR_WHILE_RESOLVING_ANCESTOR_ORGANIZATIONS, e, organizationId);
@@ -79,7 +80,7 @@ public <T> T getResourcesFromOrgHierarchy(String organizationId, String applicat
             }
 
             return aggregationStrategy.aggregate(organizationIds, ancestorAppIds, resourceRetriever);
-        } catch (OrganizationManagementException e) {
+        } catch (OrganizationManagementServerException e) {
             throw OrgResourceHierarchyTraverseUtil.handleServerException(
                     OrgResourceHierarchyTraverseConstants.ErrorMessages
                             .ERROR_CODE_SERVER_ERROR_WHILE_RESOLVING_ANCESTOR_ORGANIZATIONS, e, organizationId);
@@ -92,7 +93,7 @@ public <T> T getResourcesFromOrgHierarchy(String organizationId, String applicat
     }
 
     private List<String> getAncestorOrganizationsIds(String organizationId)
-            throws OrganizationManagementException {
+            throws OrganizationManagementServerException {
 
         OrganizationManager organizationManager = OrgResourceHierarchyTraverseUtil.getOrganizationManager();
         return organizationManager.getAncestorOrganizationIds(organizationId);

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/constant/OrgResourceHierarchyTraverseConstants.java

@@ -19,18 +19,23 @@
 package org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.constant;
 
 /**
- * Constants for organization resource hierarchy traverse service.
+ * Constants defined for the organization resource hierarchy traverse service.
  */
 public class OrgResourceHierarchyTraverseConstants {
 
     private static final String ORGANIZATION_RESOURCE_HIERARCHY_TRAVERSE_ERROR_CODE_PREFIX = "ORHT-";
 
+    /**
+     * Private constructor to prevent instantiation of this constant class.
+     */
     private OrgResourceHierarchyTraverseConstants() {
 
     }
 
     /**
-     * Enum for error messages related to organization resource hierarchy traverse service.
+     * Enum which provides error codes and predefined error messages related to the traversal of
+     * the organization resource hierarchy. It ensures that error handling within the service is consistent
+     * and that detailed error descriptions are available for debugging and troubleshooting.
      */
     public enum ErrorMessages {
 
@@ -50,23 +55,56 @@ public enum ErrorMessages {
         private final String message;
         private final String description;
 
+        /**
+         * Constructor for the ErrorMessages enum.
+         * <p>
+         * This constructor is used to define each error message with a unique error code, a brief message, and
+         * a detailed description.
+         *
+         * @param code        The unique error code for the message (prefixed with "ORHT-").
+         * @param message     A brief message describing the error.
+         * @param description A detailed description of the error, often including placeholders for dynamic data.
+         */
         ErrorMessages(String code, String message, String description) {
 
             this.code = code;
             this.message = message;
             this.description = description;
         }
 
+        /**
+         * Gets the unique error code for the error message.
+         * <p>
+         * The error code is prefixed with "ORHT-" to ensure consistency in the error code system.
+         *
+         * @return The error code prefixed with "ORHT-".
+         */
         public String getCode() {
 
             return ORGANIZATION_RESOURCE_HIERARCHY_TRAVERSE_ERROR_CODE_PREFIX + code;
         }
 
+        /**
+         * Gets the brief message for the error.
+         * <p>
+         * This message provides a short description of the error, usually without context-specific details.
+         * It is used for logging or displaying to the user as part of the error response.
+         *
+         * @return A brief message describing the error.
+         */
         public String getMessage() {
 
             return message;
         }
 
+        /**
+         * Gets the detailed description for the error message.
+         * <p>
+         * This description provides a more detailed explanation of the error and often contains placeholders
+         * for dynamic data (e.g., organization or application IDs). It is typically used for logging or debugging.
+         *
+         * @return A detailed description of the error, including placeholders for dynamic data.
+         */
         public String getDescription() {
 
             return description;

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/exception/OrgResourceHierarchyTraverseClientException.java

@@ -25,14 +25,20 @@
 import java.util.List;
 
 /**
- * Exception class for client side errors in organization resource hierarchy traverse.
+ * Exception class for client-side errors during organization resource hierarchy traversal.
+ * <p>
+ * This class handles exceptions where client-side errors occur, capturing error codes, messages, and descriptions
+ * to provide detailed context for troubleshooting.
  */
 public class OrgResourceHierarchyTraverseClientException extends OrgResourceHierarchyTraverseException {
 
-    private static final long serialVersionUID = 559143944402014381L;
-
     private String[] messages;
 
+    /**
+     * Constructs a new exception with an array of specified error messages.
+     *
+     * @param messages Detailed error messages
+     */
     public OrgResourceHierarchyTraverseClientException(String[] messages) {
 
         super(Arrays.toString(messages));

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/exception/OrgResourceHierarchyTraverseException.java

@@ -19,14 +19,17 @@
 package org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.exception;
 
 /**
- * Exception class that represents exceptions thrown upon organization resource hierarchy traverse.
+ * Custom exception for errors encountered during organization resource hierarchy traversal.
+ * <p>
+ * This exception captures detailed error information, including error codes, messages, descriptions,
+ * and causes, to assist in troubleshooting issues related to resolving ancestor organizations or applications.
  */
 public class OrgResourceHierarchyTraverseException extends Exception {
 
     private String errorCode;
     private String description;
 
-    private static final long serialVersionUID = -1982152066401023165L;
+    private static final long serialVersionUID = 5967152066669023668L;
 
     /**
      * Constructs a new exception with the specified message.

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/exception/OrgResourceHierarchyTraverseServerException.java

@@ -19,7 +19,10 @@
 package org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.exception;
 
 /**
- * Exception class that represents server side errors in organization resource hierarchy traverse.
+ * Exception class for server-side errors during organization resource hierarchy traversal.
+ * <p>
+ * This class handles exceptions related to server-side failures, including error codes, messages,
+ * descriptions, and causes, to provide detailed information for debugging.
  */
 public class OrgResourceHierarchyTraverseServerException extends OrgResourceHierarchyTraverseException {
 

components/org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service/src/main/java/org/wso2/carbon/identity/organization/resource/hierarchy/traverse/service/internal/OrgResourceHierarchyTraverseServiceComponent.java

@@ -33,7 +33,10 @@
 import org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service.OrgResourceResolverServiceImpl;
 
 /**
- * OSGi declarative services component of the organization resource hierarchy traverse service.
+ * OSGi component responsible for managing the activation and deactivation of the organization resource hierarchy
+ * traverse service.
+ * <p>
+ * It manages dynamic references to necessary services required by {@link OrgResourceResolverService} as well.
  */
 @Component(
         name = "org.wso2.carbon.identity.organization.resource.hierarchy.traverse.service",
@@ -42,6 +45,12 @@ public class OrgResourceHierarchyTraverseServiceComponent {
 
     private static final Log log = LogFactory.getLog(OrgResourceHierarchyTraverseServiceComponent.class);
 
+    /**
+     * Activates the OSGi component by registering the {@link OrgResourceResolverService} service.
+     * This method is called when the component is activated in the OSGi environment.
+     *
+     * @param context The ComponentContext instance that provides the OSGi environment context.
+     */
     @Activate
     protected void activate(ComponentContext context) {
 
@@ -57,6 +66,12 @@ protected void activate(ComponentContext context) {
         }
     }
 
+    /**
+     * Deactivates the OSGi component by cleaning up resources and logging the deactivation.
+     * This method is called when the component is deactivated in the OSGi environment.
+     *
+     * @param context The ComponentContext instance that provides the OSGi environment context.
+     */
     @Deactivate
     protected void deactivate(ComponentContext context) {
 
@@ -65,6 +80,11 @@ protected void deactivate(ComponentContext context) {
         }
     }
 
+    /**
+     * Sets the OrganizationManager instance in the OrgResourceHierarchyTraverseServiceDataHolder.
+     *
+     * @param organizationManager The OrganizationManager instance to be assigned.
+     */
     @Reference(name = "org.wso2.carbon.identity.organization.management.service",
             service = OrganizationManager.class,
             cardinality = ReferenceCardinality.OPTIONAL,
@@ -76,12 +96,22 @@ protected void setOrganizationManager(OrganizationManager organizationManager) {
         log.debug("OrganizationManager set in OrgResourceManagementServiceComponent bundle.");
     }
 
+    /**
+     * Unsets the OrganizationManager instance in the OrgResourceHierarchyTraverseServiceDataHolder.
+     *
+     * @param organizationManager The OrganizationManager instance to be removed.
+     */
     protected void unsetOrganizationManager(OrganizationManager organizationManager) {
 
         OrgResourceHierarchyTraverseServiceDataHolder.getInstance().setOrganizationManager(null);
         log.debug("OrganizationManager unset in OrgResourceManagementServiceComponent bundle.");
     }
 
+    /**
+     * Sets the ApplicationManagementService instance in the OrgResourceHierarchyTraverseServiceDataHolder.
+     *
+     * @param applicationManagementService The ApplicationManagementService instance to be assigned.
+     */
     @Reference(
             name = "org.wso2.carbon.identity.application.mgt",
             service = ApplicationManagementService.class,
@@ -95,6 +125,11 @@ protected void setApplicationManagementService(ApplicationManagementService appl
         log.debug("ApplicationManagementService set in OrgResourceManagementServiceComponent bundle.");
     }
 
+    /**
+     * Unsets the ApplicationManagementService instance in the OrgResourceHierarchyTraverseServiceDataHolder.
+     *
+     * @param applicationManagementService The ApplicationManagementService instance to be removed.
+     */
     protected void unsetApplicationManagementService(ApplicationManagementService applicationManagementService) {
 
         OrgResourceHierarchyTraverseServiceDataHolder.getInstance().setApplicationManagementService(null);