Workspace/Siman-Common/src/org/splat/service/PublicationService.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.FileNotFoundException;
  13 import java.io.IOException;
  14 import java.util.Date;
  15
  16 import org.splat.dal.bo.kernel.User;
  17 import org.splat.dal.bo.som.ConvertsRelation;
  18 import org.splat.dal.bo.som.DocumentType;
  19 import org.splat.dal.bo.som.ProgressState;
  20 import org.splat.dal.bo.som.ProjectElement;
  21 import org.splat.dal.bo.som.Publication;
  22 import org.splat.dal.bo.som.Study;
  23 import org.splat.dal.bo.som.Timestamp;
  24 import org.splat.kernel.InvalidPropertyException;
  25 import org.splat.kernel.MismatchException;
  26 import org.splat.kernel.MissedPropertyException;
  27 import org.splat.kernel.MultiplyDefinedException;
  28 import org.splat.kernel.NotApplicableException;
  29 import org.splat.som.DocumentRights;
  30 import org.splat.som.Revision;
  31 import org.splat.som.Step;
  32
  33 /**
  34  * Publication service interface.
  35  *
  36  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  37  */
  38 public interface PublicationService {
  39
  40         /**
  41          * Copy the publication to the given project element.
  42          *
  43          * @param aPublication
  44          *            the publication to copy
  45          * @param publisher
  46          *            the target project element
  47          * @return the created copy of the publication
  48          */
  49         Publication copy(Publication aPublication, ProjectElement publisher);
  50
  51         /**
  52          * Create a new version of the document.
  53          *
  54          * @param step
  55          *            the study step where the document is published
  56          * @param user
  57          *            the current user
  58          * @param filename
  59          *            the new version file name
  60          * @param docIndex
  61          *            the publication id
  62          * @param docver
  63          *            new document version string, empty for external documents
  64          * @param summary
  65          *            the version comment
  66          * @param state
  67          *            the new state of the document
  68          * @param date
  69          *            the new modification date
  70          * @param docuses
  71          *            the array of documents ids used by the versioned document
  72          * @param docusedby
  73          *            the array of impacted documents ids
  74          * @throws MissedPropertyException
  75          *             if some mandatory property is missed
  76          * @throws InvalidPropertyException
  77          *             if some property has invalid value
  78          * @throws MultiplyDefinedException
  79          *             if some property occurs several times
  80          * @throws IOException
  81          *             if file moving is failed
  82          * @throws MismatchException
  83          *             if step number in properties doesn't match to the given step
  84          * @throws NotApplicableException
  85          *             if publication's document is undefined
  86          * @throws InterruptedException
  87          *             by Thread.sleep if interrupted
  88          */
  89         void versionDocument(Step step, User user, String filename, long docIndex,
  90                         String docver, String summary, ProgressState state, Date date,
  91                         String[] docuses, long[] docusedby) throws MissedPropertyException,
  92                         InvalidPropertyException, MultiplyDefinedException, IOException,
  93                         MismatchException, NotApplicableException, InterruptedException;
  94
  95         /**
  96          * Returns the study Step into which the document version referenced by this publication has been published.
  97          *
  98          * @param aPublication
  99          *            the document publication
 100          * @return study step
 101          */
 102         Step getInvolvedStep(Publication aPublication);
 103
 104         /**
 105          * Promotes the document referenced by this publication from In-Check to Approved state, if not out-dated, and attaches the
 106          * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
 107          * is promoted as well.<br/> <br/> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
 108          * final result document.
 109          *
 110          * @param aPublication
 111          *            the document publication
 112          * @param adate
 113          *            the date of approval
 114          * @return true if the approval succeeded
 115          * @see #getProgressState()
 116          * @see DocumentRights#canApprove()
 117          * @see DocumentType#isStudyResult()
 118          * @see Study#getApproverOf(Publication)
 119          */
 120         Timestamp approve(Publication aPublication, Date adate);
 121
 122         /**
 123          * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.<br/> The
 124          * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.<br/>
 125          * If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/> Limitation: the
 126          * way this demotion is propagated to the study supposes that the study has only ONE final result document.
 127          *
 128          * @param aPublication
 129          *            the document publication
 130          * @return true if the demotion succeeded
 131          * @see #getProgressState()
 132          * @see DocumentRights#canDemote()
 133          * @see DocumentType#isStudyResult()
 134          */
 135         boolean demote(Publication aPublication);
 136
 137         /**
 138          * Undo the review operation by demoting the document referenced by this publication from In-Check to In-Draft state and removing the
 139          * Reviewer.<br/> If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/>
 140          * Limitation: the way this demotion is propagated to the study supposes that the study has only ONE final result document.
 141          *
 142          * @param aPublication
 143          *            the document publication
 144          * @return true if the demotion succeeded
 145          * @see #getProgressState()
 146          * @see #review()
 147          * @see DocumentRights#canInvalidate()
 148          * @see DocumentType#isStudyResult()
 149          */
 150         boolean invalidate(Publication aPublication);
 151
 152         /**
 153          * Promotes the document referenced by this publication from In-Work to In-Draft or In-Check state, if not out-dated, and attaches the
 154          * corresponding time-stamp to the document.<br/> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
 155          * of the document does not include the review step.<br/> Also, if the promoted document is the final result of the owner study, the
 156          * study is itself promoted as well.<br/> This operation can be undo-ed by demote().<br/> <br/> Limitation: the way this promotion is
 157          * propagated to the study supposes that the study has only ONE final result document.
 158          *
 159          * @param aPublication
 160          *            the document publication
 161          * @param pdate
 162          *            the date of promotion
 163          * @return true if the promotion succeeded
 164          * @see #getProgressState()
 165          * @see #demote()
 166          * @see DocumentRights#canPromote()
 167          * @see DocumentType#isStudyResult()
 168          */
 169         Timestamp promote(Publication aPublication, Date pdate);
 170
 171         /**
 172          * Promotes the document referenced by this publication from In-Draft to In-Check state, if not out-dated, and attaches the
 173          * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
 174          * is promoted as well.<br/> This operation can be undo-ed by invalidate().<br/> <br/> Limitation: the way this promotion is
 175          * propagated to the study supposes that the study has only ONE final result document.
 176          *
 177          * @param aPublication
 178          *            the document publication
 179          * @param rdate
 180          *            the date of review
 181          * @return true if the review succeeded
 182          * @see #getProgressState()
 183          * @see #invalidate()
 184          * @see DocumentRights#canReview()
 185          * @see DocumentType#isStudyResult()
 186          * @see Study#getReviewerOf(Publication)
 187          */
 188         Timestamp review(Publication aPublication, Date rdate);
 189
 190         /**
 191          * Publishes the document referenced by this publication into the owner Project Element under the given state, the revision number of
 192          * the document being automatically set accordingly. If the given state is In-Draft and the document is final result of the owner study,
 193          * this automatically promotes the study to In-Draft. The old publication is removed from the scenario.
 194          *
 195          * @param aPublication
 196          *            the document publication
 197          * @param state
 198          *            the required progress state
 199          * @throws FileNotFoundException
 200          *             If the referenced document is empty
 201          * @throws NotApplicableException
 202          *             If the referenced document is undefined
 203          */
 204         void saveAs(Publication aPublication, ProgressState state)
 205                         throws FileNotFoundException, NotApplicableException;
 206
 207         /**
 208          * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/> The state
 209          * of the referenced document is supposed being automatically set according to the given revision number, but, due to the versioning
 210          * scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is currently used
 211          * only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/> Note: in the context of branch
 212          * versioning, the given revision may be modified by an update of the branch name. The old publication is removed from the scenario.
 213          *
 214          * @param aPublication
 215          *            the document publication
 216          * @param newvers
 217          *            the required revision number
 218          * @throws FileNotFoundException
 219          *             If the referenced document is empty
 220          * @throws NotApplicableException
 221          *             If the referenced document is undefined
 222          * @deprecated
 223          */
 224         @Deprecated
 225         void saveAs(Publication aPublication, Revision newvers)
 226                         throws FileNotFoundException, NotApplicableException;
 227
 228         /**
 229          * Rename the published document.
 230          *
 231          * @param aPublication
 232          *            the publication of the document
 233          * @param title
 234          *            the new document title
 235          * @throws InvalidPropertyException
 236          *             if the new title is empty
 237          */
 238         void rename(Publication aPublication, String title)
 239                         throws InvalidPropertyException;
 240
 241         /**
 242          * Create "Converts" relation for the given document publication and format.
 243          *
 244          * @param aPublication
 245          *            the document publication
 246          * @param format
 247          *            the format
 248          * @return the created "Converts" relation
 249          */
 250         ConvertsRelation attach(Publication aPublication, String format);
 251
 252         /**
 253          * Create "Converts" relation for the given document publication, format and description.
 254          *
 255          * @param aPublication
 256          *            the document publication
 257          * @param format
 258          *            the format
 259          * @param description
 260          *            the description of the relation
 261          * @return the created "Converts" relation
 262          */
 263         ConvertsRelation attach(Publication aPublication, String format,
 264                         String description);
 265
 266         /**
 267          * Undo the out-date operation.
 268          *
 269          * @param aPublication
 270          *            the publication
 271          * @return true if the acceptance succeeds
 272          * @see #outdate()
 273          * @see DocumentRights#canAccept()
 274          */
 275         boolean actualize(Publication aPublication);
 276
 277         /**
 278          * Out-dates this publication and recursively all publications using this one. Typically, a publication is out-dated when modifying a
 279          * document to which it depends.
 280          *
 281          * @param aPublication
 282          *            the publication
 283          * @see #isOutdated()
 284          * @see #getProgressState()
 285          * @see #actualize()
 286          */
 287         void outdate(Publication aPublication);
 288 }