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.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.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 an invalid value is passed to a property
  65          * @throws MultiplyDefinedException
  66          *             if some property is defined several times
  67          */
  68         Study createStudy(Study.Properties sprop) throws MissedPropertyException,
  69                         InvalidPropertyException, 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 an invalid value is passed to a property
  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, SimulationContext context);
 100
 101         /**
 102          * Remove a simulation context from a study.
 103          *
 104          * @param aStudy
 105          *            the study
 106          * @param context
 107          *            the simulation context to remove
 108          * @return true if removing succeeded
 109          */
 110         boolean removeProjectContext(Study aStudy, SimulationContext context);
 111
 112         /**
 113          * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
 114          * document of the study.
 115          *
 116          * @param aStudy
 117          *            the study to demote
 118          * @return true if the demotion succeeded.
 119          */
 120         boolean demote(Study aStudy);
 121
 122         /**
 123          * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
 124          * final result document of the study.
 125          *
 126          * @param aStudy
 127          *            the study to promote
 128          * @return true if the promotion succeeded.
 129          */
 130         boolean promote(Study aStudy);
 131
 132         /**
 133          * Add a contributor to the study.
 134          *
 135          * @param aStudy
 136          *            the study
 137          * @param user
 138          *            the contributor
 139          * @return true if addition succeeded
 140          */
 141         boolean addContributor(Study aStudy, User user);
 142
 143         /**
 144          * Remove contributors from the study.
 145          *
 146          * @param aStudy
 147          *            the study
 148          * @param users
 149          *            contributor(s)
 150          * @return true if removing succeeded
 151          */
 152         boolean removeContributor(Study aStudy, User... users);
 153
 154         /**
 155          * Set a validation cycle for documents of the given type in the given study.
 156          *
 157          * @param aStudy
 158          *            the target study
 159          * @param type
 160          *            the document type
 161          * @param vprop
 162          *            validation cycle properties
 163          */
 164         void setValidationCycle(Study aStudy, DocumentType type,
 165                         ValidationCycle.Properties vprop);
 166
 167         /**
 168          * Moves this study from the Private to the Public area of the repository.
 169          *
 170          * @param aStudy
 171          *            the study to move
 172          * @return true if the move succeeded.
 173          * @see #isPublic()
 174          */
 175         boolean moveToPublic(Study aStudy);
 176
 177         /**
 178          * Moves this study from the Public to the Private area of the repository.
 179          *
 180          * @param aStudy
 181          *            the study to move
 182          * @return true if the move succeeded.
 183          */
 184         boolean moveToPrivate(Study aStudy);
 185
 186         /**
 187          * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
 188          * previously be approved.
 189          *
 190          * @param aStudy
 191          *            the study to move
 192          * @return true if the move succeeded.
 193          * @see #moveToPublic()
 194          * @see #isPublic()
 195          * @see Publication#approve(Date)
 196          */
 197         boolean moveToReference(Study aStudy);
 198
 199         /**
 200          * Update a study.
 201          *
 202          * @param aStudy
 203          *            the study to update
 204          * @param sprop
 205          *            new properties of the study
 206          * @return true if the study has been updated successfully
 207          * @throws InvalidPropertyException
 208          *             if an invalid value is passed to a property
 209          */
 210         boolean update(Study aStudy, Properties sprop)
 211                         throws InvalidPropertyException;
 212
 213         /**
 214          * Initialize shortcuts of the study as its transient collections.
 215          *
 216          * @param aStudy
 217          *            the study
 218          */
 219         void loadWorkflow(Study aStudy);
 220
 221         /**
 222          * Returns the validation cycle of the given document type.
 223          *
 224          * @param aStudy
 225          *            the study
 226          * @param type
 227          *            the document type being subject of validation
 228          * @return the validation cycle of the document, or null if not defined.
 229          */
 230         ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
 231
 232         /**
 233          * Checks if the given user participates to this study. The Study staff includes the author and contributors.
 234          *
 235          * @param aStudy
 236          *            the study
 237          * @param user
 238          *            the user to look for
 239          * @return true if the given user is actor of this study.
 240          * @see #getContributors()
 241          */
 242         boolean isStaffedBy(Study aStudy, User user);
 243
 244         /**
 245          * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
 246          *
 247          * @param aStudy
 248          *            the study
 249          * @param user
 250          *            the user to look for
 251          * @return true if the given user is actor of this study.
 252          * @see #getActors()
 253          */
 254         boolean hasActor(Study aStudy, User user);
 255
 256         /**
 257          * Returns unmodifiable initialized transient list of contributors of this study.
 258          *
 259          * @param aStudy
 260          *            the study
 261          * @return the unmodifiable not null transient list of contributors of this study
 262          */
 263         List<User> getContributors(Study aStudy);
 264
 265         /**
 266          * Mark study as reference.
 267          *
 268          * @param aStudy -
 269          *            the Study
 270          */
 271         void markStudyAsReference(Study aStudy);
 272
 273         /**
 274          * Remove study as reference. This operation is inverse one to Mark as reference.
 275          *
 276          * @param aStudy -
 277          *            the Study
 278          */
 279         void removeStudyAsReference(Study aStudy);
 280
 281         /**
 282          * Get the description attribute related to the study (there supposed to be the only one such attribute in the database).
 283          *
 284          * @param studyId
 285          *            the study id
 286          * @return the description attribute value (null if does not exist)
 287          * @throws InvalidParameterException
 288          *             if a study with such id does not exist in the database.
 289          */
 290         String getDescription(Long studyId) throws InvalidParameterException;
 291
 292         /**
 293          * Set the description attribute related to the study.
 294          *
 295          * @param studyId
 296          *            the study id
 297          * @param descriptionText
 298          *            the description text
 299          * @throws InvalidParameterException
 300          *             if some parameters are invalid.
 301          */
 302         void setDescription(Long studyId, String descriptionText)
 303                         throws InvalidParameterException;
 304
 305         /**
 306          * Remove a description attached to a study.
 307          *
 308          * @param studyId
 309          *            the study id
 310          * @throws InvalidParameterException
 311          *             if no study with such Id has been found in the database.
 312          * @return true if succeeded, false if study doesn't have a description.
 313          */
 314         boolean removeDescription(final Long studyId)
 315                         throws InvalidParameterException;
 316
 317         /**
 318          * Compare the studies and generate the file that contains the result chart.
 319          *
 320          * @param docsList
 321          *            the list of dtos each contains information: StudyTitle, ScenarioTitle, PathToFile in vault.
 322          * @param userName
 323          *            the name of the user who compare the results.
 324          * @throws IncompatibleDataException
 325          *             if data is incompatible for "Compare the studies" functionality.
 326          *
 327          * @return path to result file in the vault.
 328          */
 329         String compare(List<DocToCompareDTO> docsList, final String userName)
 330                         throws IncompatibleDataException;
 331 }