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