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