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.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;
  27
  28 /**
  29  * This class defines all methods for creation, modification the study.
  30  *
  31  * @author Maria KRUCHININA
  32  *
  33  */
  34 public interface StudyService {
  35
  36         /**
  37          * Increment total number of study documents including versions (docount) and update it in the study.
  38          *
  39          * @param aStudy
  40          *            the study
  41          * @return incremented docount value
  42          */
  43         int generateLocalIndex(Study aStudy);
  44
  45         /**
  46          * Get study by its id.
  47          *
  48          * @param index
  49          *            the study id
  50          * @return found study or null
  51          */
  52         Study selectStudy(long index);
  53
  54         /**
  55          * Create a new study.
  56          *
  57          * @param sprop
  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
  66          */
  67         Study createStudy(Study.Properties sprop)
  68                         throws MissedPropertyException, InvalidPropertyException,
  69                         MultiplyDefinedException;
  70
  71         /**
  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.
  73          *
  74          * @param aStudy
  75          *            the study
  76          * @param cprop
  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
  85          */
  86         SimulationContext addProjectContext(Study aStudy,
  87                         SimulationContext.Properties cprop) throws MissedPropertyException,
  88                         InvalidPropertyException, MultiplyDefinedException;
  89
  90         /**
  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.
  92          *
  93          * @param aStudy
  94          *            the study
  95          * @param context
  96          *            the simulation context to add
  97          * @return the added simulation context
  98          */
  99         SimulationContext addProjectContext(Study aStudy,
 100                         SimulationContext context);
 101
 102         /**
 103          * Remove a simulation context from a study.
 104          *
 105          * @param aStudy
 106          *            the study
 107          * @param context
 108          *            the simulation context to remove
 109          * @return true if removing succeeded
 110          */
 111         boolean removeProjectContext(Study aStudy, SimulationContext context);
 112
 113         /**
 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.
 116          *
 117          * @param aStudy
 118          *            the study to demote
 119          * @return true if the demotion succeeded.
 120          */
 121         boolean demote(Study aStudy);
 122
 123         /**
 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.
 126          *
 127          * @param aStudy
 128          *            the study to promote
 129          * @return true if the promotion succeeded.
 130          */
 131         boolean promote(Study aStudy);
 132
 133         /**
 134          * Add a contributor to the study.
 135          *
 136          * @param aStudy
 137          *            the study
 138          * @param user
 139          *            the contributor
 140          * @return true if addition succeeded
 141          */
 142         boolean addContributor(Study aStudy, User user);
 143
 144         /**
 145          * Remove contributors from the study.
 146          *
 147          * @param aStudy
 148          *            the study
 149          * @param users
 150          *            contributor(s)
 151          * @return true if removing succeeded
 152          */
 153         boolean removeContributor(Study aStudy, User... users);
 154
 155         /**
 156          * Set a validation cycle for documents of the given type in the given study.
 157          *
 158          * @param aStudy
 159          *            the target study
 160          * @param type
 161          *            the document type
 162          * @param vprop
 163          *            validation cycle properties
 164          */
 165         void setValidationCycle(Study aStudy, DocumentType type,
 166                         ValidationCycle.Properties vprop);
 167
 168         /**
 169          * Moves this study from the Private to the Public area of the repository.
 170          *
 171          * @param aStudy
 172          *            the study to move
 173          * @return true if the move succeeded.
 174          * @see #isPublic()
 175          */
 176         boolean moveToPublic(Study aStudy);
 177
 178         /**
 179          * Moves this study from the Public to the Private area of the repository.
 180          *
 181          * @param aStudy
 182          *            the study to move
 183          * @return true if the move succeeded.
 184          */
 185         boolean moveToPrivate(Study aStudy);
 186
 187         /**
 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.
 190          *
 191          * @param aStudy
 192          *            the study to move
 193          * @return true if the move succeeded.
 194          * @see #moveToPublic()
 195          * @see #isPublic()
 196          * @see Publication#approve(Date)
 197          */
 198         boolean moveToReference(Study aStudy);
 199
 200         /**
 201          * Update a study.
 202          *
 203          * @param aStudy
 204          *            the study to update
 205          * @param sprop
 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
 210          */
 211         boolean update(Study aStudy, Properties sprop)
 212                         throws InvalidPropertyException;
 213
 214         /**
 215          * Initialize shortcuts of the study as its transient collections.
 216          *
 217          * @param aStudy
 218          *            the study
 219          */
 220         void loadWorkflow(Study aStudy);
 221
 222         /**
 223          * Returns the validation cycle of the given document type.
 224          *
 225          * @param aStudy
 226          *            the study
 227          * @param type
 228          *            the document type being subject of validation
 229          * @return the validation cycle of the document, or null if not defined.
 230          */
 231         ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
 232
 233         /**
 234          * Checks if the given user participates to this study. The Study staff includes the author and contributors.
 235          *
 236          * @param aStudy
 237          *            the study
 238          * @param user
 239          *            the user to look for
 240          * @return true if the given user is actor of this study.
 241          * @see #getContributors()
 242          */
 243         boolean isStaffedBy(Study aStudy, User user);
 244
 245         /**
 246          * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
 247          *
 248          * @param aStudy
 249          *            the study
 250          * @param user
 251          *            the user to look for
 252          * @return true if the given user is actor of this study.
 253          * @see #getActors()
 254          */
 255         boolean hasActor(Study aStudy, User user);
 256
 257         /**
 258          * Returns unmodifiable initialized transient list of contributors of this study.
 259          *
 260          * @param aStudy
 261          *            the study
 262          * @return the unmodifiable not null transient list of contributors of this study
 263          */
 264         List<User> getContributors(Study aStudy);
 265
 266         /**
 267          * Mark study as reference.
 268          *
 269          * @param aStudy - the Study
 270          */
 271         void markStudyAsReference(Study aStudy);
 272
 273         /**
 274          * Remove study as reference.
 275          * This operation is inverse one to Mark as reference.
 276          *
 277          * @param aStudy - the Study
 278          */
 279         void removeStudyAsReference(Study aStudy);
 280
 281         /**
 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.
 287          */
 288         String getDescription(Long studyId) throws InvalidParameterException;
 289
 290         /**
 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.
 295          */
 296         void setDescription(Long studyId, String descriptionText) throws InvalidParameterException;
 297
 298         /**
 299          * Remove a description attached to a study.
 300          *
 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.
 305          */
 306         boolean removeDescription(final Long studyId) throws InvalidParameterException;
 307
 308         /**
 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.
 312          *
 313          * @return path to result file in the vault.
 314          */
 315         String compare (List<DocToCompareDTO> docsList);
 316 }