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