Workspace/Siman-Common/src/org/splat/service/ScenarioService.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.kernel.User;
  16 import org.splat.dal.bo.som.KnowledgeElement;
  17 import org.splat.dal.bo.som.Scenario;
  18 import org.splat.dal.bo.som.SimulationContext;
  19 import org.splat.dal.bo.som.Study;
  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.ScenarioDTO;
  27 import org.splat.service.dto.StepDTO;
  28 import org.splat.som.Step;
  29
  30 /**
  31  * Scenario service interface.
  32  *
  33  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  34  */
  35 public interface ScenarioService {
  36
  37         /**
  38          * Get a list of scenarios of a study with the given id.
  39          *
  40          * @param studyId
  41          *            the study id
  42          * @return list of scenario DTOs
  43          */
  44         List<ScenarioDTO> getStudyScenarios(final Long studyId);
  45
  46         /**
  47      * Get a new id to document arriver after check-out.
  48      * Return two several values: -1 or ID of the existing document.
  49      *
  50      * @param scenId
  51      *            the scenario id
  52      * @param activityNumber
  53      *            the number of activity
  54      * @param docId
  55      *            the document id
  56      * @param fileExt
  57      *            the file extension
  58      * @return new document id or -1 if same document do nor exist.
  59      *
  60      * @throws InvalidPropertyException if activityNumber is incorrect.
  61      */
  62
  63      long getNewDocumentId(final long scenId,
  64             final int activityNumber, final Long docId,
  65             final String fileExt) throws InvalidPropertyException;
  66
  67         /**
  68          * Copy content of a source study into the given study up to the given step.
  69          *
  70          * @param fromStudyId
  71          *            the source study id
  72          * @param fromScenId
  73          *            the source scenario id
  74          * @param finalStepNum
  75          *            the final source step number
  76          * @param toStudyId
  77          *            the target study
  78          * @throws InvalidParameterException
  79          *             if study, scenario or step is not found
  80          * @throws MissedPropertyException
  81          *             if document creation is failed
  82          * @throws InvalidPropertyException
  83          *             if document creation is failed
  84          * @throws MultiplyDefinedException
  85          *             if document creation is failed
  86          * @throws IOException
  87          *             if document file creation is failed
  88          * @throws NotApplicableException
  89          *             if document state is not applicable
  90          */
  91         void copyStudyContent(final long fromStudyId, final long fromScenId,
  92                         final int finalStepNum, final long toStudyId)
  93                         throws InvalidParameterException, MissedPropertyException,
  94                         InvalidPropertyException, MultiplyDefinedException,
  95                         NotApplicableException, IOException;
  96
  97         /**
  98          * Get lists of scenario steps, documents and files for building siman-salome.conf file.
  99          *
 100          * @param scenarioId
 101          *            scenario id
 102          * @return list of step DTOs
 103          */
 104         List<StepDTO> getScenarioInfo(long scenarioId);
 105
 106         /**
 107          * Assign context to the study.
 108          *
 109          * @param studyId
 110          *            study id
 111          * @param ctxType
 112          *            context type name
 113          * @param ctxValue
 114          *            context value
 115          * @throws InvalidPropertyException
 116          *             if an invalid value is passed to a property
 117          * @throws MissedPropertyException
 118          *             if a mandatory property is missed
 119          * @throws MultiplyDefinedException
 120          *             if some property is defined several times
 121          */
 122         void assignStudyContext(final Long studyId, final String ctxType,
 123                         final String ctxValue) throws MissedPropertyException,
 124                         InvalidPropertyException, MultiplyDefinedException;
 125
 126         /**
 127          * Create a new study.
 128          *
 129          * @param username
 130          *            user login
 131          * @param title
 132          *            study title
 133          * @param productName
 134          *            study product simulation context value
 135          * @param description
 136          *            study summary
 137          * @return the created study id
 138          * @throws InvalidPropertyException
 139          *             if an invalid value is passed to a property
 140          * @throws MissedPropertyException
 141          *             if a mandatory property is missed
 142          * @throws MultiplyDefinedException
 143          *             if some property is defined several times
 144          */
 145         long createStudy(final String username, final String title,
 146                         final String productName, final String description)
 147                         throws InvalidPropertyException,
 148                         MissedPropertyException,
 149                         MultiplyDefinedException;
 150
 151         /**
 152          * Create a new study with one scenario and "product"
 153          * simulation context.
 154          *
 155          * @param sprop
 156          *            the study properties
 157          * @param oprop
 158          *            the scenario properties
 159          * @param cprop
 160          *            the "product" simulation context properties
 161          * @return the created study
 162          * @throws MissedPropertyException
 163          *             if a mandatory property is missed
 164          * @throws InvalidPropertyException
 165          *             if a property is invalid
 166          * @throws MultiplyDefinedException
 167          *             if some property occurs several times
 168          */
 169         Study createStudy(Study.Properties sprop, Scenario.Properties oprop,
 170                         SimulationContext.Properties cprop) throws MissedPropertyException,
 171                         InvalidPropertyException, MultiplyDefinedException;
 172
 173         /**
 174          * Add a new scenario to the study.
 175          *
 176          * @param aStudy
 177          *            the study
 178          * @param sprop
 179          *            scenario properties
 180          * @return the added scenario
 181          * @throws MissedPropertyException
 182          *             if a mandatory property is missed
 183          * @throws InvalidPropertyException
 184          *             if an invalid value is passed to a property
 185          * @throws MultiplyDefinedException
 186          *             if some property occurs several times
 187          */
 188         Scenario addScenario(Study aStudy, Scenario.Properties sprop)
 189                         throws MissedPropertyException, InvalidPropertyException,
 190                         MultiplyDefinedException;
 191
 192         /**
 193          * Add a new knowledge element to the scenario.
 194          *
 195          * @param aScenario
 196          *            the scenario
 197          * @param kprop
 198          *            knowledge element properties
 199          * @return the created knowledge element
 200          * @throws MissedPropertyException
 201          *             if a mandatory property is missed
 202          * @throws InvalidPropertyException
 203          *             if an invalid value is passed to a property
 204          * @throws MultiplyDefinedException
 205          *             if some property is defined several times
 206          */
 207         KnowledgeElement addKnowledgeElement(Scenario aScenario,
 208                         KnowledgeElement.Properties kprop) throws MissedPropertyException,
 209                         InvalidPropertyException, MultiplyDefinedException;
 210
 211         /**
 212          * Check-in the scenario after SALOME session. If a document to be checked in already exists then create a new version of it. Otherwise
 213          * create a new document of the appropriate step result type.
 214          * <ul>
 215          * <li>For each new created document version we copy Uses relations from the previous document version. If used document has been also
 216          * versioned during this check-in operation then refer to its new version.</li>
 217          * <li>For each new document create uses relation to the last versions of results of a previous step.</li>
 218          * </ul>
 219          * <b>NOTE:</b> Only the first attached file is processed for each document. <br/>All new documents/versions are created in inWORK
 220          * state.
 221          *
 222          * @param scenId
 223          *            the scenario id
 224          * @param userId
 225          *            the id of the user who modified documents
 226          * @param scInfo
 227          *            the list of scenario steps DTO
 228          * @throws InvalidPropertyException
 229          *             if the scenario hasn't some of given steps or documents
 230          * @throws IOException
 231          *             if a file can't be moved into the vault
 232          * @throws MismatchException
 233          *             if version creation in some of steps is failed
 234          * @throws MissedPropertyException
 235          *             if some mandatory property is missed when new document or new document version is created
 236          * @throws MultiplyDefinedException
 237          *             if some property is defined several times when new document or new document version is created
 238          * @throws NotApplicableException
 239          *             if failed saving of a new publication with a given state
 240          */
 241         void checkin(final long scenId, final long userId,
 242                         final List<StepDTO> scInfo) throws InvalidPropertyException,
 243                         MissedPropertyException, MultiplyDefinedException,
 244                         MismatchException, IOException, NotApplicableException;
 245
 246         /**
 247          * Check in the scenario.
 248          *
 249          * @param scenarioId
 250          *            the id of the scenario to check in
 251          * @throws InvalidPropertyException
 252          *             if the scenario is not found in the database
 253          */
 254         void checkin(final long scenarioId) throws InvalidPropertyException;
 255
 256         /**
 257          * Check out the scenario.
 258          *
 259          * @param aScenario
 260          *            the scenario to check out
 261          * @param user
 262          *            the current user
 263          * @return true if check out operation succeeded
 264          */
 265         boolean checkout(Scenario aScenario, User user);
 266
 267         /**
 268          * Mark the given scenario as checked out by the given user.
 269          *
 270          * @param scenarioId
 271          *            the scenario id
 272          * @param userId
 273          *            the id of the user performing the check out
 274          * @throws InvalidPropertyException
 275          *             if the user or the scenario is not found in the database
 276          * @throws NotApplicableException
 277          *             if the given user can not check out the scenario
 278          */
 279         void checkout(final long scenarioId, final long userId)
 280                         throws InvalidPropertyException, NotApplicableException;
 281
 282         /**
 283          * Copy contents from other scenario up to its given step into the given scenario.
 284          *
 285          * @param scenario
 286          *            the target scenario
 287          * @param lastep
 288          *            the last processed step of the source scenario
 289          */
 290         void copyContentsUpTo(Scenario scenario, Step lastep);
 291
 292         /**
 293          * Check if the scenario is empty, i.d. no one of its steps doesn't contain any knowledge elements or documents.
 294          *
 295          * @param scenario
 296          *            the scenario to check
 297          * @return true if the scenario is empty
 298          */
 299         boolean isEmpty(Scenario scenario);
 300
 301         /**
 302          * Remove a knowledge element from a scenario.
 303          *
 304          * @param scenario
 305          *            the scenario
 306          * @param kelm
 307          *            the knowledge element to remove
 308          * @return true if removal succeeded
 309          */
 310         boolean removeKnowledgeElement(Scenario scenario, KnowledgeElement kelm);
 311
 312         /**
 313          * Rename the scenario.
 314          *
 315          * @param scenario -
 316          *            the scenario with a new title.
 317          */
 318         void renameScenario(final Scenario scenario);
 319
 320         /**
 321          * Remove the scenario.
 322          *
 323          * @param scenarioId -
 324          *            the id of the scenario to remove.
 325          */
 326         void removeScenario(final long scenarioId);
 327 }