SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
EXAM PRE-WORK
OVERVIEW
The SOFT3202 Exam will comprise a custom piece of software you will develop during Weeks 11, 12, and 13, which you will further modify in the ‘long release’ window during the exam period with an extra set of instructions. In weeks 11, 12, and 13, you will be building a desktop GUI Java application, which consumes web APIs to achieve specified functionality.
The specification of your software is governed by a pair of APIs that vary from student to student. For each API you have levels of completion. The completion level will decide your Pass, Credit, and the Distinction mark.
Submission
As done in previous assignments, you will use a private GitHub repository located here: https://github.sydney.edu.au. The repository must be named SCD2_2021_Exam and you must add the following collaborators:
• jbur2821
• mmcg5982
• bsch0132
• ttho6664
This pre-work submission should only be modified up until 23:59 on the Sunday of Week 13 (06JUN). At this time, your work on the given features must have been completed – your work during the 48 hours of the exam itself must be based on the state of your repository at this time to be accepted.
Specifications
There are 4 sets of instructions you will be sent over the course of your work on this exam.
• This document: explains the work you will be doing in weeks 11, 12, and 13. The same for all students.
• An email indicating what APIs you have been assigned to work with. You should receive this soon
after this document is released.
• The ‘exam period modification’ specification: explains the work you will be doing in the 48-hour exam
window during the exam period. This will be released prior to the exam so you know what to expect,
but will not tell you what the modification is. The same for all students.
• An email indicating what your personal modification is. This will be sent at the beginning of the exam
window.
As always Ed announcements should also be considered part of the specification.
THE API
The APIs are divided up into 2 categories – an ‘input’ list API, and an ‘output’ list API (note that you may need to both send and receive information from either category, it is a thematic difference rather than a purely technical one). You will be assigned 1 API from each category – in essence your application will take information from one API and output it in some way through another.
You grade is determined by the completion level of the API. Each version will follow a similar scheme:
Page 1 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
PASS:
You will be given an entity, and you need to display information about it. This entity is derived from your input API. There may be multiple steps required to build this entity. You may need to perform an operation on this entity after you have derived it. Your task is to display this entity in a way that would be useful to a user – detailed UI requirements will not be mandated, but you should ensure that the presented information of your entity is easily readable, and the interaction is simple.
Instructions are given about the report that should be produced for your output API. This report is related to the entity you have built.
CREDIT:
Cached items: this is something you need to cache in your local SQLite database each time it is retrieved from the API. If a user requests a matching item, you need to ask the user if they would like to just use the cached version, or grab a fresh copy from the API (and update the DB version along with it).
DISTINCTION:
The distinction requirement is the same for all: you need to separate out the GUI thread from the API requests / database access thread. The GUI must remain live and responsive during API request. It is suggested to use the provisions in your chosen GUI library to help with this.
Other requirements
Note that the above requirements are feature requirements only, and should be considered as a ‘ceiling’ – that is, if you do not implement the Credit requirements, your maximum mark is 64%. How close to your earned ceiling your mark reaches, is based on the design, process, testing, style, and documentation requirements listed later, as well as from your work during the exam period itself.
INPUTS
Entity: The entity you need to derive from this API, and any extra features that are required. Report data: The data you will need to send to the output API when the user requests.
Database caching: What should be stored in the database and offered in place of a fresh web call.
https://www.abstractapi.com/holidays-api
Entity: This API works slightly differently as each API call will be small. Display a calendar, in which the user can flip through (page-per-month view). When the user clicks on a day, it will retrieve the necessary information about the chosen day and display a ‘This is a holiday’ or ‘This is not a holiday’ message, and update the day’s slot in that calendar with a visual indication of this state.
Report data: a list of known public holidays for a given month Note: Ask the user for a country on application start-up. Database caching: known holidays/not holidays
Page 2 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
https://coinmarketcap.com/api/documentation/v1/
Entity: Display a list of cryptocurrencies. Having selected one of the cryptocurrencies, display an info panel on that cryptocurrency. Given a base currency and an amount show the conversion in either direction.
Report data: data on a given cryptocurrency. Database caching: info on cryptocurrencies
https://currencyscoop.com/api-documentation
Entity: Display a list of fiat currencies. Having selected one of the fiat currencies, display an info panel on that currency. Given a base currency and an amount show the conversion in either direction.
Report data: data on a given fiat currency. Database caching: info on fiat currencies
https://www.abstractapi.com/ip-geolocation-api
Entity: Information on a given IP address including images. App should be able to display multiple requests (showing different IP addresses).
Report data: data on a given IP address.
Database caching: info on IP addresses (Image paths should be cached, the images themselves do not need to
be).
https://macaddress.io/api
Entity: Information on a given MAC address. Also display a counter for current credit balance. App should be able to display multiple requests (showing different MAC addresses).
Report data: data on a given MAC address. Database caching: info on MAC addresses.
https://www.linguarobot.io/
Entity: Information on a given word. If an audio link is available allow the user to play it. Report data: data on a given word
Database caching: info on words
https://developer.oxforddictionaries.com/
Entity: Given a word, check if it has an entry or a list of possible root forms. Given an entry, display an info panel about that entry.
Report data: data on a given entry. Database caching: info on entries.
Page 3 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
https://www.iqair.com/commercial/air-quality-monitors/airvisual-platform/api
Entity: Using sequential calls returning lists the user selects from, drill down from country, to state, to city, and display an info panel about that city including AQI.
Report data: data on a given city Database caching: info on cities
https://www.alphavantage.co/
Entity: Information on a given company code. Also include information about the company’s most recent annual cash flow.
Report data: data on a given company Database caching: info on companies
https://developer.edamam.com/food-database-api
Entity: Given a text-based search, display a list of matched items. Given a selected matched item, display that item’s nutrition
Report data: nutrition data on a matched item
Database caching: info on a matched item and the initial text-based search that yielded it. Caching should offer to yield this matched item either on a matching search term or attempting to retrieve the same item itself.
https://developer.marvel.com/
Entity: Given a specified Marvel character name, information on that character including image. Report data: data on a given character
Database caching: info on characters (Image paths should be cached, the images themselves do not need to be).
https://developers.pandascore.co/
Entity: Display a list of leagues (1x the default page size is enough here). Having selected a league, list the series for that league (1x the default page size is enough here).
Report data: data on a given league w/ series Database caching: info on leagues
https://developer.riotgames.com/
Entity: Given a summoner name, information for the matching summoner
Report data: data on a matching summoner
Note: (using SUMMONER-V4 and LEAGUE-V4, selectable region at application start) Database caching: info on summoners
Page 4 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
https://open-platform.theguardian.com/
Entity: Given a search string list matching tags (1x the default page size is enough here). Having selected a tag, list matching articles (1x the default page size is enough here). Having selected an article, display information for the matching article
Report data: data on a matching article
Database caching: data on a matching article. Caching should offer to yield cached data for either a matching previously searched tag, or a matching previously searched article. Note that an article counts as being ‘searched’ for caching if it is included as part of a response to a searched tag.
https://www.weatherbit.io/api
Entity: Given a US zip code list current weather information. Upon user request also display matching severe weather alerts for the same zip code.
Report data: weather data on a matching zip code (not alerts) Database caching: weather data for zip codes (not alerts)
https://the-one-api.dev/
Entity: List available characters. Having selected a character list of available quotes. Report data: data on a selected character (not including quotes)
Database caching: info on character quotes
OUTPUTS
https://www.twilio.com/
Send the report data as an SMS to a single configured number (can be configured in a text config file or the app itself).
https://sendgrid.com/solutions/email-api/
Send the report data as an email to a single configured email address (can be configured in a text config file or the app itself)
https://pastebin.com/doc_api
Send the report as a saved pastebin and output the url.
https://apidocs.imgur.com/
Combine with zxing, create a QR code that contains a text string version of the usual report.
https://github.com/zxing/zxing
Upload this QR code to Imgur anonymously.
Page 5 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
DUMMY API
Just as in Task 3 and for exactly the same reasons, you will need to implement a dummy version of both your input and your output APIs. These dummy APIs do not need to be dynamic, simply outputting reasonable looking data in order to demonstrate your GUI, database, and concurrency work is sufficient. These should be independent – so live input – dummy output, vice versa, both live, or both dummy should work. These should be selectable on the command line with 2 arguments in sequence aka:
gradle run –args=”offline online”
or
gradle run –args=”online offline”
with the first controlling the input API, and the second controlling the output API.
DESIGN REQUIREMENTS
You will be assessed on your application of the design principles taught throughout the semester. One aspect you should focus on is ensuring you have separation between your Model, and your View. This at a minimum will be necessary to achieve the testing/process requirements.
Your design will be assessed against the 3 goals this unit focuses on – maintainability, extensibility, and modularity (MEM), with intermediate principles such as SOLID, GRASP, and others applied to evaluate these.
Design Patterns
With the exception of the Façade pattern as the public surface of your Model, you are not explicitly required to use design patterns – in contrast, you should NOT use design patterns where there is no benefit to the 3 MEM goals by doing so. If there is a benefit however, you should of course use them.
TESTING & PROCESS REQUIREMENTS
You should follow a basic Test-Driven Development process when developing your application. This does not need to be at the component level (though you are welcome to do so and may find it both speeds up and improves your work overall) – but must be applied to your Model overall.
Note that following and demonstrating this process forms part of the Pass requirement – not following this process will cap your exam mark at 49%
Your TDD practice should involve the Red-Green-Refactor process, as applied to your Model. You will need to demonstrate this in your readme file by indicating:
• The URL for the commit where you finished writing the tests for a specific feature or set of features, where your tests can be compiled and run, but do not pass (i.e., RED)
• The URL for the later commit where you had finished implementing those features and your tests passed (i.e., GREEN)
• Optionally for the Pass requirement, but for improved marks – the URL for a subsequent commit where you refactored some or all of that implementation, with those tests still passing (i.e., REFACTOR) – one per RED-GREEN is all that is required.
Page 6 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
You should do this for all major features in your Model – trivial changes do not need to go through this process, and you can modify your tests if your overall design requires it, but any new method you add to your Model’s façade should be part of a Red-Green-Refactor sequence.
Testing Notes
Do not overdo your testing. You have already demonstrated your ability to test for coverage in a black-box scenario in Assignments 1 and 2 – you do not need to do this again. The previous stipulations that were present in those assignments, namely:
• test simple getters/setters
• test constructors
• exhaustively test defensive programming
• exhaustively mock any path
do not apply in this assessment. You should ensure you test for the most critical ‘good’ paths through your software. You should mock all external dependencies (both APIs, even the dummy versions (so you can verify), and any database), but do not need to test independently otherwise, and your mocks only need to be sufficient for your current implementation to be tested (white box mocking). You should test defensive programming anywhere a human user is giving raw input, but nowhere else is required.
STYLE & COMMENTING
You should generally follow Google’s Java Style guide – https://google.github.io/styleguide/javaguide.html
For marking purposes, the following sections and their sub-sections should be considered enforceable: 2, 5, 7.
Outside of these, variation from the guide is acceptable, but must be a) readable, and b) consistent.
DOCUMENTATION
You must include a readme file in your repository. This can optionally be in readme.txt or readme.md formats. This readme file must:
• Include citations for any code you have used that you did not write
• Include citations for any code you DID write, but in another unit of study or prior attempt at this unit
(note that you must also indicate where you have done either of the above with comments in the
locations you have done so)
• A list of commit URLs indicating your RED-GREEN-REFACTOR processes
• Any quirks to running your application the marker needs to know about
• For the above especially any configuration files which should be modified before running the
application (i.e. for database information, API keys, etc).
• An indication of which level of features you are claiming to have implemented (either PASS, CREDIT,
or DISTINCTION)
DATABASE
For those wishing to achieve a Credit score for their exam or higher (65% and up) you will need to include a SQLite database as part of your application. You can use the SQLite JDBC library to communicate with this database: https://mvnrepository.com/artifact/org.xerial/sqlite-jdbc/3.34.0 which has sample code here: https://github.com/xerial/sqlite-jdbc.
Page 7 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
You will need to decide on the database schema and other properties yourself. You can either have your application set this schema up on first run, or you may include a .SQL file to do this that your marker will run manually.
Information on what to use this database for is dependent on your Input API and listed in that section.
CONCURRENCY
For those wishing to achieve a Distinction score for their exam or higher (75% and up) you will need to include some basic concurrency. This should allow the GUI/View to operate independently of the operations the Model is conducting. You should have the GUI drawing and events on 1 thread, and the Model operations occurring on another thread. Most GUI libraries include dedicated support for this paradigm, and will usually refer to the Model thread or threads as ‘Workers’.
You do not need to achieve true concurrency in your Model for this requirement – a single thread GUI thread and a single thread handling Model calls is all that is required. This should limit the need for handling race conditions or dealing with resource contention.
ADDING DEPENDENCIES
As at the writing of this document the following libraries are allowed to be included in your build.gradle file:
• Junit 4
• Hamcrest
• Mockito
• SQLIte-JDBC
• JavaFX
• Apache HttpClient
• json-simple
There will be a pinned Ed post where you can make requests to add to this list – these will be reviewed and either accepted or rejected on a whole-class basis. Note that any ‘sdk’ style libraries that model a given web API you are using will not be accepted.
Including an unapproved dependency will result in your submission being rejected.
PLAGIARISM WARNING
During the process for Task 3 there have been several questions asked and answered in ways that are close to the boundary of what is acceptable. Given the low stakes nature of Task 3 and its intended purpose of fairly collaborative learning this was allowed, however for the exam pre-work there is no benefit of the doubt available. It is crucial that you avoid any apparent collusion however innocent. I would recommend making any Ed posts you are not absolutely sure are ok private – they will be converted to public posts if they are of broad relevance and are ok to share. Under no circumstances should you publicly post your exam code, errors, or designs.
You should be careful when engaging with the development and support communities that exist for all of your APIs. Asking for information about the API (respectfully) is encouraged – asking for help with your exam is definitely not. It is also not acceptable to copy any existing Java SDKs the API communities have developed whether you cite them or not – it is your job to implement these features yourself.
Page 8 of 9
SOFT3202 S1 2021 Exam Pre-Work Specification 16/05/2021
Breaches here must be treated with the same severity as breaches in a normal exam environment – do not put yourself in that situation.
THE EXAM PERIOD
During the exam period you will be asked by your pretend client to add a feature to your existing application. This feature will not add any new APIs to your application, but will require you to use your existing APIs and GUI to do something new. You will also be required to write a report about what you have done and reflecting on your design.
You will not be told what the modification is until the start time of the 2-day window, but you will be given the exam document itself before the day.
GETTING STARTED
As always, the first steps should be to explore your assigned APIs. You will require an API token for each of these. While they all have a free tier that should be more than sufficient for this assignment, there are request limits you should be aware of – do not waste this!
You should then spend some time on your overall design. While the exam work you will complete in the exam period itself is intended to only take a few hours, this will only be true if you set yourself up for success with an extensible design in this phase.
You should then work from the bottom up. Achieve the Pass requirements before adding in the Credit database caching, and only once you have that working should you implement the Distinction concurrency. These requirements are stepped – if you do not meet the pass requirements it does not matter if you have a working database or threads.
Avoiding a Zero
Your application must compile and run. This is the fundamental requirement both of your application at the end of Week 13, and your application at the end of the exam window. If your application does not compile, or does not run, your exam score will be zero. You are being implicitly assessed on your ability to make use of the fundamental tools and techniques of reliable software construction and design in order to avoid this.
The most obvious of these is your own manual testing – you should obviously be able to run your application yourself using the same gradle run command your marker will be using.
Next is version control. You should work on your application in steps as indicated above – first Pass, then Credit, then Distinction, then polish. Note down the commits you have made where you are confident you have met these requirements and your application runs successfully. This means that if you hit the end of week 13 and do not have one of the more advanced features finished, or break something tweaking the design, you can roll back those changes. During the exam period itself you may find that the more advanced features are making your modification more difficult – you are allowed to roll back changes and use an older version during the exam period as well if you wish.
Finally comes programmatic testing. You are not being asked to follow Test-Driven Development to meet some archaic teaching requirement, it is a widespread technique used in software development globally to ensure code not only works more reliably once it is done, but to ensure that it reaches the point of viability faster – this is part of the Agile development toolkit. By ensuring that you have tests running early, and that you keep running them as you develop, crippling errors are less likely to end up in what you deliver.
Page 9 of 9