From e5e506c3c28604e731b625534fce1453b2ab9404 Mon Sep 17 00:00:00 2001
From: Fernando Bellas Permuy <fbellas@udc.es>
Date: Thu, 2 Jul 2009 10:08:55 +0200
Subject: [PATCH] ItEr15S04ArquitecturaServidorItEr14S04: Documentation of
 conversational aspects in IWokerModel.

Conversational aspects have been commented in IWorkerModel. Conversational aspects include: (1) the state of the worker being edited/created and (2) the order of method invocation (protocol). Implementations of IWorkerModel can have additional state (such additional state is transparent for the clients of IWorkerModel).
---
 .../web/resources/worker/IWorkerModel.java    | 41 ++++++++++++++++++-
 .../worker/LocalizationsController.java       |  1 +
 .../worker/WorkRelationshipsController.java   |  1 +
 .../web/resources/worker/WorkerModel.java     |  1 +
 4 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/IWorkerModel.java b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/IWorkerModel.java
index c93276151..e241a1976 100644
--- a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/IWorkerModel.java
+++ b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/IWorkerModel.java
@@ -11,8 +11,47 @@ import org.navalplanner.business.resources.entities.ICriterionType;
 import org.navalplanner.business.resources.entities.Worker;
 
 /**
- * Interface for {@link WorkerModel}. <br />
+ * This interface contains the operations to create/edit a worker. The
+ * creation/edition process of a worker is conversational. <br/>
+ *
+ * <strong>Conversation state</strong>: the <code>Worker</code> instance and
+ * the associated <code>CriterionSatisfaction</code> instances. Some of the
+ * <code>CriterionSatisfaction</code> instances represent temporal work
+ * relationships (e.g. paternity leave) and others represent locations. <br/>
+ *
+ * <strong>Non conversational steps</strong>: <code>getWorkers</code> (to return
+ * all workers) and <code>getLaboralRelatedCriterions</code></li> (to return
+ * all <code>Criterion</code> instances representing temporal work
+ * relationships). <br/>
+ *
+ * <strong>Conversation protocol:</strong>
+ * <ul>
+ * <li>
+ * Initial conversation step: <code>prepareForCreate</code> (to create
+ * a worker) or (exclusive) <code>prepareEditFor</code> (to edit an existing
+ * worker).
+ * </li>
+ * <li>
+ * Intermediate conversation steps: <code>getWorker</code> (to return the
+ * worker being edited/created), <code>getLocalizationsAssigner</code> (to
+ * assist in the location tab), <code>isCreating</code> (to check if the worker
+ * is being created or edited),
+ * <code>getLaboralRelatedCriterionSatisfactions</code> (to return all the
+ * temporal work relationships), <code>addSatisfaction</code> (to add a
+ * temporal work relationship), <code>removeSatisfaction</code> (to remove a
+ * temporal work relationship) (note: to modify an existing temporal work
+ * relationship, it is necessary to remove it and add a new one),
+ * <code>assignCriteria</code> (to add locations), and
+ * <code>unassignSatisfactions</code> (to remove locations).
+ * </li>
+ * <li>
+ * Final conversational step: <code>save</code> (to save the worker being
+ * edited/created).
+ * </li>
+ * </ul>
+ *
  * @author Óscar González Fernández <ogonzalez@igalia.com>
+ * @author Fernando Bellas Permuy <fbellas@udc.es>
  */
 public interface IWorkerModel {
 
diff --git a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/LocalizationsController.java b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/LocalizationsController.java
index 5b389d6ec..09cfc2d32 100644
--- a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/LocalizationsController.java
+++ b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/LocalizationsController.java
@@ -20,6 +20,7 @@ import org.zkoss.zul.api.Listitem;
 /**
  * Subcontroller for assigning localizations <br />
  * @author Óscar González Fernández <ogonzalez@igalia.com>
+ * @author Fernando Bellas Permuy <fbellas@udc.es>
  */
 public class LocalizationsController extends GenericForwardComposer {
 
diff --git a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkRelationshipsController.java b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkRelationshipsController.java
index 840e83bd0..25a912e06 100644
--- a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkRelationshipsController.java
+++ b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkRelationshipsController.java
@@ -24,6 +24,7 @@ import org.zkoss.zul.Listbox;
 /**
  * Subcontroller for {@link Worker} resource <br />
  * @author Lorenzo Tilve Álvaro <ltilve@igalia.com>
+ * @author Fernando Bellas Permuy <fbellas@udc.es>
  */
 public class WorkRelationshipsController extends GenericForwardComposer {
 
diff --git a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkerModel.java b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkerModel.java
index 5d6670ee5..90f4235f7 100644
--- a/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkerModel.java
+++ b/navalplanner-webapp/src/main/java/org/navalplanner/web/resources/worker/WorkerModel.java
@@ -34,6 +34,7 @@ import org.springframework.transaction.annotation.Transactional;
 /**
  * Model for worker <br />
  * @author Óscar González Fernández <ogonzalez@igalia.com>
+ * @author Fernando Bellas Permuy <fbellas@udc.es>
  */
 @Component
 @Scope(BeanDefinition.SCOPE_PROTOTYPE)