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 }