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