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