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.ValidationCycle;
21 import org.splat.dal.bo.som.Study.Properties;
22 import org.splat.exception.IncompatibleDataException;
23 import org.splat.exception.InvalidParameterException;
24 import org.splat.kernel.InvalidPropertyException;
25 import org.splat.kernel.MismatchException;
26 import org.splat.kernel.MissedPropertyException;
27 import org.splat.kernel.MultiplyDefinedException;
28 import org.splat.service.dto.DocToCompareDTO;
29 import org.splat.service.dto.DocumentDTO;
30 import org.splat.service.dto.StudyFacadeDTO;
31 import org.splat.service.dto.StudyFacadeDTO.ScenarioDTO;
34 * This class defines all methods for creation, modification the study.
36 * @author Maria KRUCHININA
39 public interface StudyService {
42 * Increment total number of study documents including versions (docount) and update it in the study.
46 * @return incremented docount value
48 int generateLocalIndex(Study aStudy);
51 * Get study by its id.
55 * @return found study or null
57 Study selectStudy(long index);
65 public void removeStudy(final long index);
71 * properties of the new study
72 * @return the created study
73 * @throws MissedPropertyException
74 * if a mandatory property is missed
75 * @throws InvalidPropertyException
76 * if an invalid value is passed to a property
77 * @throws MultiplyDefinedException
78 * if some property is defined several times
80 Study createStudy(Study.Properties sprop) throws MissedPropertyException,
81 InvalidPropertyException, MultiplyDefinedException;
84 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
89 * the simulation context properties
90 * @return the added simulation context
91 * @throws MissedPropertyException
92 * if a mandatory property is missed
93 * @throws InvalidPropertyException
94 * if an invalid value is passed to a property
95 * @throws MultiplyDefinedException
96 * if some property occurs several times
98 SimulationContext addProjectContext(Study aStudy,
99 SimulationContext.Properties cprop) throws MissedPropertyException,
100 InvalidPropertyException, MultiplyDefinedException;
103 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
108 * the simulation context to add
109 * @return the added simulation context
111 SimulationContext addProjectContext(Study aStudy, SimulationContext context);
114 * Remove a simulation context from a study.
119 * the simulation context to remove
120 * @return true if removing succeeded
122 boolean removeProjectContext(Study aStudy, SimulationContext context);
125 * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
126 * document of the study.
129 * the study to demote
130 * @return true if the demotion succeeded.
132 boolean demote(Study aStudy);
135 * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
136 * final result document of the study.
139 * the study to promote
140 * @return true if the promotion succeeded.
142 boolean promote(Study aStudy);
145 * Add a contributor to the study.
151 * @return true if addition succeeded
153 boolean addContributor(Study aStudy, User user);
156 * Remove contributors from the study.
162 * @return true if removing succeeded
164 boolean removeContributor(Study aStudy, User... users);
167 * Set a validation cycle for documents of the given type in the given study.
174 * validation cycle properties
176 void setValidationCycle(Study aStudy, DocumentType type,
177 ValidationCycle.Properties vprop);
180 * Moves this study from the Private to the Public area of the repository.
184 * @return true if the move succeeded.
187 boolean moveToPublic(Study aStudy);
190 * Moves this study from the Public to the Private area of the repository.
194 * @return true if the move succeeded.
196 boolean moveToPrivate(Study aStudy);
199 * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
200 * previously be approved.
204 * @return true if the move succeeded.
205 * @see #moveToPublic()
207 * @see Publication#approve(Date)
209 boolean moveToReference(Study aStudy);
215 * the study to update
217 * new properties of the study
218 * @return true if the study has been updated successfully
219 * @throws InvalidPropertyException
220 * if an invalid value is passed to a property
222 boolean update(Study aStudy, Properties sprop)
223 throws InvalidPropertyException;
226 * Initialize shortcuts of the study as its transient collections.
231 void loadWorkflow(Study aStudy);
234 * Returns the validation cycle of the given document type.
239 * the document type being subject of validation
240 * @return the validation cycle of the document, or null if not defined.
242 ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
245 * Checks if the given user participates to this study. The Study staff includes the author and contributors.
250 * the user to look for
251 * @return true if the given user is actor of this study.
252 * @see #getContributors()
254 boolean isStaffedBy(Study aStudy, User user);
257 * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
262 * the user to look for
263 * @return true if the given user is actor of this study.
266 boolean hasActor(Study aStudy, User user);
269 * Returns unmodifiable initialized transient list of contributors of this study.
273 * @return the unmodifiable not null transient list of contributors of this study
275 List<User> getContributors(Study aStudy);
278 * Mark study as reference.
283 void markStudyAsReference(Study aStudy);
286 * Remove study as reference. This operation is inverse one to Mark as reference.
291 void removeStudyAsReference(Study aStudy);
294 * Get studies, scenarios and publications available for comparison.
295 * <br><b> DocumentDto.id are actually filled in with Publication ids.</b>
296 * @param userId id of the user to to whom visible studies will be returned.
297 * @return list of {@link StudyFacadeDTO} containing lists of {@link ScenarioDTO} containing list of
298 * {@link DocumentDTO}, corresponding to to the publications available for comparison,
299 * with ids and titles filled in.
300 * @throws MismatchException if some configurations considering postprocessing step are invalid.
302 List<StudyFacadeDTO> getComparableStudies(final long userId) throws MismatchException;
305 * Get the description attribute related to the study (there supposed to be the only one such attribute in the database).
309 * @return the description attribute value (null if does not exist)
310 * @throws InvalidParameterException
311 * if a study with such id does not exist in the database.
313 String getDescription(Long studyId) throws InvalidParameterException;
316 * Set the description attribute related to the study.
320 * @param descriptionText
321 * the description text
322 * @throws InvalidParameterException
323 * if some parameters are invalid.
325 void setDescription(Long studyId, String descriptionText)
326 throws InvalidParameterException;
329 * Remove a description attached to a study.
333 * @throws InvalidParameterException
334 * if no study with such Id has been found in the database.
335 * @return true if succeeded, false if study doesn't have a description.
337 boolean removeDescription(final Long studyId)
338 throws InvalidParameterException;
341 * Compare the studies and generate the file that contains the result chart.
344 * the list of dtos each contains information: StudyTitle, ScenarioTitle, PathToFile in vault.
346 * the name of the user who compare the results.
347 * @throws IncompatibleDataException
348 * if data is incompatible for "Compare the studies" functionality.
350 * @return path to result file in the vault.
352 String compare(List<DocToCompareDTO> docsList, final String userName)
353 throws IncompatibleDataException;