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.Study.Properties;
  21 import org.splat.dal.bo.som.ValidationCycle;
  22 import org.splat.exception.InvalidParameterException;
  23 import org.splat.kernel.InvalidPropertyException;
  24 import org.splat.kernel.MissedPropertyException;
  25 import org.splat.kernel.MultiplyDefinedException;
  26
  27 /**
  28  * This class defines all methods for creation, modification the study.
  29  *
  30  * @author Maria KRUCHININA
  31  *
  32  */
  33 public interface StudyService {
  34
  35         /**
  36          * Increment total number of study documents including versions (docount) and update it in the study.
  37          *
  38          * @param aStudy
  39          *            the study
  40          * @return incremented docount value
  41          */
  42         int generateLocalIndex(Study aStudy);
  43
  44         /**
  45          * Get study by its id.
  46          *
  47          * @param index
  48          *            the study id
  49          * @return found study or null
  50          */
  51         Study selectStudy(long index);
  52
  53         /**
  54          * Create a new study.
  55          *
  56          * @param sprop
  57          *            properties of the new study
  58          * @return the created study
  59          * @throws MissedPropertyException
  60          *             if a mandatory property is missed
  61          * @throws InvalidPropertyException
  62          *             if some property doesn't exist
  63          * @throws MultiplyDefinedException
  64          *             if some property is defined several times
  65          */
  66         Study createStudy(Study.Properties sprop)
  67                         throws MissedPropertyException, InvalidPropertyException,
  68                         MultiplyDefinedException;
  69
  70         /**
  71          * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
  72          *
  73          * @param aStudy
  74          *            the study
  75          * @param cprop
  76          *            the simulation context properties
  77          * @return the added simulation context
  78          * @throws MissedPropertyException
  79          *             if a mandatory property is missed
  80          * @throws InvalidPropertyException
  81          *             if some property doesn't exist
  82          * @throws MultiplyDefinedException
  83          *             if some property occurs several times
  84          */
  85         SimulationContext addProjectContext(Study aStudy,
  86                         SimulationContext.Properties cprop) throws MissedPropertyException,
  87                         InvalidPropertyException, MultiplyDefinedException;
  88
  89         /**
  90          * Add a simulation context to the first step of the study. If the context doesn't yet saved it is created in the database.
  91          *
  92          * @param aStudy
  93          *            the study
  94          * @param context
  95          *            the simulation context to add
  96          * @return the added simulation context
  97          */
  98         SimulationContext addProjectContext(Study aStudy,
  99                         SimulationContext context);
 100
 101         /**
 102          * Remove a simulation context from a study.
 103          *
 104          * @param aStudy
 105          *            the study
 106          * @param context
 107          *            the simulation context to remove
 108          * @return true if removing succeeded
 109          */
 110         boolean removeProjectContext(Study aStudy, SimulationContext context);
 111
 112         /**
 113          * Demotes this study from In-Check to In-Draft then In-Work states. This function is called internally when demoting the final result
 114          * document of the study.
 115          *
 116          * @param aStudy
 117          *            the study to demote
 118          * @return true if the demotion succeeded.
 119          */
 120         boolean demote(Study aStudy);
 121
 122         /**
 123          * Promotes this study from In-Work to In-Draft then In-Check and APPROVED states. This function is called internally when promoting the
 124          * final result document of the study.
 125          *
 126          * @param aStudy
 127          *            the study to promote
 128          * @return true if the promotion succeeded.
 129          */
 130         boolean promote(Study aStudy);
 131
 132         /**
 133          * Add a contributor to the study.
 134          *
 135          * @param aStudy
 136          *            the study
 137          * @param user
 138          *            the contributor
 139          * @return true if addition succeeded
 140          */
 141         boolean addContributor(Study aStudy, User user);
 142
 143         /**
 144          * Remove contributors from the study.
 145          *
 146          * @param aStudy
 147          *            the study
 148          * @param users
 149          *            contributor(s)
 150          * @return true if removing succeeded
 151          */
 152         boolean removeContributor(Study aStudy, User... users);
 153
 154         /**
 155          * Set a validation cycle for documents of the given type in the given study.
 156          *
 157          * @param aStudy
 158          *            the target study
 159          * @param type
 160          *            the document type
 161          * @param vprop
 162          *            validation cycle properties
 163          */
 164         void setValidationCycle(Study aStudy, DocumentType type,
 165                         ValidationCycle.Properties vprop);
 166
 167         /**
 168          * Moves this study from the Private to the Public area of the repository.
 169          *
 170          * @param aStudy
 171          *            the study to move
 172          * @return true if the move succeeded.
 173          * @see #isPublic()
 174          */
 175         boolean moveToPublic(Study aStudy);
 176
 177         /**
 178          * Moves this study from the Public to the Private area of the repository.
 179          *
 180          * @param aStudy
 181          *            the study to move
 182          * @return true if the move succeeded.
 183          */
 184         boolean moveToPrivate(Study aStudy);
 185
 186         /**
 187          * Moves this study from the Public to the Reference area of the repository. For being moved to the Reference area, the study must
 188          * previously be approved.
 189          *
 190          * @param aStudy
 191          *            the study to move
 192          * @return true if the move succeeded.
 193          * @see #moveToPublic()
 194          * @see #isPublic()
 195          * @see Publication#approve(Date)
 196          */
 197         boolean moveToReference(Study aStudy);
 198
 199         /**
 200          * Update a study.
 201          *
 202          * @param aStudy
 203          *            the study to update
 204          * @param sprop
 205          *            new properties of the study
 206          * @return true if the study has been updated successfully
 207          * @throws InvalidPropertyException
 208          *             if some property doesn't exist
 209          */
 210         boolean update(Study aStudy, Properties sprop)
 211                         throws InvalidPropertyException;
 212
 213         /**
 214          * Initialize shortcuts of the study as its transient collections.
 215          *
 216          * @param aStudy
 217          *            the study
 218          */
 219         void loadWorkflow(Study aStudy);
 220
 221         /**
 222          * Returns the validation cycle of the given document type.
 223          *
 224          * @param aStudy
 225          *            the study
 226          * @param type
 227          *            the document type being subject of validation
 228          * @return the validation cycle of the document, or null if not defined.
 229          */
 230         ValidationCycle getValidationCycleOf(Study aStudy, DocumentType type);
 231
 232         /**
 233          * Checks if the given user participates to this study. The Study staff includes the author and contributors.
 234          *
 235          * @param aStudy
 236          *            the study
 237          * @param user
 238          *            the user to look for
 239          * @return true if the given user is actor of this study.
 240          * @see #getContributors()
 241          */
 242         boolean isStaffedBy(Study aStudy, User user);
 243
 244         /**
 245          * Checks if the given user is actor of this study. Actors include contributors, reviewers and approvers.
 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 #getActors()
 253          */
 254         boolean hasActor(Study aStudy, User user);
 255
 256         /**
 257          * Returns unmodifiable initialized transient list of contributors of this study.
 258          *
 259          * @param aStudy
 260          *            the study
 261          * @return the unmodifiable not null transient list of contributors of this study
 262          */
 263         List<User> getContributors(Study aStudy);
 264
 265         /**
 266          * Mark study as reference.
 267          *
 268          * @param aStudy - the Study
 269          */
 270         void markStudyAsReference(Study aStudy);
 271
 272         /**
 273          * Remove study as reference.
 274          * This operation is inverse one to Mark as reference.
 275          *
 276          * @param aStudy - the Study
 277          */
 278         void removeStudyAsReference(Study aStudy);
 279
 280         /**
 281          * Get the description attribute related to the study
 282          *              (there supposed to be the only one such attribute in the database).
 283          * @param studyId the study id
 284          * @return the description attribute value (null if does not exist)
 285          * @throws InvalidParameterException if a study with such id does not exist in the database.
 286          */
 287         String getDescription(Long studyId) throws InvalidParameterException;
 288
 289         /**
 290          * Set the description attribute related to the study.
 291          * @param studyId the study id
 292          * @param descriptionText the description text
 293          * @throws InvalidParameterException if some parameters are invalid.
 294          */
 295         void setDescription(Long studyId, String descriptionText) throws InvalidParameterException;
 296
 297         /**
 298          * Remove a description attached to a study.
 299          *
 300          * @param studyId the study id
 301          * @throws InvalidParameterException
 302          *              if no study with such Id has been found in the database.
 303          * @return true if succeeded, false if study doesn't have a description.
 304          */
 305         boolean removeDescription(final Long studyId) throws InvalidParameterException;
 306 }