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.text.ParseException;
15 import java.util.Date;
16 import java.util.List;
18 import org.splat.dal.bo.kernel.User;
19 import org.splat.dal.bo.som.ConvertsRelation;
20 import org.splat.dal.bo.som.DocumentType;
21 import org.splat.dal.bo.som.ProgressState;
22 import org.splat.dal.bo.som.ProjectElement;
23 import org.splat.dal.bo.som.Publication;
24 import org.splat.dal.bo.som.Study;
25 import org.splat.dal.bo.som.Timestamp;
26 import org.splat.kernel.InvalidPropertyException;
27 import org.splat.kernel.MismatchException;
28 import org.splat.kernel.MissedPropertyException;
29 import org.splat.kernel.MultiplyDefinedException;
30 import org.splat.kernel.NotApplicableException;
31 import org.splat.som.DocumentRights;
32 import org.splat.som.Revision;
33 import org.splat.som.Step;
36 * Publication service interface.
38 * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
40 public interface PublicationService {
43 * Copy the publication to the given project element.
46 * the publication to copy
48 * the target project element
49 * @return the created copy of the publication
51 Publication copy(Publication aPublication, ProjectElement publisher);
53 public Publication createDoc(final long ownerId, final Step step,
54 final long documentTypeId, final long userId, final String fname,
55 final String doctitle, final ProgressState docstate,
56 final String reference, final String version, final Date docDate,
57 final List<Long> docuses) throws MissedPropertyException,
58 InvalidPropertyException, MultiplyDefinedException, IOException,
59 NotApplicableException, InterruptedException, ParseException;
62 * Create a new version of the document.
65 * the study step where the document is published
69 * the new version file name
73 * new document version string, empty for external documents
77 * the new state of the document
79 * the new modification date
81 * the array of documents ids used by the versioned document
83 * the array of impacted documents ids
84 * @throws MissedPropertyException
85 * if some mandatory property is missed
86 * @throws InvalidPropertyException
87 * if some property has invalid value
88 * @throws MultiplyDefinedException
89 * if some property occurs several times
91 * if file moving is failed
92 * @throws MismatchException
93 * if step number in properties doesn't match to the given step
94 * @throws NotApplicableException
95 * if publication's document is undefined
96 * @throws InterruptedException
97 * by Thread.sleep if interrupted
99 void versionDocument(Step step, User user, String filename, long docIndex,
100 String docver, String summary, ProgressState state, Date date,
101 String[] docuses, long[] docusedby) throws MissedPropertyException,
102 InvalidPropertyException, MultiplyDefinedException, IOException,
103 MismatchException, NotApplicableException, InterruptedException;
106 * Returns the study Step into which the document version referenced by this publication has been published.
108 * @param aPublication
109 * the document publication
112 Step getInvolvedStep(Publication aPublication);
115 * Promotes the document referenced by this publication from In-Check to Approved state, if not out-dated, and attaches the
116 * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
117 * is promoted as well.<br/> <br/> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
118 * final result document.
120 * @param aPublication
121 * the document publication
123 * the date of approval
124 * @return true if the approval succeeded
125 * @see #getProgressState()
126 * @see DocumentRights#canApprove()
127 * @see DocumentType#isStudyResult()
128 * @see Study#getApproverOf(Publication)
130 Timestamp approve(Publication aPublication, Date adate);
133 * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.<br/> The
134 * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.<br/>
135 * If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/> Limitation: the
136 * way this demotion is propagated to the study supposes that the study has only ONE final result document.
138 * @param aPublication
139 * the document publication
140 * @return true if the demotion succeeded
141 * @see #getProgressState()
142 * @see DocumentRights#canDemote()
143 * @see DocumentType#isStudyResult()
145 boolean demote(Publication aPublication);
148 * Undo the review operation by demoting the document referenced by this publication from In-Check to In-Draft state and removing the
149 * Reviewer.<br/> If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/>
150 * Limitation: the way this demotion is propagated to the study supposes that the study has only ONE final result document.
152 * @param aPublication
153 * the document publication
154 * @return true if the demotion succeeded
155 * @see #getProgressState()
157 * @see DocumentRights#canInvalidate()
158 * @see DocumentType#isStudyResult()
160 boolean invalidate(Publication aPublication);
163 * Promotes the document referenced by this publication from In-Work to In-Draft or In-Check state, if not out-dated, and attaches the
164 * corresponding time-stamp to the document.<br/> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
165 * of the document does not include the review step.<br/> Also, if the promoted document is the final result of the owner study, the
166 * study is itself promoted as well.<br/> This operation can be undo-ed by demote().<br/> <br/> Limitation: the way this promotion is
167 * propagated to the study supposes that the study has only ONE final result document.
169 * @param aPublication
170 * the document publication
172 * the date of promotion
173 * @return true if the promotion succeeded
174 * @see #getProgressState()
176 * @see DocumentRights#canPromote()
177 * @see DocumentType#isStudyResult()
179 Timestamp promote(Publication aPublication, Date pdate);
182 * Promotes the document referenced by this publication from In-Draft to In-Check state, if not out-dated, and attaches the
183 * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
184 * is promoted as well.<br/> This operation can be undo-ed by invalidate().<br/> <br/> Limitation: the way this promotion is
185 * propagated to the study supposes that the study has only ONE final result document.
187 * @param aPublication
188 * the document publication
191 * @return true if the review succeeded
192 * @see #getProgressState()
194 * @see DocumentRights#canReview()
195 * @see DocumentType#isStudyResult()
196 * @see Study#getReviewerOf(Publication)
198 Timestamp review(Publication aPublication, Date rdate);
201 * Publishes the document referenced by this publication into the owner Project Element under the given state, the revision number of
202 * the document being automatically set accordingly. If the given state is In-Draft and the document is final result of the owner study,
203 * this automatically promotes the study to In-Draft. The old publication is removed from the scenario.
205 * @param aPublication
206 * the document publication
208 * the required progress state
209 * @throws FileNotFoundException
210 * If the referenced document is empty
211 * @throws NotApplicableException
212 * If the referenced document is undefined
214 void saveAs(Publication aPublication, ProgressState state)
215 throws FileNotFoundException, NotApplicableException;
218 * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/> The state
219 * of the referenced document is supposed being automatically set according to the given revision number, but, due to the versioning
220 * scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is currently used
221 * only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/> Note: in the context of branch
222 * versioning, the given revision may be modified by an update of the branch name. The old publication is removed from the scenario.
224 * @param aPublication
225 * the document publication
227 * the required revision number
228 * @throws FileNotFoundException
229 * If the referenced document is empty
230 * @throws NotApplicableException
231 * If the referenced document is undefined
235 void saveAs(Publication aPublication, Revision newvers)
236 throws FileNotFoundException, NotApplicableException;
239 * Rename the published document.
241 * @param aPublication
242 * the publication of the document
244 * the new document title
245 * @throws InvalidPropertyException
246 * if the new title is empty
248 void rename(Publication aPublication, String title)
249 throws InvalidPropertyException;
252 * Create "Converts" relation for the given document publication and format.
254 * @param aPublication
255 * the document publication
258 * @return the created "Converts" relation
260 ConvertsRelation attach(Publication aPublication, String format);
263 * Create "Converts" relation for the given document publication, format and description.
265 * @param aPublication
266 * the document publication
270 * the description of the relation
271 * @return the created "Converts" relation
273 ConvertsRelation attach(Publication aPublication, String format,
277 * Undo the out-date operation.
279 * @param aPublication
281 * @return true if the acceptance succeeds
283 * @see DocumentRights#canAccept()
285 boolean actualize(Publication aPublication);
288 * Out-dates this publication and recursively all publications using this one. Typically, a publication is out-dated when modifying a
289 * document to which it depends.
291 * @param aPublication
294 * @see #getProgressState()
297 void outdate(Publication aPublication);