Car Park Finder - 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 look at how to configure Intellij to check style-compliance as you write code.

Set up Travis to perform Continuous Integration (CI) for your fork. See how to setup Travis to learn how.

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

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

The mechanism does an API call to the website data.gov.sg to obtain car park information in JSON format. An external library Gson is used to parse the data in GsonUtil. The data is stored internally as a CarparkJson object.

Some notable methods that GsonUtil implement are:

Only GsonUtil#fetchCarparkInfo() is used in QueryCommand, inside QueryCommand#readCarpark() method.

Given below is an example usage scenario of how the query mechanism behaves at each step.

Step 1. The user launches the application, where the initial state of Car Park Finder is not up-to-date with the latest data published by data.gov.sg.

Step 2. The user executes the query command to fetch the latest data. The query command calls GsonUtil#fetchCarparkInfo() which in turn runs GsonUtil#getCarparkData() and GsonUtil#getCarparkAvailability().

Step 3. The user waits for data to be updated. GsonUtil#getCarparkData() establishes a connection with the API to read JSON data containing basic car park information.

Step 4. The JSON data is parsed using Gson library and stored inside CarparkJson. A HashSet is used to consolidate all the car parks and prevent duplicate entries.

Step 5. Once GsonUtil#getCarparkData() is done getting all the basic car park information, GsonUtil#getCarparkAvailability() retrieves additional details of the parking lot. The process is similar to how GsonUtil#getCarparkData() retrieves data from the API.

Step 6. GsonUtil#getCarparkAvailability() appends the additional the parking lot details using CarparkJson#addOn()

Step 7. Next, a final check is done to see if there is any car park with no parking lot data. The value '0' is added if there is no data.

Step 8. Finally an ArrayList<ArrayList<String>> is returned from GsonUtil#fetchCarparkInfo() to update the car park finder state. The line of text at the bottom of the application then will show that the application is updated.

Please refer to the Figure 11 below for how the query operation works.

To find out why certain designs were chosen for the query feature, please read the following section for the explanation and reason behind such choices.

The find mechanism is facilitated by FindCommand and FindCommandParser. It extends Command and implements the following operations:

The find mechanism is supported by FindCommandParser. It implements Parser and contains the following operations:

The predicate CarparkContainsKeywordsPredicate takes in a list of strings and checks if any of the strings matches the name or address of a car park fully or partially.

The diagram above describes how the flow of a find command would execute. It rely on FindCommandParser to ensure the variables are correct.

Given below is an example usage scenario of how the find mechanism behaves at each step.

Step 1. The user launches the application for the first time.

Step 2. The user executes find punggol command to get all car parks in punggol. The find command calls FindCommandParser#parse().

Step 3. The entire list of car parks is filtered by the predicate CarparkContainsKeywordsPredicate, which checks for the keyword punggol.

Step 4. The filtered list of car parks is returned to the GUI.

The flow chart below describes the user interaction with the application and how it processes it.

The filter mechanism is facilitated by FilterCommand and FilterCommandParser. The filter mechanism can filter car parks by the following criteria. The corresponding flag of each criterion is also indicated below.

The FilterCommandParser extends Parser and implements the following operation:

The FilterCommand extends Command and implements the following operation:

The FilterCommand is able to filter car parks by multiple criteria at a time.

Given below is an example usage scenario of how the filter mechanism behaves at each step when filtering with the following criteria:

Step 1. The user launches the application.

Step 2. The user executes filter ct/ COVERED f/ SUN 11.30AM 3.30PM a/.

Step 3. After CarparkFinderParser detects filter as the command word, a FilterCommandParser is created to parse the arguments supplied to the command.

Step 4. The FilterCommandParser splits the arguments by white spaces and store them into List<String> argumentsList.

Step 5. Then, it identifies the flags present in List<String> argumentsList and store them in List<String> flagList.

Step 6. FilterCommandParser also parses the parameter(s) of each flag, and throws ParseException when necessary.

Step 7. Parameters of ct/ and f/ are packaged into CarparkTypeParameter carparkTypeParameter and FreeParkingParameter freeParkingParameter respectively. They are then passed to a newly created FilterCommand together with List<String> flagList.

Step 8. The FilterCommand object obtains the last predicate used by FindCommand from model and creates the CarparkFilteringPredicate.

Step 9. Besides filtering by the last predicate used by FindCommand (location), CarparkFilteringPredicate has a series of if statements that checks which flags are present in List<String> flagList, before looking into the parameters of the flags.

Step 10. To combine the filtering criteria, a boolean variable, collective, is used. The following snippet of code shows more clearly how it is used.

Step 11. The list of car parks is filtered against the predicate and returned to the GUI.

Please refer to the Sequence Diagram below for the filter operation.

The calculate mechanism is facilitated by CalculateCommand and CalculateCommandParser.

Given below is an example usage scenario of how the calculate mechanism behaves at each step when the user wants to know the cost of parking at car park W49, on a Monday, from 9.00am to 5.30pm.

Step 1. The user launches the application.

Step 2. The user executes calculate W49 SUN 9.00AM 5.30PM.

Step 3. After CarparkFinderParser detects calculate as the command word, a CalculateCommandParser is created to parse the arguments supplied to the command.

Step 4. The CarparkFinderParser splits the arguments by white spaces, then creates a CalculateCommand object.

Step 5. CalculateCommand creates a CarparkIsOfNumberPredicate to find the specified car park, car park W49, from the list of car parks.

Step 6. CalculateCommand checks if the car park W49 has short-term parking.

Step 7. As some car parks only has short-term parking between certain timings, CalculateCommand checks if the parking time input by the user is valid.

Step 8. After which CalculateCommand checks of there is free parking on Monday between the specified time. Since there is no free parking during that time period, it will calculate the cost of parking by the standard rate of $0.60 per half an hour.

Step 9. The calculated cost is then returned to the GUI as a command result.

The following Activity Diagram summarizes the implementation of the calculate command.

The notify mechanism is facilitated by NotifyCommand and NotifyCommandParser. It enables notifications at a given interval and disables notification when it detects that the interval is set to '0'.

The NotifyCommandParser implements Parser with the following operation:

When notification is enabled:

Take a look before at the code snippet below for more details on how NotifyTimeTask works.

Given below is an example usage scenario of how the notify mechanism behaves at each step.

Step 1. The user executes select 10 to select the 10th car park in the list.

Step 2. The user then executes notify 10, indicating the interval to be 10 seconds.

Step 3. The NotifyCommandParser#parse() gets called to parse the arguments supplied. It checks if the interval is valid non-negative integer, in the range of 10 to 600 and including 0.

Step 4. A new instance of NotifyCommand is created by NotifyCommandParser, and the argument then gets stored as int targetTime in NotifyCommand.

Step 5. Inside NotifyCommand, ScheduledExecutorService#scheduleAtFixedRate() starts NotifyTimeTask#run() with targetTime as one of the parameters passed in. This sets NotifyTimeTask to run and repeat every targetTime.

Step 6. When NotifyTimeTask#run() is active, GsonUtil#getSelectedCarparkInfo() gets called and fetches the data from the database. It returns the specific car park to be updated.

Step 7. To find which car park to be updated in the list, parallelStream() is used to filter through. Once it is found, Carpark#setLots() gets called to update the TotalLots and LotsAvailable variables.

Step 8. To show that the list of car parks is updated, NotifyCarparkRequestEvent() and NewResultAvailableEvent() are created to update the UI and display a message respectively.

Step 9. Every 10 seconds, the user will receive a notification on the number of available lots left for the 10th car park.

Step 10. The whole process will repeat itself starting from Step 6, until ScheduledExecutorService#shutdownNow() gets called by notify 0 which disables notification.

Figure 16 below summarises what happens when a user executes the notify command:

To find out why certain designs were chosen for the notify feature, please read the following section for the explanation and reason behind such choices.

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

These operations are exposed in the Model interface as Model#commitCarparkFinder(), Model#undoCarparkFinder() and Model#redoCarparkFinder() 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 VersionedCarparkFinder will be initialized with the initial car park finder state, and the currentStatePointer pointing to that single car park finder state.

Figure 17 below showcases the state at the start of the program.

Step 2. The user executes find sengkang command to find list of car park which contain sengkang from the car park finder. The find command calls Model#updateFilteredCarparkList(), causing the modified state of the car park finder after the find sengkang command executes to be saved in the carparkFinderStateList, and the currentStatePointer is shifted to the newly inserted car park finder state.

Figure 18 below shows a new state is created after the command find segkang is ran.

Step 3. The user executes clear to clear all entries. The clear command also calls Model#commitCarparkFinder(), causing another modified car park finder state to be saved into the carparkFinderStateList.

Figure 19 below shows a new state is created after the command clear is ran.

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

Figure 20 below shows a new state is created after the command undo is ran. The state pointer is moved.

Figure 21 below shows how the undo operation works.

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

Step 5. The user then decides to execute the command list. Commands that do not modify the car park finder, such as list, will usually not call Model#commitCarparkFinder(), Model#undoCarparkFinder() or Model#redoCarparkFinder(). Thus, the carparkFinderStateList remains unchanged.

Figure 22 below showcases what happen when a command that does not modify the state is used.

Step 6. The user executes clear, which calls Model#commitCarparkFinder(). Since the currentStatePointer is not pointing at the end of the carparkFinderStateList, all car park finder states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the find sengkang command. This is the behavior that most modern desktop applications follow.

Figure 23 below showcases when a new command is used after an undo.

Figure 24 below summarises what happens when a user executes a new command:

The abbreviation mechanism is facilitated by CarparkFinderParser. It extends the cases to allow command abbreviations to be parsed through parseCommand as well.

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

Step 1. The user launches the application for the first time. The LogicManager is initialized with an CarparkFinderParser.

Step 2. The user executes c command instead of calculate. The Matcher object in CarparkFinderParser splits the command text into command word and arguments, in which the command word is checked. Because it is an ambiguous abbrevation (we do not know if it stands for clear or calculate), it is rejected by throwing a ParseException

Step 2. The user now tries s command instead of select. The Matcher object in CarparkFinderParser again splits the command text into command word and arguments, in which the command word is checked. This time, it is checked that the input string is contained in one of the command words that is calculate. Therefore, it proceeds as if a select command is given.

The Activity Diagram above explains what happens when a user executes a f command.

The autocomplete mechanism is facilitated by CommandBox. It calls autocomplete() to displayFormat() if applicable command word is entered or to highlight the next parameter if full format is already provided in the command box.

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

Step 1. The user launches the application for the first time.

Step 2. The user enters fi in command box and then presses Tab . autoComplete() compares input through the list of applicable command words and abbreviations, and proceeds to displayFormat() because fi is an ambiguous COMMAND, it fails with an exception.

Step 3. User tries with fil again. It passes as part of the autocomplete command filter thus moves on to highlight its first placeholder, DAY, in the command line. As seen from the following diagrams.

Step 3. The user replaces DAY with an actual value, SUN, and presses 'Tab' key again. autoComplete() is called again, but because this time it checks that input isFilterCommandFormat, the next placeholder, START_TIME, is highlighted. Result is shown in the following diagram.

Step 4. The user continues step 3 until all placeholders are filled up with actual values and then presses Enter to execute this command.

The Activity Diagram above explains what happens when user presses Tab.

Currently, postal code data are stored in a separate file. This is due to it being too slow and unreliable to convert coordinate to postal code in real time. However, in order to generate the file, we went through every car park and found their respective postal code.

Step 1. The user launches the application.

Step 2. The system loads the file, postalcodeData.txt into a Hashmap<Long,String> using the GsonUtil#loadCarparkPostalCode() where the key is a hash and the value is a postal code.

Step 3. The system goes through every car park’s coordinates and hashes them together with GsonUtil#fnvHash(x,y) where x is the x-coordinate of the carpark and y is the y-coordinate of the carpark.

Step 4. If the key is found, it will return the value which is the postal code of the car park. If not, it will return the default value 000000.

Initially, we wanted to showcase real time updates when the user issues a command. This would mean updating the HTML accordingly. However, we did not want to just update it, we wanted to showcase the selected car park or the filtered list accordingly.

Step 1. The user launches the application and is greeted by this UI.

Step 2. The user selects a car park with a select command. E.g. select 10.

SelectCommand#Execute is called. If the input is valid, it creates a JumpToListRequestEvent event for BrowserPanel#handleCarparkPanelSelectionChangedEvent() to catch.

Step 3. The user then list all the car park with a list command. A ListCarparkRequestEvent is created and BrowserPanel catches the event to call BrowserPanel#handleListCarparkRequestEvent()

The HTML is refreshed to show all car parks.

The data encryption mechanism works by encrypting the information by a unique key generated by every users individual system. The key will stored in a secured location to prevent people from accessing it.

The two main files it will encrypt are:

This feature is coming in v2.0.