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.SimulationContext;
17 import org.splat.dal.bo.som.Study;
18 import org.splat.dal.bo.som.ValidationCycle;
19 import org.splat.dal.bo.som.Study.Properties;
20 import org.splat.exception.InvalidParameterException;
21 import org.splat.kernel.InvalidPropertyException;
22 import org.splat.kernel.MissedPropertyException;
23 import org.splat.kernel.MultiplyDefinedException;
24 import org.splat.service.dto.UserDTO;
27 * This class defines all methods for creation, modification the study.
29 * @author Maria KRUCHININA
32 public interface StudyService {
35 * Check if the study can be promoted taking into account its documents states.
38 * the study to be checked
39 * @return true if states of study documents allows the operation
41 boolean canBePromoted(final Study study);
44 * Check if the study can be validated taking into account its documents states.
47 * the study to be checked
48 * @return true if states of study documents allows the operation
50 boolean canBeReviewed(final Study study);
53 * Check if the study can be approved taking into account its documents states.
56 * the study to be checked
57 * @return true if states of study documents allows the operation
59 boolean canBeApproved(final Study study);
62 * Get the study result document type.
66 * @return document type
68 DocumentType getStudyResultType(final Study aStudy);
71 * Increment total number of study documents including versions (docount) and update it in the study.
75 * @return incremented docount value
77 int generateLocalIndex(Study aStudy);
80 * Get study by its id.
84 * @return found study or null
86 Study selectStudy(long index);
94 void removeStudy(final Long index);
100 * properties of the new study
101 * @return the created study
102 * @throws MissedPropertyException
103 * if a mandatory property is missed
104 * @throws InvalidPropertyException
105 * if an invalid value is passed to a property
106 * @throws MultiplyDefinedException
107 * if some property is defined several times
109 Study createStudy(Study.Properties sprop) throws MissedPropertyException,
110 InvalidPropertyException, MultiplyDefinedException;
113 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
118 * the simulation context properties
119 * @return the added simulation context
120 * @throws MissedPropertyException
121 * if a mandatory property is missed
122 * @throws InvalidPropertyException
123 * if an invalid value is passed to a property
124 * @throws MultiplyDefinedException
125 * if some property occurs several times
127 SimulationContext addProjectContext(Study aStudy,
128 SimulationContext.Properties cprop) throws MissedPropertyException,
129 InvalidPropertyException, MultiplyDefinedException;
132 * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
137 * the simulation context to add
138 * @return the added simulation context
140 SimulationContext addProjectContext(Study aStudy, SimulationContext context);
143 * Remove a simulation context from a study.
148 * the simulation context to remove
149 * @return true if removing succeeded
151 boolean removeProjectContext(Study aStudy, SimulationContext context);
154 * Demotes this study from In-Check or In-Draft to In-Work states.
158 * @return true if the demotion succeeded.
160 boolean demote(Study aStudy);
163 * Promotes this study from In-Work to In-Draft then In-Check and APPROVED <BR>
164 * states. This function takes into account statuses of final result<BR>
165 * documents of the study.
169 * @return true if the promotion succeeded.
171 boolean promote(Study aStudy);
174 * Add a contributor to the study.
180 * @return true if addition succeeded
182 boolean addContributor(Study aStudy, User user);
185 * Remove contributors from the study.
191 * @return true if removing succeeded
193 boolean removeContributor(Study aStudy, User... users);
196 * Set a validation cycle for documents of the given type in the given study.
203 * validation cycle properties
205 void setValidationCycle(Study aStudy, DocumentType type,
206 ValidationCycle.Properties vprop);
209 * Moves this study from the Private to the Public area of the repository.
213 * @return true if the move succeeded.
216 boolean moveToPublic(Study aStudy);
219 * Moves this study from the Public to the Private area of the repository.
223 * @return true if the move succeeded.
225 boolean moveToPrivate(Study aStudy);
231 * the study to update
233 * new properties of the study
234 * @return true if the study has been updated successfully
235 * @throws InvalidPropertyException
236 * if an invalid value is passed to a property
238 boolean update(Study aStudy, Properties sprop)
239 throws InvalidPropertyException;
242 * Initialize shortcuts of the study as its transient collections.
247 void loadWorkflow(Study aStudy);
250 * Returns the validation cycle of the given document type.
255 * the document type being subject of validation
256 * @return the validation cycle of the document, or null if not defined.
258 ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
261 * Checks if the given user participates to this study. The Study staff includes the author and contributors.
266 * the user to look for
267 * @return true if the given user is actor of this study.
268 * @see #getContributors()
270 boolean isStaffedBy(Study aStudy, User user);
273 * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
278 * the user to look for
279 * @return true if the given user is actor of this study.
282 boolean hasActor(Study aStudy, User user);
285 * Returns unmodifiable initialized transient list of contributors of this study.
289 * @return the unmodifiable not null transient list of contributors of this study
291 List<User> getContributors(Study aStudy);
294 * Mark this study as Reference. The study must previously be approved.
298 * @return true if succeeded
300 boolean markStudyAsReference(Study aStudy);
303 * Remove study as reference. This operation is inverse one to Mark as reference.
308 void removeStudyAsReference(Study aStudy);
311 * Get the description attribute related to the study (there supposed to be the only one such attribute in the database).
315 * @return the description attribute value (null if does not exist)
316 * @throws InvalidParameterException
317 * if a study with such id does not exist in the database.
319 String getDescription(Long studyId) throws InvalidParameterException;
322 * Set the description attribute related to the study.
326 * @param descriptionText
327 * the description text
328 * @throws InvalidParameterException
329 * if some parameters are invalid.
331 void setDescription(Long studyId, String descriptionText)
332 throws InvalidParameterException;
335 * Remove a description attached to a study.
339 * @throws InvalidParameterException
340 * if no study with such Id has been found in the database.
341 * @return true if succeeded, false if study doesn't have a description.
343 boolean removeDescription(final Long studyId)
344 throws InvalidParameterException;
347 * Get readers of a given study.
351 * @return list of user DTO corresponding to the study readers.
352 * @throws InvalidParameterException
353 * if no study with such id has been found in the database.
355 List<UserDTO> getReaders(final long studyId)
356 throws InvalidParameterException;
359 * Add reader to a given study.
365 * @return true if the user has been added as a reader
366 * @throws InvalidParameterException
367 * if no study or user with such id has been found in the database.
369 boolean addReader(final long studyId, final long userId)
370 throws InvalidParameterException;
373 * Remove reader from a given study.
379 * @return true if the relation has been found and removed
380 * @throws InvalidParameterException
381 * if no study or user with such id has been found in the database.
383 boolean removeReader(final long studyId, final long userId)
384 throws InvalidParameterException;