Discussion 4 handout

Objectives

Prepration: BoundingBox project

Your TA will be demonstrating features of IDEA during portions of this section. In order to follow along, you should download the demo code for this activity and extract the Zip file to a known location on your computer. Your TA will show you how to create a “lab04” project containing these source files (but you are welcome to get a head start by creating the project yourself).

Task 1: Create project

Create a new project in IDEA from the sources you downloaded for this activity.

  1. Select File → New → Project from Existing Sources….
  2. Browse to the folder where you extracted “lab04.zip” and select the “lab04” folder (the “src” directory should be a subfolder of the folder you select).
  3. Select “Create project from existing sources”.
  4. Name the project “lab04” and take note of the project location (it should match the directory you selected previously).
  5. The next screen should say “Source files for your project have been found.” Ensure that the “src” directory is checked, then click Next.
  6. Click Next two more times (libraries and modules), then ensure that JDK 17 is selected as the project SDK. Click Next.
  7. Click Create, then open the project in a new window (presumably your other window is being used for your A2 project).

Explore the code in this project. It should look familiar—it is an example (immutable) bounding box interface along with two implementing classes using different representations.

Task 2: Generate JavaDoc documentation

Because the code in this project uses JavaDoc to document its specifications, you can generate nice, browsable documentation pages from it.

  1. In your project browser, right-click the project name, then select New → Directory. Name the directory “docs” and press Enter.
  2. Select Tools → Generate JavaDoc…. Change the “Output directory” to your “docs” folder.
  3. If allowed, select “Link to JDK documentation”. This will create hyperlinks to the documentation for standard Java classes like String.
  4. Click Generate. A web browser should appear showing you your documentation. If it does not, open “index.html” in your “docs” directory using a web browser.

Task 3: Evaluating specifications

Evaluate the following method specifications and decide whether you think they are sufficient. Do they contain all applicable clauses (preconditions, postconditions, side effects) in some form? Do they address all corner cases? Are they precise and relatively concise? Most importantly, as a client programmer, would you be comfortable calling these methods without being able to look at their implementation? Write your group’s feedback, both good and bad, on your worksheet.

The first example is a static method from A1:

/**
 * Return a string that contains the same characters as str, but with each
 * vowel duplicated.
 */
public static String duplicateVowels(String str) { ... }

The second example is from Java’s StringBuilder class, which represents a mutable string:

/**
 * Returns the index within this string of the first occurrence of the
 * specified substring. The integer returned is the smallest value
 * <i>k</i> such that:
 * <pre>this.toString().startsWith(str, k)</pre>
 * is true.
 * 
 * @param   str   any string.
 * @return  if the string argument occurs as a substring within this
 *          object, then the index of the first character of the first
 *          such substring is returned; if it does not occur as a
 *          substring, -1 is returned.
 * @throws  java.lang.NullPointerException if <code>str</code> is
 *          null.
 */
public int indexOf(String str) { ... }

The third example is from Java’s Calendar class. The roll method is used when interacting with a date picker (for example, clicking the “next month” arrow in Google Calendar and seeing the same numbered day highlighted):

/**
 * Adds or subtracts (up/down) a single unit of time on the given time
 * field without changing larger fields. For example, to roll the current
 * date up by one day, you can achieve it by calling:
 * <p>roll(Calendar.DATE, true).
 * When rolling on the year or Calendar.YEAR field, it will roll the year
 * value in the range between 1 and the value returned by calling
 * <code>getMaximum(Calendar.YEAR)</code>.
 * When rolling on the month or Calendar.MONTH field, other fields like
 * date might conflict and, need to be changed. For instance,
 * rolling the month on the date 01/31/96 will result in 02/29/96.
 * When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will
 * roll the hour value in the range between 0 and 23, which is zero-based.
 *
 * @param field the time field.
 * @param up indicates if the value of the specified time field is to be
 * rolled up or rolled down. Use true if rolling up, false otherwise.
 */
abstract public void roll(int field, boolean up);

Task 4: Unit tests for contains

Consider the following method specification from the BoundingBox interface:

/**
* Determine whether the specified point is contained strictly within the
* interior of this box. Points on the boundary of the box are not considered to
* be contained within its interior.
*
* @param p The point to perform the interior test on.  Non-null.
* @return True if <code>p</code> is strictly within the interior of this box;
*         otherwise false.
*/
boolean contains(Point p);

Choose an implementation of BoundingBox (either TwoPointBoundingBox or CenterExtentsBoundingBox). Create a JUnit test suite for your chosen class using the following procedure (your TA will demonstrate this for the Point class):

  1. If you have not already done so, create a “tests” directory in your project (right-click, New → Directory, as with “docs” before). Then right-click on your “tests” directory in your project browser and select Mark Directory As → Test Sources Root. It should turn green.
  2. Open the source code for the class you want to test. Place your cursor on the class declaration line, then click the light bulb icon (or right-click and select Show Context Actions) and select Create Test. If you see “JUnit5 library not found in the module”, click the Fix button and click OK. Then click OK to create the test suite class. Note that it will be stored in your “tests” folder and will be named TwoPointBoundingBoxTest (or CenterExtentsBoundingBoxTest).
  3. Create a procedure named testContains() and apply the @Test annotation.

In your test procedure, write test cases for the contains() method above. Each case should involve the creation of a BoundingBox and a Point and should use assertTrue() or assertFalse() to indicate the expected outcome for whether that point is contained within the box.

Write as many test cases as you think are necessary to be confident that the method is implemented correctly, but try to avoid redundancy in your cases—each case should exercise the method in a different geometric regime. Summarize your group’s test cases on your worksheet (indicate the rectangle, the point, and the expected result).

Bugs

After collecting test cases from various groups, your TA will show you some buggy implementations of contains(). For each bug, indicate on your worksheet whether your test suite would have caught the bug (and if so, which case):

In case you run out of time in section, these buggy implementations will be available on the course website on Thursday.

Submission

  1. Open the assignment page for “Discussion activity 4” in CMSX
  2. [Recorder] Find the “Group Management” section and invite each group member
  3. [Others] Refresh the page and accept your invitation
  4. [Recorder] Take a picture of your work and save as either a JPEG or a PDF file named “discussion_responses”. After all invitations have been accepted, upload your picture as your group’s submission.
    • Recommended scanning apps: Microsoft Office Lens, Adobe Scan, Genius Scan, Evernote Scannable

Ensure that your group is formed and your work submitted before the Friday evening deadline.

Tips and reminders