import org.splat.som.Step;
/**
- * @author RKV
+ * Publication service interface.
*
+ * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
*/
public interface PublicationService {
+ /**
+ * Copy the publication to the given project element.
+ *
+ * @param aPublication
+ * the publication to copy
+ * @param publisher
+ * the target project element
+ * @return the created copy of the publication
+ */
public Publication copy(Publication aPublication, ProjectElement publisher);
/**
* Returns the study Step into which the document version referenced by this publication has been published.
+ *
+ * @param aPublication
+ * the document publication
+ * @return study step
*/
public Step getInvolvedStep(Publication aPublication);
/**
* Promotes the document referenced by this publication from In-Check to Approved state, if not out-dated, and attaches the
- * corresponding time-stamp to the document.</br> If the promoted document is the final result of the owner study, the study is itself
- * is promoted as well.</br> </br> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
+ * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
+ * is promoted as well.<br/> <br/> Limitation: the way this promotion is propagated to the study supposes that the study has only ONE
* final result document.
*
+ * @param aPublication
+ * the document publication
* @param adate
* the date of approval
* @return true if the approval succeeded
public Timestamp approve(Publication aPublication, Date adate);
/**
- * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.</br> The
- * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.</br>
- * If the demoted document is the final result of the owner study, the study is itself is demoted as well.</br> </br> Limitation: the
+ * Demotes the document referenced by this publication to In-Work state, and removes the Promoter of the document, if exist.<br/> The
+ * In-Draft state is skipped (direct demotion to In-Work) if the validation cycle of the document does not include the review step.<br/>
+ * If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/> Limitation: the
* way this demotion is propagated to the study supposes that the study has only ONE final result document.
*
+ * @param aPublication
+ * the document publication
* @return true if the demotion succeeded
* @see #getProgressState()
* @see DocumentRights#canDemote()
/**
* Undo the review operation by demoting the document referenced by this publication from In-Check to In-Draft state and removing the
- * Reviewer.</br> If the demoted document is the final result of the owner study, the study is itself is demoted as well.</br> </br>
+ * Reviewer.<br/> If the demoted document is the final result of the owner study, the study is itself is demoted as well.<br/> <br/>
* Limitation: the way this demotion is propagated to the study supposes that the study has only ONE final result document.
*
+ * @param aPublication
+ * the document publication
* @return true if the demotion succeeded
* @see #getProgressState()
* @see #review()
/**
* Promotes the document referenced by this publication from In-Work to In-Draft or In-Check state, if not out-dated, and attaches the
- * corresponding time-stamp to the document.</br> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
- * of the document does not include the review step.</br> Also, if the promoted document is the final result of the owner study, the
- * study is itself promoted as well.</br> This operation can be undo-ed by demote().</br> </br> Limitation: the way this promotion is
+ * corresponding time-stamp to the document.<br/> The In-Draft state is skipped (direct promotion to In-Check) if the validation cycle
+ * of the document does not include the review step.<br/> Also, if the promoted document is the final result of the owner study, the
+ * study is itself promoted as well.<br/> This operation can be undo-ed by demote().<br/> <br/> Limitation: the way this promotion is
* propagated to the study supposes that the study has only ONE final result document.
*
+ * @param aPublication
+ * the document publication
+ * @param pdate
+ * the date of promotion
* @return true if the promotion succeeded
* @see #getProgressState()
* @see #demote()
/**
* Promotes the document referenced by this publication from In-Draft to In-Check state, if not out-dated, and attaches the
- * corresponding time-stamp to the document.</br> If the promoted document is the final result of the owner study, the study is itself
- * is promoted as well.</br> This operation can be undo-ed by invalidate().</br> </br> Limitation: the way this promotion is propagated
- * to the study supposes that the study has only ONE final result document.
+ * corresponding time-stamp to the document.<br/> If the promoted document is the final result of the owner study, the study is itself
+ * is promoted as well.<br/> This operation can be undo-ed by invalidate().<br/> <br/> Limitation: the way this promotion is
+ * propagated to the study supposes that the study has only ONE final result document.
*
+ * @param aPublication
+ * the document publication
* @param rdate
* the date of review
* @return true if the review succeeded
* the document being automatically set accordingly. If the given state is In-Draft and the document is final result of the owner study,
* this automatically promotes the study to In-Draft.
*
+ * @param aPublication
+ * the document publication
* @param state
* the required progress state
* @throws FileNotFoundException
throws FileNotFoundException, NotApplicableException;
/**
- * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/>
- * The state of the referenced document is supposed being automatically set according to the given revision number, but, due to the
- * versioning scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is
- * currently used only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/>
- * Note: in the context of branch versioning, the given revision may be modified by an update of the branch name.
+ * Publishes the document referenced by this publication into the owner Project Element under the given revision number.<br/> The state
+ * of the referenced document is supposed being automatically set according to the given revision number, but, due to the versioning
+ * scheme, as it is not possible to differentiate In-Work and In-Draft states, this function has been deprecated (it is currently used
+ * only for the need of integration of Microsoft Office which anyway has to be redesigned). <br/> Note: in the context of branch
+ * versioning, the given revision may be modified by an update of the branch name.
*
+ * @param aPublication
+ * the document publication
* @param newvers
* the required revision number
* @throws FileNotFoundException
