From 103d837bcfea0015c9e1560c94efb7cad3268ef3 Mon Sep 17 00:00:00 2001
From: Sonia Zorba <zorba@oats.inaf.it>
Date: Tue, 30 Jan 2018 16:47:52 +0100
Subject: [PATCH] Added (a lots of) comments to code
---
.../java/it/inaf/ia2/tsm/ChildEntity.java | 22 +-
.../src/main/java/it/inaf/ia2/tsm/Column.java | 17 ++
.../java/it/inaf/ia2/tsm/ColumnHolder.java | 3 +
.../it/inaf/ia2/tsm/ConsistencyChecks.java | 225 +++++++++++++++++-
.../it/inaf/ia2/tsm/EntitiesContainer.java | 47 ++--
.../java/it/inaf/ia2/tsm/EntityProperty.java | 42 +++-
.../ia2/tsm/InconsistentColumnProperty.java | 50 +++-
.../src/main/java/it/inaf/ia2/tsm/Key.java | 68 +++++-
.../main/java/it/inaf/ia2/tsm/KeyColumn.java | 27 ++-
.../main/java/it/inaf/ia2/tsm/KeyHolder.java | 17 +-
.../src/main/java/it/inaf/ia2/tsm/Schema.java | 5 +-
.../src/main/java/it/inaf/ia2/tsm/Table.java | 58 ++++-
.../java/it/inaf/ia2/tsm/TapSchemaEntity.java | 97 ++++++--
.../java/it/inaf/ia2/tsm/TapSchemaMender.java | 4 +-
.../it/inaf/ia2/tsm/UpdateOperations.java | 4 +-
.../java/it/inaf/ia2/tsm/WrongDataType.java | 67 +++---
.../ia2/tsm/datalayer/DBBrokerTemplate.java | 6 +-
.../it/inaf/ia2/tsm/model/ColumnModel.java | 60 +++++
.../src/main/webapp/consistencyChecks.xhtml | 8 +-
19 files changed, 695 insertions(+), 132 deletions(-)
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ChildEntity.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ChildEntity.java
index 7ff7479..df9e07a 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ChildEntity.java
+++ b/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();
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Column.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Column.java
index a85d678..73648d9 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Column.java
+++ b/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;
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ColumnHolder.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ColumnHolder.java
index 57a870d..431953c 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ColumnHolder.java
+++ b/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 {
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ConsistencyChecks.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ConsistencyChecks.java
index 7b34732..54d9b1a 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/ConsistencyChecks.java
+++ b/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();
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntitiesContainer.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntitiesContainer.java
index 01c9c95..f7731ca 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntitiesContainer.java
+++ b/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();
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntityProperty.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntityProperty.java
index c09d49a..f9bfbbf 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/EntityProperty.java
+++ b/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() {
return value;
}
+ /**
+ * Returns the initial value of this property.
+ */
public T getOriginalValue() {
return originalValue;
}
+ /**
+ * Returns the default value for this property, as defined into the
+ * {@code ColumnModel} parsed from the XML configuration.
+ */
public T getDefaultValue() {
return defaultValue;
}
+ /**
+ * Sets the current value for this property.
+ */
public <X> void setValue(X value) {
this.setValue(value, true);
}
@@ -82,6 +92,9 @@ public class EntityProperty<T> implements Serializable {
this.value = (T) value;
}
+ /**
+ * Returns true if the current value is different from the initial value.
+ */
public boolean isChanged() {
if (changed) {
return true;
@@ -92,12 +105,12 @@ public class EntityProperty<T> implements Serializable {
return !originalValue.equals(value);
}
- public void setChanged(boolean changed) {
- this.changed = changed;
- }
-
/**
- * Initialize the value.
+ * Initializes the value of the property.
+ *
+ * @param <X> a class compatible con the {@code ColumnModel} definition used
+ * by this property.
+ * @param initialValue the initial value for this property.
*/
public final <X> void init(X initialValue) {
if (!propertyModel.isNullable() && initialValue == null) {
@@ -107,18 +120,35 @@ public class EntityProperty<T> implements Serializable {
this.originalValue = (T) initialValue;
}
+ /**
+ * Sets the current value as the initial value.
+ */
public void save() {
this.originalValue = value;
}
+ /**
+ * Returns the class of the property value.
+ */
public Class getType() {
return type;
}
+ /**
+ * Indicates if the property value can be edited by the user.
+ *
+ * @return true if the property value can be edited by the user, false
+ * otherwise
+ */
public boolean isUpdatable() {
return propertyModel.isUpdatable();
}
+ /**
+ * Indicates if the property can have a null value.
+ *
+ * @return true if the property can have a null value, false otherwise.
+ */
public boolean isNullable() {
return propertyModel.isNullable();
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/InconsistentColumnProperty.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/InconsistentColumnProperty.java
index fc567ab..39b0b70 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/InconsistentColumnProperty.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/InconsistentColumnProperty.java
@@ -25,21 +25,36 @@ package it.inaf.ia2.tsm;
import java.io.Serializable;
/**
+ * Models a value stored in a TAP_SCHEMA column entity having a wrong value
+ * according to the information read from the database metadata (or
+ * information_schema).
+ * <p>
+ * Example: the structure of a table exposed by the TAP_SCHEMA has changed
+ * setting a varchar column length from 255 to 50. In this case the
+ * {@code arraysize} value will contain an inconsistent value and this has to be
+ * detected by the consistency checking mechanism.
*
+ * @see it.inaf.ia2.tsm.ConsistencyChecks
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
public class InconsistentColumnProperty implements Serializable {
private static final long serialVersionUID = -5145865322582594970L;
- private ColumnHolder columnHolder;
- private String key;
- private Object currentValue;
- private Object correctValue;
-
- private InconsistentColumnProperty() {
- }
+ private final ColumnHolder columnHolder;
+ private final String key;
+ private final Object currentValue;
+ private final Object correctValue;
+ /**
+ * Default constructor.
+ *
+ * @param columnHolder the model representing the column owning the
+ * inconsistent property.
+ * @param key the name of the inconsistent property.
+ * @param currentValue the (inconsistent) value stored into the TAP_SCHEMA.
+ * @param correctValue the value read from the database metadata.
+ */
public InconsistentColumnProperty(ColumnHolder columnHolder, String key, Object currentValue, Object correctValue) {
this.columnHolder = columnHolder;
this.key = key;
@@ -47,14 +62,14 @@ public class InconsistentColumnProperty implements Serializable {
this.correctValue = correctValue;
}
+ /**
+ * Returns the model representing the column owning the inconsistent
+ * property.
+ */
public ColumnHolder getColumnHolder() {
return columnHolder;
}
- public void setColumnHolder(ColumnHolder columnHolder) {
- this.columnHolder = columnHolder;
- }
-
public String getTableCompleteName() {
return String.format("%s.%s", columnHolder.getSchemaName(), columnHolder.getTableName());
}
@@ -62,15 +77,26 @@ public class InconsistentColumnProperty implements Serializable {
public String getColumnName() {
return columnHolder.getColumnName();
}
-
+
+ /**
+ * Returns the name of the property containing the inconsistent value.
+ */
public String getKey() {
return key;
}
+ /**
+ * Returns the (inconsistent) value of the property stored into the
+ * TAP_SCHEMA.
+ */
public Object getCurrentValue() {
return currentValue;
}
+ /**
+ * Returns the (correct) value of the property, as read from the database
+ * metadata.
+ */
public Object getCorrectValue() {
return correctValue;
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Key.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Key.java
index b16933c..1e65b1d 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Key.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Key.java
@@ -32,7 +32,7 @@ import java.util.Objects;
import java.util.regex.Pattern;
/**
- * The main implementation of {@link Key}.
+ * Represents a Key entity belonging to a {@link TapSchema}.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
@@ -52,10 +52,18 @@ public class Key extends TapSchemaEntity implements Serializable {
private String targetSchema;
private String targetTable;
+ /**
+ * Only for serialization.
+ */
private Key() {
super();
}
+ /**
+ * Default constructor.
+ *
+ * @see TapSchemaEntity
+ */
public Key(TapSchema tapSchema, Map<String, Object> metadata) {
super(tapSchema, tapSchema.getTableModel(TapSchema.KEYS_TABLE), metadata);
@@ -71,18 +79,42 @@ public class Key extends TapSchemaEntity implements Serializable {
targetTable = targetSplit[1];
}
+ /**
+ * Tells if a key has to be exposed by the TAP_SCHEMA. This happens when
+ * both the key {@code from_column} and {@code target_column} have been
+ * added to the TAP_SCHEMA.
+ *
+ * @return true if the column has to be exposed by the TAP_SCHEMA, false
+ * otherwise.
+ */
public boolean isVisible() {
return visible;
}
+ /**
+ * Update the key visibility.
+ *
+ * @param visible true if the key has to be exposed by the TAP_SCHEMA, false
+ * otherwise.
+ */
protected void setVisible(boolean visible) {
this.visible = visible;
}
+ /**
+ * Returns the identifier for this key. The TAP standard defines it as a
+ * String, but TASMAN sets its value as an incremental integer (stored as a
+ * String). Keys not already persisted have a null id.
+ */
public String getId() {
return getValue(ID_KEY, String.class);
}
+ /**
+ * Sets the identifier for this key.
+ *
+ * @see {@code getId()}
+ */
public void setId(String id) {
setValue(ID_KEY, id);
for (KeyColumn keyColumn : keyColumns) {
@@ -90,34 +122,65 @@ public class Key extends TapSchemaEntity implements Serializable {
}
}
+ /**
+ * Returns all the {@code KeyColumn}s owned by this key.
+ */
public List<KeyColumn> getKeyColumns() {
return Collections.unmodifiableList(keyColumns);
}
+ /**
+ * Returns the name of the schema owning the foreign key.
+ */
public String getFromSchemaName() {
return fromSchema;
}
+ /**
+ * Returns the name of the table owning the foreign key (the name of the
+ * table, without its schema name).
+ */
public String getFromTableSimpleName() {
return fromTable;
}
+ /**
+ * Returns the complete name of the table owning the foreign key (the schema
+ * name plus the table name).
+ */
public String getFromTableCompleteName() {
return getValue(FROM_TABLE_KEY, String.class);
}
+ /**
+ * Returns the name of the schema owning the primary key.
+ */
public String getTargetSchemaName() {
return targetSchema;
}
+ /**
+ * Returns the name of the table owning the primary key (the name of the
+ * table, without its schema name).
+ */
public String getTargetTableSimpleName() {
return targetTable;
}
+ /**
+ * Returns the complete name of the table owning the primary key (the schema
+ * name plus the table name).
+ */
public String getTargetTableCompleteName() {
return getValue(TARGET_TABLE_KEY, String.class);
}
+ /**
+ * Adds a {@link KeyColumn} object to this key.
+ *
+ * @param fromColumn the name of the column owning the foreign key.
+ * @param targetColumn the name of the column owning the primary key.
+ */
public KeyColumn addKeyColumn(String fromColumn, String targetColumn) {
Map<String, Object> keyColumnMetadata = new HashMap<>();
keyColumnMetadata.put(KeyColumn.FROM_COLUMN_KEY, fromColumn);
@@ -127,6 +190,9 @@ public class Key extends TapSchemaEntity implements Serializable {
return keyColumn;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public void save() {
if (!isVisible()) {
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyColumn.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyColumn.java
index af97007..cba11a9 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyColumn.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyColumn.java
@@ -26,7 +26,8 @@ import java.util.Map;
import java.util.Objects;
/**
- * The main implementation of {@link KeyColumn}.
+ * Represents a {@code KeyColumn} entity belonging to a {@link TapSchema}. Each
+ * {@link Key} owns one or more {@code KeyColumn}s.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
@@ -40,32 +41,54 @@ public class KeyColumn extends TapSchemaEntity {
private Key key;
+ /**
+ * Only for serialization.
+ */
private KeyColumn() {
- // for serialization
super();
}
+ /**
+ * Default constructor.
+ *
+ * @see TapSchemaEntity
+ */
protected KeyColumn(TapSchema tapSchema, Key key, Map<String, Object> keyColumnMetadata) {
super(tapSchema, tapSchema.getTableModel(TapSchema.KEY_COLUMNS_TABLE), keyColumnMetadata);
this.key = key;
}
+ /**
+ * Returns the {@link Key} owning this {@code KeyColumn}.
+ */
public Key getParent() {
return key;
}
+ /**
+ * Returns the id of the parent key.
+ */
public String getKeyId() {
return getValue(KEY_ID_KEY, String.class);
}
+ /**
+ * Sets the id of the parent key.
+ */
public void setKeyId(String keyId) {
setValue(KEY_ID_KEY, keyId);
}
+ /**
+ * Returns the name of the column owning the foreign key.
+ */
public String getFromColumn() {
return getValue(FROM_COLUMN_KEY, String.class);
}
+ /**
+ * Returns the name of the column owning the primary key.
+ */
public String getTargetColumn() {
return getValue(TARGET_COLUMN_KEY, String.class);
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyHolder.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyHolder.java
index a8fff37..e554a5b 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyHolder.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/KeyHolder.java
@@ -25,21 +25,20 @@ package it.inaf.ia2.tsm;
import java.io.Serializable;
/**
- *
+ * Model used during consistency checking phase to represents a
+ *
+ *
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
public class KeyHolder implements Serializable {
private static final long serialVersionUID = 3711149068153684261L;
- private String keyId;
- private String fromTable;
- private String[] fromColumns;
- private String targetTable;
- private String[] targetColumns;
-
- private KeyHolder() {
- }
+ private final String keyId;
+ private final String fromTable;
+ private final String[] fromColumns;
+ private final String targetTable;
+ private final String[] targetColumns;
public KeyHolder(String keyId, String fromTable, String[] fromColumns, String targetTable, String[] targetColumns) {
this.keyId = keyId;
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Schema.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Schema.java
index e168d97..227576d 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Schema.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Schema.java
@@ -90,7 +90,6 @@ public class Schema extends ChildEntity<TapSchema> implements EntitiesContainer<
/**
* @param tableSimpleName the name of the table, without the schema name.
- * @return
*/
@Override
public Table addChild(String tableSimpleName) throws SQLException {
@@ -186,6 +185,10 @@ public class Schema extends ChildEntity<TapSchema> implements EntitiesContainer<
return TSMUtil.getAddableChildrenNames(tables);
}
+
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean isAddable(String childName) {
return tables.containsKey(childName);
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Table.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Table.java
index 1ecb213..2c68261 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Table.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/Table.java
@@ -33,7 +33,7 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * The main implementation of {@link Table}.
+ * Represents a Table entity belonging to a {@link TapSchema}.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
@@ -56,11 +56,20 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
// WARNING: this is different from tableModel inherited field.
private TableModel tableTableModel;
+ /**
+ * Only for serialization.
+ */
private Table() {
- // for serialization
super();
}
+ /**
+ * If this table is one of the TAP_SCHEMA tables or it is the ObsCore table
+ * this method returns the related {@link TableModel}. This method is used
+ * inside the constructor to set the {@link #tableTableModel} field.
+ * <strong>WARNING</strong>: this has a different meaning compared to the
+ * inherited {@link #getTableModel()} method.
+ */
private TableModel getTableTableModel() {
if (tapSchema.getName().equals(parentSchema.getName())) {
return tapSchema.getTapSchemaModel().getTable(simpleName);
@@ -89,6 +98,16 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
}
+ /**
+ * Default constructor.
+ *
+ * @see TapSchemaEntity
+ * @param tapSchema the {@code TapSchema} owning this table.
+ * @param schema the {@code Schema} owning this table.
+ * @param tableSimpleName the name of the table without its schema name.
+ * @throws SQLException if there are problems while retrieving columns
+ * metadata.
+ */
protected Table(TapSchema tapSchema, Schema schema, String tableSimpleName) throws SQLException {
super(tapSchema, tapSchema.getTableModel(TapSchema.TABLES_TABLE), schema.getTableMetadata(tableSimpleName));
@@ -113,7 +132,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * Only the table name.
+ * Returns only the table name (without the schema name).
*/
@Override
public String getName() {
@@ -121,7 +140,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@code schema_name.table_name}.
+ * Returns the complete table name: {@code schema_name.table_name}.
*/
public String getCompleteName() {
return getValue(TABLE_NAME_KEY, String.class);
@@ -135,7 +154,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@inheritDoc }
+ * {@inheritDoc}
*/
@Override
public Column addChild(String columnName) {
@@ -171,7 +190,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@inheritDoc }
+ * {@inheritDoc}
*/
@Override
public void removeChild(String columnName) {
@@ -200,7 +219,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@inheritDoc }
+ * {@inheritDoc}
*/
@Override
public Column getChild(String childName, Status... statuses) {
@@ -208,7 +227,7 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@inheritDoc }
+ * {@inheritDoc}
*/
@Override
public List<Column> getChildren(Status... statuses) {
@@ -216,23 +235,32 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
/**
- * {@inheritDoc }
+ * {@inheritDoc}
*/
@Override
public List<String> getAddableChildrenNames() {
return TSMUtil.getAddableChildrenNames(columns);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean isAddable(String childName) {
return columns.containsKey(childName);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public List<Column> getAddedChildren() {
return getChildren(Status.ADDED_PERSISTED, Status.ADDED_NOT_PERSISTED);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public List<Column> getAddedOrRemovedChildren() {
return getChildren(Status.ADDED_PERSISTED, Status.ADDED_NOT_PERSISTED, Status.TO_REMOVE, Status.REMOVED_NOT_PERSISTED);
@@ -267,11 +295,23 @@ public class Table extends ChildEntity<Schema> implements EntitiesContainer<Colu
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public Schema getParent() {
return parentSchema;
}
+ /**
+ * Returns the metadata about a column children of this table. Metadata are
+ * column properties the value of which can be retrieved from the database
+ * metadata (or information_schema).
+ *
+ * @param columnName the name of the column of which retrieve the metadata.
+ * @return a {@code Map} the keys of which are property names and the values
+ * of which are property values retrieved from database metadata.
+ */
public Map<String, Object> getColumnMetadata(String columnName) {
return columnsMetadata.get(columnName);
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaEntity.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaEntity.java
index e9506a3..3e02e56 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaEntity.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaEntity.java
@@ -35,8 +35,9 @@ import org.slf4j.LoggerFactory;
/**
* Represents an object that is mapped on a table of the TAP_SCHEMA.
*
- * A TapSchemaEntity has some properties that correspond to columns of the table
- * represented by the TapSchemaEntity.<br>
+ * A {@code TapSchemaEntity} has some properties that correspond to columns of
+ * the table represented by the {@code TapSchemaEntity}.
+ * <p>
* Property value can be changed but the original value has to be maintained
* until the {@link #save()} method is called.
*
@@ -52,9 +53,23 @@ public abstract class TapSchemaEntity implements Serializable {
protected TapSchema tapSchema;
private TableModel tableModel;
+ /**
+ * Only for serialization.
+ */
protected TapSchemaEntity() {
}
+ /**
+ * Default constructor.
+ *
+ * @param tapSchema the {@code TapSchema} owning this entity.
+ * @param tableModel the {@code TableModel} defining this entity (for
+ * example, if the instance of this entity is a {@link Column}, the
+ * {@code TableModel} represents the TAP_SCHEMA {@code columns} table).
+ * @param metadata a map containing the property values read from the
+ * database metadata or information_schema (this properties can't be edited
+ * or have always a suggested value).
+ */
public TapSchemaEntity(TapSchema tapSchema, TableModel tableModel, Map<String, Object> metadata) {
this.tapSchema = tapSchema;
this.tableModel = tableModel;
@@ -63,6 +78,10 @@ public abstract class TapSchemaEntity implements Serializable {
fillProperties();
}
+ /**
+ * Initializes the properties owned by this entity, retrieving them from the
+ * {@code metadata} map.
+ */
private void fillProperties() {
for (ColumnModel propModel : tableModel.getColumns()) {
Object defaultValue = null;
@@ -86,24 +105,36 @@ public abstract class TapSchemaEntity implements Serializable {
}
}
+ /**
+ * Returns a property value that has been read from the database metadata
+ * (or information_schema), given the name of the property owned by this
+ * entity.
+ *
+ * @param key the name of a property owned by this entity.
+ * @return the value of the property read from the database metadata, null
+ * if no value for the given property name has been retrieved.
+ */
public Object getMetadata(String key) {
return metadata.get(key);
}
/**
- * Initializes the value of a property (store the original value).
+ * Initializes the value of a property (stores the original value).
+ *
+ * @param <T> a class compatible with the definition for the given column.
+ * @param key the name of the property.
+ * @param value the initial value for the property.
*/
public <T> void initProperty(String key, T value) {
properties.get(key).init(value);
}
- protected String getVersion() {
- return tapSchema.getVersion();
- }
-
/**
* Returns true if one or more property values is changed (the current value
* is different from the original value).
+ *
+ * @return true if one or more properties owned by this entity have been
+ * changed, false otherwise.
*/
public boolean isChanged() {
for (EntityProperty property : properties.values()) {
@@ -114,57 +145,84 @@ public abstract class TapSchemaEntity implements Serializable {
return false;
}
+ /**
+ * Returns the value of a property owned by this entity, given its name.
+ *
+ * @param key the name of the property.
+ * @return the value of the property.
+ */
public Object getValue(String key) {
return properties.get(key).getValue();
}
+ /**
+ * Returns the Java class type of a property owned by this entity, given its
+ * name.
+ *
+ * @param key key the name of the property.
+ * @return the Java class type of the property.
+ */
public Class getPropertyType(String key) {
return properties.get(key).getType();
}
+ /**
+ * Returns a property owned by this entity, given its name.
+ *
+ * @param key the name of the property.
+ * @return an {@link EntityProperty}
+ */
public EntityProperty getProperty(String key) {
return properties.get(key);
}
/**
- * Retrieve the current value of the property (the last value set).
+ * Returns the current value of the property (the last value set).
*/
public <T> T getValue(String key, Class<T> type) {
return (T) properties.get(key).getValue();
}
+ /**
+ * Sets a new value to a property owned by this entity.
+ *
+ * @param key the name of the property.
+ * @param value the new value of the property.
+ */
public void setValue(String key, Object value) {
properties.get(key).setValue(value);
}
/**
- * Retrieve the original value of the property.
+ * Retrieve the original/initial value of the property.
*
* @param key the name of the property (the name of the table column).
* @param type the class of the property value.
- * @return
+ * @return the value with which the property has been initialized.
*/
public <T> T getOriginalValue(String key, Class<T> type) {
return (T) properties.get(key).getOriginalValue();
}
/**
- * Returns true the value of property which key is passed as parameter is
- * changed (the current value is different from the original value).
+ * Returns true the value of property the key of which is passed as
+ * parameter is changed (the current value is different from the original
+ * value).
*/
public boolean isChanged(String key) {
return properties.get(key).isChanged();
}
/**
- * Retrieve a list of all properties names (the names of the table columns).
+ * Retrieves a list of all properties names (the names of the table columns)
+ * owned by this entity.
*/
public List<String> getPropertiesKeys() {
return new ArrayList<>(properties.keySet());
}
/**
- * Marks the TapSchemaEntity as saved (all original values are set equals to
+ * Marks this entity as saved (all original values are set equals to their
* current values).
*/
public void save() {
@@ -174,15 +232,10 @@ public abstract class TapSchemaEntity implements Serializable {
}
/**
- * Set the correct value for a fixed property that has inconsistent value in
- * the TAP_SCHEMA.
+ * Returns the {@code TableModel} defining this entity (for example, if the
+ * instance of this entity is a {@link Column}, the {@code TableModel}
+ * represents the TAP_SCHEMA {@code columns} table).
*/
- public <T> void amendProperty(String key, T value) {
- EntityProperty prop = properties.get(key);
- prop.init(value);
- prop.setChanged(true);
- }
-
public TableModel getTableModel() {
return tableModel;
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaMender.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaMender.java
index 40402e1..13346e0 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaMender.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/TapSchemaMender.java
@@ -119,10 +119,10 @@ public class TapSchemaMender {
for (String schema : consistencyChecks.getUnexisingSchemas()) {
keysToRemoveIds.addAll(tapSchemaDBBroker.getKeysToRemove(tapSchemaName, schema));
}
- for (String table : consistencyChecks.getUnexisingTables()) {
+ for (String table : consistencyChecks.getUnexistingTables()) {
keysToRemoveIds.addAll(tapSchemaDBBroker.getKeysToRemove(tapSchemaName, table));
}
- for (ColumnHolder unexistingColumn : consistencyChecks.getUnexisingColumns()) {
+ for (ColumnHolder unexistingColumn : consistencyChecks.getUnexistingColumns()) {
keysToRemoveIds.addAll(tapSchemaDBBroker.getKeysToRemoveFromUnexistingColumn(tapSchemaName, unexistingColumn));
}
for (KeyHolder unexistingKey : consistencyChecks.getUnexistingKeys()) {
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/UpdateOperations.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/UpdateOperations.java
index 68fc839..9df0f31 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/UpdateOperations.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/UpdateOperations.java
@@ -29,9 +29,9 @@ import org.slf4j.LoggerFactory;
/**
* List of operations that have to be performed by the
- * {@link it.inaf.oats.ia2.tapschemamanager.contract.TapSchema#save()} method,
+ * {@link it.inaf.ia2.tsm.TapSchema#save()} method,
* in terms of adding, updating or removing
- * {@link it.inaf.ia2.tsm.api.TapSchemaEntity} entities. Could be used
+ * {@link it.inaf.ia2.tsm.TapSchemaEntity} entities. Could be used
* stand-alone to obtain a preview of the operations that will be performed on
* the database.
*
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/WrongDataType.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/WrongDataType.java
index cd429eb..7de2eb3 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/WrongDataType.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/WrongDataType.java
@@ -25,6 +25,10 @@ package it.inaf.ia2.tsm;
import java.io.Serializable;
/**
+ * Models an inconsistency in a column definition detected in an existing
+ * column. This happens when the column datatype read from the database metadata
+ * is different from which is expected according the {@link ColumnModel}
+ * defining that column. To fix this issue an {@code ALTER TABLE} is necessary.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
@@ -32,15 +36,23 @@ public class WrongDataType implements Serializable {
private static final long serialVersionUID = 1541867434766884291L;
- private ColumnHolder columnHolder;
- private String wrongDataType;
- private String correctDataType;
- private String adqlCorrectDataType;
- private Integer size;
-
- public WrongDataType() {
- }
-
+ private final ColumnHolder columnHolder;
+ private final String wrongDataType;
+ private final String correctDataType;
+ private final String adqlCorrectDataType;
+ private final Integer size;
+
+ /**
+ * Default constructor.
+ *
+ * @param columnHolder a representation for the column having a wrong
+ * datatype.
+ * @param wrongDataType the current (wrong) column datatype.
+ * @param correctDataType the expected column datatype.
+ * @param adqlCorrectDataType the expected column datatype, using ADQL
+ * datatype syntax.
+ * @param size the expected column size.
+ */
public WrongDataType(ColumnHolder columnHolder, String wrongDataType, String correctDataType, String adqlCorrectDataType, Integer size) {
this.columnHolder = columnHolder;
this.wrongDataType = wrongDataType;
@@ -49,43 +61,40 @@ public class WrongDataType implements Serializable {
this.size = size;
}
+ /**
+ * Returns the representation of the column having the wrong datatype.
+ */
public ColumnHolder getColumnHolder() {
return columnHolder;
}
- public void setColumnHolder(ColumnHolder columnHolder) {
- this.columnHolder = columnHolder;
- }
-
+ /**
+ * Returns the current (wrong) datatype, as retrieved from the database
+ * metadata.
+ */
public String getWrongDataType() {
return wrongDataType;
}
- public void setWrongDataType(String wrongDataType) {
- this.wrongDataType = wrongDataType;
- }
-
+ /**
+ * Returns the expected datatype, according to the {@link ColumnModel}
+ * associated to this column.
+ */
public String getCorrectDataType() {
return correctDataType;
}
- public void setCorrectDataType(String correctDataType) {
- this.correctDataType = correctDataType;
- }
-
+ /**
+ * Returns the expected datatype, using ADQL datatype syntax.
+ */
public String getAdqlCorrectDataType() {
return adqlCorrectDataType;
}
- public void setAdqlCorrectDataType(String adqlCorrectDataType) {
- this.adqlCorrectDataType = adqlCorrectDataType;
- }
-
+ /**
+ * Returns the desired columns size.
+ */
public Integer getSize() {
return size;
}
-
- public void setSize(Integer size) {
- this.size = size;
- }
}
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/datalayer/DBBrokerTemplate.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/datalayer/DBBrokerTemplate.java
index 311e0d9..ddb3b6a 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/datalayer/DBBrokerTemplate.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/datalayer/DBBrokerTemplate.java
@@ -925,7 +925,7 @@ public abstract class DBBrokerTemplate implements DBBroker {
}
// Removing all columns
- for (ColumnHolder unexistingColumn : consistencyChecks.getUnexisingColumns()) {
+ for (ColumnHolder unexistingColumn : consistencyChecks.getUnexistingColumns()) {
query = String.format("DELETE FROM %s.%s WHERE table_name = ? AND column_name = ?", tapSchemaNameEscaped, escape(TapSchema.COLUMNS_TABLE));
try (PreparedStatement ps = conn.prepareStatement(query)) {
String completeTableName = String.format("%s.%s",
@@ -936,7 +936,7 @@ public abstract class DBBrokerTemplate implements DBBroker {
ps.executeUpdate();
}
}
- for (String table : consistencyChecks.getUnexisingTables()) {
+ for (String table : consistencyChecks.getUnexistingTables()) {
query = String.format("DELETE FROM %s.%s WHERE table_name = ?", tapSchemaNameEscaped, escape(TapSchema.COLUMNS_TABLE));
try (PreparedStatement ps = conn.prepareStatement(query)) {
ps.setString(1, table);
@@ -954,7 +954,7 @@ public abstract class DBBrokerTemplate implements DBBroker {
}
// Removing all tables
- for (String table : consistencyChecks.getUnexisingTables()) {
+ for (String table : consistencyChecks.getUnexistingTables()) {
query = String.format("DELETE FROM %s.%s WHERE table_name = ?", tapSchemaNameEscaped, escape(TapSchema.TABLES_TABLE));
try (PreparedStatement ps = conn.prepareStatement(query)) {
ps.setString(1, table);
diff --git a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/model/ColumnModel.java b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/model/ColumnModel.java
index 670e0f0..2317fcb 100644
--- a/TASMAN-core/src/main/java/it/inaf/ia2/tsm/model/ColumnModel.java
+++ b/TASMAN-core/src/main/java/it/inaf/ia2/tsm/model/ColumnModel.java
@@ -30,6 +30,7 @@ import javax.xml.bind.annotation.XmlTransient;
import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
/**
+ * Models a database column managed by TASMAN.
*
* @author Sonia Zorba {@literal <zorba at oats.inaf.it>}
*/
@@ -63,6 +64,9 @@ public class ColumnModel implements Serializable {
mandatory = true;
}
+ /**
+ * The column name
+ */
@XmlAttribute(name = "name")
public String getName() {
return name;
@@ -72,6 +76,9 @@ public class ColumnModel implements Serializable {
this.name = name;
}
+ /**
+ * The column type, in ADQL datatype format.
+ */
@XmlElement(name = "type")
public String getType() {
return type;
@@ -81,6 +88,10 @@ public class ColumnModel implements Serializable {
this.type = type;
}
+ /**
+ * The column size, if it can be set, null otherwise (for example VARCHAR
+ * must have a size, INTEGER not).
+ */
@XmlElement(name = "size")
public Integer getSize() {
return size;
@@ -90,6 +101,9 @@ public class ColumnModel implements Serializable {
this.size = size;
}
+ /**
+ * True if the user can edit the value, false otherwise.
+ */
@XmlElement(name = "updatable", defaultValue = "true")
public boolean isUpdatable() {
return updatable;
@@ -99,6 +113,9 @@ public class ColumnModel implements Serializable {
this.updatable = updatable;
}
+ /**
+ * True if the column can contain null values, false otherwise.
+ */
@XmlElement(name = "nullable", defaultValue = "true")
public boolean isNullable() {
return nullable;
@@ -108,6 +125,9 @@ public class ColumnModel implements Serializable {
this.nullable = nullable;
}
+ /**
+ * True if VO defines the column as a standard.
+ */
@XmlElement(name = "standard", defaultValue = "false")
public boolean isStandard() {
return standard;
@@ -117,6 +137,9 @@ public class ColumnModel implements Serializable {
this.standard = standard;
}
+ /**
+ * Used for defining ObsCore mandatory or optional columns.
+ */
@XmlElement(name = "mandatory", defaultValue = "true")
public boolean isMandatory() {
return mandatory;
@@ -126,6 +149,9 @@ public class ColumnModel implements Serializable {
this.mandatory = mandatory;
}
+ /**
+ * Specify the column default value.
+ */
@XmlElement(name = "default-value")
public String getDefaultValueString() {
return defaultValueString;
@@ -135,6 +161,10 @@ public class ColumnModel implements Serializable {
this.defaultValueString = defaultValue;
}
+ /**
+ * Key to use for retrieving the initial values of the column from the
+ * {@code TapSchemaEntity} {@code metadata} field.
+ */
@XmlElement(name = "key")
public String getLoaderKey() {
return loaderKey;
@@ -144,6 +174,9 @@ public class ColumnModel implements Serializable {
this.loaderKey = loaderMethod;
}
+ /**
+ * Column description (used to fill TAP_SCHEMA schema description fields).
+ */
@XmlElement(name = "description")
public String getDescription() {
return description;
@@ -153,6 +186,9 @@ public class ColumnModel implements Serializable {
this.description = description;
}
+ /**
+ * UCD for ObsCore columns.
+ */
@XmlElement(name = "ucd")
public String getUcd() {
return ucd;
@@ -162,6 +198,9 @@ public class ColumnModel implements Serializable {
this.ucd = ucd;
}
+ /**
+ * Utype for ObsCore columns.
+ */
@XmlElement(name = "utype")
public String getUtype() {
return utype;
@@ -171,6 +210,9 @@ public class ColumnModel implements Serializable {
this.utype = utype;
}
+ /**
+ * VOUnit for ObsCore columns.
+ */
@XmlElement(name = "unit")
public String getUnit() {
return unit;
@@ -180,6 +222,9 @@ public class ColumnModel implements Serializable {
this.unit = unit;
}
+ /**
+ * Defines if the columns is a principal one according to TAP standard.
+ */
@XmlElement(name = "principal", defaultValue = "false")
public boolean isPrincipal() {
return principal;
@@ -189,6 +234,9 @@ public class ColumnModel implements Serializable {
this.principal = principal;
}
+ /**
+ * Used in ObsCore table for specifying an enum constraint.
+ */
@XmlElement(name = "enum-values", nillable = true, required = false)
@XmlJavaTypeAdapter(CommaSeparatedListAdapter.class)
public List<String> getEnumValues() {
@@ -199,6 +247,9 @@ public class ColumnModel implements Serializable {
this.enumValues = enumValues;
}
+ /**
+ * Define the minimum value allowed for the column.
+ */
@XmlElement(name = "min", nillable = true, required = false)
public Integer getMinValue() {
return minValue;
@@ -208,6 +259,9 @@ public class ColumnModel implements Serializable {
this.minValue = minValue;
}
+ /**
+ * Define the maximum value allowed for the column.
+ */
@XmlElement(name = "max", nillable = true, required = false)
public Integer getMaxValue() {
return maxValue;
@@ -217,6 +271,9 @@ public class ColumnModel implements Serializable {
this.maxValue = maxValue;
}
+ /**
+ * Retrieve the default value.
+ */
@XmlTransient
public Object getDefaultValue() {
if (defaultValueString == null) {
@@ -225,6 +282,9 @@ public class ColumnModel implements Serializable {
return TypesMapping.parseDefaultValue(defaultValueString, getType());
}
+ /**
+ * Retrieve the Java type from the column datatype.
+ */
@XmlTransient
public Class getJavaType() {
return TypesMapping.getClassFromAdqlType(getType());
diff --git a/TASMAN-webapp/src/main/webapp/consistencyChecks.xhtml b/TASMAN-webapp/src/main/webapp/consistencyChecks.xhtml
index 36dbd1c..9b7ee7d 100644
--- a/TASMAN-webapp/src/main/webapp/consistencyChecks.xhtml
+++ b/TASMAN-webapp/src/main/webapp/consistencyChecks.xhtml
@@ -47,7 +47,7 @@
</h:panelGroup>
<h:panelGroup rendered="#{consistency.tapSchema.consistencyChecks.unexisingSchemas.size() gt 0}">
- <h2>Unexisting schemas</h2>
+ <h2>Inexistent schemas</h2>
<ul>
<ui:repeat value="#{consistency.tapSchema.consistencyChecks.unexisingSchemas}" var="schema">
<li>${schema}</li>
@@ -56,7 +56,7 @@
</h:panelGroup>
<h:panelGroup rendered="#{consistency.tapSchema.consistencyChecks.unexisingTables.size() gt 0}">
- <h2>Unexisting tables</h2>
+ <h2>Inexistent tables</h2>
<ul>
<ui:repeat value="#{consistency.tapSchema.consistencyChecks.unexisingTables}" var="table">
<li>${table}</li>
@@ -65,7 +65,7 @@
</h:panelGroup>
<h:panelGroup rendered="#{consistency.tapSchema.consistencyChecks.unexisingColumns.size() gt 0}">
- <h2>Unexisting columns</h2>
+ <h2>Inexistent columns</h2>
<ul>
<ui:repeat value="#{consistency.tapSchema.consistencyChecks.unexisingColumns.toArray()}" var="column">
<li>${column}</li>
@@ -74,7 +74,7 @@
</h:panelGroup>
<h:panelGroup rendered="#{consistency.tapSchema.consistencyChecks.unexistingKeys.size() gt 0}">
- <h2>Unexisting keys</h2>
+ <h2>Inexistent keys</h2>
<ul>
<ui:repeat value="#{consistency.tapSchema.consistencyChecks.unexistingKeys.toArray()}" var="key">
<li>${key}</li>
--
GitLab