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