Update documentation

bda-controller/src/main/java/gr/ntua/ece/cslab/selis/bda/controller/Entrypoint.java

@@ -38,12 +38,20 @@
 
 /**
  * Created by Giannis Giannakopoulos on 8/31/17.
+ * This class represents the actual BDA server and contains all the functional components
+ * that need to be instantiated when the server is launched.
  */
 public class Entrypoint {
     private final static Logger LOGGER = Logger.getLogger(Entrypoint.class.getCanonicalName());
     public static Configuration configuration;
 
-
+    /**
+     * This is the main method of the BDA server which is used when starting and stopping it to
+     * initialize or shutdown connections with the IAM server, the BDA database and the Pub/Sub
+     * server and also to start/stop the CronJob scheduler.
+     * @param args the BDA configuration file
+     * @throws SystemConnectorException
+     */
     public static void main(String[] args) throws SystemConnectorException {
         if (args.length < 1) {
             LOGGER.log(Level.WARNING, "Please provide a configuration file as a first argument");

bda-datastore/src/main/java/gr/ntua/ece/cslab/selis/bda/datastore/beans/DimensionTable.java

@@ -24,6 +24,12 @@
 
 /**
  * Created by Giannis Giannakopoulos on 10/11/17.
+ * This class represents a Dimension (Entity) Table.
+ *
+ * Entity Tables are modeled as resources identified by a name, a schema, and the data they
+ * are storing.
+ *
+ * @see DimensionTableSchema
  */
 @XmlRootElement(name = "DimensionTable")
 @XmlAccessorType(XmlAccessType.PUBLIC_MEMBER)
@@ -32,34 +38,60 @@ public class DimensionTable {
     private DimensionTableSchema schema;
     private List<Tuple> data;
 
+    /**
+     * A simple placeholder constructor.
+     */
     public DimensionTable(){ this.data = new LinkedList<>();}
 
+    /**
+     * @param name the table name
+     * @param schema the table schema as defined in {@link DimensionTableSchema}
+     * @param data the table data in the form of a list (must comply with the schema in {@param schema})
+     */
     public DimensionTable(String name, DimensionTableSchema schema, List<Tuple> data) {
         this.name = name;
         this.schema = schema;
         this.data = data;
     }
 
+    /**
+     * @return
+     */
     public DimensionTableSchema getSchema() {
         return schema;
     }
 
+    /**
+     * @param schema
+     */
     public void setSchema(DimensionTableSchema schema) {
         this.schema = schema;
     }
 
+    /**
+     * @return
+     */
     public List<Tuple> getData() {
         return data;
     }
 
+    /**
+     * @param data
+     */
     public void setData(List<Tuple> data) {
         this.data = data;
     }
 
+    /**
+     * @return
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * @param name
+     */
     public void setName(String name) {
         this.name = name;
     }

bda-datastore/src/main/java/gr/ntua/ece/cslab/selis/bda/datastore/beans/DimensionTableSchema.java

@@ -24,6 +24,12 @@
 
 /**
  * Created by Giannis Giannakopoulos on 10/11/17.
+ * This class represents the schema of a Dimension (Entity) Table.
+ *
+ * Entity Tables are stored in a RDBMS integrated with the BDA, therefore need to have their schema well defined according
+ * to SQL requirements. The minimum information required for the initialization of such resources is the column names and types
+ * as well as primary keys.
+ *
  */
 @XmlRootElement(name = "DimensionTableSchema")
 @XmlAccessorType(XmlAccessType.PUBLIC_MEMBER)
@@ -34,32 +40,55 @@ public class DimensionTableSchema {
 
     public DimensionTableSchema(){ this.columnNames = new LinkedList<>();};
 
+    /**
+     * @param columnNames a list including the names of the table columns
+     * @param columnTypes a {@link KeyValue} list including the name and type of each table column
+     * @param primaryKey the table primary key
+     */
     public DimensionTableSchema(List<String> columnNames, List<KeyValue> columnTypes, String primaryKey) {
         this.columnNames = columnNames;
         this.columnTypes = columnTypes;
         this.primaryKey = primaryKey;
     }
 
+    /**
+     * @return a list including the names of the table columns
+     */
     public List<String> getColumnNames() {
         return columnNames;
     }
 
+    /**
+     * @param columnNames a list including the names of the table columns
+     */
     public void setColumnNames(List<String> columnNames) {
         this.columnNames = columnNames;
     }
 
+    /**
+     * @return a {@link KeyValue}  list including the name and type of each table column
+     */
     public List<KeyValue> getColumnTypes() {
         return columnTypes;
     }
 
+    /**
+     * @param columnTypes a {@link KeyValue} list including the name and type of each table column
+     */
     public void setColumnTypes(List<KeyValue> columnTypes) {
         this.columnTypes = columnTypes;
     }
 
+    /**
+     * @return the table primary key
+     */
     public String getPrimaryKey() {
         return primaryKey;
     }
 
+    /**
+     * @param primaryKey the table primary key
+     */
     public void setPrimaryKey(String primaryKey) {
         this.primaryKey = primaryKey;
     }

bda-datastore/src/main/java/gr/ntua/ece/cslab/selis/bda/datastore/beans/Job.java

@@ -28,8 +28,15 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/**
+ * This class represents a Job. Jobs are instanciated 'recipes' which are connected to a specific trigger
+ * (either an incoming message or a periodic recurring trigger). This class contains all meta-data a job requires to be
+ * executed.
+ *
+ */
 public class Job implements Serializable {
     private final static Logger LOGGER = Logger.getLogger(Job.class.getCanonicalName());
+
     private final static int DEFAULT_VECTOR_SIZE = 10;
 
     private transient int id;
@@ -100,9 +107,22 @@ public class Job implements Serializable {
 
     public Job() { }
 
+    /**
+     * Default constructor
+     *
+     * @param name job name
+     * @param description a textual description of the job
+     * @param active a boolean active/inactive switch
+     * @param messageTypeId the messageType ID as defined during the configuration process
+     * @param recipeId the recipe ID as defined during the configuration process
+     * @param scheduleInfo the time pattern to schedule the job if it is cron-based
+     * @param resultStorage a string to identify where the result of the job will be saved (kpidb/pubsub/hdfs)
+     * @param dependJobId the id of the parent job if its result must be used as an input
+     */
     public Job(String name, String description, boolean active, Integer messageTypeId,
                int recipeId, String resultStorage, String scheduleInfo,
                Integer dependJobId) {
+
         this.name = name;
         this.description = description;
         this.active = active;
@@ -184,6 +204,9 @@ public void setJobType() {
 
     public void setDependJobId(Integer dependJobId) { this.dependJobId = dependJobId; }
 
+    /**
+     * @return the contents of a Job object as a string
+     */
     @Override
     public String toString() {
         return "Job{" +
@@ -202,9 +225,14 @@ public String toString() {
                 '}';
     }
 
+    /**
+     * @param slug the SCN slug as defined in the configuration process
+     * @return a list containing Job objects corresponding to existing jobs
+     * @throws SQLException
+     * @throws SystemConnectorException
+     */
     public static List<Job> getJobs(String slug) throws SQLException, SystemConnectorException {
-
-        PostgresqlConnector connector = (PostgresqlConnector ) 
+        PostgresqlConnector connector = (PostgresqlConnector )
             SystemConnector.getInstance().getDTconnector(slug);
 
         Connection connection = connector.getConnection();
@@ -241,8 +269,13 @@ public static List<Job> getJobs(String slug) throws SQLException, SystemConnecto
         return jobs;
      }
 
+    /**
+     * @param slug the SCN slug as defined in the configuration process
+     * @return a list containing Job objects corresponding to existing active jobs
+     * @throws SQLException
+     * @throws SystemConnectorException
+     */
     public static List<Job> getActiveJobs(String slug) throws SQLException, SystemConnectorException {
-
         PostgresqlConnector connector = (PostgresqlConnector ) 
             SystemConnector.getInstance().getDTconnector(slug);
 
@@ -279,8 +312,14 @@ public static List<Job> getActiveJobs(String slug) throws SQLException, SystemCo
         return jobs;
      }
 
+    /**
+     * @param slug the SCN slug as defined in the configuration process
+     * @param id an existing job ID
+     * @return a Job object corresponding to the job with the given ID
+     * @throws SQLException
+     * @throws SystemConnectorException
+     */
     public static Job getJobById(String slug, int id) throws SQLException, SystemConnectorException {
-
         PostgresqlConnector connector = (PostgresqlConnector ) 
             SystemConnector.getInstance().getDTconnector(slug);
 
@@ -320,9 +359,15 @@ public static Job getJobById(String slug, int id) throws SQLException, SystemCon
         throw new SQLException("Job object not found.");
     }
 
+    /**
+     * @param slug the SCN slug as defined in the configuration process
+     * @param id the message ID as defined in the configuration process
+     * @return a Job object corresponding to a job triggered by the message type with the given ID
+     * @throws SQLException
+     * @throws SystemConnectorException
+     */
     public static Job getJobByMessageId(String slug, int id) throws SQLException, SystemConnectorException {
-
-        PostgresqlConnector connector = (PostgresqlConnector ) 
+        PostgresqlConnector connector = (PostgresqlConnector )
             SystemConnector.getInstance().getDTconnector(slug);
 
         Connection connection = connector.getConnection();

bda-datastore/src/main/java/gr/ntua/ece/cslab/selis/bda/datastore/beans/KeyValue.java

@@ -48,7 +48,7 @@ public KeyValue(String key, String value) {
 
     /**
      * Getter for the key
-     * @return
+     * @return key
      */
     public String getKey() {
         return key;
@@ -64,7 +64,7 @@ public void setKey(String key) {
 
     /**
      * Getter for the value
-     * @return
+     * @return value
      */
     public String getValue() {
         return value;