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