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