Workspace/Siman-Common/src/org/splat/service/DocumentService.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.util.List;
  13
  14 import org.splat.dal.bo.som.ConvertsRelation;
  15 import org.splat.dal.bo.som.Document;
  16 import org.splat.dal.bo.som.DocumentType;
  17 import org.splat.dal.bo.som.ProgressState;
  18 import org.splat.dal.bo.som.ProjectElement;
  19 import org.splat.dal.bo.som.Study;
  20 import org.splat.dal.bo.som.Timestamp;
  21 import org.splat.dal.bo.som.Document.Properties;
  22 import org.splat.kernel.InvalidPropertyException;
  23 import org.splat.kernel.MissedPropertyException;
  24 import org.splat.kernel.MultiplyDefinedException;
  25 import org.splat.kernel.NotApplicableException;
  26 import org.splat.service.technical.ProjectSettingsService;
  27 import org.splat.som.Revision;
  28 import org.splat.som.Step;
  29 import org.springframework.transaction.annotation.Transactional;
  30
  31 /**
  32  * Document service interface.
  33  *
  34  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  35  *
  36  */
  37 public interface DocumentService {
  38
  39         /**
  40          * Get document by its path.
  41          *
  42          * @param path
  43          *            the document path
  44          * @return the document if found or null
  45          */
  46         public Document getDocumentByPath(String path);
  47
  48         /**
  49          * Defines this document.
  50          *
  51          * @param aDoc
  52          *            the document to define
  53          * @param dprop
  54          *            the properties of the document
  55          * @throws MissedPropertyException
  56          *             if a mandatory property is missed
  57          * @throws InvalidPropertyException
  58          *             if a property doesn't exist
  59          * @throws NotApplicableException
  60          *             if the document is undefined
  61          * @see Step#createDocument(Properties)
  62          * @see #isUndefined()
  63          */
  64         public void initialize(Document aDoc, Properties dprop)
  65                         throws MissedPropertyException, InvalidPropertyException,
  66                         NotApplicableException;
  67
  68         /**
  69          * Find a document by its id.
  70          *
  71          * @param index
  72          *            document id
  73          * @return found document
  74          */
  75         public Document selectDocument(long index);
  76
  77         /**
  78          * Find a document by its reference and version.
  79          *
  80          * @param refid
  81          *            document reference
  82          * @param version
  83          *            document version
  84          * @return found document
  85          */
  86         public Document selectDocument(String refid, String version);
  87
  88         /**
  89          * Generate document reference.
  90          *
  91          * @param aDoc
  92          *            the document
  93          * @param dprop
  94          *            document properties (owner project element is used)
  95          */
  96         public void generateDocumentId(Document aDoc, Properties dprop);
  97
  98         /**
  99          * Get a directory where the document file is saved.
 100          *
 101          * @param aDoc
 102          *            the document
 103          * @return a directory
 104          */
 105         public java.io.File getSaveDirectory(Document aDoc);
 106
 107         /**
 108          * Extract title and reference properties from the given file.
 109          *
 110          * @param file
 111          *            the file to parse
 112          * @return the extracted properties
 113          */
 114         public Properties extractProperties(java.io.File file);
 115
 116         /**
 117          * Create "Converts" relation for the given document and the given format.
 118          *
 119          * @param aDoc
 120          *            the document
 121          * @param format
 122          *            the format
 123          * @return the created "Converts" relation
 124          */
 125         public ConvertsRelation attach(Document aDoc, String format);
 126
 127         /**
 128          * Create "Converts" relation for the given document, format and description.
 129          *
 130          * @param aDoc
 131          *            the document
 132          * @param format
 133          *            the format
 134          * @param description
 135          *            the description of the relation
 136          * @return the created "Converts" relation
 137          */
 138         public ConvertsRelation attach(Document aDoc, String format,
 139                         String description);
 140
 141         /**
 142          * Build a reference (document id) for the given document in the given study basing on the given original document.
 143          *
 144          * @param aDoc
 145          *            the document to set set the new reference to
 146          * @param scope
 147          *            the study
 148          * @param lineage
 149          *            the original document
 150          * @return true if the new reference is set
 151          */
 152         public boolean buildReferenceFrom(Document aDoc, ProjectElement scope,
 153                         Document lineage);
 154
 155         /**
 156          * Build a reference (document id) for the given document in the given study.
 157          *
 158          * @param aDoc
 159          *            the document to set set the new reference to
 160          * @param scope
 161          *            the study
 162          * @return true if the new reference is set
 163          */
 164         public boolean buildReferenceFrom(Document aDoc, Study scope);
 165
 166         /**
 167          * Demote a document.
 168          *
 169          * @param aDoc
 170          *            the document to demote
 171          * @return true if demoting succeeded
 172          */
 173         public boolean demote(Document aDoc);
 174
 175         /**
 176          * Promote a document.
 177          *
 178          * @param aDoc
 179          *            the document to promote
 180          * @param stamp
 181          *            the timestamp of the promotion
 182          * @return true if promotion succeeded
 183          */
 184         public boolean promote(Document aDoc, Timestamp stamp);
 185
 186         /**
 187          * Increments the reference count of this document following its publication in a Study step.
 188          *
 189          * @param aDoc
 190          *            the document to hold
 191          * @see #release()
 192          */
 193         public void hold(Document aDoc);
 194
 195         /**
 196          * Decrements the reference count of this document following the removal of a Publication from a Study step.
 197          *
 198          * @param aDoc
 199          *            the document to release
 200          * @see #hold()
 201          */
 202         public void release(Document aDoc);
 203
 204         /**
 205          * Rename a document.
 206          *
 207          * @param aDoc
 208          *            the document to rename
 209          * @param title
 210          *            the new document title
 211          * @throws InvalidPropertyException
 212          *             if the new title is empty
 213          */
 214         public void rename(Document aDoc, String title)
 215                         throws InvalidPropertyException;
 216
 217         /**
 218          * Update a version of the given document.
 219          *
 220          * @param aDoc
 221          *            the document
 222          * @param newvers
 223          *            the new version
 224          */
 225         public void updateAs(Document aDoc, Revision newvers);
 226
 227         /**
 228          * Update a state of the given document.
 229          *
 230          * @param aDoc
 231          *            the document
 232          * @param state
 233          *            the new state
 234          */
 235         public void updateAs(Document aDoc, ProgressState state);
 236
 237         /**
 238          * Checks if documents of this type are result of a study. A document is the result of a study when it is the result of the last step of
 239          * the study.
 240          *
 241          * @param aType
 242          *            the document type
 243          * @return true if documents of this type are result of a study.
 244          * @see #isStepResult()
 245          * @see #isResultOf(org.splat.service.technical.ProjectSettingsServiceImpl.Step)
 246          */
 247         public boolean isStudyResult(DocumentType aType);
 248 }