documentation and code cleanup

Author: anhefti

src/main/java/ch/ethz/seb/sps/server/datalayer/batis/custommappers/SearchSessionMapper.java

@@ -11,12 +11,16 @@
 import java.sql.Date;
 import java.util.List;
 
+/** This mapper is used to search for dates that has matching screenshot data for a given filter.*/
 @Mapper
 public interface SearchSessionMapper {
 
     @SelectProvider(type = CustomSqlProvider.class, method = "selectDistinctCreationDates")
     List<Date> selectDistinctCreationTimes(SelectStatementProvider selectStatement);
 
+    /** Used to select on session records creation_time by dates (instead of timestamp).
+     * 
+     * @return QueryExpressionDSL to add additional clauses if needed*/ 
     default QueryExpressionDSL<MyBatis3SelectModelAdapter<List<Date>>> selectCreationTimesAsDates(){
         return SelectDSL.selectDistinctWithMapper(this::selectDistinctCreationTimes, SessionRecordDynamicSqlSupport.creationTime)
                 .from(SessionRecordDynamicSqlSupport.sessionRecord);

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/ActivatableEntityDAO.java

@@ -25,6 +25,11 @@ public interface ActivatableEntityDAO<T extends Entity, M extends ModelIdAware>
      * @return The Collection of Results refer to the EntityKey instance or refer to an error if happened */
     Result<EntityKey> setActive(EntityKey entityKey, boolean active);
 
+    /** Set all entities referred by the given Collection of EntityKey active / inactive
+     *
+     * @param entity T the entity to set active or inactive
+     * @param active The active flag
+     * @return The Collection of Results refer to the Entity instance or refer to an error if happened */
     default Result<T> setActive(final T entity, final boolean active) {
         return setActive(entity.getEntityKey(), active)
                 .map(key -> byModelId(key.modelId).getOr(entity));

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/ClientAccessDAO.java

@@ -13,6 +13,11 @@
 
 public interface ClientAccessDAO extends ActivatableEntityDAO<ClientAccess, ClientAccess> {
 
-    public Result<CharSequence> getEncodedClientPWD(String clientId, boolean checkActive);
+    /** Get the encoded client password that is used by a SEB client to authenticate.
+     * 
+     * @param clientId The client authentication entity id.
+     * @param checkActive Only gets the password if the client authentication entity is active.
+     * @return Result refer to CharSequence with the encoded client password. */
+    Result<CharSequence> getEncodedClientPWD(String clientId, boolean checkActive);
 
 }

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/DAOAdapterType.java

@@ -18,33 +18,74 @@
 import ch.ethz.seb.sps.domain.model.user.EntityPrivilege;
 import ch.ethz.seb.sps.utils.Result;
 
+/** An EntityPrivilege is a privilege for a specific user on a specific entity instance.
+ * EntityPrivilege maps a user UUID to a entity (type and id) and specifies a privilege for the user.
+ * The PrivilegeType is either "r" for read, "m" for modify (and read) or "w" for write (and modify and read) */
 public interface EntityPrivilegeDAO {
 
-    Result<Collection<EntityPrivilege>> getEntityPrivileges(
-            EntityType type,
-            Long entityId);
+    /** Get all entity privileges for a given entity type and id.
+     * 
+     * @param entityType The entity type
+     * @param entityId The entity id (PK)
+     * @return Result refer to a collection of all EntityPrivilege for the given entity or to an error when happened.*/
+    Result<Collection<EntityPrivilege>> getEntityPrivileges(EntityType entityType, Long entityId);
 
-    Result<Set<Long>> getEntityIdsWithPrivilegeForUser(
-            EntityType type,
-            String userUUID,
-            PrivilegeType privilegeType);
+    /** Get all entity ids for a given user and a given PrivilegeType.
+     * 
+     * @param entityType The entity type
+     * @param userUUID The user UUID
+     * @param privilegeType The privilege type
+     * @return Result refer to a set of entity ids (PKs) that the given user has the privilege for, or to an error when happened */
+    Result<Set<Long>> getEntityIdsWithPrivilegeForUser(EntityType entityType, String userUUID, PrivilegeType privilegeType);
 
+    /** Get all EntityPrivilege for a given user.
+     * 
+     * @param userUUID The user UUID
+     * @return Result refer to the collection of EntityPrivilege the given user has or to an error when happened */
     Result<Collection<EntityPrivilege>> getEntityPrivilegesForUser(String userUUID);
 
+    /** Add a given privilege for a user to an entity.
+     * 
+     * @param entityType The entity type 
+     * @param entityId The entity id (PK)
+     * @param userUUID The user UUID
+     * @param privilegeType The type of privilege to give to the user on entity
+     * @return Result refer to added EntityPrivilege or to an error when happened */
     Result<EntityPrivilege> addPrivilege(
-            EntityType type,
+            EntityType entityType,
             Long entityId,
             String userUUID,
             PrivilegeType privilegeType);
 
-    Result<EntityKey> deletePrivilege(
-            EntityType type,
-            Long entityId,
-            String userUUID);
-
-    Result<Collection<EntityKey>> deleteAllPrivileges(EntityType type, Long entityId);
+    /** Deletes a privilege for a user on an object.
+     * 
+     * @param entityType The entity type 
+     * @param entityId The entity id (PK)
+     * @param userUUID The user UUID
+     * @return Result refer to the EntityKey of the deleted EntityPrivilege or to an error when happened*/
+    Result<EntityKey> deletePrivilege(EntityType entityType, Long entityId, String userUUID);
 
-    void updatePrivileges(Long epId, PrivilegeType privilegeType);
+    /** Deletes all EntityPrivileges of a specific entity.
+     * 
+     * @param entityType The entity type 
+     * @param entityId The entity id (PK)
+     * @return Result refer to a collection of all deleted EntityPrivilege keys or to an error when happened. */
+    Result<Collection<EntityKey>> deleteAllPrivileges(EntityType entityType, Long entityId);
 
+    /** Deletes all privileges for a specified user.
+     * 
+     * @param user_uuid The user UUID to delete all privileges for*/
     void deleteAllPrivilegesForUser(String user_uuid);
+
+    /** Update one single EntityPrivilege.
+     * 
+     * @param epId EntityPrivilege id (PK)
+     * @param privilegeType The PrivilegeType to update to */
+    void updatePrivilege(Long epId, PrivilegeType privilegeType);
+
+    /** Update all given EntityPrivileges to a given PrivilegeType.
+     * 
+     * @param epIds Collection of EntityPrivilege ids (PKs)
+     * @param privilegeType The PrivilegeType to update to */
+    void updatePrivileges(Collection<Long> epIds, PrivilegeType privilegeType);
 }

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/EntityPrivilegeDAO.java

@@ -15,12 +15,18 @@
 
 public interface ScreenshotDAO {
 
-    Result<InputStream> getImage(
-            Long pk,
-            String sessionUUID);
+    /** Get an Image via InputStream.
+     * 
+     * @param pk The PK of the image to get
+     * @param sessionUUID The session UUID where the image belongs to.
+     * @return Result refer to an InputSteam for the image data */
+    Result<InputStream> getImage(Long pk, String sessionUUID);
 
-    Result<List<Long>> deleteAllForSession(
-            String sessionUUID,
-            List<Long> screenShotPKs);
+    /** Deletes all images for a specified session
+     * 
+     * @param sessionUUID The session UUID
+     * @param screenShotPKs List of all image PKs to delete.
+     * @return Result refer to the list of image PK that has been deleted or to an error when happened */
+    Result<List<Long>> deleteAllForSession(String sessionUUID, List<Long> screenShotPKs);
 
 }

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/ScreenshotDAO.java

@@ -40,17 +40,17 @@ public interface ScreenshotDataDAO extends EntityDAO<ScreenshotData, ScreenshotD
 
     Result<ScreenshotDataRecord> getLatest(String sessionUUID);
 
-    @Transactional(readOnly = true)
-    default Result<Map<String, ScreenshotDataRecord>> allLatestOf(final String sessionUUIDList) {
-        return Result.tryCatch(() -> {
-
-            final List<String> ids = sessionUUIDList.contains(Constants.LIST_SEPARATOR)
-                    ? Arrays.asList(StringUtils.split(sessionUUIDList, Constants.LIST_SEPARATOR))
-                    : Arrays.asList(sessionUUIDList);
-
-            return allLatestIn(ids).getOrThrow();
-        });
-    }
+//    @Transactional(readOnly = true)
+//    default Result<Map<String, ScreenshotDataRecord>> allLatestOf(final String sessionUUIDList) {
+//        return Result.tryCatch(() -> {
+//
+//            final List<String> ids = sessionUUIDList.contains(Constants.LIST_SEPARATOR)
+//                    ? Arrays.asList(StringUtils.split(sessionUUIDList, Constants.LIST_SEPARATOR))
+//                    : Arrays.asList(sessionUUIDList);
+//
+//            return allLatestIn(ids).getOrThrow();
+//        });
+//    }
 
     Result<Map<String, ScreenshotDataRecord>> allLatestIn(List<String> sessionUUIDs);
 

src/main/java/ch/ethz/seb/sps/server/datalayer/dao/ScreenshotDataDAO.java

@@ -21,6 +21,17 @@
 
 public interface SessionDAO extends ActivatableEntityDAO<Session, Session> {
 
+    /** Creates a new Session for a specified group
+     * 
+     * @param groupUUID The group UUID
+     * @param uuid The Session UUID that is used to identify the new session
+     * @param userSessionName The username for the session
+     * @param clientIP The client IP of the new session
+     * @param clientMachineName The client machine name for the new session
+     * @param clientOSName The client OS name for the new session
+     * @param clientVersion The client version of the new session
+     * @param imageFormat The image format of the new session
+     * @return Result refer to the new created session or to an error when happened*/
     Result<Session> createNew(
             String groupUUID,
             String uuid,
@@ -31,29 +42,97 @@ Result<Session> createNew(
             String clientVersion,
             ImageFormat imageFormat);
 
+    /** Get a collection of all session uuid that are actually active for a given group.
+     * 
+     * @param groupId The group id (PK)
+     * @return Result refer to the resulting collection or to an error if happened */
     Result<Collection<String>> allLiveSessionUUIDsByGroupId(Long groupId);
 
+    /** Get a collection of all session uuid for a given group.
+     * 
+     * @param groupId The group id (PK)
+     * @return Result refer to the resulting collection or to an error if happened */
     Result<Collection<String>> allSessionUUIDsByGroupId(Long groupId);
 
+    /** Get a count of all active live session of a given group.
+     * 
+     * @param groupId The group id (PK)
+     * @return Result refer to the count or to an error when happened */
     Result<Long> allLiveSessionCount(Long groupId);
 
+    /** Get a count of all session of a given group.
+     * 
+     * @param groupId The group id (PK)
+     * @return Result refer to the count or to an error when happened */
     Result<Long> allSessionCount(Long groupId);
 
+    /** Close a given session.
+     * 
+     * @param sessionUUID The session UUID to close.
+     * @return Result refer to the UUID of the closed session or to an error when happened */
     Result<String> closeSession(String sessionUUID);
 
+    /** Close all open sessions within a given group.
+     * 
+     * @param groupPK The group id (PK)
+     * @return Result refer to a collection of EntityKey of all sessions that has been closed, or to an error when happened*/
     Result<Collection<EntityKey>> closeAllSessionsForGroup(Long groupPK);
 
+    /** Deletes all Session for a given list of groups
+     * 
+     * @param groupPKs List of group PKs to delete all sessions for
+     * @return Result refer to a collection of EntityKey of all deleted session, or to an error when happened*/
     Result<Collection<EntityKey>> deleteAllForGroups(final List<Long> groupPKs);
 
+    /** Get the number of screenshots for a given session filtered by screenshot metadata.
+     * Filter criteria are of type API.ScreenshotMetadataType and are AND combined.
+     * 
+     * @param uuid The session UUID
+     * @param filterMap filter map containing filter criteria to apply to before count
+     * @return the number of filtered screenshots for a given session */
     Long getNumberOfScreenshots(String uuid, FilterMap filterMap);
 
+    /** Indicates if there are any session data for a given list of groups.
+     * 
+     * @param groupIds Collection of group ids (PK) to check for.
+     * @return Result refer to the indicator or to an error when happened.*/
     Result<Boolean> hasAnySessionData(Collection<Long> groupIds);
 
+    /** Get a list of dates for which screenshot data exists for a given filter criteria.
+     * This is used in multiple step searches where first a list of dates is presented where screenshot data exists
+     * and only if one is interested in screenshot data of a specific date, the search is applied to get the data for
+     * only this date, to improve performance.
+     * <p> 
+     * Filter criteria:
+     * <pre>
+     *     active = filterMap.getBooleanObject(API.ACTIVE_FILTER);
+     *     fromTime = filterMap.getLong(API.PARAM_FROM_TIME);
+     *     toTime = filterMap.getLong(API.PARAM_TO_TIME);
+     *     groupPKs = filterMap.getString(Domain.SESSION.ATTR_GROUP_ID);
+     *     sessionUUID = filterMap.contains(API.PARAM_SESSION_ID)
+     *  </pre>
+     * @param filterMap The map containing the filter criteria
+     * @return Result refer to a list of dates where screenshots exists or to an error when happened.*/
     Result<List<Date>> queryMatchingDaysForSessionSearch(final FilterMap filterMap);
 
+    /** This is only for distributed setups where we can get all session UUIDs of a given group that
+     * are out of sync on its cached instances. This checks the update_time timestamps of cached instances with the once
+     * on the database and gives all Session UUID that has different update_time and where updated by another SPS service.
+     * @param groupId The group id (PK)
+     * @param updateTimes List of update_time timestamps of all cached sessions.
+     * @return Result refer to the list of session UUIDs that needs update, ot to an error when happened*/
     Result<List<String>> allTokensThatNeedsUpdate(Long groupId, Set<Long> updateTimes);
-    
+
+    /** Get the encryption key of the session used to encrypt/decrypt client side stored screenshot data.
+     * 
+     * @param uuid The UUID of the session
+     * @return Result refer to the encryption key of the session or to an error when happened */
     Result<String> getEncryptionKey(String uuid);
 
+    /** This us used to close a given open session at a given time.
+     * 
+     * @param sessionUUID The UUID of the session to close at given time
+     * @param termination_time The timestamp on which to close the session (unix timestamp im milliseconds)
+     * @return Result refer to the close timestamp or to an error when happened.*/
     Result<Long> closeAt(String sessionUUID, Long termination_time);
 }