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 ...@@ -37,24 +37,38 @@ public abstract class ChildEntity<T extends EntitiesContainer> extends TapSchema
private Status status; private Status status;
/**
* Only for serialization.
*/
protected ChildEntity() { protected ChildEntity() {
} }
/**
* Default constructor.
*
* @see TapSchemaEntity
*/
public ChildEntity(TapSchema tapSchema, TableModel tableModel, Map<String, Object> metadata) { public ChildEntity(TapSchema tapSchema, TableModel tableModel, Map<String, Object> metadata) {
super(tapSchema, tableModel, metadata); super(tapSchema, tableModel, metadata);
} }
/** /**
* The persistence status of the {@link ChildEntity}. * Returns the persistence status of this entity.
*/ */
public Status getStatus() { public Status getStatus() {
return status; return status;
} }
/**
* Updates the persistence status of this entity.
*/
public void setStatus(Status status) { public void setStatus(Status status) {
this.status = status; this.status = status;
} }
/**
* {@inheritDoc} The entity status becomes {@code Status.ADDED_PERSISTED}.
*/
@Override @Override
public void save() { public void save() {
setStatus(Status.ADDED_PERSISTED); setStatus(Status.ADDED_PERSISTED);
...@@ -62,13 +76,13 @@ public abstract class ChildEntity<T extends EntitiesContainer> extends TapSchema ...@@ -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 * Returns the name of this entity. Each child has a name that is univocal
* the parent can search a child by name. * for a given parent, in this way the parent can search a child by name.
*/ */
public abstract String getName(); public abstract String getName();
/** /**
* The {@link EntitiesContainer} that owns the {@link ChildEntity}. * Returns the {@link EntitiesContainer} that owns this object.
*/ */
public abstract T getParent(); public abstract T getParent();
} }
...@@ -27,6 +27,8 @@ import org.slf4j.Logger; ...@@ -27,6 +27,8 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory; import org.slf4j.LoggerFactory;
/** /**
* Represent a TAP_SCHEMA column entity.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>} * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/ */
public class Column extends ChildEntity<Table> { public class Column extends ChildEntity<Table> {
...@@ -71,6 +73,9 @@ public class Column extends ChildEntity<Table> { ...@@ -71,6 +73,9 @@ public class Column extends ChildEntity<Table> {
setStatus(Status.LOADED); setStatus(Status.LOADED);
} }
/**
* Retrieve the {@code Key} having this column as {@code from_column}.
*/
public Key getForeignKey() { public Key getForeignKey() {
if (!foreignKeySearched) { // lazy loading (but the foreignKey value can be null, so we use this boolean) 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> { ...@@ -94,15 +99,24 @@ public class Column extends ChildEntity<Table> {
return foreignKey; return foreignKey;
} }
/**
* Returns parent table complete name (schema name plus table name).
*/
public String getTableCompleteName() { public String getTableCompleteName() {
return getValue(TABLE_NAME_KEY, String.class); return getValue(TABLE_NAME_KEY, String.class);
} }
/**
* Returns column name.
*/
@Override @Override
public String getName() { public String getName() {
return getValue(COLUMN_NAME_KEY, String.class); return getValue(COLUMN_NAME_KEY, String.class);
} }
/**
* Returns true if the column is indexed.
*/
public boolean getIndexed() { public boolean getIndexed() {
EntityProperty indexedProp = getProperty(INDEXED_KEY); EntityProperty indexedProp = getProperty(INDEXED_KEY);
if (indexedProp.getType() == Boolean.class) { if (indexedProp.getType() == Boolean.class) {
...@@ -122,6 +136,9 @@ public class Column extends ChildEntity<Table> { ...@@ -122,6 +136,9 @@ public class Column extends ChildEntity<Table> {
return (boolean) getMetadata(PRIMARY_KEY); return (boolean) getMetadata(PRIMARY_KEY);
} }
/**
* Returns true if the column is a mandatory one (used for ObsCore).
*/
public boolean isMandatory() { public boolean isMandatory() {
return mandatory; return mandatory;
} }
......
...@@ -26,7 +26,10 @@ import java.io.Serializable; ...@@ -26,7 +26,10 @@ import java.io.Serializable;
import java.util.Objects; 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>} * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/ */
public class ColumnHolder implements Serializable { public class ColumnHolder implements Serializable {
......
...@@ -35,7 +35,23 @@ import org.slf4j.Logger; ...@@ -35,7 +35,23 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory; 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>} * @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/ */
...@@ -46,7 +62,7 @@ public class ConsistencyChecks implements Serializable { ...@@ -46,7 +62,7 @@ public class ConsistencyChecks implements Serializable {
private final List<InconsistentColumnProperty> inconsistencies; private final List<InconsistentColumnProperty> inconsistencies;
private final Set<String> unexisingSchemas; private final Set<String> unexisingSchemas;
private final Set<String> unexisingTables; private final Set<String> unexistingTables;
private final Set<ColumnHolder> unexistingColumns; private final Set<ColumnHolder> unexistingColumns;
private final Set<KeyHolder> unexistingKeys; private final Set<KeyHolder> unexistingKeys;
private final Map<String, Set<String>> missingTables; private final Map<String, Set<String>> missingTables;
...@@ -57,13 +73,13 @@ public class ConsistencyChecks implements Serializable { ...@@ -57,13 +73,13 @@ public class ConsistencyChecks implements Serializable {
private boolean missingObscore; private boolean missingObscore;
private boolean obscoreToAdd; 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; private final Set<ColumnHolder> unaddedOptionalColumns;
public ConsistencyChecks() { public ConsistencyChecks() {
inconsistencies = new ArrayList<>(); inconsistencies = new ArrayList<>();
unexisingSchemas = new HashSet<>(); unexisingSchemas = new HashSet<>();
unexisingTables = new HashSet<>(); unexistingTables = new HashSet<>();
unexistingColumns = new HashSet<>(); unexistingColumns = new HashSet<>();
unexistingKeys = new HashSet<>(); unexistingKeys = new HashSet<>();
missingTables = new HashMap<>(); missingTables = new HashMap<>();
...@@ -74,38 +90,90 @@ public class ConsistencyChecks implements Serializable { ...@@ -74,38 +90,90 @@ public class ConsistencyChecks implements Serializable {
wrongDataTypes = new ArrayList<>(); 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() { public List<InconsistentColumnProperty> getInconsistencies() {
return inconsistencies; 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() { public Set<String> getUnexisingSchemas() {
return unexisingSchemas; 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) { public void addUnexistingSchema(String schemaName) {
unexisingSchemas.add(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) { 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; 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) { public void addUnexistingColumn(String schemaName, String tableName, String columnName) {
unexistingColumns.add(new ColumnHolder(schemaName, tableName, 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) { public void addUnexistingKey(String keyId, String fromTable, String[] fromColumns, String targetTable, String[] targetColumns) {
if (keyId == null) { if (keyId == null) {
throw new IllegalArgumentException("key_id can't be null"); throw new IllegalArgumentException("key_id can't be null");
...@@ -113,16 +181,38 @@ public class ConsistencyChecks implements Serializable { ...@@ -113,16 +181,38 @@ public class ConsistencyChecks implements Serializable {
unexistingKeys.add(new KeyHolder(keyId, fromTable, fromColumns, targetTable, targetColumns)); 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() { public Set<KeyHolder> getUnexistingKeys() {
return unexistingKeys; 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) { public void addMissingColumn(ColumnHolder columnHolder, ColumnModel columnModel) {
// Removing table from unexisting columns set // Removing table from unexisting columns set
unexistingColumns.remove(columnHolder); unexistingColumns.remove(columnHolder);
missingColumns.put(columnHolder, columnModel); 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() { public Map<ColumnHolder, ColumnModel> getMissingColumns() {
return missingColumns; return missingColumns;
} }
...@@ -136,9 +226,17 @@ public class ConsistencyChecks implements Serializable { ...@@ -136,9 +226,17 @@ public class ConsistencyChecks implements Serializable {
tables.add(tableName); 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) { public void addMissingTable(String schemaName, String tableName) {
// Removing table from unexisting table set // 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 // Removing table from unexisting columns set
Iterator<ColumnHolder> ite = unexistingColumns.iterator(); Iterator<ColumnHolder> ite = unexistingColumns.iterator();
...@@ -152,50 +250,136 @@ public class ConsistencyChecks implements Serializable { ...@@ -152,50 +250,136 @@ public class ConsistencyChecks implements Serializable {
addTableToMap(schemaName, tableName, missingTables); 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) { public void addTableToAdd(String schemaName, String tableName) {
addTableToMap(schemaName, tableName, tablesToAdd); 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() { public Map<String, Set<String>> getTablesToAdd() {
return tablesToAdd; 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() { public Map<String, Set<String>> getMissingTables() {
return missingTables; 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) { public void addColumnToAdd(ColumnHolder columnHolder) {
columnsToAdd.add(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() { public Set<ColumnHolder> getColumnsToAdd() {
return columnsToAdd; return columnsToAdd;
} }
/**
* Indicates if the ObsCore table should be created.
*
* @return true if the ObsCore table doesn't exist, false otherwise.
*/
public boolean isMissingObscore() { public boolean isMissingObscore() {
return missingObscore; return missingObscore;
} }
/**
* @param missingObscore true if the ObsCore table doesn't exist, false
* otherwise.
*/
public void setMissingObscore(boolean missingObscore) { public void setMissingObscore(boolean missingObscore) {
this.missingObscore = 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() { public boolean isObscoreToAdd() {
return obscoreToAdd; return obscoreToAdd;
} }
/**
* @param obscoreToAdd true if the ObsCore table must be added to the
* TAP_SCHEMA, false otherwise.
*/
public void setObscoreToAdd(boolean obscoreToAdd) { public void setObscoreToAdd(boolean obscoreToAdd) {
this.obscoreToAdd = 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) { public void addUnaddedOptionalColumn(ColumnHolder columnHolder) {
unaddedOptionalColumns.add(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.