Javadoc added

Author: dariol83

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/activity/IActivityOccurrenceDataArchive.java

@@ -17,12 +17,6 @@
 package eu.dariolucia.reatmetric.api.activity;
 
 import eu.dariolucia.reatmetric.api.archive.IDataItemArchive;
-import eu.dariolucia.reatmetric.api.archive.exceptions.ArchiveException;
-import eu.dariolucia.reatmetric.api.events.EventData;
-import eu.dariolucia.reatmetric.api.events.EventDataFilter;
-
-import java.time.Instant;
-import java.util.List;
 
 /**
  * This interface is a specialisation of the {@link IDataItemArchive}, for activity occurrences.

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/alarms/IAlarmParameterDataArchive.java

@@ -17,8 +17,6 @@
 package eu.dariolucia.reatmetric.api.alarms;
 
 import eu.dariolucia.reatmetric.api.archive.IDataItemArchive;
-import eu.dariolucia.reatmetric.api.parameters.ParameterData;
-import eu.dariolucia.reatmetric.api.parameters.ParameterDataFilter;
 
 /**
  * This interface is a specialisation of the {@link IDataItemArchive}, for parameter alarms.

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/archive/IArchive.java

@@ -19,16 +19,36 @@
 import eu.dariolucia.reatmetric.api.archive.exceptions.ArchiveException;
 import eu.dariolucia.reatmetric.api.common.AbstractDataItem;
 import eu.dariolucia.reatmetric.api.common.AbstractDataItemFilter;
-import eu.dariolucia.reatmetric.api.events.IEventDataArchive;
-import eu.dariolucia.reatmetric.api.messages.IOperationalMessageArchive;
-import eu.dariolucia.reatmetric.api.parameters.IParameterDataArchive;
-import eu.dariolucia.reatmetric.api.rawdata.IRawDataArchive;
 
+/**
+ * This interface specifies the entry point contract for archive service providers.
+ */
 public interface IArchive {
 
+    /**
+     * Connect to the archive backend system. The archive can be used only after return from this invocation.
+     *
+     * @throws ArchiveException in case of problems connecting to the archive backend system
+     */
     void connect() throws ArchiveException;
 
+    /**
+     * Close the connection to the archive backend system. After this call, the object should be no longer be used.
+     *
+     * @throws ArchiveException in case of problems disconnecting to the archive backend system
+     */
     void dispose() throws ArchiveException;
 
-    <U extends IDataItemArchive<J,K>,J extends AbstractDataItem,K extends AbstractDataItemFilter> U getArchive(Class<U> clazz);
+    /**
+     * Retrieve the {@link IDataItemArchive} implementation specified by parameter clazz. This method is allowed
+     * to return null, if no implementation of the requested interface is available, so callers should check the return
+     * value.
+     *
+     * @param clazz the type class of the {@link IDataItemArchive}
+     * @param <U> the type class of clazz
+     * @param <J> the {@link AbstractDataItem} type managed by the specified archive interface clazz
+     * @param <K> the {@link AbstractDataItemFilter} type managed by the specified archive interface clazz
+     * @return the implementation of the requested {@link IDataItemArchive} type or null if such implementation is not available
+     */
+    <U extends IDataItemArchive<J,K>,J extends AbstractDataItem,K extends AbstractDataItemFilter<J>> U getArchive(Class<U> clazz);
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/archive/IArchiveFactory.java

@@ -18,8 +18,25 @@
 
 import eu.dariolucia.reatmetric.api.archive.exceptions.ArchiveException;
 
+/**
+ * This interface is the service interface representing the persistence service in a ReatMetric system. It contains
+ * a single factory method that can be used to instantiate an implementation of the {@link IArchive} interface.
+ */
 public interface IArchiveFactory {
 
+    /**
+     * Return an implementation of the {@link IArchive} interface supplied by the provider of the service. The
+     * archiveLocation parameter type and format depends on the archive specific implementation, i.e. can be a
+     * JDBC string, a file path containing a configuration, an IP address. From this string, the specific implementation
+     * shall be able to construct and return an object.
+     *
+     * The returned {@link IArchive} object is not required to be a different new object: {@link IArchiveFactory}
+     * implementations are allowed to cache objects or use a singleton-based design.
+     *
+     * @param archiveLocation the 'location' of the archive
+     * @return an implementation of {@link IArchive} interface
+     * @throws ArchiveException in case of problems arising from the construction of the specific {@link IArchive} object
+     */
     IArchive buildArchive(String archiveLocation) throws ArchiveException;
 
 }

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/archive/IDataItemArchive.java

@@ -31,7 +31,7 @@
  * @param <T> the {@link AbstractDataItem} that this service stores/retrieves
  * @param <K> the {@link AbstractDataItemFilter} that can be used with this service
  */
-public interface IDataItemArchive<T extends AbstractDataItem, K extends AbstractDataItemFilter> {
+public interface IDataItemArchive<T extends AbstractDataItem, K extends AbstractDataItemFilter<T>> {
 
     /**
      * Retrieve a maximum of numRecords data items, with a generation time greater/lower or equals than the provided startTime (if

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/archive/exceptions/ArchiveException.java

@@ -18,6 +18,9 @@
 
 import eu.dariolucia.reatmetric.api.common.exceptions.ReatmetricException;
 
+/**
+ * Exception class for usage in the archive-related operations.
+ */
 public class ArchiveException extends ReatmetricException {
 
     /**

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/common/AbstractDataItem.java

@@ -17,42 +17,68 @@
 
 import java.io.Serializable;
 import java.time.Instant;
-import java.util.Arrays;
 import java.util.Objects;
 
 /**
+ * This class is the base class for all data items managed and stored by the ReatMetric infrastructure. Such items
+ * are characterized by having a generation time and an extension object, that can be serialized and stored.
  *
- * @author dario
+ * Being a derivation from the {@link UniqueItem} class, objects of this class have an internal ID, which is unique
+ * among all the object instances of the same class type.
+ *
+ * Objects of this class are supposed to be immutable. In particular, the extension object, when used, must be immutable
+ * or not modified, as soon as provided in the object constructor. This means, exclusive ownership to modify the object
+ * shall be transferred to the {@link AbstractDataItem} object. Failing to do so may result in undefined behaviour
+ * during the handling and storage of the instance.
  */
 public abstract class AbstractDataItem extends UniqueItem implements Serializable {
 
     /**
 	 * 
 	 */
-	private static final long serialVersionUID = -7442923730308757888L;
+	private static final long serialVersionUID = 1L;
 
 	protected final Object extension;
 
     protected final Instant generationTime;
-    
+
+    /**
+     * Constructor of the object. If null generation time is provided, the object generation time is set to
+     * Instant.EPOCH.
+     *
+     * @param internalId the unique internal ID that identifies this specific instance
+     * @param generationTime the generation time - if set to null, Instant.EPOCH is used
+     * @param extension the extension object (can be null)
+     */
     public AbstractDataItem(IUniqueId internalId, Instant generationTime, Object extension) {
         super(internalId, null);
-        if(generationTime != null) {
-            this.generationTime = generationTime;
-        } else {
-            this.generationTime = Instant.EPOCH;
-        }
+        this.generationTime = Objects.requireNonNullElse(generationTime, Instant.EPOCH);
         this.extension = extension;
     }
 
+    /**
+     * Return the data item generation time.
+     *
+     * @return the generation time (cannot be null)
+     */
     public Instant getGenerationTime() {
         return generationTime;
     }
 
+    /**
+     * Return the extension object that was specified in the constructor.
+     *
+     * @return the extension object (can be null)
+     */
     public Object getExtension() {
         return extension;
     }
 
+    /**
+     * The hashcode defined by this object takes into account only the internal ID and the generation time fields.
+     *
+     * @return the object hashcode
+     */
     @Override
     public int hashCode() {
         int hash = 5;
@@ -61,6 +87,13 @@ public int hashCode() {
         return hash;
     }
 
+    /**
+     * The equality defined by this object is based on the class type, the equality of the internal ID and the
+     * equality of the generation time.
+     *
+     * @param obj the object, to check equality against
+     * @return true if obj is equal to this, otherwise false
+     */
     @Override
     public boolean equals(Object obj) {
         if (this == obj) {
@@ -76,10 +109,7 @@ public boolean equals(Object obj) {
         if (!Objects.equals(this.internalId, other.internalId)) {
             return false;
         }
-        if (!Objects.equals(this.generationTime, other.generationTime)) {
-            return false;
-        }
-        return true;
+        return Objects.equals(this.generationTime, other.generationTime);
     }
 
     @Override

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/common/AbstractDataItemFilter.java

@@ -16,8 +16,6 @@
 package eu.dariolucia.reatmetric.api.common;
 
 import eu.dariolucia.reatmetric.api.model.SystemEntity;
-import eu.dariolucia.reatmetric.api.model.SystemEntityPath;
-import eu.dariolucia.reatmetric.api.model.SystemEntityType;
 
 import java.io.Serializable;
 import java.util.function.Predicate;

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/common/Pair.java

@@ -19,8 +19,26 @@
 import java.io.Serializable;
 import java.util.Objects;
 
+/**
+ * A pair class that contains two related values in a single object.
+ *
+ * Objects of this class are immutable. Values shall be immutable: failing to have immutable objects as values
+ * may result in undefined behaviour.
+ *
+ * @param <T> type of the first value
+ * @param <K> type of the second value
+ */
 public final class Pair<T, K> implements Serializable {
 
+    /**
+     * Factory method.
+     *
+     * @param first the first value, can be null
+     * @param second the second value, can be null
+     * @param <T> the first value type
+     * @param <K> the second value type
+     * @return the Pair object
+     */
     public static <T,K> Pair<T, K> of(T first, K second) {
         return new Pair<>(first, second);
     }
@@ -33,14 +51,30 @@ private Pair(T first, K second) {
         this.second = second;
     }
 
+    /**
+     * Return the first value.
+     *
+     * @return the first value (can be null)
+     */
     public T getFirst() {
         return first;
     }
 
+    /**
+     * Return the second value.
+     *
+     * @return the second value (can be null)
+     */
     public K getSecond() {
         return second;
     }
 
+    /**
+     * A Pair is equal to another one if the first values are equals(...) and the second values are equals(...)
+     *
+     * @param o the Pair object, to check equality against
+     * @return true if the pairs are equals, otherwise false
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

eu.dariolucia.reatmetric.api/src/main/java/eu/dariolucia/reatmetric/api/common/exceptions/ReatmetricException.java

@@ -16,15 +16,14 @@
 package eu.dariolucia.reatmetric.api.common.exceptions;
 
 /**
- *
- * @author dario
+ * Base-class for ReatMetric-defined exceptions.
  */
 public class ReatmetricException extends Exception {
 
     /**
 	 * 
 	 */
-	private static final long serialVersionUID = -3949315104317147362L;
+	private static final long serialVersionUID = 1L;
 
 	public ReatmetricException() {
     }