README - 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.

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,

In order to implement the multiple commands for the application, we require a way to disallow certain commands in certain contexts.

For example, when the user is viewing the archives, commands he enter are parsed in the "Archive context" as shown above. If he enters the archive command, it will not be recognised as a valid command since every entry shown is already archived.

When a user is uses the list command, he switches to the "List context". Now, when he enters the archive command with valid arguments, it is successfully executed. However, the unarchive command will now not be recognised.

This presents two main problems; the need for separate command parsers for each context, and a way for the application to keep track of its context.

Ultimately, Alternative 1 was chosen because we later decided that context should have a one-to-one correspondence to which entrybook to display to the user (refer to Section 3.5, “Multiple EntryBooks”), in addition to being the option which required the least modification to the rest of the code base to implement.

Autofill-related code lies in the EntryAutofill utility class. The constructor takes in the original Title and Description, and there are methods to parse URL and HTML in order to extract replacement candidates, as well as to get the best Title and Description candidates.

The fallback is a default Title and Description guaranteed to work. The first attempt to find replacement candidates is by parsing just the URL. This will work even if there is no Internet access, whereas the following attempts require Internet access. The next attempt is by using the Jsoup library to parse the raw HTML into a Document object and obtain information likely to be present, and the last attempt is by using the Readability4J library to process the Document object and extract metadata. In this way, the last successful attempt to replace Title and Description becomes their current best replacement candidate. Since we cascade from the last choice to the first choice for Title and Description separately, by the end we have found the best possible replacement candidate for each of them given the circumstances. However, replacement candidates are only chosen if the original Title and Description are empty, so the original user input is still the first choice, followed by the best replacement candidates found.

This means that if both Title and Description are already specified by the user, AddCommand just adds the Entry to the Model. Otherwise, AddCommand attempts to find replacement candidates for a missing Title or Description heuristically, then updates the Entry with the best replacement and adds it to the Model.

Available view types are specified in the ViewType enum, and available reader view styles are specified in the ReaderViewStyle enum. The ViewMode object encapsulates a ViewType and ReaderViewStyle and represents a user setting. The Model exposes an observable viewModeProperty, which is set by ViewModeCommand and observed by BrowserPanel.

The BrowserPanel is a wrapper around the JavaFX WebView component, and is responsible for displaying web pages. It keeps track of whether an internal page, offline page, online page or HTML content is loaded, and reacts to events like changes in loading status, view mode and selected entry.

There are two conditions which cause reader view to be generated and loaded:

The Jsoup and Readability4J external libraries do the heavy lifting of parsing the raw HTML currently loaded in the WebView to extract useful metadata and content. Jsoup was chosen as it is a mature HTML parser library while Readability4J was chosen as it is a port of port of Mozilla’s excellent Readability.js. These are combined into a new HTML document, which is styled using Bootstrap and then loaded in the WebView.

As Readability4J does not extract all available and useful metadata information, Jsoup is used to manually extract author information, as well as Open Graph metadata like published datetime and section information if available. As Readability4J also does not provide the estimated reading time, Jsoup is used to extract text content from the HTML DOM Document Object, and reading time is estimated from the number of words present and the average human reading speed.

We define a new static class FeedUtil in commons.util. FeedUtil is primarily in charge of fetching a web feed from a URL and serializing its contents into an EntryBook. The advantage of this approach, which is why we decided to use it, is because keeping all the feed handling code in a single class restricts the dependency of ROME at the program boundary, which is more maintainable.

Another approach we can consider is to directly invoke ROME whenever we deal with web feeds.

Reading Entries from a web feed shares a major similarity with reading a stored EntryBook from disk. Both actions serialize an EntryBook from a source of external data. To apply this general observation we can consider the following design.

To support multiple EntryBooks, we decided to have multiple differently named EntryBooks each with their own accessors.

Another task is to decouple the EntryBook that is displayed from the ones that we added to ModelManager. Decoupling the displayed EntryBook means that the following additional methods are implemented

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

This component is depended on by the following components:

Thus, our design needs to take into consideration how it is going to be used.

Because it’s possible that the settings we use to fetch resources may need to be changed over time (e.g. timeouts, request headers, cookies, etc.), we should centralise the design to one component so that these can easily be changed. Obviously, this component should be easily accessible from all the components listed above. Finally, the interface for this component should be general and apply to all use cases because we have a large mix of possible requests: articles, feeds, or other resources.

The only way we can make this component easily accessible is to make it global. However, there are a couple of ways to design a global component. The following sections describe the patterns considered.

This pattern is to create a new class named Network. This class is abstract so it cannot be instantiated, and all its methods are marked private.

This pattern is very similar to the pattern above. We create a new class named Network, and a static getter method that returns a single instance of Network. This allows us the flexibility of working with objects rather than with static methods.

We could also choose to directly call the network API from whatever calling methods would have called Network before. This is the simplest "pattern" as it involves not writing any code.

Ranking the patterns from least effort to most effort, we have ad-hoc being the easiest, followed by static class, and finally singleton.

Generally, the less code, the better. This is usually the primary consideration. This means if there are two patterns where both meet some minimum quality standard but one takes more effort, we should go with the one that takes less effort to write.

We did not choose the ad-hoc pattern because we anticipate future changes to the networking code as we take into account more details like timeouts, asynchronicity, cookies, etc. In other words, this led us to prioritise good cohesion in our desired pattern.

However, aside from this, both singleton and static class pattern have roughly the same benefits. We do not yet need to consider things like dependency inversion because Network calls are decidedly a very global concept which makes it less applicable. Using the singleton pattern would have improved testability of our code, but it would have required rewriting many of our classes to use dependency inversion, and this makes the code more complex.

So this is why we went with the static class pattern, which has effectively the same benefits as singleton after ruling out dependency inversion, and the static class pattern is easier to write than the singleton pattern.

As the entirety of addressbook-level4 (AB4) is written synchronously, it is a major undertaking to convert AB4 to use asynchronous (async) network calls. We did a small scale experiment to see how async might be done by making the select command download un-downloaded articles in the background.

Here is a sequence diagram showing how the interaction works:

Notice that when returning from the async network call, we wrap our code in Platform.runLater(…​) to ensure that the rest of the execution is done on the JavaFX Application Thread. This helps to prevent certain race conditions from potentially ruining the model.

However, in the process of implementing this, we found that it made testing this unreliable as we could no longer be sure when the command has "truly" finished executing. Thus, we decided to defer the conversion of the rest of the AB4 to async to the v2.0 milestone.

After the architectural changes were made, there are a few design considerations that needed to be made:

As an example, what happens when viewing an entry with offline mode enabled? This is summarised by the activity diagram below:

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

Examples:

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