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