Workspace/Siman-Common/src/org/splat/service/StepService.java

   1 /*****************************************************************************
   2  * Company         OPEN CASCADE
   3  * Application     SIMAN
   4  * File            $Id$
   5  * Creation date   06.10.2012
   6  * @author         $Author$
   7  * @version        $Revision$
   8  *****************************************************************************/
   9
  10 package org.splat.service;
  11
  12 import java.io.IOException;
  13 import java.util.List;
  14
  15 import org.splat.dal.bo.som.Document;
  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.exception.DocumentIsUsedException;
  20 import org.splat.exception.InvalidParameterException;
  21 import org.splat.kernel.InvalidPropertyException;
  22 import org.splat.kernel.MismatchException;
  23 import org.splat.kernel.MissedPropertyException;
  24 import org.splat.kernel.MultiplyDefinedException;
  25 import org.splat.kernel.NotApplicableException;
  26 import org.splat.service.dto.StepCommentDTO;
  27 import org.splat.som.Step;
  28
  29 /**
  30  * Step service interface.
  31  *
  32  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  33  */
  34 public interface StepService {
  35
  36         /**
  37          * Create a new document published in the given study step.
  38          *
  39          * @param aStep
  40          *            the target study step
  41          * @param dprop
  42          *            properties of the new document
  43          * @return the created publication of the new document
  44          * @throws MissedPropertyException
  45          *             if a mandatory property is missed
  46          * @throws InvalidPropertyException
  47          *             if some property doesn't exist
  48          * @throws MultiplyDefinedException
  49          *             if some property is defined several times
  50          * @throws IOException
  51          *             if a file system error occurs
  52          */
  53         Publication createDocument(Step aStep, Document.Properties dprop)
  54                         throws MissedPropertyException, InvalidPropertyException,
  55                         MultiplyDefinedException, IOException;
  56
  57         /**
  58          * Publish an existing document in the given study step.
  59          *
  60          * @param aStep
  61          *            the target study step
  62          * @param dprop
  63          *            new properties of the document
  64          * @return the created publication of the document
  65          * @throws MissedPropertyException
  66          *             if a mandatory property is missed
  67          * @throws InvalidPropertyException
  68          *             if some property doesn't exist
  69          * @throws NotApplicableException
  70          *             if the document is undefined
  71          */
  72         Publication assignDocument(Step aStep, Document.Properties dprop)
  73                         throws MissedPropertyException, InvalidPropertyException,
  74                         NotApplicableException;
  75
  76         /**
  77          * Create a new version of a document in the given study step.
  78          *
  79          * @param aStep
  80          *            the study step
  81          * @param base
  82          *            the base document published version
  83          * @param dprop
  84          *            properties of the new version
  85          * @return the new version publication
  86          * @throws MissedPropertyException
  87          *             if a mandatory property is missed
  88          * @throws InvalidPropertyException
  89          *             if some property doesn't exist
  90          * @throws MultiplyDefinedException
  91          *             if some property is defined several times
  92          * @throws IOException
  93          *             if a file system error occurs
  94          * @throws MismatchException
  95          *             if the document is not applicable to the given study step
  96          */
  97         Publication versionDocument(Step aStep, Publication base,
  98                         Document.Properties dprop) throws MissedPropertyException,
  99                         InvalidPropertyException, MultiplyDefinedException, IOException,
 100                         MismatchException;
 101
 102         /**
 103          * Add simulation context to the study step.
 104          *
 105          * @param aStep
 106          *            the study step
 107          * @param dprop
 108          *            properties of the simulation context to add
 109          * @return the added simulation context
 110          * @throws MissedPropertyException
 111          *             if a mandatory property is missed
 112          * @throws InvalidPropertyException
 113          *             if some property doesn't exist
 114          * @throws MultiplyDefinedException
 115          *             if some property is defined several times
 116          */
 117         SimulationContext addSimulationContext(Step aStep,
 118                         SimulationContext.Properties dprop) throws MissedPropertyException,
 119                         InvalidPropertyException, MultiplyDefinedException;
 120
 121         /**
 122          * Add simulation context to the study step.
 123          *
 124          * @param firstStep
 125          *            the study step
 126          * @param context
 127          *            the simulation context to add
 128          * @return the added simulation context
 129          */
 130         SimulationContext addSimulationContext(Step firstStep,
 131                         SimulationContext context);
 132
 133         /**
 134          * Remove a simulation context from the study step.
 135          *
 136          * @param aStep
 137          *            the study step
 138          * @param context
 139          *            the simulation context to remove
 140          * @return true if removal succeeded
 141          */
 142         boolean removeSimulationContext(Step aStep, SimulationContext context);
 143
 144         /**
 145          * Add a document publication to the given step.
 146          *
 147          * @param aStep
 148          *            the target study step
 149          * @param newdoc
 150          *            the document publication to add
 151          * @return true if publication succeeded
 152          */
 153         boolean add(Step aStep, Publication newdoc);
 154
 155         /**
 156          * Remove a document publication from the given step.
 157          *
 158          * @param aStep
 159          *            the study step
 160          * @param oldoc
 161          *            the document publication to remove
 162          * @return true if removing of the publication succeeded
 163          */
 164         boolean remove(Step aStep, Publication oldoc);
 165
 166         /**
 167          * Remove a document from the given step and from the database if it is no more used.
 168          *
 169          * @param aStep
 170          *            the study step
 171          * @param docId
 172          *            the document id
 173          * @return true if removing of the document succeeded
 174          * @throws DocumentIsUsedException
 175          *             if the document is used by other documents
 176          */
 177         boolean removeDocument(Step aStep, long docId)
 178                         throws DocumentIsUsedException;
 179
 180         /**
 181          * Get document types which are applicable for the given study step (activity).
 182          *
 183          * @param aStep
 184          *            the study step
 185          * @return the list of document types
 186          */
 187         List<DocumentType> getValidDocumentTypes(Step aStep);
 188
 189
 190         /**
 191          * Add a comment to study step specified in DTO.
 192          * The 'id' field must be null, new primary key will be placed there if succeeded.
 193          * User is identified by userId, userName is not necessary.
 194          *
 195          * @param comment
 196          *            data to be placed in the comment attribute
 197          * @throws InvalidParameterException
 198          *                        if some parameter is invalid
 199          */
 200         void addStepComment(final StepCommentDTO comment) throws InvalidParameterException;
 201
 202         /**
 203          * Retrieves from the database all the comments related to the given step.
 204          *
 205          * @param step
 206          *            the step
 207          * @return list of StepCommentDTO's with properties 'id', 'text', 'user', 'date' filled in.
 208          *
 209          * @throws InvalidParameterException
 210          *                        if the owner of the step is not found in the database.
 211          */
 212         List<StepCommentDTO> getStepComments(final Step step) throws InvalidParameterException;
 213
 214         /**
 215          * Removes the comment with given id from the database.
 216          *
 217          * @param commentId
 218          *            the comment id
 219          * @throws InvalidParameterException
 220          *                        if the comment is not found in the database.
 221          */
 222          void removeStepComment(final long commentId) throws InvalidParameterException;
 223
 224
 225         /**
 226          * Checks if a given comment was made by a given user.
 227          * @param commentId the comment id
 228          * @param userId the user id
 229          * @return if the comment was made by the user
 230          * @throws InvalidParameterException if the comment with such id does not exist.
 231          */
 232         boolean isCommentMadeByUser(final long commentId, final long userId) throws InvalidParameterException;
 233
 234
 235         /**
 236          * Edit value and title of a comment.
 237          * If value or title is null - no changes will be applied to this field.
 238          * @param commentId the comment id
 239          * @param newValue the new comment value
 240          * @param newTitle the new comment title
 241          * @throws InvalidParameterException if the comment with such id does not exist.
 242          */
 243         void editStepComment(final long commentId, final String newValue, final String newTitle)
 244                         throws InvalidParameterException;
 245 }