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