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