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