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