1 /*****************************************************************************
5 * Creation date 02.10.2012
6 * @author Author: Maria KRUCHININA
8 *****************************************************************************/
10 package org.splat.service;
12 import java.util.List;
14 import org.splat.dal.bo.kernel.User;
15 import org.splat.dal.bo.som.DocumentType;
16 import org.splat.dal.bo.som.Publication;
17 import org.splat.dal.bo.som.SimulationContext;
18 import org.splat.dal.bo.som.Study;
19 import org.splat.dal.bo.som.ValidationCycle;
20 import org.splat.dal.bo.som.Study.Properties;
21 import org.splat.exception.IncompatibleDataException;
22 import org.splat.exception.InvalidParameterException;
23 import org.splat.kernel.InvalidPropertyException;
24 import org.splat.kernel.MismatchException;
25 import org.splat.kernel.MissedPropertyException;
26 import org.splat.kernel.MultiplyDefinedException;
27 import org.splat.service.dto.DocToCompareDTO;
28 import org.splat.service.dto.DocumentDTO;
29 import org.splat.service.dto.StudyFacadeDTO;
30 import org.splat.service.dto.StudyFacadeDTO.ScenarioDTO;
33 * This class defines all methods for creation, modification the study.
35 * @author Maria KRUCHININA
38 public interface StudyService {
41 * Increment total number of study documents including versions (docount) and update it in the study.
45 * @return incremented docount value
47 int generateLocalIndex(Study aStudy);
50 * Get study by its id.
54 * @return found study or null
56 Study selectStudy(long index);
64 public void removeStudy(final Long index);
70 * properties of the new study
71 * @return the created study
72 * @throws MissedPropertyException
73 * if a mandatory property is missed
74 * @throws InvalidPropertyException
75 * if an invalid value is passed to a property
76 * @throws MultiplyDefinedException
77 * if some property is defined several times
79 Study createStudy(Study.Properties sprop) throws MissedPropertyException,
80 InvalidPropertyException, MultiplyDefinedException;
83 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
88 * the simulation context properties
89 * @return the added simulation context
90 * @throws MissedPropertyException
91 * if a mandatory property is missed
92 * @throws InvalidPropertyException
93 * if an invalid value is passed to a property
94 * @throws MultiplyDefinedException
95 * if some property occurs several times
97 SimulationContext addProjectContext(Study aStudy,
98 SimulationContext.Properties cprop) throws MissedPropertyException,
99 InvalidPropertyException, MultiplyDefinedException;
102 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
107 * the simulation context to add
108 * @return the added simulation context
110 SimulationContext addProjectContext(Study aStudy, SimulationContext context);
113 * Remove a simulation context from a study.
118 * the simulation context to remove
119 * @return true if removing succeeded
121 boolean removeProjectContext(Study aStudy, SimulationContext context);
124 * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
125 * document of the study.
128 * the study to demote
129 * @return true if the demotion succeeded.
131 boolean demote(Study aStudy);
134 * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
135 * final result document of the study.
138 * the study to promote
139 * @return true if the promotion succeeded.
141 boolean promote(Study aStudy);
144 * Add a contributor to the study.
150 * @return true if addition succeeded
152 boolean addContributor(Study aStudy, User user);
155 * Remove contributors from the study.
161 * @return true if removing succeeded
163 boolean removeContributor(Study aStudy, User... users);
166 * Set a validation cycle for documents of the given type in the given study.
173 * validation cycle properties
175 void setValidationCycle(Study aStudy, DocumentType type,
176 ValidationCycle.Properties vprop);
179 * Moves this study from the Private to the Public area of the repository.
183 * @return true if the move succeeded.
186 boolean moveToPublic(Study aStudy);
189 * Moves this study from the Public to the Private area of the repository.
193 * @return true if the move succeeded.
195 boolean moveToPrivate(Study aStudy);
198 * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
199 * previously be approved.
203 * @return true if the move succeeded.
204 * @see #moveToPublic()
206 * @see Publication#approve(Date)
208 boolean moveToReference(Study aStudy);
214 * the study to update
216 * new properties of the study
217 * @return true if the study has been updated successfully
218 * @throws InvalidPropertyException
219 * if an invalid value is passed to a property
221 boolean update(Study aStudy, Properties sprop)
222 throws InvalidPropertyException;
225 * Initialize shortcuts of the study as its transient collections.
230 void loadWorkflow(Study aStudy);
233 * Returns the validation cycle of the given document type.
238 * the document type being subject of validation
239 * @return the validation cycle of the document, or null if not defined.
241 ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
244 * Checks if the given user participates to this study. The Study staff includes the author and contributors.
249 * the user to look for
250 * @return true if the given user is actor of this study.
251 * @see #getContributors()
253 boolean isStaffedBy(Study aStudy, User user);
256 * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
261 * the user to look for
262 * @return true if the given user is actor of this study.
265 boolean hasActor(Study aStudy, User user);
268 * Returns unmodifiable initialized transient list of contributors of this study.
272 * @return the unmodifiable not null transient list of contributors of this study
274 List<User> getContributors(Study aStudy);
277 * Mark study as reference.
282 void markStudyAsReference(Study aStudy);
285 * Remove study as reference. This operation is inverse one to Mark as reference.
290 void removeStudyAsReference(Study aStudy);
293 * Get studies, scenarios and publications available for comparison.
294 * <br><b> DocumentDto.id are actually filled in with Publication ids.</b>
295 * @param userId id of the user to to whom visible studies will be returned.
296 * @return list of {@link StudyFacadeDTO} containing lists of {@link ScenarioDTO} containing list of
297 * {@link DocumentDTO}, corresponding to to the publications available for comparison,
298 * with ids and titles filled in.
299 * @throws MismatchException if some configurations considering postprocessing step are invalid.
301 List<StudyFacadeDTO> getComparableStudies(final long userId) throws MismatchException;
304 * Get the description attribute related to the study (there supposed to be the only one such attribute in the database).
308 * @return the description attribute value (null if does not exist)
309 * @throws InvalidParameterException
310 * if a study with such id does not exist in the database.
312 String getDescription(Long studyId) throws InvalidParameterException;
315 * Set the description attribute related to the study.
319 * @param descriptionText
320 * the description text
321 * @throws InvalidParameterException
322 * if some parameters are invalid.
324 void setDescription(Long studyId, String descriptionText)
325 throws InvalidParameterException;
328 * Remove a description attached to a study.
332 * @throws InvalidParameterException
333 * if no study with such Id has been found in the database.
334 * @return true if succeeded, false if study doesn't have a description.
336 boolean removeDescription(final Long studyId)
337 throws InvalidParameterException;
340 * Compare the studies and generate the file that contains the result chart.
343 * the list of dtos each contains information: StudyTitle, ScenarioTitle, PathToFile in vault.
345 * the name of the user who compare the results.
346 * @throws IncompatibleDataException
347 * if data is incompatible for "Compare the studies" functionality.
349 * @return path to result file in the vault.
351 String compare(List<DocToCompareDTO> docsList, final String userName)
352 throws IncompatibleDataException;