The Personal Self-Assessment Environment

Project 2 Software Requirements Specification

Last modified: Fri Sep 17 16:51:14 HST 1999

Overview

This semester, you will be incrementally constructing a "Personal Self-Assessment Environment"---a small software system that you can use to build assessment quizzes on topics of your choice. You can think of this system as a flexible, configurable set of "intelligent flash cards" that you can use to help you learn factually-oriented material. Each assessment quiz consists of a set of multiple choice questions, where one or more of the potential answers can be correct. No "short answer" or "essay" question types are allowed so that the system can automatically grade and correct your answer on each question. Some example application areas for the personal self-assessment environment are learning vocabulary words in a foreign language, important events in history, or technical concepts relevent to a certification exam. Note that many technical certification exams are multiple choice and automatically graded, making this software ideal for certification self-study.

The basic components of the Personal Self-Assessment Environment are:

A file format for storing questions and answers, which we'll call the "QA" format (for Question and Answer).
QA-Reader: A mechanism for reading a QA file into memory.
QA-Presenter: A mechanism for presenting the multiple choice questions in a file to the user and storing their responses.
QA-Grader: A feedback mechanism for checking the responses and providing the user with corrected answers.
QA-Editor: A mechanism for defining questions and answers and writing them out in the QA file format.

The initial set of projects will focus on creating simple versions of these components. Later in the semester, you will extend your initial components with enhancements to support more advanced and interesting features. Thus, it is to your advantage to design even the simple components with an eye toward future extension and enhancement. To help you with this process, here are some of the potential enhancements you may be making to the basic system during the semester:

Providing two kinds of questions: multiple choice, multiple answer (i.e. checkbox-based) and multiple choice, single answer (i.e. radio button-based).
Reading and writing multiple QA files.
Organizing sets of questions into quizzes.
Computed answers. Here you provide a formula, such as how to convert fahrenheit to centrigrade, and a range of acceptable fahrenheit values. The system then generates questions asking you to to convert a fahrenheit value within the range to its equivalent centrigrade value, and uses the formula to check your response.
Downloading QA files from the web.
Recording the elapsed time and comparing it to a recommended value.
Recording scores in a file. (Useful to assess progress).
Randomized presentation of all questions.
Randomized presentation of all answers to a question.
Randomized selection of a subset of questions. (i.e. any 5 of the 10 questions).
Support for embedded graphics such as gif or jpeg files in questions.
Support for embedded applets in questions.
Assistive technologies.
Palm Pilot version using the KVM for Java.
History-based question selection, based upon prior quiz results to focus on questions that were incorrectly answered previously.

Project 2 Increment: Incorporating difficulty ratings and question collections

This increment involves an extension to the representation of questions to support difficulty ratings, and some basic functionality for sorting and filtering the set of questions to be presented by the system.

Here are the specific requirements for this project.

First, the software must conform to all of the requirements stated in Project 1. This includes coding standards, JavaDoc standards, command line argument processing, etc. Your Project 2 software must pass all of the test cases created for Project 1, in addition to new test cases created to test the new functionality specified for Project 2.
This is version 2.0. You should have a single (typically static) string instance somewhere in your program storing this version number. This single string instance should be used whenever the version number is printed. It is a design error for you to create multiple copies of the version number string. Remember to update the first line of your output to refer to this version string.
The software must parse the :DIFFICULTY declaration. This is a new feature which is documented in an updated version of the PSAE File Format Specification. This declaration is the only change to the specification, and is backward compatible. In other words, this declaration does not make any previously legal .qa files illegal, since any question not containing a :DIFFICULTY declaration gets a difficulty value of 0 by default.
The software must support the command line argument "-diffSet". The -diffSet argument takes one parameter: an integer from 0 to 100. This parameter selects a subset of the loaded questions for presentation given a difficulty value equal to or greater than the argument. For example, "-diffSet 0" means to present all questions from difficulty level 0 to 100, in other words, all loaded questions. A missing -diffSet argument is equivalent to "-diffSet 0". A "-diffSet 50" means to select the questions from difficulty level 50 to 100 for presentation.
The software must support the command line argument "-sort". The -sort argument takes one of the following parameters: "alpha", "difficulty+", "difficulty-", "random", and "file".
- If the parameter is "alpha", the selected subset of questions should be presented in alphabetical order based on their title (the comparison should be done in a case-insensitive fashion).
- If the parameter is "difficulty+", the selected subset of questions should be presented in order from lowest difficulty to highest difficulty.
- If the parameter is "difficulty-", the selected subset of questions should be presented in order from highest difficult to lowest difficulty.
- If the parameter is "random", the selected subset of questions should be presented in random order. Important note: each run of the system should result in a different random ordering, so you'll need to use the current time as a seed.
- If the parameter is "file", the selected subset of questions should be presented in the order that they appeared in the .qa file. This is the default behavior when no -sort argument appears on the command line.
The software must support the command line argument "-printSelected". This argument instructs the software to print to standard output a listing of the titles of all questions selected for presentation in whatever order was specified by the command line arguments.
If the program is invoked with no command line arguments, it should print out a short, Unix-style "Usage" message indicating all of the required and optional command line arguments, then exit.
The software must support the command line argument "-help". This has the same effect as invoking the program with no command line arguments. Any other command line arguments are ignored.
As always, you must handle incorrect command line arguments.

Examples

First, assume a legal file of 10 questions called test.qa. In this file, the questions are titled "Question01", "Question02", and so forth up to "Question10". Each question contains a :DIFFICULTY declaration with a value equal to their question number, so Question01 has declared difficulty value 1, Question02 has declared difficulty value 2, and so forth up to 10. Given this test file, here are some example invocations and outputs.

The following case illustrates the behavior when the -printSelected argument is not provided.

% java -jar johnson-P2.jar -qa test.qa 
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Question01
Loading question title: Question02
Loading question title: Question03
Loading question title: Question04
Loading question title: Question05
Loading question title: Question06
Loading question title: Question07
Loading question title: Question08
Loading question title: Question09
Loading question title: Question10
10 questions successfully loaded.

Note that this same output would occur even if another command line argument such as -sort was provided, since -printSelected is not present.

Default -printSelected behavior, which is also equivalent to "-sort file".

% java -jar johnson-P2.jar -qa test.qa -printSelected
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Question01
Loading question title: Question02
Loading question title: Question03
Loading question title: Question04
Loading question title: Question05
Loading question title: Question06
Loading question title: Question07
Loading question title: Question08
Loading question title: Question09
Loading question title: Question10
10 questions successfully loaded.
Questions selected for presentation:
Question01
Question02
Question03
Question04
Question05
Question06
Question07
Question08
Question09
Question10

Random selection. Note the order should be different each time the system is invoked!

% java -jar johnson-P2.jar -qa test.qa -printSelected -sort random
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Question01
Loading question title: Question02
Loading question title: Question03
Loading question title: Question04
Loading question title: Question05
Loading question title: Question06
Loading question title: Question07
Loading question title: Question08
Loading question title: Question09
Loading question title: Question10
10 questions successfully loaded.
Questions selected for presentation:
Question04
Question01
Question06
Question03
Question10
Question09
Question02
Question08
Question05
Question07

Descending difficulty.

% java -jar johnson-P2.jar -qa test.qa -printSelected -sort difficulty-
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Question01
Loading question title: Question02
Loading question title: Question03
Loading question title: Question04
Loading question title: Question05
Loading question title: Question06
Loading question title: Question07
Loading question title: Question08
Loading question title: Question09
Loading question title: Question10
10 questions successfully loaded.
Questions selected for presentation:
Question10
Question09
Question08
Question07
Question06
Question05
Question04
Question03
Question02
Question01

Here we select the subset with difficulty >=5, and present the results in random order.

% java -jar johnson-P2.jar -qa test.qa -sort random -diffSet 5  -printSelected 
Personal Self-Assessment Environment V1.0 Philip Johnson
Loading question title: Question01
Loading question title: Question02
Loading question title: Question03
Loading question title: Question04
Loading question title: Question05
Loading question title: Question06
Loading question title: Question07
Loading question title: Question08
Loading question title: Question09
Loading question title: Question10
10 questions successfully loaded.
Questions selected for presentation:
Question10
Question05
Question07
Question08
Question06
Question09

Philip Johnson