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