]> SALOME platform Git repositories - tools/siman.git/blob - Workspace/Siman-Common/src/org/splat/service/StudyService.java
Salome HOME
9726ddb83f055c39b38cc231eac14851c017124f
[tools/siman.git] / Workspace / Siman-Common / src / org / splat / service / StudyService.java
1 /*****************************************************************************
2  * Company         OPEN CASCADE
3  * Application     SIMAN
4  * File            Id: 
5  * Creation date   02.10.2012
6  * @author         Author: Maria KRUCHININA
7  * @version        Revision: 
8  *****************************************************************************/
9
10 package org.splat.service;
11
12 import java.util.Date;
13 import java.util.List;
14
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.IncompatibleDataException;
23 import org.splat.exception.InvalidParameterException;
24 import org.splat.kernel.InvalidPropertyException;
25 import org.splat.kernel.MissedPropertyException;
26 import org.splat.kernel.MultiplyDefinedException;
27 import org.splat.service.dto.DocToCompareDTO;
28
29 /**
30  * This class defines all methods for creation, modification the study.
31  * 
32  * @author Maria KRUCHININA
33  * 
34  */
35 public interface StudyService {
36
37         /**
38          * Increment total number of study documents including versions (docount) and update it in the study.
39          * 
40          * @param aStudy
41          *            the study
42          * @return incremented docount value
43          */
44         int generateLocalIndex(Study aStudy);
45
46         /**
47          * Get study by its id.
48          * 
49          * @param index
50          *            the study id
51          * @return found study or null
52          */
53         Study selectStudy(long index);
54
55         /**
56          * Create a new study.
57          * 
58          * @param sprop
59          *            properties of the new study
60          * @return the created study
61          * @throws MissedPropertyException
62          *             if a mandatory property is missed
63          * @throws InvalidPropertyException
64          *             if some property doesn't exist
65          * @throws MultiplyDefinedException
66          *             if some property is defined several times
67          */
68         Study createStudy(Study.Properties sprop)
69                         throws MissedPropertyException, InvalidPropertyException,
70                         MultiplyDefinedException;
71
72         /**
73          * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
74          * 
75          * @param aStudy
76          *            the study
77          * @param cprop
78          *            the simulation context properties
79          * @return the added simulation context
80          * @throws MissedPropertyException
81          *             if a mandatory property is missed
82          * @throws InvalidPropertyException
83          *             if some property doesn't exist
84          * @throws MultiplyDefinedException
85          *             if some property occurs several times
86          */
87         SimulationContext addProjectContext(Study aStudy,
88                         SimulationContext.Properties cprop) throws MissedPropertyException,
89                         InvalidPropertyException, MultiplyDefinedException;
90
91         /**
92          * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
93          * 
94          * @param aStudy
95          *            the study
96          * @param context
97          *            the simulation context to add
98          * @return the added simulation context
99          */
100         SimulationContext addProjectContext(Study aStudy,
101                         SimulationContext context);
102
103         /**
104          * Remove a simulation context from a study.
105          * 
106          * @param aStudy
107          *            the study
108          * @param context
109          *            the simulation context to remove
110          * @return true if removing succeeded
111          */
112         boolean removeProjectContext(Study aStudy, SimulationContext context);
113
114         /**
115          * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
116          * document of the study.
117          * 
118          * @param aStudy
119          *            the study to demote
120          * @return true if the demotion succeeded.
121          */
122         boolean demote(Study aStudy);
123
124         /**
125          * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
126          * final result document of the study.
127          * 
128          * @param aStudy
129          *            the study to promote
130          * @return true if the promotion succeeded.
131          */
132         boolean promote(Study aStudy);
133
134         /**
135          * Add a contributor to the study.
136          * 
137          * @param aStudy
138          *            the study
139          * @param user
140          *            the contributor
141          * @return true if addition succeeded
142          */
143         boolean addContributor(Study aStudy, User user);
144
145         /**
146          * Remove contributors from the study.
147          * 
148          * @param aStudy
149          *            the study
150          * @param users
151          *            contributor(s)
152          * @return true if removing succeeded
153          */
154         boolean removeContributor(Study aStudy, User... users);
155
156         /**
157          * Set a validation cycle for documents of the given type in the given study.
158          * 
159          * @param aStudy
160          *            the target study
161          * @param type
162          *            the document type
163          * @param vprop
164          *            validation cycle properties
165          */
166         void setValidationCycle(Study aStudy, DocumentType type,
167                         ValidationCycle.Properties vprop);
168
169         /**
170          * Moves this study from the Private to the Public area of the repository.
171          * 
172          * @param aStudy
173          *            the study to move
174          * @return true if the move succeeded.
175          * @see #isPublic()
176          */
177         boolean moveToPublic(Study aStudy);
178         
179         /**
180          * Moves this study from the Public to the Private area of the repository.
181          * 
182          * @param aStudy
183          *            the study to move
184          * @return true if the move succeeded.
185          */
186         boolean moveToPrivate(Study aStudy);
187
188         /**
189          * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
190          * previously be approved.
191          * 
192          * @param aStudy
193          *            the study to move
194          * @return true if the move succeeded.
195          * @see #moveToPublic()
196          * @see #isPublic()
197          * @see Publication#approve(Date)
198          */
199         boolean moveToReference(Study aStudy);
200
201         /**
202          * Update a study.
203          * 
204          * @param aStudy
205          *            the study to update
206          * @param sprop
207          *            new properties of the study
208          * @return true if the study has been updated successfully
209          * @throws InvalidPropertyException
210          *             if some property doesn't exist
211          */
212         boolean update(Study aStudy, Properties sprop)
213                         throws InvalidPropertyException;
214
215         /**
216          * Initialize shortcuts of the study as its transient collections.
217          * 
218          * @param aStudy
219          *            the study
220          */
221         void loadWorkflow(Study aStudy);
222
223         /**
224          * Returns the validation cycle of the given document type.
225          * 
226          * @param aStudy
227          *            the study
228          * @param type
229          *            the document type being subject of validation
230          * @return the validation cycle of the document, or null if not defined.
231          */
232         ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
233
234         /**
235          * Checks if the given user participates to this study. The Study staff includes the author and contributors.
236          * 
237          * @param aStudy
238          *            the study
239          * @param user
240          *            the user to look for
241          * @return true if the given user is actor of this study.
242          * @see #getContributors()
243          */
244         boolean isStaffedBy(Study aStudy, User user);
245
246         /**
247          * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
248          * 
249          * @param aStudy
250          *            the study
251          * @param user
252          *            the user to look for
253          * @return true if the given user is actor of this study.
254          * @see #getActors()
255          */
256         boolean hasActor(Study aStudy, User user);
257
258         /**
259          * Returns unmodifiable initialized transient list of contributors of this study.
260          * 
261          * @param aStudy
262          *            the study
263          * @return the unmodifiable not null transient list of contributors of this study
264          */
265         List<User> getContributors(Study aStudy);
266         
267         /**
268          * Mark study as reference.
269          * 
270          * @param aStudy - the Study
271          */
272         void markStudyAsReference(Study aStudy);
273         
274         /**
275          * Remove study as reference.
276          * This operation is inverse one to Mark as reference.
277          * 
278          * @param aStudy - the Study
279          */
280         void removeStudyAsReference(Study aStudy);
281         
282         /**
283          * Get the description attribute related to the study
284          *              (there supposed to be the only one such attribute in the database).
285          * @param studyId the study id
286          * @return the description attribute value (null if does not exist)
287          * @throws InvalidParameterException if a study with such id does not exist in the database.
288          */
289         String getDescription(Long studyId) throws InvalidParameterException;
290         
291         /**
292          * Set the description attribute related to the study.
293          * @param studyId the study id
294          * @param descriptionText the description text
295          * @throws InvalidParameterException if some parameters are invalid.
296          */
297         void setDescription(Long studyId, String descriptionText) throws InvalidParameterException;
298
299         /**
300          * Remove a description attached to a study.
301          * 
302          * @param studyId the study id
303          * @throws InvalidParameterException
304          *              if no study with such Id has been found in the database.
305          * @return true if succeeded, false if study doesn't have a description.
306          */
307         boolean removeDescription(final Long studyId) throws InvalidParameterException;
308         
309         /**
310          * Compare the studies and generate the file that contains the result chart.
311          * @param docsList the list of dtos each contains information: 
312          *        StudyTitle, ScenarioTitle, PathToFile in vault. 
313          * @param userName the name of the user who compare the results.       
314          * @throws IncompatibleDataException
315          *         if data is incompatible for "Compare the studies" functionality.
316          * 
317          * @return path to result file in the vault.
318          */
319         String compare (List<DocToCompareDTO> docsList, final String userName) throws IncompatibleDataException;
320 }