[Yanel-commits] rev 25156 - public/yanel/trunk/src/core/java/org/wyona/yanel/core/api/attributes

[josias at wyona.com]

Author: josias
Date: 2007-06-15 12:04:19 +0200 (Fri, 15 Jun 2007)
New Revision: 25156

Modified:
   public/yanel/trunk/src/core/java/org/wyona/yanel/core/api/attributes/WorkflowableV1.java
Log:
added javadoc

Modified: public/yanel/trunk/src/core/java/org/wyona/yanel/core/api/attributes/WorkflowableV1.java
===================================================================
--- public/yanel/trunk/src/core/java/org/wyona/yanel/core/api/attributes/WorkflowableV1.java	2007-06-15 09:23:39 UTC (rev 25155)
+++ public/yanel/trunk/src/core/java/org/wyona/yanel/core/api/attributes/WorkflowableV1.java	2007-06-15 10:04:19 UTC (rev 25156)
@@ -23,25 +23,107 @@
 
 /**
  * DEV (not released yet, this interface still might change ...)
+ * <br/>
+ * A workflow is composed of states and transitions. Each revision of a workflowable resource 
+ * has a state, which can be changed by performing transitions.
+ * Transitions may be bound to conditions or actions, but this is implementation specific.
+ * Further, a workflowable resource can be live, or not live. If it is live, it must
+ * provide a live-view.
  * 
- * A workflow state belongs to a revision.
- * A workflow variable belongs to a resource.
+ * The workflow information of a resource can be stored in two types of properties:
+ * <ul>
+ *   <li> 
+ *     workflow state: property which belongs to a revision.
+ *   </li> 
+ *   <li> 
+ *     workflow variable: property which belongs to a resource (shared among all revisions).
+ *   </li> 
+ * </ul> 
+ * 
+ * Typically, the workflow state of a revision is something like draft/approved.
+ * A workflow variable may e.g. store the revision number of the live revision.
  */
 public interface WorkflowableV1 {
 
+    /**
+     * Perform the transition with the given id to the indicated revision.
+     * @param transitionID
+     * @param revision
+     * @throws WorkflowException
+     */
     void doTransition(String transitionID, String revision) throws WorkflowException;
 
+    /**
+     * Indicates whether this resource is live or not.
+     * @return true if this resource is live, false otherwise.
+     * @throws WorkflowException
+     */
     boolean isLive() throws WorkflowException;
+    
+    /**
+     * Gets the view of the live version of this resource.
+     * @param viewid
+     * @return live view
+     * @throws Exception
+     */
     View getLiveView(String viewid) throws Exception;
     
+    /**
+     * Gets the workflow state of the given revision.
+     * @param revision
+     * @return workflow state or null if the revision has no workflow state
+     * @throws WorkflowException
+     */
     String getWorkflowState(String revision) throws WorkflowException;
+    
+    /**
+     * Sets the workflow state of the given revision.
+     * @param state
+     * @param revision
+     * @throws WorkflowException
+     */
     void setWorkflowState(String state, String revision) throws WorkflowException;
+    
+    /**
+     * Gets the workflow date of the given revision, that is the date when
+     * the state has changed.
+     * @param revision
+     * @return workflow date or null if the revision has no workflow date
+     * @throws WorkflowException
+     */
     Date getWorkflowDate(String revision) throws WorkflowException;
     
+    
+    /**
+     * Gets the workflow variable with the given name.
+     * @param name
+     * @return workflow variable or null if this resource has no workflow variable with the given name.
+     * @throws WorkflowException
+     */
     String getWorkflowVariable(String name) throws WorkflowException;
+    
+    /**
+     * Sets the workflow variable with the given name.
+     * @param name
+     * @param value
+     * @throws WorkflowException
+     */
     void setWorkflowVariable(String name, String value) throws WorkflowException;
+    
+    /**
+     * Removes the workflow variable with the given name.
+     * @param name
+     * @throws WorkflowException
+     */
     void removeWorkflowVariable(String name) throws WorkflowException;
     
+    /**
+     * Gets the introspection xml containing the workflow information.
+     * Since workflow is tied to versioning, this xml also contains the revision
+     * information.
+     * @return workflow introspection xml
+     * @throws WorkflowException
+     */
     String getWorkflowIntrospection() throws WorkflowException;
     
     //boolean canDoTransition(String transitionID) throws WorkflowException;