A preamble is an introductory statement, a preliminary explanation of the purpose of the dossier. Explain why it was worthy of spending your time developing it. What is its social significance? What is the dossier supposed to accomplish.

Defend the choice of application by what it does for the end user and society. The dossier program must be a socially redeeming application. This is not an end-of-chapter exercise. The thought, effort, time and expense that you spend on this dossier is justified because it will do something useful when it is finished. Describe what is useful about this dossier program. Describe why it is useful. Describe who will use it. Why will they value it over doing the same thing by hand? Will it save the user time, money, or enable the user to actually do things that they may not have typically done without the use of the dossier program? Does the dossier program do what was done before in a somewhat different way? Does it add meaningful choice to an identified population of end users?

This is where you thank those who contributed to your ability to produce your dossier: authors of the one or more textbooks that you studied to learn Java and the topic that your dossier addressed, mentors that interacted with you during the development of the dossier, friends and fellow students that tested your program or criticised your dossier, and family members who supported you or got out of your way when the pressure was on.

1. Three Reviews of Analagous Software (Example: Gerry Donaldson's 2001 Review of MacMahon 2.36)

2. One Review of How It Was Done Without A Computer (Example: Shinji Kim's 2005 dossier review of non-computerized personal organizers and appointment books, pages 9-10)

3. Interview Transcript with a SME (Subject Matter Expert)

4. UML User Stories (Example: NCSU's CofferMaker Project User Stories)

5. UML Use Case Diagram (Example: NCSU's CofferMaker Project Use Cases Diagram)

6. Analysis Incorporating the Above

7. If applicable, a theoretical analysis as exemplified in Bobby Naini's 2000 dossier Gravity Works

8. Construct a Systems Flowchart of the dossier program.

1. Minimum Performance

   1. Tabulate the JUnit boolean assert( ) statements that will test the correctness of the functions. Place the method's signature in the left column and the corresponding assert statement in the middle column. Place an explanation of the assertion (why does it work?) in the third column.

   2. Time to retrieve data from a file: Predict results under different scenarios using Java's System.currentTimeMillis( ) as illustrated in Measurement Is Everything from the book Java Platform Performance: Strategies and Tactics by Steve Wilson and Jeff Kesselman. Google "java stopwatch class" for more examples. Different scenarios could be the time to save one hundred thousand records, or time to load ten thousand records into an array.

   3. Response to invalid data input: Give examples and predictions of both the data and responses. A table with two columns is recommended, where the left column is labelled "Input" and the right column is labelled "Expected Output".

   4. Response to extreme data input: Give examples and predictions of both the data and responses.

   5. Quantify the data that can be stored. Indicate system requirements.

2. Usability

   1. Ease of use of input screen: How sophisticated need be the user? How old? How literate? Compare the required effort and knowledge to doing the task(s) by hand, with a different interface, under different conditions.

   2. Appropriate response to user input: Give examples and predictions of both data and responses.

1. Initial Design:

   1. UML Class (Structure) Diagram Showing Only Associations: (Example: Deitel's Elevator class diagram)

   2. UML Class (Structure) Diagram Including Attributes and Operations: (Example: Deitel's Elevator class diagram)

   3. UML Sequence Diagram showing the sequence of messages, which are exchanged among roles that implement the behavior of the system, arranged in time. (Example: Wikipedia's Service in a Restaurant)

   
   

2. Functional Prototype

   1. Input: Command Line or GUI

   2. Process: Implementation of one or more of:
      • Direct Access File Handling
      • Linked List
      • Binary Search Tree
      • Stack (Array or Linked List)
      • Queue (Array or Linked List)
      • Hash Table implemented in an array
      
      

   3. Output: Command Line or GUI and/or Results of JUnit Tests

3. Documentation of User Feedback: Questionnaire administered.

1. Sketches/Illustrations of sequential versus direct file handling and a comparison of the dynamic structures: linked list binary search tree, stack, queue and hash table. See Walls and Mirrors C++ 2nd Ed for an illustration of:
   • Insertion and deletion of nodes of a linked list, see page 149.
   • A queue implemented with a linear linked list, see page 309.
   • A queue implemented with an array, see page 314.
   • Insertion of a node into an empty tree, see page 478.
   • A file partitioned into blocks of records, see page 666.
   
   

2. Provide sample source code from the dossier program of each file or dynamic structure used. The reference caption should identify the page number and line number of the source code as found in Section C1.

3. Sample Data of every use of file handling and dynamic structures: hardwire test data into array lists or data files, using input redirection to avoid user interaction while testing processing. Show annotated data dumps of the data.

4. Indicate how data objects will be changed during execution.

5. Quantity of data that can be stored.

Stubs that are appropriate for the data

1. Parameters of both constructors and methods
2. Return Values of methods
3. Pre-Conditions of methods
4. Post-Conditions of methods

Do one of the following to choose modules that incorporate the data structures and methods required for the solution in a logical way.

1. Stepwise Refinement in System Design Specifications: (Example: See Gerry Donaldson's FIDE Swiss Tournament Wizard)

2. Structure Chart: these were more appropriate for structured programming and OOP (Object Oriented Programming). See Creating A Structure Chart Using WordPerfect 8 to see how to create a structure chart.

3. Hard Copy of CRC Cards: CRC = "classes", "responsibilities", and "collaborators". See Horstmann's BIG JAVA 2nd Ed, pages 614-616 for an explanation and pages 636-639 for an example in using CRC cards to design an ATM program.

Program listings must be easily readable.

1. Apply a stardardized coding style consistently to all source code.

   This is easily done in Eclipse by setting and implementing a standard coding style.

   Import UBC's implementation of Big Java's Source Code Formatting Rules.

   Thereafter pressing "Ctrl-Shift-F" reformats source code to specifications.

2. Source code is placed here, in this section.

3. Identification header for each class and interface:

   1. Program name and purpose
   2. Author, Date, School
   3. Computer used, IDE used.
   
   

4. Good internal documentation:

   1. Constant, type and variable declarations have explanatory comments.

      The purpose of every paramenter is explained using the Javadoc tag @param .

      Note that parameters are the receiving variables in the signature of a method or constructor.

   2. The precondition(s) of every non-selfdocumenting method must be identified using the Javadoc tag @pre.

      The postcondition(s) of every non-selfdcoumenting method must be identified using the Javadoc tag @post.

      The precondition(s) and/or postcondition(s) of accessor methods such as getNum( ) and mutator methods such as setNum( ) are usually "self-documenting" by virtue of their self-explanatory names and relatively small code size. These methods do not generally require documentation of their preconditions and/or postconditions.

      When in doubt, do document with @pre and @post Javadoc tags.

   3. Identifiers have meaningful names.

   4. Methods are small == generally each method fits entirely on one screen.

   5. Objects are clearly separated.

   6. Objects have comments for their parameters.

   7. Indentation illustrates the programming constructs.

   8. All source code must apply syntax highlighting. Minimally, reserved terms must be in bold fonts and/or of a different colour from non-reserved terms.

   9. All lines of source code must be numbered. This is essential for making specific references to the source code when commenting on it in other documentation.

      The first line of each externally named (not internal or annonymous) class should begin with the number "1" (one).

      Note: Versions of Eclipse through 3.3 do not support the printing of line numbers to a printer or clip board. Copy and paste does not retain the line numbers. One work around is to convert the Java source code to an html or rtf (rich text file) format with a program that both generates syntax highlighting and numbers the lines of the source code. One such program that does this is Java2Html. I have found that rtf files retain indentation whereas html files sometimes lose the appropriate indentation. I also observed that Java2Html formated html files get inserted as tables when read into WORD and WordPerfect, but not so for rtf files. I recommend convertions to the rtf format. Using Java2Html, copy the rtf code into a text editor such as TextPad. Remember to tick the check box for generating "Line Numbers" and to choose "RTF" in the "Target" drop down menu before clicking the "Convert" button. Save the resulting text file with the appropriate "rtf" extension. The resulting rtf file retains syntax highlighting, indentation and line numbering when inserted into a current version of WORD or WordPerfect after Insert --> File.... Caveat: Lines are not automatically renumbered if deleted or inserted in code after it has been converted. Code must be again converted by running Java2Html if lines are deleted or inserted or modified such to trigger either situation, as could happen if code were modified in the wordprocessor.

      
      

   10. The wrapped portion of wrapped lines are indented.

   11. There must be no "magic numbers". For example, the size of records are derived from clear documentation of the addition of the length of each field of the record.

The teacher runs the program with the student to confirm that the program executes as claimed.

Construct a table summarizes the features. The table should make reference to both the annotated sample runs and the program listing.

Program has features that make it user friendly.

1. GUI Interface.
2. Helpful Menus.
3. Help Page. [See Jacky Lee's How To Create A Help Page.]

Handling Errors

Sun's Java Tutorial:
Handling Errors Using Exceptions

Kjell Tutorials 80 81

Horstmann's BIG JAVA 2nd Ed: Chap 15 - Exception Handling

Deitel's JAVA HTP 4th Ed: Chap 14 - Exception Handling

Use try, catch, and finally statements.

1. IOException: detect and reject erroneous data input from the user.
2. Run-time exceptions.
3. Arithmetic exceptions.
4. Data-file errors.

Implement customized exception types for errors paticular to your program.

• Kjell's Tutorial 81, Slides 13-14
• Horstmann's BIG JAVA (2nd Edition), pages 563-564.

Provide annotated screen dumps showing that the program runs properly.

1. Input/Output: Annotate Screen Dumps of Sample Runs
   1. Create tables with two columns as did Maria Dantsiguer's 2004 dossier, European Museum Information System.
      • Place the screen dump in the left column.
      • Place the explanation in the right column.
   2. an explanation caption for every screen dump of both:
      • what is to be seen in the screen dump.
      • which objective from A2 is addressed by that screen dump.
   
   

2. Algorithms: Annotate Results of JUnit Tests demonstrating that the methods executed as expected and without errors.

   Add a fourth column to the JUnit Tabulation designed in Section A2. Place a check mark beside each test that successfully passed and an X beside each test that failed the JUnit test.

Place the Java source code and JUnit Javadocs for the JUnit classes here. Start each class on a different page. Give a two column table showing the correspondance between each class of the program and its corresponding JUnit testing class.

Provide tables of annotated screen dumps of the test output as exemplified by Bei Li's 2005 dossier Mercury Express Delivery System. There should be a different run for each branch of the program. Each annotation must identify the "aspect" that is being tested.

Samples of all objectives in criterion A2 must be tested, screen dumped and annotated!

1. JUnit Tests: Tabulate results of executing JUnit boolean assert( ) statements itemized in Criterion A2.

   There must be a better way to record the results of JUnit tests. Is JUnitReport the solution? It requires Ant. That requires a knowledge of XML. Is this the next level?

2. Time to Return A Research Result Using System.currentTimeMillis( ), compare the times predicted under the scenarios established in criterion A2 with the actual times measured after the coding of the program was completed.

3. Responses to valid data: Record a table of annotated screen dumps showing entering valid data and the program's responses. Place screen dumps in the left column and annotations in the right column.

4. Responses to invalid data input: Demonstrate exception handling itemized in criterion A2 in a table of two columns where each row demonstrates a different error (exception) and the program's response (catch). Place screen dumps showing the exceptions and responses in the left column. Place the annotations describing thoses exceptions and responses in the right column.

5. Responses to extreme data input: Place the screen dumps in the left column and the annotations describing the program's responses in the right column.

In this critical analysis of the resulting solution, identify:

1. criteria that the program successfully addressed. Refer to the results of criterion D1.
2. limitations of the program.
3. improvements for future releases.

In this critical analysis of the resulting solution, identify:

1. sample input
2. written instructions
3. screen shots

1. Every class and interface should have the following tags where applicable.

   @author [author name]	author's name of the class/interface
   @version [version]	version information of the class/interface
   purpose [rationale for existing]	the reason that the class/interface exists.
   @invariant [condition]	an assertion that is always true at a particular point in an algorithm

   
   

2. Methods and constructors should have the following tags where applicable.

   @pre [condition]	precondition that must exist at the beginning of a method in order for the method to work correctly
   @post [condition]	postcondition existing after a method has finished executing
   @param [argument name] [argument description]	describes an argument
   @return [description of return]	data returned by a method. Constructors never return data.
   @exception [exception thrown] [exception description]	exception thrown by a method

   
   
3. Print a hard copy of output of the HTML Javadoc files. Remove references to "Methods inherited from class java..." that do not refer to methods used in the dossier program.

Provide a hard copy of a dated log or blog documenting:

1. Tasks attempted or completed on specific dates.

2. Reflections as seen in the conclusion of Thushy Amirthalingam's 1997 Pascal dossier, Personal Information Manager (PIM).

3. Significant experiences or resources that contributed toward understanding the dossier.

4. Revelations, realizations, epiphanies and/or discoveries that transfer beyond the dossier's specific subject matter.

In past years students successfully achieved IBO's objectives for Boolean Logic with Electronic Workbench. It is more powerful than Eck's xLogicCircuits Java applet, but has a steeper learning curve. It may be that Eck's xLogicCircuits applet is sufficient to practice all of the electronic aspects of Boolean Logic that we require. If time permits, it would still be useful to explore those concepts using Electronic Workbench. If time permits, do the following.

Look at some of the nine tutorials by Ron Reis of Los Angeles Valley College entitled Computer Simulation of Digital Circuits found on a Prentice-Hall companion web site to the textbook, Digital Fundamentals Seventh Edition by Thomas L. Floyd.

• 1: Introductory Digital Concepts
• 2: Number Systems, Operations and codes
• 3: Logic Gates
• 4: Boolean Algebra and Logic Simplification
• 5: Combinational Logic
• 6: Functions of Combinational Logic
• There is no Workbench tutorial for Chapter 7.
• 8: Flip-flops and Related Devices
• 9: Counters
• 10: Registers