Cleanup and added a bunch of javadoc

Signed-off-by: Alberto Codutti <alberto.codutti@eurotech.com>

commons/src/main/java/org/eclipse/kapua/commons/configuration/AbstractKapuaConfigurableResourceLimitedService.java

@@ -13,7 +13,10 @@
 package org.eclipse.kapua.commons.configuration;
 
 import org.eclipse.kapua.KapuaException;
+import org.eclipse.kapua.commons.configuration.exception.KapuaConfigurationErrorCodes;
+import org.eclipse.kapua.commons.configuration.exception.KapuaConfigurationException;
 import org.eclipse.kapua.commons.jpa.AbstractEntityCacheFactory;
+import org.eclipse.kapua.commons.jpa.CacheFactory;
 import org.eclipse.kapua.commons.jpa.EntityManagerFactory;
 import org.eclipse.kapua.commons.security.KapuaSecurityUtils;
 import org.eclipse.kapua.locator.KapuaLocator;
@@ -28,22 +31,48 @@
 import org.eclipse.kapua.model.query.KapuaQuery;
 import org.eclipse.kapua.model.query.predicate.AttributePredicate.Operator;
 import org.eclipse.kapua.service.KapuaEntityService;
+import org.eclipse.kapua.service.KapuaService;
 import org.eclipse.kapua.service.account.Account;
 import org.eclipse.kapua.service.account.AccountFactory;
 import org.eclipse.kapua.service.account.AccountListResult;
 import org.eclipse.kapua.service.account.AccountQuery;
 import org.eclipse.kapua.service.account.AccountService;
+import org.eclipse.kapua.service.config.KapuaConfigurableService;
 
 import java.util.Map;
 
+/**
+ * Base {@code abstract} {@link KapuaConfigurableService} implementation for services that have a max number of entities allowed.
+ * <p>
+ * The usually contain properties named:
+ * <ul>
+ *     <li>infiniteChildEntities</li>
+ *     <li>maxNumberChildEntities</li>
+ * </ul>
+ *
+ * @param <E> The {@link KapuaEntity} type.
+ * @param <C> The {@link KapuaEntityCreator} type.
+ * @param <S> The {@link KapuaEntityService} type.
+ * @param <L> The {@link KapuaListResult} type.
+ * @param <Q> The {@link KapuaQuery} type.
+ * @param <F> The {@link KapuaEntityFactory} type.
+ * @since 1.0.0
+ */
 public abstract class AbstractKapuaConfigurableResourceLimitedService<E extends KapuaEntity, C extends KapuaEntityCreator<E>, S extends KapuaEntityService<E, C>, L extends KapuaListResult<E>, Q extends KapuaQuery, F extends KapuaEntityFactory<E, C, Q, L>>
         extends AbstractKapuaConfigurableService {
 
     private final Class<S> serviceClass;
     private final Class<F> factoryClass;
 
     /**
-     * @deprecated this constructor will be removed in a next release (may be)
+     * Constructor.
+     *
+     * @param pid                  The {@link KapuaConfigurableService} id.
+     * @param domain               The {@link Domain} on which check access.
+     * @param entityManagerFactory The {@link EntityManagerFactory} that handles persistence unit
+     * @param serviceClass         The {@link KapuaService} type.
+     * @param factoryClass         The {@link KapuaEntityFactory} type.
+     * @deprecated Since 1.2.0. This constructor will be removed in a next release (may be)
      */
     @Deprecated
     protected AbstractKapuaConfigurableResourceLimitedService(
@@ -55,6 +84,17 @@ protected AbstractKapuaConfigurableResourceLimitedService(
         this(pid, domain, entityManagerFactory, null, serviceClass, factoryClass);
     }
 
+    /**
+     * Constructor.
+     *
+     * @param pid                  The {@link KapuaConfigurableService} id.
+     * @param domain               The {@link Domain} on which check access.
+     * @param entityManagerFactory The {@link EntityManagerFactory} that handles persistence unit
+     * @param abstractCacheFactory The {@link CacheFactory} that handles caching of the entities
+     * @param serviceClass         The {@link KapuaService} type.
+     * @param factoryClass         The {@link KapuaEntityFactory} type.
+     * @since 1.2.0
+     */
     protected AbstractKapuaConfigurableResourceLimitedService(
             String pid,
             Domain domain,
@@ -63,6 +103,7 @@ protected AbstractKapuaConfigurableResourceLimitedService(
             Class<S> serviceClass,
             Class<F> factoryClass) {
         super(pid, domain, entityManagerFactory, abstractCacheFactory);
+
         this.serviceClass = serviceClass;
         this.factoryClass = factoryClass;
     }
@@ -72,33 +113,58 @@ protected boolean validateNewConfigValuesCoherence(KapuaTocd ocd, Map<String, Ob
         super.validateNewConfigValuesCoherence(ocd, updatedProps, scopeId, parentId);
         int availableChildEntitiesWithNewConfig = allowedChildEntities(scopeId, null, updatedProps);
         if (availableChildEntitiesWithNewConfig < 0) {
-            throw new KapuaConfigurationException(KapuaConfigurationErrorCodes.SELF_LIMIT_EXCEEDED_IN_CONFIG);
+            throw new KapuaConfigurationException(KapuaConfigurationErrorCodes.LIMIT_EXCEEDED);
         }
         if (parentId != null) {
             int availableParentEntitiesWithCurrentConfig = allowedChildEntities(parentId, scopeId);
             if (availableParentEntitiesWithCurrentConfig - availableChildEntitiesWithNewConfig < 0) {
-                throw new KapuaConfigurationException(KapuaConfigurationErrorCodes.PARENT_LIMIT_EXCEEDED_IN_CONFIG);
+                throw new KapuaConfigurationException(KapuaConfigurationErrorCodes.PARENT_LIMIT_EXCEEDED);
             }
         }
         return true;
     }
 
+    /**
+     * Gets the number of remaining allowed entity for the given scope, according to the {@link KapuaConfigurableService#getConfigValues(KapuaId)}
+     *
+     * @param scopeId The scope {@link KapuaId}.
+     * @return The number of entities remaining for the given scope
+     * @throws KapuaException
+     * @since 1.0.0
+     */
     protected int allowedChildEntities(KapuaId scopeId) throws KapuaException {
         return allowedChildEntities(scopeId, null, null);
     }
 
+    /**
+     * Gets the number of remaining allowed entity for the given scope, according to the {@link KapuaConfigurableService#getConfigValues(KapuaId)}
+     * excluding a specific scope when checking resources available.
+     * <p>
+     * The exclusion of the scope is required when updating a limit for a target account.
+     *
+     * @param scopeId       The scope {@link KapuaId}.
+     * @param targetScopeId The excluded scope {@link KapuaId}.
+     * @return The number of entities remaining for the given scope
+     * @throws KapuaException
+     * @since 1.0.0
+     */
     protected int allowedChildEntities(KapuaId scopeId, KapuaId targetScopeId) throws KapuaException {
         return allowedChildEntities(scopeId, targetScopeId, null);
     }
 
+
     /**
-     * @param scopeId       The {@link KapuaId} of the account to be tested
-     * @param targetScopeId Optional scopeId of the child account to be excluded when validating the new configuration for that scopeId.
-     * @param configuration The configuration to be tested. If null will be read
-     *                      from the current service configuration; otherwise the passed configuration
-     *                      will be used in the test
-     * @return the number of child accounts spots still available
+     * Gets the number of remaining allowed entity for the given scope, according to the given {@link KapuaConfigurableService}
+     * excluding a specific scope when checking resources available.
+     * <p>
+     * The exclusion of the scope is required when updating a limit for a target account.
+     *
+     * @param scopeId       The scope {@link KapuaId}.
+     * @param targetScopeId The excluded scope {@link KapuaId}.
+     * @param configuration The configuration to be checked. If not provided will be read from the current service configuration
+     * @return The number of entities remaining for the given scope
      * @throws KapuaException
+     * @since 1.0.0
      */
     protected int allowedChildEntities(KapuaId scopeId, KapuaId targetScopeId, Map<String, Object> configuration) throws KapuaException {
         KapuaLocator locator = KapuaLocator.getInstance();
@@ -126,7 +192,7 @@ protected int allowedChildEntities(KapuaId scopeId, KapuaId targetScopeId, Map<S
                 // Resources assigned to children
                 long childCount = 0;
                 for (Account childAccount : childAccounts.getItems()) {
-                    Map<String, Object> childConfigValues = getConfigValues(childAccount);
+                    Map<String, Object> childConfigValues = getConfigValues(childAccount.getId());
                     // maxNumberChildEntities can be null if such property is disabled via the
                     // isPropertyEnabled() method in the service implementation. In such case,
                     // it makes sense to treat the service as it had 0 available entities
@@ -142,17 +208,16 @@ protected int allowedChildEntities(KapuaId scopeId, KapuaId targetScopeId, Map<S
         return Integer.MAX_VALUE;
     }
 
-    /**
-     * Gets the scoped configuration values from the given {@link Account}.
-     * This method defaults to {@link Account#getId()}, but implementations can change it to use other attributes.
-     *
-     * @param account The account from which get the id.
-     * @return The scoped configurations for the given {@link Account}.
-     * @throws KapuaException
-     * @since 1.0.0
-     */
-    protected Map<String, Object> getConfigValues(Account account) throws KapuaException {
-        return getConfigValues(account.getId());
-    }
-
+//
+//    /**
+//     * Gets the {@link ServiceConfig} values for the given {@link Account}.
+//     * This method defaults to {@link Account#getId()}, but implementations can change it to use other attributes.
+//     *
+//     * @param account The account from which get the id.
+//     * @return The scoped configurations for the given {@link Account}.
+//     * @throws KapuaException
+//     */
+//    protected Map<String, Object> getConfigValues(Account account) throws KapuaException {
+//        return getConfigValues(account.getId());
+//    }
 }