1 /*****************************************************************************
5 * Creation date 06.10.2012
8 *****************************************************************************/
10 package org.splat.service;
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;
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;
42 * Publication service interface.
44 * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
46 public interface PublicationService {
49 * Copy the publication to the given project element.
52 * the publication to copy
54 * the target project element
55 * @return the created copy of the publication
57 Publication copy(Publication aPublication, ProjectElement publisher);
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;
68 * Create a new version of the document.
71 * the study step where the document is published
75 * the new version file name
79 * new document version string, empty for external documents
83 * the new state of the document
85 * the new modification date
87 * the array of documents ids used by the versioned document
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
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
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;
112 * Returns the study Step into which the document version referenced by this publication has been published.
114 * @param aPublication
115 * the document publication
118 Step getInvolvedStep(Publication aPublication);
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.
126 * @param aPublication
127 * the document publication
129 * the date of approval
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)
142 Timestamp approve(Publication aPublication, Date adate, User user)
143 throws UserRightsException, InvalidParameterException;
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.
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()
158 boolean demote(Publication aPublication);
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.
165 * @param aPublication
166 * the document publication
167 * @return true if the demotion succeeded
168 * @see #getProgressState()
170 * @see DocumentRights#canInvalidate()
171 * @see DocumentType#isStudyResult()
173 boolean invalidate(Publication aPublication);
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.
182 * @param aPublication
183 * the document publication
185 * the date of promotion
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()
193 * @see DocumentRights#canPromote()
194 * @see DocumentType#isStudyResult()
196 Timestamp promote(Publication aPublication, Date pdate, User user) throws UserRightsException;
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.
204 * @param aPublication
205 * the document publication
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()
217 * @see DocumentRights#canReview()
218 * @see DocumentType#isStudyResult()
219 * @see Study#getReviewerOf(Publication)
221 Timestamp review(Publication aPublication, Date rdate, User user)
222 throws UserRightsException, InvalidParameterException;
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.
229 * @param aPublication
230 * the document publication
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
238 void saveAs(Publication aPublication, ProgressState state)
239 throws FileNotFoundException, NotApplicableException;
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.
248 * @param aPublication
249 * the document publication
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
259 void saveAs(Publication aPublication, Revision newvers)
260 throws FileNotFoundException, NotApplicableException;
263 * Rename the published document.
265 * @param aPublication
266 * the publication of the document
268 * the new document title
269 * @throws InvalidPropertyException
270 * if the new title is empty
272 void rename(Publication aPublication, String title)
273 throws InvalidPropertyException;
276 * Replace the document source file. The document status must be inWORK or <BR>
277 * EXTERN to be able to replace the source file.
280 * document publication
285 * @return true if succeeded otherwise return false
286 * @throws IncompatibleDataException
287 * if the document status is not valid for replacing
289 boolean replace(final Publication pub, final File newFile,
290 final Date modifTime) throws IncompatibleDataException;
293 * Create "Converts" relation for the given document publication and format.
295 * @param aPublication
296 * the document publication
299 * @return the created "Converts" relation
301 ConvertsRelation attach(Publication aPublication, String format);
304 * Create "Converts" relation for the given document publication, format and description.
306 * @param aPublication
307 * the document publication
311 * the description of the relation
312 * @return the created "Converts" relation
314 ConvertsRelation attach(Publication aPublication, String format,
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
325 Document getLastVersion(final Document doc, final ProjectElement owner);
328 * Undo the out-date operation.
330 * @param aPublication
332 * @return true if the acceptance succeeds
334 * @see DocumentRights#canAccept()
336 boolean actualize(Publication aPublication);
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.
342 * @param aPublication
345 * @see #getProgressState()
348 void outdate(Publication aPublication);
351 * Get DocToCompareDTO by publication id.
353 * @param publicationId
355 * @return DocToCompareDTO
356 * @throws InvalidParameterException
357 * if there is no document with such id.
359 DocToCompareDTO getDocToCompareDTO(long publicationId)
360 throws InvalidParameterException;
363 * Check if this publication is outdated and other publications used by it are up-to-date.
365 * @param aPublication
367 * @return true if succeeded
369 boolean canBeActualized(Publication aPublication);