Added (a lots of) comments to code

TASMAN-core/src/main/java/it/inaf/ia2/tsm/ChildEntity.java

@@ -37,24 +37,38 @@ public abstract class ChildEntity<T extends EntitiesContainer> extends TapSchema
 
     private Status status;
 
+    /**
+     * Only for serialization.
+     */
     protected ChildEntity() {
     }
 
+    /**
+     * Default constructor.
+     *
+     * @see TapSchemaEntity
+     */
     public ChildEntity(TapSchema tapSchema, TableModel tableModel, Map<String, Object> metadata) {
         super(tapSchema, tableModel, metadata);
     }
 
     /**
-     * The persistence status of the {@link ChildEntity}.
+     * Returns the persistence status of this entity.
      */
     public Status getStatus() {
         return status;
     }
 
+    /**
+     * Updates the persistence status of this entity.
+     */
     public void setStatus(Status status) {
         this.status = status;
     }
 
+    /**
+     * {@inheritDoc} The entity status becomes {@code Status.ADDED_PERSISTED}.
+     */
     @Override
     public void save() {
         setStatus(Status.ADDED_PERSISTED);
@@ -62,13 +76,13 @@ public abstract class ChildEntity<T extends EntitiesContainer> extends TapSchema
     }
 
     /**
-     * Each child has a name that is univocal for a given parent, in this way
-     * the parent can search a child by name.
+     * Returns the name of this entity. Each child has a name that is univocal
+     * for a given parent, in this way the parent can search a child by name.
      */
     public abstract String getName();
 
     /**
-     * The {@link EntitiesContainer} that owns the {@link ChildEntity}.
+     * Returns the {@link EntitiesContainer} that owns this object.
      */
     public abstract T getParent();
 }

TASMAN-core/src/main/java/it/inaf/ia2/tsm/Column.java

@@ -27,6 +27,8 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
+ * Represent a TAP_SCHEMA column entity.
+ *
  * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
  */
 public class Column extends ChildEntity<Table> {
@@ -71,6 +73,9 @@ public class Column extends ChildEntity<Table> {
         setStatus(Status.LOADED);
     }
 
+    /**
+     * Retrieve the {@code Key} having this column as {@code from_column}.
+     */
     public Key getForeignKey() {
         if (!foreignKeySearched) { // lazy loading (but the foreignKey value can be null, so we use this boolean)
 
@@ -94,15 +99,24 @@ public class Column extends ChildEntity<Table> {
         return foreignKey;
     }
 
+    /**
+     * Returns parent table complete name (schema name plus table name).
+     */
     public String getTableCompleteName() {
         return getValue(TABLE_NAME_KEY, String.class);
     }
 
+    /**
+     * Returns column name.
+     */
     @Override
     public String getName() {
         return getValue(COLUMN_NAME_KEY, String.class);
     }
 
+    /**
+     * Returns true if the column is indexed.
+     */
     public boolean getIndexed() {
         EntityProperty indexedProp = getProperty(INDEXED_KEY);
         if (indexedProp.getType() == Boolean.class) {
@@ -122,6 +136,9 @@ public class Column extends ChildEntity<Table> {
         return (boolean) getMetadata(PRIMARY_KEY);
     }
 
+    /**
+     * Returns true if the column is a mandatory one (used for ObsCore).
+     */
     public boolean isMandatory() {
         return mandatory;
     }

TASMAN-core/src/main/java/it/inaf/ia2/tsm/ColumnHolder.java

@@ -26,7 +26,10 @@ import java.io.Serializable;
 import java.util.Objects;
 
 /**
+ * Models a column during the consistency checking phase (it is used to display
+ * information about columns not already loaded/added into the TAP_SCHEMA).
  *
+ * @see it.inaf.ia2.tsm.ConsistencyChecks
  * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
  */
 public class ColumnHolder implements Serializable {

TASMAN-core/src/main/java/it/inaf/ia2/tsm/ConsistencyChecks.java

@@ -35,7 +35,23 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
- * DataModel for consistency checking result.
+ * Data model for storing consistency checking result. The consistency checking
+ * phase verify if the data stored into the TAP_SCHEMA is consistent with the
+ * data read from the database metadata (or information_schema).
+ * <p>
+ * Naming convention:
+ * <ul>
+ * <li><strong>inconsistency</strong>: when a property of a column exposed by
+ * the TAP_SCHEMA is different from the value read from the database metadata
+ * (for example the column is defined with a given size which is different from
+ * the arraysize stored into the TAP_SCHEMA;</li>
+ * <li><strong>inexistent entity</strong>: when a TAP_SCHEMA entity (schema,
+ * table, etc.) is represented into the TAP_SCHEMA, but it doesn't exists
+ * according to information retrieved from the database metadata;</li>
+ * <li><strong>missing entity</strong>: when a mandatory TAP_SCHEMA entity has
+ * not been added to an existing TAP_SCHEMA (this is used for ObsCore mandatory
+ * columns).</li>
+ * </ul>
  *
  * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
  */
@@ -46,7 +62,7 @@ public class ConsistencyChecks implements Serializable {
 
     private final List<InconsistentColumnProperty> inconsistencies;
     private final Set<String> unexisingSchemas;
-    private final Set<String> unexisingTables;
+    private final Set<String> unexistingTables;
     private final Set<ColumnHolder> unexistingColumns;
     private final Set<KeyHolder> unexistingKeys;
     private final Map<String, Set<String>> missingTables;
@@ -57,13 +73,13 @@ public class ConsistencyChecks implements Serializable {
     private boolean missingObscore;
     private boolean obscoreToAdd;
 
-    // This will not consider an inconsistency: it is only used to display a warning
+    // This is not consider an inconsistency: it is only used to display a warning
     private final Set<ColumnHolder> unaddedOptionalColumns;
 
     public ConsistencyChecks() {
         inconsistencies = new ArrayList<>();
         unexisingSchemas = new HashSet<>();
-        unexisingTables = new HashSet<>();
+        unexistingTables = new HashSet<>();
         unexistingColumns = new HashSet<>();
         unexistingKeys = new HashSet<>();
         missingTables = new HashMap<>();
@@ -74,38 +90,90 @@ public class ConsistencyChecks implements Serializable {
         wrongDataTypes = new ArrayList<>();
     }
 
-    public void addInconsistency(InconsistentColumnProperty problemDescription) {
-        inconsistencies.add(problemDescription);
+    /**
+     * Adds an inconsistent column property.
+     */
+    public void addInconsistency(InconsistentColumnProperty inconsistentProperty) {
+        inconsistencies.add(inconsistentProperty);
     }
 
+    /**
+     * Returns a list of all inconsistent column properties detected.
+     */
     public List<InconsistentColumnProperty> getInconsistencies() {
         return inconsistencies;
     }
 
+    /**
+     * Returns a set of schema names that have been stored into the TAP_SCHEMA
+     * but are not currently existing according to the information read from the
+     * database metadata.
+     */
     public Set<String> getUnexisingSchemas() {
         return unexisingSchemas;
     }
 
+    /**
+     * Adds the name of a schema that has been stored into the TAP_SCHEMA but is
+     * not currently existing according to the information read from the
+     * database metadata.
+     */
     public void addUnexistingSchema(String schemaName) {
         unexisingSchemas.add(schemaName);
     }
 
-    public Set<String> getUnexisingTables() {
-        return unexisingTables;
+    /**
+     * Returns a set of table names that have been stored into the TAP_SCHEMA
+     * but are not currently existing according to the information read from the
+     * database metadata. Unexisting columns.
+     */
+    public Set<String> getUnexistingTables() {
+        return unexistingTables;
     }
 
+    /**
+     * Adds the name of a table that has been stored into the TAP_SCHEMA but is
+     * not currently existing according to the information read from the
+     * database metadata.
+     */
     public void addUnexistingTable(String schemaName, String tableSimpleName) {
-        unexisingTables.add(schemaName + "." + tableSimpleName);
+        unexistingTables.add(schemaName + "." + tableSimpleName);
     }
 
-    public Set<ColumnHolder> getUnexisingColumns() {
+    /**
+     * Returns a set of column names that have been stored into the TAP_SCHEMA
+     * but are not currently existing according to the information read from the
+     * database metadata.
+     */
+    public Set<ColumnHolder> getUnexistingColumns() {
         return unexistingColumns;
     }
 
+    /**
+     * Adds the representation of a column that has been stored into the
+     * TAP_SCHEMA but is not currently existing according to the information
+     * read from the database metadata.
+     *
+     * @param schemaName the name of the schema owning the inexistent column.
+     * @param tableName the name of the table owning the inexistent column.
+     * @param columnName the name of the inexistent column.
+     */
     public void addUnexistingColumn(String schemaName, String tableName, String columnName) {
         unexistingColumns.add(new ColumnHolder(schemaName, tableName, columnName));
     }
 
+    /**
+     * Adds the representation of a key that has been stored into the TAP_SCHEMA
+     * but is not currently existing according to the information read from the
+     * database metadata.
+     *
+     * @param keyId the identifier of the inexistent key stored into the
+     * TAP_SCHEMA.
+     * @param fromTable the table owning the foreign key.
+     * @param fromColumns the column owning the foreign key.
+     * @param targetTable the table owning the primary key.
+     * @param targetColumns the table owning the primary.
+     */
     public void addUnexistingKey(String keyId, String fromTable, String[] fromColumns, String targetTable, String[] targetColumns) {
         if (keyId == null) {
             throw new IllegalArgumentException("key_id can't be null");
@@ -113,16 +181,38 @@ public class ConsistencyChecks implements Serializable {
         unexistingKeys.add(new KeyHolder(keyId, fromTable, fromColumns, targetTable, targetColumns));
     }
 
+    /**
+     * Returns a set of key representations that have been stored into the
+     * TAP_SCHEMA but are not currently existing according to the information
+     * read from the database metadata.
+     */
     public Set<KeyHolder> getUnexistingKeys() {
         return unexistingKeys;
     }
 
+    /**
+     * Adds a model representing a column that must be created and then exposed
+     * by the TAP_SCHEMA and currently is not existing according to the database
+     * metadata (this could happen for TAP_SCHEMA schema columns and ObsCore
+     * columns).
+     *
+     * @param columnHolder the object representing the missing column.
+     * @param columnModel the model defining the column properties.
+     */
     public void addMissingColumn(ColumnHolder columnHolder, ColumnModel columnModel) {
         // Removing table from unexisting columns set
         unexistingColumns.remove(columnHolder);
         missingColumns.put(columnHolder, columnModel);
     }
 
+    /**
+     * Returns a map of all columns which are not existing yet and must be
+     * created and then exposed by the TAP_SCHEMA (this could happen for
+     * TAP_SCHEMA schema columns and ObsCore columns).
+     *
+     * @return a {@code Map} having {@link ColumnHolder} instances as keys and
+     * {@link ColumnModel} instances as values.
+     */
     public Map<ColumnHolder, ColumnModel> getMissingColumns() {
         return missingColumns;
     }
@@ -136,9 +226,17 @@ public class ConsistencyChecks implements Serializable {
         tables.add(tableName);
     }
 
+    /**
+     * Adds a table that must be created and then exposed by the TAP_SCHEMA and
+     * currently is not existing (this could happen for TAP_SCHEMA tables and
+     * ObsCore table).
+     *
+     * @param schemaName the name of the schema owning the missing table.
+     * @param tableName the name of the missing table.
+     */
     public void addMissingTable(String schemaName, String tableName) {
         // Removing table from unexisting table set
-        unexisingTables.remove(String.format("%s.%s", schemaName, tableName));
+        unexistingTables.remove(String.format("%s.%s", schemaName, tableName));
 
         // Removing table from unexisting columns set
         Iterator<ColumnHolder> ite = unexistingColumns.iterator();
@@ -152,50 +250,136 @@ public class ConsistencyChecks implements Serializable {
         addTableToMap(schemaName, tableName, missingTables);
     }
 
+    /**
+     * Adds a table that is existing and must be exposed by the TAP_SCHEMA but
+     * currently has not been added to it (this could happen for TAP_SCHEMA
+     * tables and ObsCore table).
+     *
+     * @param schemaName
+     * @param tableName
+     */
     public void addTableToAdd(String schemaName, String tableName) {
         addTableToMap(schemaName, tableName, tablesToAdd);
     }
 
+    /**
+     * Returns all the existing tables that must be exposed by the TAP_SCHEMA
+     * and currently are not (this could happen for TAP_SCHEMA tables and
+     * ObsCore table).
+     *
+     * @return a {@code Map} the keys of which are schema names and the values
+     * of which are {@code Set}s of table names owned by the schema having its
+     * name used as the key in the {@code Map}.
+     */
     public Map<String, Set<String>> getTablesToAdd() {
         return tablesToAdd;
     }
 
+    /**
+     * Returns all the tables that must be added into the TAP_SCHEMA and then
+     * exposed by it and currently are not (this could happen for TAP_SCHEMA
+     * schema tables and ObsCore table).
+     *
+     * @return a {@code Map} the keys of which are schema names and the values
+     * of which are {@code Set}s of table names owned by the schema having its
+     * name used as the key in the {@code Map}.
+     */
     public Map<String, Set<String>> getMissingTables() {
         return missingTables;
     }
 
+    /**
+     * Adds an existing column which must be exposed by the TAP_SCHEMA but
+     * currently has not been added to it (this could happen for TAP_SCHEMA
+     * schema columns and ObsCore columns).
+     *
+     * @param columnHolder a representation for the column.
+     */
     public void addColumnToAdd(ColumnHolder columnHolder) {
         columnsToAdd.add(columnHolder);
     }
 
+    /**
+     * Returns a set of all column representations regarding existing columns
+     * which must be exposed by the TAP_SCHEMA but have not been added to it
+     * yet.
+     */
     public Set<ColumnHolder> getColumnsToAdd() {
         return columnsToAdd;
     }
 
+    /**
+     * Indicates if the ObsCore table should be created.
+     *
+     * @return true if the ObsCore table doesn't exist, false otherwise.
+     */
     public boolean isMissingObscore() {
         return missingObscore;
     }
 
+    /**
+     * @param missingObscore true if the ObsCore table doesn't exist, false
+     * otherwise.
+     */
     public void setMissingObscore(boolean missingObscore) {
         this.missingObscore = missingObscore;
     }
 
+    /**
+     * Indicates if the ObsCore table must be added to the TAP_SCHEMA. In this
+     * case the ObsCore table already exists, it has simply not been exposed by
+     * the TAP_SCHEMA yet.
+     *
+     * @return true if the ObsCore table must be added to the TAP_SCHEMA, false
+     * otherwise.
+     */
     public boolean isObscoreToAdd() {
         return obscoreToAdd;
     }
 
+    /**
+     * @param obscoreToAdd true if the ObsCore table must be added to the
+     * TAP_SCHEMA, false otherwise.
+     */
     public void setObscoreToAdd(boolean obscoreToAdd) {
         this.obscoreToAdd = obscoreToAdd;
     }
 
+    /**
+     * Adds an existing optional column which has not been added to the
+     * TAP_SCHEMA (used for ObsCore). This is not consider an inconsistency: it
+     * is only used to display a suggestion.
+     *
+     * @param columnHolder a representation for the column
+     */
     public void addUnaddedOptionalColumn(ColumnHolder columnHolder) {
         unaddedOptionalColumns.add(columnHolder);
     }
 
+    /**
+     * Returns the set of all existing optional columns which have not been
+     * added to the TAP_SCHEMA yet. This doesn't represents an inconsistency: it
+     * is only used to display a suggestion.
+     */
     public Set<ColumnHolder> getUnaddedOptionalColumns() {
         return unaddedOptionalColumns;
     }
 
+    /**
+     * Adds a {@link WrongDataType} model meaning that an existing column has a
+     * structure which is incoherent with its expected definition according to
+     * its {@link ColumnModel}. To fix this issue an {@code ALTER TABLE} is
+     * necessary.
+     *
+     * @param columnHolder the representation of the broken column.
+     * @param wrongDataType the current column datatype, according to
+     * information retrieved from the database metadata.
+     * @param correctDataType the expected column datatype, according to the
+     * {@link ColumnModel}.
+     * @param adqlCorrectDataType the expected column datatype, using ADQL
+     * datatype syntax.
+     * @param size the desired column size.
+     */
     public void addWrongDataType(ColumnHolder columnHolder, String wrongDataType, String correctDataType, String adqlCorrectDataType, Integer size) {
         // If datatype needs to be changed inconsistency on it doesn't make sense anymore.
         Iterator<InconsistentColumnProperty> ite = inconsistencies.iterator();
@@ -213,18 +397,35 @@ public class ConsistencyChecks implements Serializable {
         wrongDataTypes.add(wdt);
     }
 
+    /**
+     * Returns a list of the {@link WrongDataType}s detected. To fix this issue
+     * an {@code ALTER TABLE} is necessary.
+     */
     public List<WrongDataType> getWrongDataTypes() {
         return wrongDataTypes;
     }
 
+    /**
+     * Indicates if the loaded TAP_SCHEMA contains some consistency problems to
+     * fix.
+     *
+     * @return true if the TAP_SCHEMA contains consistency problems, false
+     * otherwise.
+     */
     public boolean isInconsistent() {
         return !inconsistencies.isEmpty() || !wrongDataTypes.isEmpty()
-                || !unexisingSchemas.isEmpty() || !unexisingTables.isEmpty() || !unexistingColumns.isEmpty()
+                || !unexisingSchemas.isEmpty() || !unexistingTables.isEmpty() || !unexistingColumns.isEmpty()
                 || !missingTables.isEmpty() || !missingColumns.isEmpty()
                 || !columnsToAdd.isEmpty() || !tablesToAdd.isEmpty()
                 || obscoreToAdd || missingObscore;
     }
 
+    /**
+     * Indicates if the TAP_SCHEMA has been loaded with warnings/suggestions.
+     *
+     * @return true if warnings have been produced during the consistency
+     * checking process, false otherwise.
+     */
     public boolean isHasWarnings() {
         return !unaddedOptionalColumns.isEmpty();
     }

TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntitiesContainer.java

@@ -33,16 +33,23 @@ import java.util.List;
 public interface EntitiesContainer<T extends ChildEntity> {
 
     /**
-     * Returns a specific child of the container, selecting it by name and
+     * Returns a specific child of this container, selecting it by name and
      * filtering it by a set of possible status: if the child doesn't have one
-     * of the status specified, this method returns null.<br>
+     * of the status specified, this method returns null.
+     * <p>
      * <strong>If no status is specified it is assumed that all status are
      * valid.</strong>
+     *
+     * @param childName the name of the {@link ChildEntity} to retrieve.
+     * @param status a set of allowed {@link Status} for the {@link ChildEntity}
+     * to retrieve.
+     * @return a {@link ChildEntity} or null if there is no child matching the
+     * specified criteria.
      */
     T getChild(String childName, Status... status);
 
     /**
-     * Add a {@link ChildEntity} specifying its name. If the child entity has
+     * Adds a {@link ChildEntity} specifying its name. If the child entity has
      * never been read from the database it is loaded when this method is
      * called. If the entity was marked as removed, it will marked as added
      * again.
@@ -50,40 +57,52 @@ public interface EntitiesContainer<T extends ChildEntity> {
     T addChild(String childName) throws SQLException;
 
     /**
-     * Remove a {@link ChildEntity} specifying its name.<br>
+     * Removes a {@link ChildEntity} given its name.
+     * <p>
      * The child isn't really removed but only marked as removed (the removal
      * will happen when the {@link TapSchema#save()} method will be called).
+     *
+     * @param childName the name of the {@code ChildEntity} to remove.
      */
     void removeChild(String childName);
 
     /**
-     * Retrieve a list of names of child entities that can be added.<br> The
-     * list contains only names of entities that have never been added: entities
-     * which instance don't exist yet or entities having
+     * Retrieves a list of names of child entities that can be added.
+     * <p>
+     * The list contains only names of entities that have never been added:
+     * entities the instances of which don't exist yet or entities having
      * {@link Status} {@code LOADED}.
      */
     List<String> getAddableChildrenNames();
 
+    /**
+     * Tells if a {@link ChildEntity} can be added to this container, given its
+     * name.
+     *
+     * @param childName the name of the entity to add.
+     * @return true if the {@code ChildEntity} can be added, false otherwise.
+     */
     boolean isAddable(String childName);
 
     /**
-     * Retrieve a list of children filtering them by a set of possible
-     * status.<br>
+     * Retrieves a list of the children of this container filtering them by a
+     * set of possible status.
+     * <p>
      * <strong>If no status is specified it is assumed that all status are
      * valid.</strong>
      */
     List<T> getChildren(Status... statuses);
 
     /**
-     * Retrieve all children having {@link Status} {@code ADDED_PERSISTED} or
-     * {@code ADDED_NOT_PERSISTED}.
+     * Retrieves all children of this container having
+     * {@link Status} {@code ADDED_PERSISTED} or {@code ADDED_NOT_PERSISTED}.
      */
     List<T> getAddedChildren();
 
     /**
-     * Retrieve all children having {@link Status} {@code ADDED_PERSISTED},
-     * {@code ADDED_NOT_PERSISTED}, {@code TO_REMOVE} or
-     * {@code REMOVED_NOT_PERSISTED}.
+     * Retrieves all children of this container having
+     * {@link Status} {@code ADDED_PERSISTED}, {@code ADDED_NOT_PERSISTED},
+     * {@code TO_REMOVE} or {@code REMOVED_NOT_PERSISTED}.
      */
     List<T> getAddedOrRemovedChildren();
 }

TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntityProperty.java

@@ -53,20 +53,30 @@ public class EntityProperty<T> implements Serializable {
     }
 
     /**
-     * Retrieve the current value.
+     * Returns the current value of this property (the last value set).
      */
     public T getValue() {