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

   1 /*****************************************************************************
   2  * Company         EURIWARE
   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.DocumentType;
  16 import org.splat.dal.bo.som.ProgressState;
  17 import org.splat.dal.bo.som.ProjectElement;
  18 import org.splat.dal.bo.som.Publication;
  19 import org.splat.dal.bo.som.Study;
  20 import org.splat.dal.bo.som.Timestamp;
  21 import org.splat.kernel.NotApplicableException;
  22 import org.splat.som.DocumentRights;
  23 import org.splat.som.Revision;
  24 import org.splat.som.Step;
  25
  26 /**
  27  * Publication service interface.
  28  *
  29  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  30  */
  31 public interface PublicationService {
  32
  33         /**
  34          * Copy the publication to the given project element.
  35          *
  36          * @param aPublication
  37          *            the publication to copy
  38          * @param publisher
  39          *            the target project element
  40          * @return the created copy of the publication
  41          */
  42         public Publication copy(Publication aPublication, ProjectElement publisher);
  43
  44         /**
  45          * Returns the study Step into which the document version referenced by this publication has been published.
  46          *
  47          * @param aPublication
  48          *            the document publication
  49          * @return study step
  50          */
  51         public Step getInvolvedStep(Publication aPublication);
  52
  53         /**
  54          * Promotes the document referenced by this publication from In-Check to Approved state, if not out-dated, and attaches the
  55          * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
  56          * is promoted as well.<br/> <br/> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
  57          * final result document.
  58          *
  59          * @param aPublication
  60          *            the document publication
  61          * @param adate
  62          *            the date of approval
  63          * @return true if the approval succeeded
  64          * @see #getProgressState()
  65          * @see DocumentRights#canApprove()
  66          * @see DocumentType#isStudyResult()
  67          * @see Study#getApproverOf(Publication)
  68          */
  69         public Timestamp approve(Publication aPublication, Date adate);
  70
  71         /**
  72          * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.<br/> The
  73          * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.<br/>
  74          * If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/> Limitation: the
  75          * way this demotion is propagated to the study supposes that the study has only ONE final result document.
  76          *
  77          * @param aPublication
  78          *            the document publication
  79          * @return true if the demotion succeeded
  80          * @see #getProgressState()
  81          * @see DocumentRights#canDemote()
  82          * @see DocumentType#isStudyResult()
  83          */
  84         public boolean demote(Publication aPublication);
  85
  86         /**
  87          * Undo the review operation by demoting the document referenced by this publication from In-Check to In-Draft state and removing the
  88          * Reviewer.<br/> If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/>
  89          * Limitation: the way this demotion is propagated to the study supposes that the study has only ONE final result document.
  90          *
  91          * @param aPublication
  92          *            the document publication
  93          * @return true if the demotion succeeded
  94          * @see #getProgressState()
  95          * @see #review()
  96          * @see DocumentRights#canInvalidate()
  97          * @see DocumentType#isStudyResult()
  98          */
  99         public boolean invalidate(Publication aPublication);
 100
 101         /**
 102          * Promotes the document referenced by this publication from In-Work to In-Draft or In-Check state, if not out-dated, and attaches the
 103          * corresponding time-stamp to the document.<br/> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
 104          * of the document does not include the review step.<br/> Also, if the promoted document is the final result of the owner study, the
 105          * study is itself promoted as well.<br/> This operation can be undo-ed by demote().<br/> <br/> Limitation: the way this promotion is
 106          * propagated to the study supposes that the study has only ONE final result document.
 107          *
 108          * @param aPublication
 109          *            the document publication
 110          * @param pdate
 111          *            the date of promotion
 112          * @return true if the promotion succeeded
 113          * @see #getProgressState()
 114          * @see #demote()
 115          * @see DocumentRights#canPromote()
 116          * @see DocumentType#isStudyResult()
 117          */
 118         public Timestamp promote(Publication aPublication, Date pdate);
 119
 120         /**
 121          * Promotes the document referenced by this publication from In-Draft to In-Check state, if not out-dated, and attaches the
 122          * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
 123          * is promoted as well.<br/> This operation can be undo-ed by invalidate().<br/> <br/> Limitation: the way this promotion is
 124          * propagated to the study supposes that the study has only ONE final result document.
 125          *
 126          * @param aPublication
 127          *            the document publication
 128          * @param rdate
 129          *            the date of review
 130          * @return true if the review succeeded
 131          * @see #getProgressState()
 132          * @see #invalidate()
 133          * @see DocumentRights#canReview()
 134          * @see DocumentType#isStudyResult()
 135          * @see Study#getReviewerOf(Publication)
 136          */
 137         public Timestamp review(Publication aPublication, Date rdate);
 138
 139         /**
 140          * Publishes the document referenced by this publication into the owner Project Element under the given state, the revision number of
 141          * the document being automatically set accordingly. If the given state is In-Draft and the document is final result of the owner study,
 142          * this automatically promotes the study to In-Draft.
 143          *
 144          * @param aPublication
 145          *            the document publication
 146          * @param state
 147          *            the required progress state
 148          * @throws FileNotFoundException
 149          *             If the referenced document is empty
 150          * @throws NotApplicableException
 151          *             If the referenced document is undefined
 152          */
 153         public void saveAs(Publication aPublication, ProgressState state)
 154                         throws FileNotFoundException, NotApplicableException;
 155
 156         /**
 157          * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/> The state
 158          * of the referenced document is supposed being automatically set according to the given revision number, but, due to the versioning
 159          * scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is currently used
 160          * only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/> Note: in the context of branch
 161          * versioning, the given revision may be modified by an update of the branch name.
 162          *
 163          * @param aPublication
 164          *            the document publication
 165          * @param newvers
 166          *            the required revision number
 167          * @throws FileNotFoundException
 168          *             If the referenced document is empty
 169          * @throws NotApplicableException
 170          *             If the referenced document is undefined
 171          * @deprecated
 172          */
 173         public void saveAs(Publication aPublication, Revision newvers)
 174                         throws FileNotFoundException, NotApplicableException;
 175 }