/*****************************************************************************
- * Company EURIWARE
+ * Company OPEN CASCADE
* Application SIMAN
* File Id:
* Creation date 02.10.2012
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.DocumentType;
import org.splat.dal.bo.som.Publication;
-import org.splat.dal.bo.som.Scenario;
import org.splat.dal.bo.som.SimulationContext;
import org.splat.dal.bo.som.Study;
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.StudyFacadeDTO.ScenarioDTO;
/**
* This class defines all methods for creation, modification the study.
+ *
* @author Maria KRUCHININA
- *
+ *
*/
public interface StudyService {
-
+
/**
- * Get the simulation context list for displaying drop-down list values populating
- * on the "Create new study" screen.
- * @return List of the simulation contexts.
+ * Increment total number of study documents including versions (docount) and update it in the study.
+ *
+ * @param aStudy
+ * the study
+ * @return incremented docount value
*/
- List<SimulationContext> getSimulationContextList();
-
- public int generateLocalIndex(Study aStudy);
+ int generateLocalIndex(Study aStudy);
- public Study selectStudy(long index);
+ /**
+ * Get study by its id.
+ *
+ * @param index
+ * the study id
+ * @return found study or null
+ */
+ Study selectStudy(long index);
- public Study createStudy(Study.Properties sprop)
- throws MissedPropertyException, InvalidPropertyException,
- MultiplyDefinedException, RuntimeException;
+ /**
+ * Delete the study.
+ *
+ * @param index
+ * the study id
+ */
+ public void removeStudy(final long index);
- public SimulationContext addProjectContext(Study aStudy,
- SimulationContext.Properties cprop) throws MissedPropertyException,
- InvalidPropertyException, MultiplyDefinedException,
- RuntimeException;
+ /**
+ * Create a new study.
+ *
+ * @param sprop
+ * properties of the new study
+ * @return the created study
+ * @throws MissedPropertyException
+ * if a mandatory property is missed
+ * @throws InvalidPropertyException
+ * 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;
- public SimulationContext addProjectContext(Study aStudy,
- SimulationContext context);
+ /**
+ * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
+ *
+ * @param aStudy
+ * the study
+ * @param cprop
+ * the simulation context properties
+ * @return the added simulation context
+ * @throws MissedPropertyException
+ * if a mandatory property is missed
+ * @throws InvalidPropertyException
+ * if an invalid value is passed to a property
+ * @throws MultiplyDefinedException
+ * if some property occurs several times
+ */
+ SimulationContext addProjectContext(Study aStudy,
+ SimulationContext.Properties cprop) throws MissedPropertyException,
+ InvalidPropertyException, MultiplyDefinedException;
- public Scenario addScenario(Study aStudy, Scenario.Properties sprop)
- throws MissedPropertyException, InvalidPropertyException,
- MultiplyDefinedException, RuntimeException;
+ /**
+ * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
+ *
+ * @param aStudy
+ * the study
+ * @param context
+ * the simulation context to add
+ * @return the added simulation context
+ */
+ SimulationContext addProjectContext(Study aStudy, SimulationContext context);
- public boolean removeProjectContext(Study aStudy, SimulationContext context);
+ /**
+ * Remove a simulation context from a study.
+ *
+ * @param aStudy
+ * the study
+ * @param context
+ * the simulation context to remove
+ * @return true if removing succeeded
+ */
+ boolean removeProjectContext(Study aStudy, SimulationContext context);
/**
* Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
* document of the study.
*
+ * @param aStudy
+ * the study to demote
* @return true if the demotion succeeded.
*/
- public boolean demote(Study aStudy);
+ boolean demote(Study aStudy);
/**
* Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
* final result document of the study.
*
- * @return true if the demotion succeeded.
+ * @param aStudy
+ * the study to promote
+ * @return true if the promotion succeeded.
*/
- public boolean promote(Study aStudy);
+ boolean promote(Study aStudy);
- public boolean addContributor(Study aStudy, User user);
+ /**
+ * Add a contributor to the study.
+ *
+ * @param aStudy
+ * the study
+ * @param user
+ * the contributor
+ * @return true if addition succeeded
+ */
+ boolean addContributor(Study aStudy, User user);
- public boolean removeContributor(Study aStudy, User... users);
+ /**
+ * Remove contributors from the study.
+ *
+ * @param aStudy
+ * the study
+ * @param users
+ * contributor(s)
+ * @return true if removing succeeded
+ */
+ boolean removeContributor(Study aStudy, User... users);
- public void setValidationCycle(Study aStudy, DocumentType type,
+ /**
+ * Set a validation cycle for documents of the given type in the given study.
+ *
+ * @param aStudy
+ * the target study
+ * @param type
+ * the document type
+ * @param vprop
+ * validation cycle properties
+ */
+ void setValidationCycle(Study aStudy, DocumentType type,
ValidationCycle.Properties vprop);
/**
* Moves this study from the Private to the Public area of the repository.
*
+ * @param aStudy
+ * the study to move
* @return true if the move succeeded.
* @see #isPublic()
*/
- public boolean moveToPublic(Study aStudy);
+ boolean moveToPublic(Study aStudy);
+
+ /**
+ * Moves this study from the Public to the Private area of the repository.
+ *
+ * @param aStudy
+ * the study to move
+ * @return true if the move succeeded.
+ */
+ boolean moveToPrivate(Study aStudy);
/**
* Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
* previously be approved.
*
+ * @param aStudy
+ * the study to move
* @return true if the move succeeded.
* @see #moveToPublic()
* @see #isPublic()
* @see Publication#approve(Date)
*/
- public boolean moveToReference(Study aStudy);
+ boolean moveToReference(Study aStudy);
- public boolean update(Study aStudy, Properties sprop)
+ /**
+ * Update a study.
+ *
+ * @param aStudy
+ * the study to update
+ * @param sprop
+ * new properties of the study
+ * @return true if the study has been updated successfully
+ * @throws InvalidPropertyException
+ * if an invalid value is passed to a property
+ */
+ boolean update(Study aStudy, Properties sprop)
throws InvalidPropertyException;
+
+ /**
+ * Initialize shortcuts of the study as its transient collections.
+ *
+ * @param aStudy
+ * the study
+ */
+ void loadWorkflow(Study aStudy);
+
+ /**
+ * Returns the validation cycle of the given document type.
+ *
+ * @param aStudy
+ * the study
+ * @param type
+ * the document type being subject of validation
+ * @return the validation cycle of the document, or null if not defined.
+ */
+ ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
+
+ /**
+ * Checks if the given user participates to this study. The Study staff includes the author and contributors.
+ *
+ * @param aStudy
+ * the study
+ * @param user
+ * the user to look for
+ * @return true if the given user is actor of this study.
+ * @see #getContributors()
+ */
+ boolean isStaffedBy(Study aStudy, User user);
+
+ /**
+ * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
+ *
+ * @param aStudy
+ * the study
+ * @param user
+ * the user to look for
+ * @return true if the given user is actor of this study.
+ * @see #getActors()
+ */
+ boolean hasActor(Study aStudy, User user);
+
+ /**
+ * Returns unmodifiable initialized transient list of contributors of this study.
+ *
+ * @param aStudy
+ * the study
+ * @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
+ */
+ void markStudyAsReference(Study aStudy);
+
+ /**
+ * Remove study as reference. This operation is inverse one to Mark as reference.
+ *
+ * @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
+ * @return the description attribute value (null if does not exist)
+ * @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.
+ */
+ void setDescription(Long studyId, String descriptionText)
+ throws InvalidParameterException;
+
+ /**
+ * Remove a description attached to a study.
+ *
+ * @param studyId
+ * the study id
+ * @throws InvalidParameterException
+ * 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;
+
+ /**
+ * 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;
}
