1 /*****************************************************************************
5 * Creation date 02.10.2012
6 * @author Author: Maria KRUCHININA
8 *****************************************************************************/
10 package org.splat.service;
12 import java.util.Date;
13 import java.util.List;
15 import org.splat.dal.bo.kernel.User;
16 import org.splat.dal.bo.som.DocumentType;
17 import org.splat.dal.bo.som.Publication;
18 import org.splat.dal.bo.som.SimulationContext;
19 import org.splat.dal.bo.som.Study;
20 import org.splat.dal.bo.som.Study.Properties;
21 import org.splat.dal.bo.som.ValidationCycle;
22 import org.splat.exception.InvalidParameterException;
23 import org.splat.kernel.InvalidPropertyException;
24 import org.splat.kernel.MissedPropertyException;
25 import org.splat.kernel.MultiplyDefinedException;
26 import org.splat.service.dto.DocToCompareDTO;
29 * This class defines all methods for creation, modification the study.
31 * @author Maria KRUCHININA
34 public interface StudyService {
37 * Increment total number of study documents including versions (docount) and update it in the study.
41 * @return incremented docount value
43 int generateLocalIndex(Study aStudy);
46 * Get study by its id.
50 * @return found study or null
52 Study selectStudy(long index);
58 * properties of the new study
59 * @return the created study
60 * @throws MissedPropertyException
61 * if a mandatory property is missed
62 * @throws InvalidPropertyException
63 * if some property doesn't exist
64 * @throws MultiplyDefinedException
65 * if some property is defined several times
67 Study createStudy(Study.Properties sprop)
68 throws MissedPropertyException, InvalidPropertyException,
69 MultiplyDefinedException;
72 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
77 * the simulation context properties
78 * @return the added simulation context
79 * @throws MissedPropertyException
80 * if a mandatory property is missed
81 * @throws InvalidPropertyException
82 * if some property doesn't exist
83 * @throws MultiplyDefinedException
84 * if some property occurs several times
86 SimulationContext addProjectContext(Study aStudy,
87 SimulationContext.Properties cprop) throws MissedPropertyException,
88 InvalidPropertyException, MultiplyDefinedException;
91 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
96 * the simulation context to add
97 * @return the added simulation context
99 SimulationContext addProjectContext(Study aStudy,
100 SimulationContext context);
103 * Remove a simulation context from a study.
108 * the simulation context to remove
109 * @return true if removing succeeded
111 boolean removeProjectContext(Study aStudy, SimulationContext context);
114 * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
115 * document of the study.
118 * the study to demote
119 * @return true if the demotion succeeded.
121 boolean demote(Study aStudy);
124 * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
125 * final result document of the study.
128 * the study to promote
129 * @return true if the promotion succeeded.
131 boolean promote(Study aStudy);
134 * Add a contributor to the study.
140 * @return true if addition succeeded
142 boolean addContributor(Study aStudy, User user);
145 * Remove contributors from the study.
151 * @return true if removing succeeded
153 boolean removeContributor(Study aStudy, User... users);
156 * Set a validation cycle for documents of the given type in the given study.
163 * validation cycle properties
165 void setValidationCycle(Study aStudy, DocumentType type,
166 ValidationCycle.Properties vprop);
169 * Moves this study from the Private to the Public area of the repository.
173 * @return true if the move succeeded.
176 boolean moveToPublic(Study aStudy);
179 * Moves this study from the Public to the Private area of the repository.
183 * @return true if the move succeeded.
185 boolean moveToPrivate(Study aStudy);
188 * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
189 * previously be approved.
193 * @return true if the move succeeded.
194 * @see #moveToPublic()
196 * @see Publication#approve(Date)
198 boolean moveToReference(Study aStudy);
204 * the study to update
206 * new properties of the study
207 * @return true if the study has been updated successfully
208 * @throws InvalidPropertyException
209 * if some property doesn't exist
211 boolean update(Study aStudy, Properties sprop)
212 throws InvalidPropertyException;
215 * Initialize shortcuts of the study as its transient collections.
220 void loadWorkflow(Study aStudy);
223 * Returns the validation cycle of the given document type.
228 * the document type being subject of validation
229 * @return the validation cycle of the document, or null if not defined.
231 ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
234 * Checks if the given user participates to this study. The Study staff includes the author and contributors.
239 * the user to look for
240 * @return true if the given user is actor of this study.
241 * @see #getContributors()
243 boolean isStaffedBy(Study aStudy, User user);
246 * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
251 * the user to look for
252 * @return true if the given user is actor of this study.
255 boolean hasActor(Study aStudy, User user);
258 * Returns unmodifiable initialized transient list of contributors of this study.
262 * @return the unmodifiable not null transient list of contributors of this study
264 List<User> getContributors(Study aStudy);
267 * Mark study as reference.
269 * @param aStudy - the Study
271 void markStudyAsReference(Study aStudy);
274 * Remove study as reference.
275 * This operation is inverse one to Mark as reference.
277 * @param aStudy - the Study
279 void removeStudyAsReference(Study aStudy);
282 * Get the description attribute related to the study
283 * (there supposed to be the only one such attribute in the database).
284 * @param studyId the study id
285 * @return the description attribute value (null if does not exist)
286 * @throws InvalidParameterException if a study with such id does not exist in the database.
288 String getDescription(Long studyId) throws InvalidParameterException;
291 * Set the description attribute related to the study.
292 * @param studyId the study id
293 * @param descriptionText the description text
294 * @throws InvalidParameterException if some parameters are invalid.
296 void setDescription(Long studyId, String descriptionText) throws InvalidParameterException;
299 * Remove a description attached to a study.
301 * @param studyId the study id
302 * @throws InvalidParameterException
303 * if no study with such Id has been found in the database.
304 * @return true if succeeded, false if study doesn't have a description.
306 boolean removeDescription(final Long studyId) throws InvalidParameterException;
309 * Compare the studies and generate the file that contains the result chart.
310 * @param docsList the list of dtos each contains information:
311 * StudyTitle, ScenarioTitle, PathToFile in vault.
313 * @return path to result file in the vault.
315 String compare (List<DocToCompareDTO> docsList);