The Infinity Machine - Developer Guide

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

After forking the repo, the documentation will still have the SE-EDU branding and refer to the se-edu/addressbook-level4 repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to se-edu/addressbook-level4), you should do the following:

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

When you are ready to start coding,

The restore feature is facilitated by Infinity Machine. It extends Infinity Machine with a recycle bin feature, allowing user to delete and restore source from a persistent deleted sources list. The Recycle Bin was extended from interactions with the delete command. Our rationale to create an entire mode is so that users can safely delete sources and have a place to access and retrieve them even after exiting the application accidentally or intentionally. Previously, this feature was implemented seperatedly as a restore and delete feature in the source manager however, after testing it, it proved to be very messy and confusing for our users if they did not had a mode that specifically allows them to interact with the deleted sources.

This sequence diagram shows what happens when a source is deleted pertaining to the recycle bin.

Given below is an example usage scenario and how the recycle bin mode behaves at each step when a user deletes and restores a source.

Step 1. The user launches the application for the first time. The Infinity Machine will be initialized with the initial source database state, by default listing all the sources in an indexed fashion, with all details and in order of their addition.

Step 2. The user executes delete 1 command and only one entry, the first one, is deleted.

Step 3. The user executes recycle-bin command and the Infinity Machine switches from the Source Manager mode to the Recycle Bin mode. A list of sources that was previously deleted in the Recycle Bin is shown.

Step 4. The user executes restore 1 and only one entry will be deleted, which is the source recently deleted in the Source Manager mode.

Step 5. The user executes exit-bin and only switches the Source Manager mode.

The user’s original data is replaced by dummy data for the duration that panic mode is enabled. Enabling panic mode can be thought of as "stashing" the user’s data temporarily in memory. This is reflected both on-screen and on-disk. On the screen, the list of sources is replaced by an empty dummy list. On disk, the contents of the JSON file storing the user’s sources is replaced by dummy content that tracks and reflects the dummy data.

This is implemented by "swapping" the source manager with an empty dummy source manager. This "swap" is carried out by storing the original source manager in a private variable sourceManagerBackup, and then resetting the original source manager with a new empty source manager instance. We also set the boolean variable panicMode = true.

When the user disables panic mode, we restore the original source manager, and reset panicMode = false.

We use a boolean variable panicMode to keep track of whether panic mode has been activated. This is to guard against the scenario of entering panic mode while already in panic mode, which results in permanent data loss.

This is because when panic mode is activated, we store the original source manager in the private variable sourceManagerBackup, and reset the original source manager, as described above.

Therefore, should panic mode be activated while already in panic mode, sourceManagerBackup will now store the dummy source manager, and the original source manager will be deallocated and eventually purged from memory by Java’s garbage collector.

Since the JSON file on disk automatically tracks the source manager through the observer pattern, it automatically updates to track and reflect the data in the dummy source manager.

This feature is backed by an in-memory database implemented as a Java HashMap<String, String>. A HashMap is chosen for the following reasons:

Alternative: No reasonable alternative implementations exist. For instance, using a Java ArrayList adds additional code complexity, as there needs to be a way of associating a key with a value. For instance, we could create an ArrayList<AliasWrapper>, where AliasWrapper is a wrapper class to associate 2 strings. However, that is inelegant and inefficient, as opposed to a HashMap solution. Furthermore, checking for membership in an ArrayList is an O(N) operation in an unsorted list, or O(log(N)) in a sorted list.

Meta-commands are not implemented as regular commands. Regular commands inherit Command, and operate on the model (their main method is public CommandResult execute(Model model, CommandHistory history) throws CommandException {}). On the other hand, meta-commands operate on an AliasManager object. Therefore, it is desirable to draw a distinction between regular commands and meta-commands throughout the codebase.

To implement aliasing, we first create an AliasManager interface to practice design by contract. AliasManager is command-agnostic. It operates through its API (specified in the interface), and is not concerned with the choice of meta-commands (e.g. alias-rm vs alias-remove). We also created a class ConcreteAliasManager to implement the AliasManager interface.

As for SourceManagerParser, we created an alternative constructor to accept an AliasManager object to support dependency injection. Otherwise, the default constructor instantiates ConcreteAliasManager.

To implement the meta-commands, we create an abstract superclass AliasMetaCommandParser that implements Parser<DummyCommand>. This serves as an alternative class of command parsers (for meta-commands), in contrast to the regular ones which are of the type Parser<? extends Command>. (As mentioned above, meta-commands are fundamentally different from regular commands, and it is desirable to maintain this distinction.) The key difference between the two is that an AliasMetaCommandParser has a field storing a reference to the AliasManager object which it requires to interact with (e.g. when adding/removing an alias).

Finally, we create a CommandValidator interface. AliasManager uses the CommandValidator for two purposes:

We chose this implementation and design pattern for several reasons:

The usefulness of aliases would be significantly diminished if they do not persist between sessions. Therefore, we want aliases to be stored on disk and automatically loaded in future sessions on application startup.

To accomplish this, we create an AliasStorage interface, and an implementing class ConcreteAliasStorage. We also modify ConcreteAliasManager to accept an AliasStorage object during its instantiation. To facilitate unit testing, we allow a null AliasStorage object which disables data persistence.

ConcreteAliasStorage is responsible for reading/writing from/to disk, and therefore converting the in-memory database (HashMap object) of aliases into/from an encoded representation. When AliasManager’s aliases database is mutated (i.e. create or remove alias), it calls ConcreteAliasStorage’s saveAliases() method.

Within ConcreteAliasStorage, its saveAliases() method encodes aliases and commands into a string, in the following format: alias1:command1;alias2:command2;alias3:command3. Conversely, readAliases() parses this string and reconstructs the aliases HashMap database.

The undo/redo mechanism is facilitated by VersionedSourceManager. It extends SourceManager with an undo/redo history, stored internally as an sourceManagerStateList and currentStatePointer. Additionally, it implements the following operations:

These operations are exposed in the Model interface as Model#commitSourceManager(), Model#undoSourceManager() and Model#redoSourceManager() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedSourceManager will be initialized with the initial source manager state, and the currentStatePointer pointing to that single source manager state.

Step 2. The user executes delete 5 command to delete the 5th source in the source manager. The delete command calls Model#commitSourceManager(), causing the modified state of the source manager after the delete 5 command executes to be saved in the sourceManagerStateList, and the currentStatePointer is shifted to the newly inserted source manager state.

Step 3. The user executes add i/algorithm …​ to add a new source. The add command also calls Model#commitSourceManager(), causing another modified source manager state to be saved into the sourceManagerStateList.

Step 4. The user now decides that adding the source was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoSourceManager(), which will shift the currentStatePointer once to the left, pointing it to the previous source manager state, and restores the source manager to that state.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoSourceManager(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the source manager to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify the source manager, such as list, will usually not call Model#commitSourceManager(), Model#undoSourceManager() or Model#redoSourceManager(). Thus, the sourceManagerStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitSourceManager(). Since the currentStatePointer is not pointing at the end of the sourceManagerStateList, all address book states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add i/algorithm …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command:

Format: search [n/TITLE] [y/TYPE] [d/DETAILS] [t/TAG] [t/TAG]…​

The search feature is facilitated by Infinity Machine. It extends Infinity Machine with an find feature, allowing user to search through source entries by the title, type, detail and/or tags, with substring matching.

This search function now has an added functionality of being able to take in multiple arguments of the type of source fields [i.e. title, type, detail and tags], and search for sources based on that. It searches in conjunction using multiple fields including title, type, detail and tag(s) input by the user, listing only those sources that satisfy all the input constraints of the matching fields, with all there corresponding field values.

Another addition to its functionality is that this search feature is enabled with substring matching as against exact field matching. This renders this feature more powerful as the user may not always be able to remember exactly the title or tag of the source. It’s major usage is in the fact that the user will store the bulk of their data in the details field, and it is unintuitive to have them list the entire contents of the source in order to match and search it. Thus now, the user is only required to search using as many consecutive words they are able to recall to narrow the listings.

How it works is, it allows the user to search through all the entries in the database through various fields at a time, and display source entries that satisfy all of the entered tags in conjunction, by checking if the source value contains these parameters. It allows compound searches to be made, allowing user to narrow down their search, hence helping in efficient retrieval of the sources, and making working on the database more efficient.

Lastly, the search is able to find string matches with minor typing errors in the spelling. This feature renders the search more powerful by accommodating any minor typing error user may make when keying in their search argument. This includes minor flips of two characters or a missing character or few extra characters etc. The implementation current accounts for less than 5 character swaps needed to transform between the strings.

i.e. misspelling a single word in the title will not be caught unless the entire title is entered, then the user entry will be matched against the entire title to see if there are less than 5 corrections needed to transform between the two strings.

However, it may seem that such an additional renders the search feature a bit too general, thus making the search output space broadened by including more sources that would have otherwise been ignored. But, one may see this as an advantage as:

This distance is know as the Levenshtein distance or the edit distance, after the Russian scientist Vladimir Levenshtein who devised the algorithm in 1965. This algorithm is used to determine how different two strings are from each other by outputing the integer number of transformations (insertions, deletions and substitutions) needed to transform one string to the other.

The algorithm implementation for this section of the code was inspired from Baeldung.

Additionally, it uses:

Given below is a sequence diagram representation of the search command of the Infinity Machine:

This feature improves the product significantly because a user can now search an entry with a particular title AND a particular type and so on. Not only that, the user can now just input whatever they are able to recall and the search returns all super strings instead of carrying out an exact matching. It helps user greatly narrow down their search should they be looking for a specific source entry with particular values, instead of cluttering the screen with all those sources with share the same title as the one the user searches using the command. It renders the search more powerful by resulting all super-strings should the user have meant something else or to prompt them about other similar source entries containing what they are looking for. It also allows user to search sources based on other fields and not just title, such as type, tags and details, and even their logical combination.

Given below is an example usage scenario and how the search mechanism behaves at each step.

Step 1. The user launches the application for the first time. The Infinity Machine will be initialized with the initial source database state, by default listing all the sources in an indexed fashion, with all details and in order of their addition.

Step 2. The user executes search i/algorithms command and only those sources that have their title as algorithms are displayed.

Step 3. The user executes search i/homework y/website and only those entries are listed that have both their title as homeowork and type as website.

Step 4. The user executes search t/CS and all those sources that have any of their tags having 'CS' in it listed, including CS2030, CS2040 and CS2103

Step 5. The user executes search i/algorihtm as a typing error, the command still displays all those sources that have their title as algorithms or other related words exactly [not contains].

Step 6. The user executes search d/training an intelligent agent t/CS2039, the search displays all sources with having the exact sentence 'training an intelligent agent' or any of its related similar strings in it’s body, and those with tag 'CS2039' or any of the related modules such as 'CS2030', 'CS2040'.

The count command is facilitated by Infinity Machine. It extends Infinity Machine with a count functionality calculating the total number of sources retrieved from the database. Additionally, it uses:

Given below is an example usage scenario and how the count mechanism behaves at each step.

Step 1. The user launches the application for the first time. The Infinity Machine will be initialized with the initial source database state, by default listing all the sources in an indexed fashion, with all details and in order of their addition.

Step 2. The user executes count command. All entries retrieved using the command entered will be counted.

Step 3. The user executes a 'search' command to search for all entries matching a certain keyword.

Step 4. The user executes count command again. The count of the total number of entries retrieved through the search command will be returned.

Alternative: It can be implemented in the Model and ModelManager instead of directly in the execute command however, this is an inefficient implementation and thus is not used.

The list command is facilitated by Infinity Machine. It extends Infinity Machine with a list functionality, enumerating all or a specific number of entries in the source database and their all their details, in the order of their addition, or custom order as may be supported by the application.

The four main formats and their usages are described below:

The concept of pinned sources works on an index bases system rather than a separate list or any additional implementation. This allows pinned sources to function just like ordinary sources in that they can be searched and listed as normal.

Essentially, the pinned sources are governed by a single number within the ModelManager and is managed through a separate class called the PinnedSourcesCoordinationCenter. This coordination center is responsible for all operations which modify the number of pinned sources.

When a new source is pinned using the pin INDEX command, the coordination center will increment the number of pinned sources by 1 as well as bring the newly pinned source to the top of the list.

When a pinned source is unpinned using the unpin INDEX command, the coordination center will decrement the numer of pinned sources by 1 and move the unpinned source down to the position of the first unpinned source.

When a source is unpinned and there are other pinned sources, the recently unpinned source will be pushed back to the position of the first unpinned source.

An example of this could be unpin 1 command in a database with 3 pinned sources.

The first source will be unpinned and moved to the position of the first unpinned source, in this case position 3.

When checking to see if a source can be pinned or unpinned, the command will call on the coordination center to check if a source is already pinned or unpinned respectively. An already pinned source cannot be pinned again and an unpinned source cannot be unpinned.

These very same source checks will also be called during the delete and order commands. For the delete command, the coordination center will check if the source to be deleted is a pinned source. If so, then the number of pinned sources will decrement by 1. If not, it just carries on with the deletion as usual. For the order command, the coordination center will check both the source being moved as well as the move location. If either of these indexes are of pinned sources, the order command will fail.

For the pinned sources to be persistent, the number of pinned sources is updated into an external text file whenever a change is made to the number. This is consistent with the source database itself so the reordering of the sources when something is pinned or unpinned will occur together with the update to the number of pinned sources.

The external storage is handled by a simple class called the PinnedSourcesStorageOperationsCenter which contains the path of the file which the number will be saved to.

Dynamic pathing was necessary because when testing the function using a default file path, changes made during the test were saved to the actual file and that caused major problems for the program. Dynamic pathing ensured that for testing, a separate test file is written to thus maintaining the integrity of the actual file.

Pinned sources are denoted by a little golden badge on top of the source that says "Pinned". This is kept updated vis a flag set in the source object itself.

At the start of the program, the ModelManager will use the number of pinned sources retrieved from the external storage to assign the flags accordingly. Every time a function affects the pinned sources, namely delete, pin and unpin, is called, the flag will be appropriately updated as well for consistency.

It is important to note that the flag itself is not stored externally and is not persistent. It is assigned at the start of every session and modified accordingly as the functions are called. The rationale behind this implementation choice is to ensure that the external source storage is kept as clean and minimalist as possible.

The function is currently implemented using the functionality of the source model. It allows users to designate a source they want to move and a location they want to move it to.

The primary uses of this feature are to facilitate source management and ordering sources by some user defined metric like personal importance.

Given the function works purely on the parameters the user enters, a parser file was necessary to filter out invalid inputs like alphabets or special characters.

Further consideration was necessary because of nature of the inputs. The inputs are array indexes which are very prone to being out or bounds that can result in system failures. Therefore, in addition to traditional exception handling, the function also implements its own checks for invalid user indexes.

These check include the following:

Once the inputs are deemed as valid, the actual moving can begin. The model uses a list implementation for its primary storage model. This means that when a source is moved to a location, every source around it will need to be shifted to the front or the back depending on where the original source originated at.

Thankfully, the Java List implementation does come with the function to add an item to the lest at a particular index, pushing everything aside automatically. The function called addSourceAtIndex was added to the model which took in the source to add as well as an index which the source should be added at.

The function takes the following steps to make the swap:

The process for swapping is slightly different for each type of swap, namely forward swapping and backwards swapping.

Given that the Infinity Machine is used to manage sources, a user might reasonably expect to use the information stored to generate usable bibligraphy entries. This functionality is implemented by the biblio command and the biblioEdit command.

When a Source object is created, in addition to the compulsory fields of Title, Author, Type, and Detail, it is also created with a set of BiblioFields for storing additional information that might be needed for creating a bibliography entry.

BiblioFields is used to store information under the following headers: "City", "Journal", "Medium", "Pages", "Publisher", "URL", "Website", "Day", "Month", "Year"

BiblioFields is empty by default.

The biblio command extends Infinity Machine with a bibliography generating functionality.

It is currently implemented with the following syntax: biblio INDEX FORMAT

An example would be biblio 1 APA.

When the command is entered, the following occurs:

Extensions: Future implementations can include additional supported source types.

The biblioEdit command is a supporting command for the Biblio feature. It is responsible for changing the information stored in the BiblioFields of a source.

It is currently implemented with the following syntax: biblioEdit INDEX HEADER BODY

An example would be biblioEdit 1 City London

Alternative: The bibliofields of a source can be set at object creation with the add command. However, this makes using the add command excessively onerous. The current implementation allows the user to change each field as needed and preserves the information stored under the other headers in Bibliofields.

Extensions: A future implementation may allow information under multiple headers to be edited at once. Additionally, checks can be introduced to ensure the entered field bodies are appropriate e.g. the Month bibliofield should only accept values matching the English name of months.

Given below is an example usage scenario and how the BiblioEdit mechanism behaves.

Edits the remark for a source specified in the INDEX.
Format: remark INDEX r/[REMARK]

Examples:

See this PR for the step-by-step solution.