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