Alfred The Hackathon Butler - Developer Guide

These are some design considerations for the UI component.

API : Model.java

The Model,

ModelManager

Each EntityList is also further subclassed into ParticipantList, MentorList, TeamList. Each of these lists can be seen as an individual address book from the original AB3 project. The following diagrams show the structure of these Entity objects within each list. These Entity objects are the building blocks of Alfred.

When the ModelManager object is first created upon starting the application, the existing data is loaded from the disc via methods on the Storage object. However, if there are any bugs in the process, perhaps due to corrupted data, a new EntityList is instantiated rather than run the risk of working with outdated data.

Due to its role as the API of the application, all calls which require access to the Entity objects will be done through Model and not via the lists directly. These operations are listed as public methods on the Model interface.

For operations which would entail mutating the data within the EntityList objects in any form, Model automatically communicates with the Storage object to save the data. The saving logic can be found within the Storage object and thus Model only needs to pass it EntityList objects on its end. The same applies for the other attributes in Model, such as CommandHistory; ModelManager will automatically communicate with it for you.

If there are any errors along the way, it will be logged but the error would be handled within Model itself. Moreover, if there is an error during a Model operation, the data will not be saved to disc.

These are some design considerations for Model.

API : AlfredStorage.java

The Storage component saves and reads 4 different data types:

All 4 data types are stored to disc in JSON files. The data is read from the JSON files when Alfred is first start up. It is also important to note that saving is automatic in Alfred. This means that after the execution of each command, the data in Alfred will automatically be saved to disk. This frees the user from the hassle of constantly calling some form of saving functionality, and ensures that the information in storage is as up-to-date as possible.

The Storage Component uses the Facade Design Pattern, and exposes the functionality of all the Storage classes to the Model Component solely through the AlfredStorage interface. The exposed functionality was deliberately kept simple, allowing the following methods for each of the 4 data types:

The Storage component handles the complexities of actually storing to and reading from disc the 4 different data types. As can be seen in the figure at the start of this section, underlying AlfredStorage’s simple interface are several classes that ensure the accurate storing and retrieval of Alfred’s data from disc. The following are some details of the Storage Component:

The following is a concrete example of the storage of a ParticipantList in JSON:

The figure above shows the contents of the JSON file storing a ParticipantList containing 2 participants. The data in the red box corresponds to the fields in a single Participant object. These fields are generated by the Jackson library from the serializable JsonAdaptedParticipant object, and the entire list of participants in the JSON file is in turn generated because the JsonSerializableParticipantList class converts the ParticipantList to a List of JsonAdaptedParticipant.

The following are some design considerations for the Storage component.

Since this feature manages data from a CSV file, import command relies on the CsvUtil class. The CsvUtil class handles reading from and writing data to a CSV file. Below shows the relationships between different classes in Alfred.

In the above class diagram, you can see that

The activity diagram below will explain the overall flow of ImportCommand.

In the above diagram, you can see that teams are buffered for later use, which the reason is explained below. Also, node A, located right before the end, will be discussed in this section. Now, the sections below will give a detailed explanation of different portions of this feature.

Once a valid user input is parsed and passed into the ImportCommand, the command will open the file and read its content line by line. Each line is then parsed into the corresponding entity by the CsvUtil class. This will be explained further below. The following sequence diagram shows the steps involved in mass importing data into Alfred.

FileUtil shown in the class diagram was omitted from the above sequence diagram for simplicity as it adds little to the overall flow of execution.

As the above figure shows, the file path from the user input is extracted and passed as a field for ImportCommand. Then, Alfred proceeds to convert file content into relevant entities.

When ImportCommand parses and adds entities to Model, it is crucial that teams are the last entities to be added. In the above sequence diagram, this process of buffering teams was also omitted for simplicity. Basically, in the #parseLineToEntity() method, if a line in CSV file corresponds to a team, the line will be buffered to be parsed after all the other lines have been parsed. The reason for this is because teams may have dependencies on other participants and mentors. It is required that all of the participants and mentors associated with a team, say Team A, exist inside the Model before Team A can be added.

So as ImportCommand accesses the CSV file line by line, the line representing a team will be stored in a Queue<String> for later use. When the end of file is reached and all other participants and mentors are parsed and added to Model, the ImportCommand will poll from the Queue, parse into a relevant team, and add it to the Model until the Queue is empty.

As mentioned before, the CsvUtil class is used to aid in parsing of CSV lines into entities. The process in which CsvUtil parses each entity is heavily dependent on the different fields each entity has. If you are not familiar with this yet, please check out our user guide.

The process of parsing a line into a mentor or a participant is very similar, so two entities - participant and team - will be explained.

First, the following is a sequence diagram for parsing a CSV line into a participant. The line to be parsed is "P,ID,Bruce Wayne,12345678,wbruce@wayne.ent".

Given CSV line is first split by commas (also allows commas surrounded by arbitrary number of spaces). Then, each String in the array is (attempted to be) converted into corresponding fields of a Participant. As the diagram shows, each field class has its own method for checking if the given String argument is valid - in the form of #isValidField() method, where Field is replaced by its respective class name. Once each field is successfully converted, a Participant is created with the parsed fields. The process of parsing into a Mentor is practically equivalent of that of a Participant. The only change is in the fields being parsed.

Next is a sequence diagram for parsing a CSV line into a team. The line to be parsed is "T,,Justice League,[P-1|P-2],M-1,Social,100,Save the Earth,1".

Also for teams, each corresponding String is converted to its field counterpart just like participants and mentors. Hence, #isValidField() method was omitted from the diagram. The difference lies in the fact that for teams, Alfred must check if any participants or mentors it makes a reference to actually exists in Model. Thus, CsvUtil calls Model#getParticipant() and Model#getMentor() methods exposed by the Model class. If there are any exceptions raised while retrieving the participants and mentors, that line in CSV will not be loaded onto Alfred.

Other than the CSV file path, if the user specifies an additional file path, Alfred will create a new CSV file path at that location containing every line in the user-given CSV file that had an error. For example, if lines 4, 6, and 7 were invalid in the imported CSV file, the error CSV file will contain only three lines, namely lines 4, 6, and 7 of the user-given CSV file.

The activity diagram below will illustrate what would happen if two file paths were provided. The following diagram starts at node A shown in Figure 15, “Import Command Activity Diagram”.

When designing this feature, different aspects - list below - were considered.

This feature, like ImportCommand, utilizes the CsvUtil class because it also handles CSV files. As mentioned before, on top of parsing of data, CsvUtil also supports writing of different entities into a provided CSV file by converting them to their corresponding CSV Strings. Below shows the relationships between different classes involved in ExportCommand.

The diagram shows that much like ImportCommand, ExportCommand also utilizes utility classes, such as CsvUtil and FileUtil. However, unlike ImportCommand, since Alfred is the one creating the file this time, if the file path given by the user is not a valid path, Alfred will create and export all data to a file located at default file path, which is ./AlfredData/Alfred_Data.csv.

The activity diagram below will show in more detail how the ExportCommand is executed.

The above diagram illustrated the general flow of how ExportCommand is executed. You can see that majority of the work is being passed onto the CsvUtil. The sequence diagram below will show how CsvUtil manages to write all the data into a CSV file.

You can see that CsvUtil receives the EntityList of each entity type from Model. CsvUtil will then iterate through one entity at a time, convert to corresponding CSV String, and write to the CSV file. As such, you can see that the actual writing to a CSV file is handled by CsvUtil instead of the ExportCommand class.

Exporting all the data from Alfred to a CSV file is nice, but sometimes, the user may only want the data of a specific entity. This would be handled by the subclasses of ExportCommand, which consists of ExportMentorCommand, ExportParticipantCommand, and ExportTeamCommand. Similar to their superclass, the subclasses also depend on FileUtil and CsvUtil classes to create and write data to CSV files.

The overall flow is the same so you can refer to the aforementioned activity diagram and sequence diagram for more information. The only difference is when the subclasses call CsvUtil. If you recall, ExportCommand passes Model to CsvUtil. For each subclass, they will retrieve the respective ReadOnlyEntityList and pass to CsvUtil. The above activity diagram shows that in CsvUtil, it makes three method calls to itself: #writeToCsv(File, MentorList), #writeToCsv(File, ParticipantList), and #writeToCsv(File, TeamList). These three methods are the methods that each subclass will call.

The general idea is as follows: The undo/redo mechanism is mainly facilitated by the interface ModelHistory and its implementation ModelHistoryManager. Alfred’s data is held in memory within the ModelManager object. After the execution of commands that mutate the data in Alfred, a deep copy of all 3 EntityLists is made and saved as a ModelHistoryRecord in ModelHistoryManager. A deep copy is necessary to ensure that any subsequent changes to data will not alter the data in the ModelHistoryRecord, allowing each ModelHistoryRecord to serve as a pristine record of the state of the data in Alfred at the end of the execution of each command.

Whenever the undo command is invoked, ModelHistoryManager returns a ModelHistoryRecord. A deep copy of the EntityLists contained within ModelHistoryRecord are then used to replace the EntityLists in the ModelManager for its operations, effectively reverting the data in Alfred to a previous state.

The following sequence diagram shows the sequence of method calls used to store the state of the data in Alfred in ModelHistory (ModelHistoryManager is an implementation of the ModelHistory interface) after the execution of a DeleteParticipantCommand:

The top half of the diagram covers the creation of the DeleteParticipantCommand object, and the bottom half covers what happens when the execute() method of the DeleteParticipantCommand object is called. The important thing to note is the fact that a deep copy of the 3 EntityLists is created and stored as a ModelHistoryRecord in ModelHistoryManager.

An important issue to take note of is that only commands that implement the TrackableState interface will cause a new ModelHistoryRecord to be created and stored in ModelHistoryManager. The TrackableState interface is a marker interface, and is used to mark the commands that mutate data in Alfred. All command types except the following implement the TrackableState interface (and will therefore have the state of the data recorded in ModelHistoryManager after command execution): help, list, find, history, leaderboard, getTop, export, help, home, undo, redo.

The following sequence diagram shows what happens when the UndoCommand is executed.

The important issue to take note of here is that the code first checks whether it is valid to undo to a certain state by calling the canUndo() method in ModelHistory. The implementation of ModelHistory in ModelHistoryManager does so by checking if there are sufficient states to undo to, otherwise an exception is thrown.

ModelHistoryMangager contains a List of ModelHistoryRecord, and a pointer pointing to the ModelHistoryRecord that reflects the current state of the data in Alfred.

In order to better illustrate how the state of the data is tracked and stored in ModelHistoryManager, consider the following example. The following commands are executed:

This is the state of ModelHistoryManager when Alfred is first started.

This is what happens after each step:

Step 1. AddParticipantCommand: add participant n/Clark Kent p/+6598321212 e/clark.kent@supermail.com

A new ModelHistoryRecord is created to reflect the state of the data in Alfred after the execution of the AddParticipantCommand.

Step 2. AddMentorCommand: add mentor n/Lex Luthor o/LexCorp p/+6598321010 e/lex.not.evil@gmail.com s/Social

A new ModelHistoryRecord is created to reflect the state of the data in Alfred after the execution of the AddMentorCommand.

Step 3. ListParticipantCommand: list participants

Note that no new ModelHistoryRecord is created because the ListParticipantCommand does not alter the state of the data in Alfred. Hence, it does not implement the TrackableState interface.

Step 4. UndoCommand: undo 2

After executing the undo 2 command, the pointer in ModelHistoryManager shifts backwards by 2 to point to the ModelHistoryRecord at the zero-th index.

Note that this means that undo 3 would throw an error, as you cannot move beyond the very first ModelHistoryRecord in ModelHistoryManager.

Step 5. AddTeamCommand: add team n/Justice League s/Social pn/BetterThanAvengers l/12

Note that the execution of a new command will invalidate the ModelHistoryRecord after the pointer. This is because all subsequent data states are the result of transformations that have already been undone, so it is not valid to be able to redo to them.

When designing the undo/redo feature, there were some design considerations to take note of.

Most of the functionality required for the history feature is similar to that of the undo/redo feature. Specifically, there is a similar reliance on the ModelHistory interface and its implementation ModelHistoryManager to provide the information on which commands are undo-able and redo-able, along with their respective command input strings. See the sequence diagram below for more information.

Since ModelHistoryManager keeps a linear history of Alfred’s data state after commands are executed, and it has a pointer to the current data state, the redo-able commands are simply the ones after the pointer, and the undo-able commands are the one before the pointer. The panels displayed in the "History" section of the Graphical User Interface is simply a visual representation of this sequential ordering of datas states. The call to getCommandHistory() in Model will return an ArrayList of CommandRecords, where each CommandRecord specifies the command input string as well as whether the CommandRecord is a delimiter. This ArrayList is then provided back to the UI for rendering in the "History" section of the Graphical User Interface.

Given the close relationship between this feature and the undo/redo feature, the design considerations are very similar as well. See Section 4.3, “Undo/Redo feature” for more information.

Every time a valid new command is executed, the string used to generate the command (i.e. the text that the user types into Alfred’s Command Input Box) is stored in the Command object.

The main class responsible for remembering and providing the previously used command input strings is the CommandHistoryManager class, which implements the CommandHistory interface. The CommandHistory interface only exposes 3 methods: saveCommandExecutionString, getPrevCommandString and getNextCommandString. The latter 2 methods directly map to the 2 situations of pressing the ALT+UP and pressing the ALT+DOWN keys respectively.

When the Command object is executed, that string is then stored in the CommandHistoryManager. A linear list of successfully executed commands' input strings is stored in CommandHistoryManager, and a pointer to the current string being displayed in the textbox is used to indicate which is the currently active string.

The following sequence diagram describes the sequence of method calls used to set and store the command input string in CommandHistoryManager

The following sequence diagram describes the sequence of method calls used to set the text in Alfred’s Command Input Box whenever the ALT + UP/DOWN arrow keys are pressed.

An analogous process is executed when the ALT+DOWN arrow keys are pressed.

The following are some design considerations for the Command History Navigation feature.

The following are some design considerations for the home command.

The main class responsible providing suggestions is the AutoCompleteCommandBox class.Typing into the AutoCompleteCommandBox will prompt the attached Listener to be activated. Activation of the Listener will prompt it to filter through the set of predefined command suggestions. The commands that start with the same alphabet or alphabets entered by user will be filtered through. The first four result will then be mapped to their respective TextFlow object and added to the ContextMenu. This ContextMenu will then appear as a pop up box. Pressing up arrow and down arrow keys will enable the user to choose a command suggestion. Additionally, pressing enter will filter out different Text from the TextFlow object. The AutoCompleteCommandBoxsetText method will then be called to set the JFXTextField to the said Text object.

The following sequence diagram shows how the assign participant operation works:

The following sequence diagram shows how the remove participant operation works:

This feature and its varieties have been implemented in a relatively straightforward manner, as the Class Diagram below showing the high level representation of the Object Oriented solution devised to implement this feature highlights.

From the above diagram it can be seen that each different implementation of the score command inherits from the same ScoreCommand abstract class. The ScoreCommand abstract class provides a base for the implementation of the current specific score commands and in the future any further additions made to the score command functionality must also follow this same convention.

Secondly, there is no ResetScoreCommand class. This is done intentionally as the SetScoreCommand can be reused to reset a particular team’s score, thereby making better use of abstraction.

A representation of how the above classes interact to provide execute a user’s command is highlighted in the sequence diagram below. This sequence diagram illustrates the object interactions when a user types the command score add T-1 40. For context, this command adds 40 points to the team with ID "T-1".

As seen from the above diagram, the execution of the score add command can be put in simple words as per the following steps:

Though the above diagram and steps are designed in the context of a score add command, the logic applies to every other type of score command as well. The only difference is that the ScoreCommandParser creates the appropriate command object for the command and each command object calls a different method from Model, as per the following:

To develop the score feature a few considerations and decisions had to be made with regards to how to implement the feature at various steps. This section focuses on some of the aspects wherein we faced dilemmas and how we addressed them.

The implementation of these two commands is very similar in nature. They both:

The class diagram below provides a high level representation of the Object-Oriented solution devised to implement the leaderboard and getTop K commands.

From the above class diagram, there are two important matters to note regarding the implementation of these features:

With the class structure covered, the following sub-sections explain how the different classes in Alfred interact to produce a result for the user, and finally the design considerations that were made for each command.

The leaderboard command fetches a leaderboard consisting of all the teams registered for the hackathon, in descending order of their score. Moreover, if the user specifies a SubjectName then the leaderboard will only consist of teams with that particular subject.

Additionally, if tiebreak methods are specified, ties between the teams will be broken in one of two ways (or a combination of both):

Given below is the sequence diagram illustrating the flow of events which generates a result for the user when he types the command leaderboard tb/moreParticipants s/Social. For your reference, here the prefix "tb/" is used to precede a tie-break method, "moreParticipants" is a tie-break method which gives a higher position to teams with more participants, and "Social" is a SubjectName within Alfred. Essentially this demonstrates the flow for a "Comparison-based tiebreak".

The observations of the above diagram can be put into the following steps:

This flow of events, albeit a few differences, is the same for every variation of the leaderboard and getTop K commands explored subsequently.

Do note that if the user’s input did not specify any tie-break methods, hence just being leaderboard s/Social then the SimpleLeaderboardCommand object would be created with an empty ArrayList of comparators. If the user’s input did not specify any subject, hence just being leaderboard, then the SimpleLeaderboardCommand object would be created with the SubjectName variable "subjectName" being null, in which case no filtering of sortedTeamList takes place. The flow of events for this particular scenario would be unchanged from the above illustration.

The leaderboard command with the tiebreak method random follows a slightly different sequence. Given below is the sequence diagram illustrating the flow of events when the user types the command "leaderboard tb/moreParticipants random". For your reference, here the prefix "tb/" is used to denote a tie-break method and "moreParticipants" is a tie-break method which gives a higher position to teams with more participants, and "random" is another non-comparison based tie-break method.

The above sequence follows the exact same logic as that for the Simple Leaderboard as explained above.

However, in this case the LeaderboardWithRandomCommand class calls the setTopK(teamListSize, comparators, subjectName) method of Model which essentially filters out the teams with subject "subjectName", breaks any remaining ties after applying the tie-break methods between teams on a random basis, and fetches a number of teams equal to teamListSize which is the size of the sortedTeamList, thereby reflecting the total number of teams in the hackathon.

Secondly, Model calls its own method setSimpleLeaderboard(comparators, subjectName) which was used for the leaderboard command without random tiebreak. This method abstracts the process of clearing sortedTeamList of any sorting, filters it by SubjectName if required, and then applies the new comparators to it. It is used to fetch and appropriately sort the appropriate teams in sortedTeamList before the algorithm for random winners can be applied to the sortedTeamList.

There were several questions we asked ourselves over the course of developing the leaderboard feature. The following contains certain aspects we had to consider during the development stage and details how and why we decided to use a certain methodologies over others.

The getTop K command fetches the top "K" number teams sorted in descending order of their points, where K is a positive integer inputted by the user. The getTop K command follows a similar pattern as the leaderboard command in the sense that ties between teams are broken in one of two ways (or a combination of both):

Given below is the sequence diagram illustrating the flow of events which generates a result for the user when he types the command "getTop 3 tb/moreParticipants". For your reference, here the prefix "tb/" is used to denote a tie-break method and "moreParticipants" is a tie-break method which gives a higher position to teams with more participants. This essentially reflects a tie being broken by comparison-based tiebreakers.

The above diagram follows a logic very similar to the leaderboard command’s logic, and can be broken down into the following steps

It is noteworthy that Model calls its own method setSimpleLeaderboard(comparators) which was associated with the leaderboard command. This is however a simple reuse of code to set the reset Model 's sortedTeamList, filter it by the subject if needed and apply the relevant comparators to it, before the algorithm for fetching the top three (or any number) teams can be applied.

When it comes to the getTop K command being used with the "random" method of tiebreak, the flow of events is resembles the above very closely. Given below is the sequence diagram illustrating the flow of events which generates a result for the user when he types the command "getTop 3 tb/moreParticipants random". For your reference, here the prefix "tb/" is used to denote a tie-break method and "moreParticipants" is a tie-break method which gives a higher position to teams with more participants whereas "random" represents the "random" method of tiebreak.

From the above diagram it can be inferred that the implementation of random winners does not deviate far from the implementation without random winners.

The first difference is that the TopTeamsCommandParser object now returns a topKRandomCommand object. Secondly, the topKRandomCommand object calls the setTopKRandom(3, comparators, subjectName) method of Model. It essentially modifies the sortedTeamList within Model to only show the top three teams (within a certain subject category if specified) as per their scores and the relevant tiebreakers as per the list of comparators comparators, and breaks any remaining ties based on the random method.

Since the implementation of the getTop K command is almost identical to that of the leaderboard command, the design considerations made for the leaderboard command apply to the implementation of this feature as well (See Section 4.10.3, “Design Considerations”). However, there were some unique aspects we had to consider with regards to the getTop K command, all of which is detailed below.

In the above sections, the UML diagrams gloss over how tiebreaking and filtering by subjects is parsed and understood by Alfred. This process is better explored in this section as per the explanations below.

The basic of tie-breaking revolves around using Comparator s to sort the teams in a particular order. Each tiebreak method available in Alfred has a Comparator associated to it and all these can be found in the Comparators class.

The basic of filtering by subject revolves around the SubjectName input parameter to the LeaderboardCommand and GetTopTeamsCommand classes. The user’s specified subject is parsed and used as an input parameter in the aforementioned classes' constructors, which they then use for filtering the sortedTeamList in Model.

The activity diagram below illustrates the internal workings within the LeaderboardCommandParser and TopTeamsCommandParser when parsing tiebreak methods and the subject. Do note that in the below diagram the term Parser encapsulates both of these Parser s as they operate in almost identical ways.

From the above there is one important aspect to note: the ArrayList of Comparator<Team> objects created in the second step. This is the ArrayList referred to in the previous sections which is tasked with containing and transferring the comparators which will be used to sort the teams in their appropriate order to form the leaderboard or top teams. This ArrayList is used as an input parameter for both leaderboard and getTop K command related classes, as explored in previous sections.

Additionally, before comparators can be passed as an argument to the commands, it is reversed. This is done intentionally so the comparators related to each tiebreak method are applied in an order such that they preserve the oder the user wants the tiebreak methods to be applied.

Secondly, if no subject is specified by the user, then the default value of the subjectName variable (of type SubjectName) is null. This signals to methods in Model (when the command is executed thereby calling Model 's methods) that no filtering of the sortedTeamList is required.

Note that the diagram above assumes there are no syntax errors made by the user when typing out the command. In case of any errors in the command, a ParseException would be thrown warning the user of such a situation. These have been excluded from the above diagram to prevent overcrowding and a deviation from the basic logic.

Though this was a relatively straightforward subset of our leaderboard and getTop K command, there were still a few, small design considerations made.

The following sequence diagram shows the sequence of method calls used to display the filtered list on the application, from Logic to ModelManager upon the execution of a FindParticipantCommand. An analogous sequence diagram also applies for the Team and Mentor objects as well.

The left half of the diagram covers creation of the FindParticipantCommand while the right half details the interaction with the Model. There are 5 main steps in the execution of the command.

The following are some design considerations for the find Command Feature