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