Add documentation for import (nus-cs2103-AY1718S2#92)

* fix merge errors * Add dummy classes to support import feature * Add details in JobEntry and SessionData * more edits * Add classes to support ImportSession * Apply SLAP to make methods smaller * Add ImportSession method to read excel file. * Add SheetHeaderFields class * Add SheetWithHeaderFields to extract row and column operations * Finish ImportSession feature to write to file * trailing whitespace * Extract messages in ImportSession as constants. Write dummy ImportAllCommand, with functional support classes. * Use unmodifiableList for getting lists in sessionData and jobEntry. * Implement importAll command * fix modelStub * fix checkstyle error * fix checkstyle error * DG test * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edits * edits * edit * edit * edit * edit * edit * edits * edit * edit * edit * edit * edit * edit * edit * edit * edit * edit * edits * edit * Rename method addUnreviewedJobEntries to addSheet * remove DG * Update DG * update DG * Add UML diagrams for set command and import/save * move session from model to storage * Add ImportSessionTest * modify test file * Add documentation for import * Add design considerations * resolve conflict * hard reset * Add aspect of supporting mass add methods addJobs/addMissingEmployees * Update UML diagrams * Add UML diagram for ImportSession closeSession()
whenzei · Apr 2, 2018 · cc868df · cc868df
1 parent 27dec66
commit cc868df
Show file tree

Hide file tree

Showing 8 changed files with 92 additions and 29 deletions.
diff --git a/docs/DeveloperGuide.adoc b/docs/DeveloperGuide.adoc
@@ -372,7 +372,7 @@ The successful execution of `AddJobCommand` adds the `Job` to CarviciM.
 === Set command feature
 ==== Current Implementation
 
-.ClassDiagram of CommandWords at runtime
+.Object Diagram of CommandWords at runtime
 image::SetCommandObjectDiagram.png[width="800"]
 [none]
 
@@ -421,12 +421,97 @@ As you can see from figure 12, AddressBookParser makes a reference to CommandWor
 // end::set[]
 
 // tag::importexport[]
-=== Import/Export feature #Coming in v2.0#
+=== Import/Save feature
 ==== Current Implementation
 
-image::blank.png[width="800"]
+.Object Diagram of `session` component
+image::SessionComponentClassDiagram.png[width="800"]
+
+`ImportSession` uses a Singleton design pattern. It is responsible for initializing and closing the session.
+`ImportSession` has 4 methods:
+
+* `static getInstance()`: Used to retrieve the single instance of `ImportSession`.
+* `setData(sessionData)`: Used to set `sessionData` for `ImportSession`.
+* `initialize(fileName)`: Initializes `sessionData` with and excel file located at `fileName`.
+* `closeSession()`: Writes the comments as a save file to same directory of import file,
+ with a timestamp added to the back of the filename.
+
+`ImportSession` is designed to be stateless on its own, with all data stored in `SessionData`. This helps to
+support `UndoableCommand`
+
+The flow of using `ImportSession` is as follows:
+
+===== Loading a file into `ImportSession`
+
+* Figure 14 below shows the process of initializing ImportSession. On the `import` command,
+`getInstance` is used to retrieve the `importSession` instance, before it calls
+`initialize(fileName)`. A new `SheetParser` is created to populate `sessionData` with excel sheet data
+as shown in Figure 11, which comes as:
+1. `SheetWithHeaderField`: augmented `Sheet` that provides API to indicate approval status and
+write comments.
+2. `JobEntry`: Augmented `Job` stores the sheet number and row number for writing into the excel file.
+`JobEntry` also contains the `Job` data which will be imported upon approval.
++
+.Sequence Diagram of `ImportSession` initialization
+image::SessionInitializationSequenceDiagram.png[width="800"]
+
+===== Reviewing job entries
+
+* Figure 15 below shows the process of reviewing job entries in an import session. On the `review`
+command, `sessionData` updates the relevant `jobEntry` and retrieves the sheet and row number,
+which is used to update `sheetWithHeaderFields`. Upon reviewing a job, CarviciM will add the job and
+any employees not present in the application.
++
+.Sequence Digram of `ImportSession` during the reviewing of a job
+image::SessionReviewSequenceDiagram.png[width="800"]
+
+===== Saving feedback from an `ImportSession`
+
+* Figure 16 below shows the process of saving a session. On the `save` command, `importSession` writes the
+modified excel sheets from `sheetWithHeaderFields` to the same path as the imported excel file, with
+a timestamp added to the back of the filename.
+
+.Sequence Digram of `ImportSession` when saving feedback to a file
+image::SessionCloseSequenceDiagram.png[width="800"]
 
 ==== Design Considerations
+===== Aspect: Supporting UndoableCommand
+
+* **Current choice:** Add the previous instance of `sessionData` when setting data for `Command`, with a
+`SaveFileStack` as shown in Figure 11. Load this `sessionData` on `undo` or `redo` command.
+** Pros: `sessionData` stores data for `importSession`, making it appropriate to be used as data in `undo`
+and `redo`. Modification is only limited to `UndoableCommand`. Single Responsibility Principle is maintained,
+as the storage of save file locations is limited to `SaveFileStack`.
+** Cons: `sessionData` will have to store the boolean `initialized` in `sessionData` so that it will
+stay up-to-date with the `UndoRedoStack`.
+
+* _Alternative:_ `importSession` provides API to `undo` and `redo`.
+** Pros: Open Closed Principle is respected, there is no need to modify `UndoableCommand`.
+** Cons: Commands that modify `sessionData` have to be written differently from other commands to support
+`undo` and `redo`. The delimiter rule is also violated as `importSession` is unnecessarily involved.
+
+===== Aspect: Supporting mass add methods addJobs/addMissingEmployees
+
+* **Current choice:** Add the methods to `Model`
+** Pros: Cohesion is maximized, these methods can also be reused by other classes.
+** Cons: Open Closed Principle is violated and adding these methods may result in confusion on the
+behavior of `Model`.
+
+* _Alternative:_ Add the methods to `ImportSession`
+** Pros: The behavior of these methods can be tailored specifically to `ImportSession`.
+** Cons: Unnecessary coupling between `Model` and `ImportSession` when `Command` is already coupled to `Model`.
+The Single Responsibility Principle is also violated.
+
+===== Aspect: Persistent Data
+
+* **Current choice:** Keep all data from `ImportSession` on `sessionData` and use it to initialize on startup.
+** Pros: `ImportSession` gets to stay as a `Singleton`, preventing confusion.
+** Cons: There will be increased coupling between `Session` and `Storage`.
+
+* _Alternative:_ Combine `ImportSession` and `SessionData` into 1 single class and store
+it directly.
+** Pros: `ImportSession` can be directly initialized on startup and coupling is reduced.
+** Cons: Confusion may occur due to allowing more than one `ImportSession`.
 // end::importexport[]
 
 // tag::theme[]

diff --git a/docs/UserGuide.adoc b/docs/UserGuide.adoc
@@ -330,13 +330,14 @@ Examples:
 
 ==== Sharing your feedback with your employees
 
-If you want to share your feedback, you can export it as an excel file, reflecting accept/reject with comments.
-Format: `export FILE_PATH`
+If you want to share your feedback, you can save it as an excel file, reflecting accept/reject with comments.
+Format: `save FILE_PATH`
 
 [TIP]
 ====
 * You can type any filename supported by your computer's storage format.
-* If you forgot to export your feedback, you can find it under C:\User\Documents\CarviciM\feedback.xls.
+* If you forgot to save your feedback, you can find it in the same directory as the imported excel file, with the time
+it is saved added to the end of the filename.
 * The feedback file's format is support for future imports.
 ====
 

diff --git a/docs/images/SessionCloseSequenceDiagram.png b/docs/images/SessionCloseSequenceDiagram.png
diff --git a/docs/images/SessionComponentClassDiagram.png b/docs/images/SessionComponentClassDiagram.png
diff --git a/docs/images/SetCommandObjectDiagram.png b/docs/images/SetCommandObjectDiagram.png
diff --git a/docs/images/sessionInitializationSequenceDiagram.png b/docs/images/sessionInitializationSequenceDiagram.png
diff --git a/docs/images/sessionReviewSequenceDiagram.png b/docs/images/sessionReviewSequenceDiagram.png
diff --git a/src/main/java/seedu/carvicim/storage/session/ImportSession.java b/src/main/java/seedu/carvicim/storage/session/ImportSession.java
@@ -151,27 +151,4 @@ private void freeResources() {
         inFile = null;
         outFile = null;
     }
-
-    /**
-     * For localized testing purposes
-     */
-    public static void main(String[] args) {
-        ImportSession importSession = getInstance();
-        String path;
-        try {
-            path = new File(".").getCanonicalPath();
-            System.out.println(path);
-        } catch (IOException e) {
-            e.printStackTrace();
-        }
-        try {
-            importSession.initializeSession(
-                    ".\\src\\test\\resources\\model.session.ImportSessionTest\\CS2103-testsheet.xlsx");
-            importSession.reviewAllRemainingJobEntries(true);
-            importSession.closeSession();
-        } catch (Exception e) {
-            e.printStackTrace();
-        }
-
-    }
 }