package org.splat.service;
-import java.util.Date;
import java.util.List;
import org.splat.dal.bo.kernel.User;
import org.splat.dal.bo.som.Publication;
import org.splat.dal.bo.som.SimulationContext;
import org.splat.dal.bo.som.Study;
-import org.splat.dal.bo.som.Study.Properties;
import org.splat.dal.bo.som.ValidationCycle;
+import org.splat.dal.bo.som.Study.Properties;
+import org.splat.exception.IncompatibleDataException;
import org.splat.exception.InvalidParameterException;
import org.splat.kernel.InvalidPropertyException;
+import org.splat.kernel.MismatchException;
import org.splat.kernel.MissedPropertyException;
import org.splat.kernel.MultiplyDefinedException;
+import org.splat.service.dto.DocToCompareDTO;
+import org.splat.service.dto.DocumentDTO;
+import org.splat.service.dto.StudyFacadeDTO;
+import org.splat.service.dto.UserDTO;
+import org.splat.service.dto.StudyFacadeDTO.ScenarioDTO;
/**
* This class defines all methods for creation, modification the study.
*/
Study selectStudy(long index);
+ /**
+ * Delete the study.
+ *
+ * @param index
+ * the study id
+ */
+ void removeStudy(final Long index);
+
/**
* Create a new study.
*
* @throws MissedPropertyException
* if a mandatory property is missed
* @throws InvalidPropertyException
- * if some property doesn't exist
+ * if an invalid value is passed to a property
* @throws MultiplyDefinedException
* if some property is defined several times
*/
- Study createStudy(Study.Properties sprop)
- throws MissedPropertyException, InvalidPropertyException,
- MultiplyDefinedException;
+ Study createStudy(Study.Properties sprop) throws MissedPropertyException,
+ InvalidPropertyException, MultiplyDefinedException;
/**
* Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
* @throws MissedPropertyException
* if a mandatory property is missed
* @throws InvalidPropertyException
- * if some property doesn't exist
+ * if an invalid value is passed to a property
* @throws MultiplyDefinedException
* if some property occurs several times
*/
* the simulation context to add
* @return the added simulation context
*/
- SimulationContext addProjectContext(Study aStudy,
- SimulationContext context);
+ SimulationContext addProjectContext(Study aStudy, SimulationContext context);
/**
* Remove a simulation context from a study.
* @see #isPublic()
*/
boolean moveToPublic(Study aStudy);
-
+
/**
* Moves this study from the Public to the Private area of the repository.
*
* new properties of the study
* @return true if the study has been updated successfully
* @throws InvalidPropertyException
- * if some property doesn't exist
+ * if an invalid value is passed to a property
*/
boolean update(Study aStudy, Properties sprop)
throws InvalidPropertyException;
* @return the unmodifiable not null transient list of contributors of this study
*/
List<User> getContributors(Study aStudy);
-
+
/**
* Mark study as reference.
*
- * @param aStudy - the Study
+ * @param aStudy -
+ * the Study
*/
void markStudyAsReference(Study aStudy);
-
+
/**
- * Remove study as reference.
- * This operation is inverse one to Mark as reference.
+ * Remove study as reference. This operation is inverse one to Mark as reference.
*
- * @param aStudy - the Study
+ * @param aStudy -
+ * the Study
*/
void removeStudyAsReference(Study aStudy);
+
+ /**
+ * Get studies, scenarios and publications available for comparison.
+ * <br><b> DocumentDto.id are actually filled in with Publication ids.</b>
+ * @param userId id of the user to to whom visible studies will be returned.
+ * @return list of {@link StudyFacadeDTO} containing lists of {@link ScenarioDTO} containing list of
+ * {@link DocumentDTO}, corresponding to to the publications available for comparison,
+ * with ids and titles filled in.
+ * @throws MismatchException if some configurations considering postprocessing step are invalid.
+ */
+ List<StudyFacadeDTO> getComparableStudies(final long userId) throws MismatchException;
/**
- * Get the description attribute related to the study
- * (there supposed to be the only one such attribute in the database).
- * @param studyId the study id
+ * Get the description attribute related to the study (there supposed to be the only one such attribute in the database).
+ *
+ * @param studyId
+ * the study id
* @return the description attribute value (null if does not exist)
- * @throws InvalidParameterException if a study with such id does not exist in the database.
+ * @throws InvalidParameterException
+ * if a study with such id does not exist in the database.
*/
String getDescription(Long studyId) throws InvalidParameterException;
-
+
/**
* Set the description attribute related to the study.
- * @param studyId the study id
- * @param descriptionText the description text
- * @throws InvalidParameterException if some parameters are invalid.
+ *
+ * @param studyId
+ * the study id
+ * @param descriptionText
+ * the description text
+ * @throws InvalidParameterException
+ * if some parameters are invalid.
*/
- void setDescription(Long studyId, String descriptionText) throws InvalidParameterException;
+ void setDescription(Long studyId, String descriptionText)
+ throws InvalidParameterException;
/**
* Remove a description attached to a study.
*
- * @param studyId the study id
+ * @param studyId
+ * the study id
* @throws InvalidParameterException
- * if no study with such Id has been found in the database.
+ * if no study with such Id has been found in the database.
* @return true if succeeded, false if study doesn't have a description.
*/
- boolean removeDescription(final Long studyId) throws InvalidParameterException;
+ boolean removeDescription(final Long studyId)
+ throws InvalidParameterException;
+
+ /**
+ * Compare the studies and generate the file that contains the result chart.
+ *
+ * @param docsList
+ * the list of dtos each contains information: StudyTitle, ScenarioTitle, PathToFile in vault.
+ * @param userName
+ * the name of the user who compare the results.
+ * @throws IncompatibleDataException
+ * if data is incompatible for "Compare the studies" functionality.
+ *
+ * @return path to result file in the vault.
+ */
+ String compare(List<DocToCompareDTO> docsList, final String userName)
+ throws IncompatibleDataException;
+
+ /**
+ * Get readers of a given study.
+ * @param studyId the study id.
+ * @return list of user DTO corresponding to the study readers.
+ * @throws InvalidParameterException if no study with such id has been found in the database.
+ */
+ List<UserDTO> getReaders(final long studyId) throws InvalidParameterException;
+
+ /**
+ * Add reader to a given study.
+ * @param studyId the study id.
+ * @param userId the user id.
+ * @return true if the user has been added as a reader
+ * @throws InvalidParameterException if no study or user with such id has been found in the database.
+ */
+ boolean addReader(final long studyId, final long userId) throws InvalidParameterException;
+
+ /**
+ * Remove reader from a given study.
+ * @param studyId the study id.
+ * @param userId the user id.
+ * @return true if the relation has been found and removed
+ * @throws InvalidParameterException if no study or user with such id has been found in the database.
+ */
+ boolean removeReader(final long studyId, final long userId) throws InvalidParameterException;
}
