Commit 103d837b authored by Sonia Zorba's avatar Sonia Zorba
Browse files

Added (a lots of) comments to code

parent 28a8abaa
Pipeline #104 passed with stage
in 32 seconds
......@@ -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();
}
......@@ -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;
}
......
......@@ -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 {
......
......@@ -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();
}
......
......@@ -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();
}
......@@ -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).
*/