Docs: Add JavaDoc

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/database/CacheManager.java

@@ -5,12 +5,19 @@ import de.hft.stuttgart.citydoctor2.datastructure.GmlId;
 
 import java.util.List;
 
+/**
+ * Utility class for accessing the FeatureCache instance. Enables access to the cache in contexts without reference or
+ * pass through of the {@link de.hft.stuttgart.citydoctor2.datastructure.CityDoctorModel CityDoctorModel}.
+ */
 public class CacheManager {
 
     private static FeatureCache cache = null;
 
     private CacheManager() {}
 
+    /**
+     * Returns the FeatureCache instance
+     */
     public static FeatureCache getFeatureCache() {
 
         if (cache == null){
@@ -19,18 +26,28 @@ public class CacheManager {
         return cache;
     }
 
+    /**
+     * Signals the cache that parsing has finished
+     */
     public static void finishParsing(){
         if (cache != null){
             cache.finishParsing();
         }
     }
 
+    /**
+     * Signals the cache to synchronize its content with the database.
+     */
     public static void synchronizeCache(){
         if (cache != null){
             cache.synchronize();
         }
     }
 
+    /**
+     * Returns a new UnconnectedCache Object.
+     * @return
+     */
     public static UnconnectedCache getUnconnectedCache(){
         return new UnconnectedCache();
     }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/database/CityObjectCache.java

@@ -8,19 +8,50 @@ import java.util.stream.Stream;
 
 public interface CityObjectCache {
 
-
+    /**
+     * Adds a CityObject to this cache, overwriting existing CityObjects with the same GmlID
+     * @param cityObject
+     */
     void put(CityObject cityObject);
 
+    /**
+     * Gets a CityObject from this cache by their GmlID
+     * @param id GmlID of the requested Object
+     * @return the associated CityObject, or null if no Object has a matching GmlID
+     */
     CityObject get(GmlId id);
 
+    /**
+     * Replaces a CityObject with another one
+     * @param id GmlID of the CityObject that is to be replaced
+     * @param cityObject the replacement
+     */
     void replace(GmlId id, CityObject cityObject);
 
+    /**
+     * Returns a Stream of CityObjects from a list of GmlIDs
+     * @param ids the list of GmlIDs
+     * @return CityObject Stream of the IDs
+     */
     Stream<CityObject> getStream(List<GmlId> ids);
 
+    /**
+     * Returns the total count of entries.
+     * @return the count
+     */
     int getTotalFeatureCount();
 
+    /**
+     * Resets the Cache to its initial state
+     */
     void resetCache();
 
+    /**
+     * Returns a list of GmlIDs, whose associated CityObjects were found to contain at least one error.
+     * <p/>
+     * Requires Validation to be run first, as unvalidated CityObjects are of unknown state.
+     * @return list of GmlIDs which were found to contain an error
+     */
     List<GmlId> getErrorFeatureIds();
 
 }

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/database/DatabaseHandler.java

@@ -28,7 +28,9 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 
-
+/**
+ * Utility class for setup and access of the embedded database.
+ */
 public class DatabaseHandler {
 
     private static final Logger logger = LogManager.getLogger(DatabaseHandler.class);

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/database/FeatureCache.java

@@ -16,7 +16,16 @@ import java.util.stream.Stream;
 
 
 /**
- * Cache for CityObjects
+ * A managed cache for CityObjects. This cache is connected to the embedded database and will automatically load missing
+ * CityObjects from it. Has a hard limit on concurrently held CityObjects and will write them back to the database upon
+ * eviction.
+ * <p>
+ * This cache may only have a single instance, use {@link CacheManager} for instantiation.
+ * <p/>
+ * <p>
+ * Avoid holding long-time strong references to CityObjects returned by the cache, as eviction will sever the
+ * connection between reference and cache, which can lead to conflicting Object states.
+ * <p/>
  */
 public class FeatureCache implements CityObjectCache{
 
@@ -115,7 +124,7 @@ public class FeatureCache implements CityObjectCache{
     }
 
     /**
-     * Synchronizes cache and database
+     * Synchronizes CityObject states by updating Database with cache content.
      */
     public void synchronize(){
         HashMap<GmlId, CityObject> cacheContent= new HashMap<>(cache.asMap());
@@ -129,6 +138,9 @@ public class FeatureCache implements CityObjectCache{
         }
     }
 
+    /**
+     * Signals the cache that parsing has finished.
+     */
     public void finishParsing() {
         if (!parsingFinished) {
             synchronize();

CityDoctorParent/CityDoctorModel/src/main/java/de/hft/stuttgart/citydoctor2/database/UnconnectedCache.java

@@ -2,7 +2,6 @@ package de.hft.stuttgart.citydoctor2.database;
 
 import de.hft.stuttgart.citydoctor2.datastructure.CityObject;
 import de.hft.stuttgart.citydoctor2.datastructure.GmlId;
-import de.hft.stuttgart.citydoctor2.parser.InvalidGmlFileException;
 
 import java.util.ArrayList;
 import java.util.HashMap;