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