1 /*****************************************************************************
5 * Creation date 06.10.2012
8 *****************************************************************************/
10 package org.splat.service;
12 import java.io.FileNotFoundException;
13 import java.io.IOException;
14 import java.util.Date;
16 import org.splat.dal.bo.kernel.User;
17 import org.splat.dal.bo.som.ConvertsRelation;
18 import org.splat.dal.bo.som.DocumentType;
19 import org.splat.dal.bo.som.ProgressState;
20 import org.splat.dal.bo.som.ProjectElement;
21 import org.splat.dal.bo.som.Publication;
22 import org.splat.dal.bo.som.Study;
23 import org.splat.dal.bo.som.Timestamp;
24 import org.splat.kernel.InvalidPropertyException;
25 import org.splat.kernel.MismatchException;
26 import org.splat.kernel.MissedPropertyException;
27 import org.splat.kernel.MultiplyDefinedException;
28 import org.splat.kernel.NotApplicableException;
29 import org.splat.som.DocumentRights;
30 import org.splat.som.Revision;
31 import org.splat.som.Step;
34 * Publication service interface.
36 * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
38 public interface PublicationService {
41 * Copy the publication to the given project element.
44 * the publication to copy
46 * the target project element
47 * @return the created copy of the publication
49 Publication copy(Publication aPublication, ProjectElement publisher);
52 * Create a new version of the document.
53 * @param step the study step where the document is published
54 * @param user the current user
55 * @param filename the new version file name
56 * @param docIndex the publication id
57 * @param docver new document version string, empty for external documents
58 * @param summary the version comment
59 * @param state the new state of the document
60 * @param date the new modification date
61 * @param docuses the array of documents ids used by the versioned document
62 * @param docusedby the array of impacted documents ids
63 * @throws MissedPropertyException if some mandatory property is missed
64 * @throws InvalidPropertyException if some property has invalid value
65 * @throws MultiplyDefinedException if some property occurs several times
66 * @throws IOException if file moving is failed
67 * @throws MismatchException if step number in properties doesn't match to the given step
68 * @throws NotApplicableException if publication's document is undefined
69 * @throws InterruptedException by Thread.sleep if interrupted
71 void versionDocument(Step step, User user, String filename,
72 long docIndex, String docver, String summary, ProgressState state,
73 Date date, String[] docuses, long[] docusedby)
74 throws MissedPropertyException, InvalidPropertyException,
75 MultiplyDefinedException, IOException, MismatchException,
76 NotApplicableException, InterruptedException;
79 * Returns the study Step into which the document version referenced by this publication has been published.
82 * the document publication
85 Step getInvolvedStep(Publication aPublication);
88 * Promotes the document referenced by this publication from In-Check to Approved state, if not out-dated, and attaches the
89 * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
90 * is promoted as well.<br/> <br/> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
91 * final result document.
94 * the document publication
96 * the date of approval
97 * @return true if the approval succeeded
98 * @see #getProgressState()
99 * @see DocumentRights#canApprove()
100 * @see DocumentType#isStudyResult()
101 * @see Study#getApproverOf(Publication)
103 Timestamp approve(Publication aPublication, Date adate);
106 * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.<br/> The
107 * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.<br/>
108 * If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/> Limitation: the
109 * way this demotion is propagated to the study supposes that the study has only ONE final result document.
111 * @param aPublication
112 * the document publication
113 * @return true if the demotion succeeded
114 * @see #getProgressState()
115 * @see DocumentRights#canDemote()
116 * @see DocumentType#isStudyResult()
118 boolean demote(Publication aPublication);
121 * Undo the review operation by demoting the document referenced by this publication from In-Check to In-Draft state and removing the
122 * Reviewer.<br/> If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/>
123 * Limitation: the way this demotion is propagated to the study supposes that the study has only ONE final result document.
125 * @param aPublication
126 * the document publication
127 * @return true if the demotion succeeded
128 * @see #getProgressState()
130 * @see DocumentRights#canInvalidate()
131 * @see DocumentType#isStudyResult()
133 boolean invalidate(Publication aPublication);
136 * Promotes the document referenced by this publication from In-Work to In-Draft or In-Check state, if not out-dated, and attaches the
137 * corresponding time-stamp to the document.<br/> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
138 * of the document does not include the review step.<br/> Also, if the promoted document is the final result of the owner study, the
139 * study is itself promoted as well.<br/> This operation can be undo-ed by demote().<br/> <br/> Limitation: the way this promotion is
140 * propagated to the study supposes that the study has only ONE final result document.
142 * @param aPublication
143 * the document publication
145 * the date of promotion
146 * @return true if the promotion succeeded
147 * @see #getProgressState()
149 * @see DocumentRights#canPromote()
150 * @see DocumentType#isStudyResult()
152 Timestamp promote(Publication aPublication, Date pdate);
155 * Promotes the document referenced by this publication from In-Draft to In-Check state, if not out-dated, and attaches the
156 * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
157 * is promoted as well.<br/> This operation can be undo-ed by invalidate().<br/> <br/> Limitation: the way this promotion is
158 * propagated to the study supposes that the study has only ONE final result document.
160 * @param aPublication
161 * the document publication
164 * @return true if the review succeeded
165 * @see #getProgressState()
167 * @see DocumentRights#canReview()
168 * @see DocumentType#isStudyResult()
169 * @see Study#getReviewerOf(Publication)
171 Timestamp review(Publication aPublication, Date rdate);
174 * Publishes the document referenced by this publication into the owner Project Element under the given state, the revision number of
175 * the document being automatically set accordingly. If the given state is In-Draft and the document is final result of the owner study,
176 * this automatically promotes the study to In-Draft.
178 * @param aPublication
179 * the document publication
181 * the required progress state
182 * @throws FileNotFoundException
183 * If the referenced document is empty
184 * @throws NotApplicableException
185 * If the referenced document is undefined
187 void saveAs(Publication aPublication, ProgressState state)
188 throws FileNotFoundException, NotApplicableException;
191 * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/> The state
192 * of the referenced document is supposed being automatically set according to the given revision number, but, due to the versioning
193 * scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is currently used
194 * only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/> Note: in the context of branch
195 * versioning, the given revision may be modified by an update of the branch name.
197 * @param aPublication
198 * the document publication
200 * the required revision number
201 * @throws FileNotFoundException
202 * If the referenced document is empty
203 * @throws NotApplicableException
204 * If the referenced document is undefined
208 void saveAs(Publication aPublication, Revision newvers)
209 throws FileNotFoundException, NotApplicableException;
212 * Rename the published document.
214 * @param aPublication
215 * the publication of the document
217 * the new document title
218 * @throws InvalidPropertyException
219 * if the new title is empty
221 void rename(Publication aPublication, String title)
222 throws InvalidPropertyException;
225 * Create "Converts" relation for the given document publication and format.
227 * @param aPublication
228 * the document publication
231 * @return the created "Converts" relation
233 ConvertsRelation attach(Publication aPublication, String format);
236 * Create "Converts" relation for the given document publication, format and description.
238 * @param aPublication
239 * the document publication
243 * the description of the relation
244 * @return the created "Converts" relation
246 ConvertsRelation attach(Publication aPublication, String format,
250 * Undo the out-date operation.
252 * @param aPublication
254 * @return true if the acceptance succeeds
256 * @see DocumentRights#canAccept()
258 boolean actualize(Publication aPublication);
261 * Out-dates this publication and recursively all publications using this one. Typically, a publication is out-dated when modifying a
262 * document to which it depends.
264 * @param aPublication
267 * @see #getProgressState()
270 void outdate(Publication aPublication);