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