CSC 308 Lecture Notes Week 5

CSC 308 Lecture Notes Week 5
Details of Requirements Model
Derivation and Refinement

Administrative matters.
1. Get started on basic modeling for Milestone 4.
  1. See the Milestone 4 example for roughly how much you should do.
    1. Each team member must commit at least six Java model classes, organized into packages.
    2. The model classes can be in one or more .java files.
    3. You'll need some team coordination for the major shared objects and the packaging structure.
  2. Create package sub-directories in the project specification directory.
  3. Put .java files to the appropriate package directories.
  4. The files must compile with javac.
2. Remember that this is the first week of inspection testing.
  1. Review the procedure in the SOP Vol. 2 handout, which we'll go over in lecture on Monday.
  2. In particular, be sure to decide in your team at what time on Friday (or even Thursday) pre-testing check-in is due in order for the inspection tester to get things done so the librarian can release them by 11PM.
  3. Note that the due time for Milestone 4 has been to 11PM (from 7PM) in order to provide adequate time for inspection testing.
Guidelines for modularizing a software model.
1. To modularize means to subdivide parts into independent units.
2. Here's an excerpt from the regular English dictionary definition for "module" that applies very well to software modeling:
  "A module is an independent unit that can be used to construct a more complex structure".
3. In the specific case of a model defined in Java, modules are defined as packages.
4. A good heuristic for defining model packages is to use the large-grain structure defined in the software requirements.
  1. For example, each menu in a menu-based UI can be considered a package.
  2. Similarly, the top-level UI toolbars can be considered to be packages.
  3. The table of contents of the requirements can also provide guidance for the organization of the model packages.
  4. The important point is that it makes sense to have the model package organization correspond to the way the user perceives the high-level organization of the software.
    1. This is another example of the "form follows function" idea noted in Lecture Notes 4.
    2. That is, a well-defined organization of the user interface leads to a well-defined model packaging structure, and vice versa.
5. Given these guidelines, the packaging structure of the Calendar Tool model can be defined as follows:
```
package file;
package edit;
package schedule;
package view;
package admin;
package options;
```
6. Within each package are the classes that support the package's functionality.
  1. For 308 Milestone 4 example, the primary focus is on the schedule and view packages, since these contain the most important and interesting features of the Calendar Tool.
  2. The packaging structure is easy to view in javadoc form in the Milestone 4 example.
  3. Note that javadoc is not a required deliverable for Milestone 4; it's provided in the Milestone 4 example for convenient viewing.
Summary of core steps of the model derivation and refinement process.
1. Derive initial model from UI screens, using these heuristics:
  1. Function buttons and menu items generally correspond to operations.
  2. Data-entry screens and output screens generally correspond to objects.
  3. More specifically, data-entry dialogs that appear in response to invoking an operation generally correspond to the input object(s) for the invoked operation.
  4. Output reporting screens that appear in response to confirming an input dialog (e.g., with an "OK" button) generally correspond to the output object(s) for the confirmed operation.
  5. Interface elements with a single number, string, or boolean value corresponding to primitive objects.
  6. The hierarchical structure of objects is generally displayed in the interface by nested or cascading windows and boxes, with primitive elements at the lowest level of nesting.
  7. Whole pull-down menus and large editing dialogs generally correspond to modules.
2. Refine object model using requirements narrative.
  1. Define component details down to primitive-level objects.
  2. Add inheritance based on references to "generic" objects mentioned in narrative.
  3. Add object descriptions that synopsize narrative details.
3. Refine operation model using requirements narrative and thoughtful functional analysis.
  1. Fully specify operation inputs and outputs.
  2. Identify default inputs that the user does not need to enter explicitly in the interface.
  3. Identify collection objects and add them to operation inputs/outputs, to ensure functional behavior.
Specific modeling guidelines.
1. Object and operation naming.
  1. Derive object and operation names directly from requirements pictures and narrative.
  2. The noun or noun phrase in the banner of a dialog is the name of the object derived from the dialog.
  3. The labels of dialog components are the names of object components.
  4. The verb or verb phrase on a menu item or function button is the name of the operation derived from the menu item or button.
  5. Spaces and other alphanumeric punctuation must be consistently removed to form legal object name identifiers; otherwise, retain full spelling and capitalization in derived names, except for the Java convention to start method and data field names with a lower case letter.
2. Inheritance.
  1. Derive inheritance relations based on explicit narrative in the requirements. The objective is to define inheritance in the model if it is perceptible in some form to the user.
  2. Inheritance should not be used in a requirements model for the purposes of representational efficiency, as it is often used in programs.
  3. The prime directive of modeling is "If the user perceives it, model it". Otherwise, leave it out.
  4. In keeping with the prime directive, inheritance is generally best derived "bottom up", i.e.,
    1. Define all objects first without inheritance.
    2. Examine object definitions to see if there are common components.
    3. Define parent object classes based on common components.
    4. Confirm the use of inheritance in the model by finding justification for it in the requirements narrative (or adding such justification if the inheritance was discovered while modeling and is legitimately deemed "user perceptible").

Details of object derivation.

When interface screens are well laid out and clearly defined, object derivation is generally straight forward.

The following table summarizes the derivation of model types from common interface forms.

Common UI Form	Model Object Type
One-line Text box	Typically a string. If the requirements narrative defines specific constraints on what can be entered in the text box, then the model structure should reflect these constraints. E.g., if the narrative limits what can be typed to an integer value, then the text box is modeled as an integer. If the narrative defines what can be typed as a two-part value of some form, then the model is a two-tuple (e.g., Time and Date).

Multi-line Text Area	A string, list of strings, ore more complex object. A single string model is appropriate if the entire text area is entered as one large block of text the system does not decompose in any way. A list of strings is the appropriate model if the line-by-line contents of the text area are handled separately, but each line is not further decomposed. A more complex object model is necessary if the system performs any detailed parsing of the text to analyze its contents.

Fixed-length selection list	An `enum` object, with each element being one of the items in the selection list.

Variable-length list	A Collection object, with elements corresponding to the type of the selections.

Check-box	A boolean object. When check boxes are grouped together in the UI, model the group as a tuple of boolean objects.

Radio-button(s)	A boolean object or enum. A single on/off radio button is modeled as a boolean, e.g., a single radio button labeled "Yes/No" or "On/Off". When radio buttons are grouped together as a set of alternatives, the model is an enum with one component for each alternative. For example, with a group of radio buttons labeled "`Range`", with button labels "`High`", "`Medium`", and "`Low`", the model is enum {High, Medium, Low}

Dialog window	A class of objects that model the dialog components.

Tabbing or Multi-Panel dialog	A class with data fields for each tab panel, with each component class defining one of the tabs or panels.

Specialized "widgets"	Graphical interfaces may contain an assortment of primitive-level forms, such as on/off toggles, numeric slider bars, and small icons representing single values. A good rule for the use of such forms is if the corresponding model object is not readily derivable from the widget, then the widget is probably not that easy to understand for the user and should be replaced with a simpler form.

Details of operation derivation.
1. The "..." suffix in a menu item generally leads to two forms of dialog:
  1. A data input dialog, with an OK button (or a button synonymous with OK).
    1. In this case, there is only one operation to model.
    2. Its name is derived from the menu item.
    3. The OK button itself is not a separate operation.
    4. Rather, there is three-phase GUI sequence to invoke a single underlying model operation:
      1. Select it from the menu (or function button).
      2. Fill in the required values in the input dialog.
      3. Confirm the operation
  2. The alternative to a single-operation input dialog leading from "..." is a larger multi-operation dialog of some form.
    1. In this case, there are multiple operations to model, one each for the buttons or sub-menus in the dialog.
    2. The menu item itself does not derive an operation name, but rather a module name, in which the multiple dialog operations are defined.
2. No "..." in a menu item means that the input(s) required for the operation are collected as default values from the surrounding environment.

Object and operation derivation examples from the Calendar Tool.

Event (introduced in Notes Week 4).
1. This annotated screen illustrates clearly the traceability between user-level requirements screens and underlying abstract model.
2. This is an admittedly simple example, however such traceability can be achieved throughout the requirements derivation process with some diligence.
Appointment
```
class Appointment {
    String title;
    Date startDate;
    Date endDate;
    Time startTime;
    Duration duration;
    RecurringInfo recurringInfo;
    Category category;
    Location location;
    AppointmentSecurity meetingSecurity;
    AppointmentPriority priority;
    RemindInfo remindInfo;
    Text Details;
}
```
1. This illustrates a more involved dialog and its derived object.
2. Note the grouping of related UI components into the RecurringInfo and RemindInfo objects.
  1. This grouping in the model is a good cue that the UI itself could have better visual cues of how related components go together.
  2. E.g., the recurring and reminder areas could be surrounded by a box.
3. Also, the number of components violates the 7+/-2 rule.
  1. This is a cue that the dialog itself may be too complex for a single window.
  2. Some form of better ergonomic organization could be used, such as toggles to show more or less detail.

Meeting

class Meeting {
    String title;
    Date startDate;
    Date endDate;
    Time startTime;
    Duration duration;
    RecurringInfo recurringInfo;
    Category category;
    Location location;
    AppointmentSecurity meetingSecurity;
    AppointmentPriority priority;
    RemindInfo remindInfo;
    Attendees attendees;
    Text Details;
    Text Minutes;
}

Task
```
class Task {
    String title;
    Data dueDate;
    Date endDate;
    Category category;
    Security security;
    int Priority;
    RemindInfo remindInfo;
    Text details;
    boolean carryOverFlag;
    boolean completedFlag;
}
```
1. Note that there is a CompletedFlag in the model object that does not appear in the task scheduling dialog.
2. There is a to-do item in the Milestone 6 task-scheduling scenario that describes how the completed flag should appear once a task is scheduled.
3. This is an example of where the model is temporarily further developed than the requirements scenarios.
Deriving the scheduleEvent operation.
```
class Calendar {
    . . .

    void scheduleEvent(Event);

    . . .
}
```
1. As discussed in Lecture Notes 4, a major collection object has been identified -- the Calendar.
2. Each of the four scheduling operations is additive in that it takes a form of scheduled item and adds it to the Calendar.
3. An additive operation takes a collection component as input In an object-oriented language like Java, Hence, the functional form of the operation signature has the Calendar as both an input and output.

Refining the scheduling objects and operations.

Initial refinement of scheduled items using inheritance.

class ScheduledItem {
  title; startOrDueDate; endDate;  category; }

class Appointment extends ScheduledItem {...}

class Meeting extends ScheduledItem {...}

class Task extends ScheduledItem {...}

class Event extends ScheduledItem {...}

Second refinement pass, which adds component details, further refines inheritance, and refines operation signatures.

/*
 *
 * This file defines objects and operations related to calendar scheduling.
 * See Sections 2.2, 2.4, and 2.5 of the Milestone 6 requirements.
 *
 */

import java.util.Collection;

/**
 * The Calendar object is derived from an overall view of Sections 2.1 through
 * 2.5 of the requirements.  The functionality described in those sections
 * makes it clear that a Calendar is the primarily data object of the Calendar
 * Tool.
 *
 * The data component of a Calendar is a collection of scheduled items.  The
 * operations are those that schedule each of the four types of scheduled
 * item.  In the case of meetings, there are two operations involved -- one to
 * compute a list of possible times, and another to confirm a specific selected
 * meeting time.
 */
abstract class Calendar {

    Collection<ScheduledItem> data;

    /**
     * ScheduleAppointment adds the given Appointment to this.data, if an
     * appointment of the same time, duration, and title is not already
     * scheduled.
     */
    abstract void scheduleAppointment(Appointment appointment);

    /**
     * ScheduleMeeting uses the given MeetingRequest to determine possible
     * times that the requested meeting might be held, within the existing set
     * of scheduled items in the this.data.  The PossibleMeetingTimes output is
     * a list of zero or more possible times and dates that the meeting can be
     * held.
     */
    abstract PossibleMeetingTimes scheduleMeeting(
        MeetingRequest meetingRequest);

    /**
     * ConfirmMeeting takes a MeetingRequest, list of PossibleMeetingTimes, and
     * a Selected time from the list.  It adds a meeting to this.data,
     * comprised of the given request, scheduled at the selected time.  Further
     * details of output constraints are forthcoming.
     */
    abstract void confirmMeeting(
        MeetingRequest request,
        PossibleMeetingTimes times,
        int selectedTime);

    /**
     * ScheduleTask adds the given Task to this.data, if a task of the same
     * time, duration, and title is not already scheduled.
     */
    abstract void scheduleTask(Task task);

    /**
     * ScheduleEvent adds the given Event to this.data, if an event of the same
     * time, duration, and title is not already scheduled.
     */
    abstract void scheduleEvent(Event event);

}

/**
 * A ScheduledItem is the generic definition for the types of items stored in a
 * calendar.  The Title component is a brief description of what the item is
 * for.  The startOrDueDate and endDate components indicate when the item is
 * scheduled.  The category component is used to organize items into related
 * color-coded categories.
 *                                                                           <p>
 * There are four extensions of ScheduledItem.  They are Appointment, Meeting,
 * Task, and Event.  A ScheduledItem is derived from examining the common data
 * fields of these four types of item, and the requirements narrative that
 * describes these items.
 *                                                                           <p>
 * The startOrDueDate is a multi-purpose component of ScheduledItem.  Its
 * purpose depends on whether an item is a Task and whether it is recurring
 * (Events cannot recur).  For non-recurring appointments and meetings,
 * StartOrDueDate is used as the single date on which the item is scheduled.
 * If the item is recurring, StartOrDueDate is the first date on which it
 * occurs.  For a non-recurring Task, StartOrDueDate is the single date the
 * task is due.  If the task is recurring, StartOrDueDate is the first date it
 * is due.
 *                                                                           <p>
 * In recurring appointments, meetings, and tasks, the endDate defines the last
 * date on which the item will recur.  In events, the end date defines the last
 * date of a multi-day event.  When the value of end date is empty, the
 * startOrDueDate component is interpreted as the single date on which the item
 * occurs.
 */
abstract class ScheduledItem {
    String title;
    Date startOrDueDate;
    Date endDate;
    Category category;
}

/**
 * An Appointment adds a number of components to a generic ScheduledItem.  The
 * StartTime and Duration indicate when the appointment starts and how long it
 * lasts.  The Location is where it is held.  The Security indicates who can
 * see that the appointment is scheduled.  AppointmentPriority is how important
 * the appointment is.  RemindInfo indicates if and how the user is reminded of
 * the appointment.  Details are free form text describing any specific
 * appointment details.
 *                                                                           <p>
 * This object is derived from Section 2.2 of the Milestone 6 requirements, in
 * particular Figure 6.
 */
abstract class Appointment extends ScheduledItem {
    Time startTime;
    Duration duration;
    RecurringInfo recurringInfo;
    Location location;
    Security security;
    AppointmentPriority priority;
    RemindInfo remind;
    Text details;
}

/**
 * A Meeting adds two components to an Appointment.  The Attendees component
 * reflects the fact that a meeting is scheduled for more than one person,
 * whereas an appointment is for a single user.  The MeetingMinutes component
 * is a URL for the minutes of a meeting, once it has been held.
 *                                                                           <p>
 * This object is derived from Section 2.4.1 of the Milestone 6 requirements, in
 * particular Figure 46.
 */
abstract class Meeting extends Appointment {
    Attendees attendees;
    MeetingMinutes minutes;
}

/**
 * A meeting request has all the components of a meeting plus three additional
 * components to specify the latest dates and time at which the meeting can be
 * scheduled.  A meeting request is used to specify a range of possible meeting
 * times, to allow scheduling alternatives to be considered.  In the meeting
 * request, the inherited fields for startDate, endDate, and time are used for
 * the earliest dates and time at which the meeting can be held, i.e., for the
 * beginning values of each range.  The description of the ScheduleMeeting
 * operation has further details on how meeting requests are handled.
 *                                                                           <p>
 * This object is derived from Section 2.4.1 of the Milestone 6 requirements,
 * in particular Figure 45.
 */
abstract class MeetingRequest extends Meeting {
    Date latestStartDate;
    Date latestEndDate;
    Time latestStartTime;
}

/**
 * The PossibleMeetingTimes object is a collection of (start time, start date)
 * pairs at which a meeting could be held.
 */
abstract class PossibleMeetingTimes {
    Collection<TimeAndDate> timesAndDates;
}

/**
 * A TimeAndDate object is an element of a possible meeting time list.
 */
class TimeAndDate {
    Time startTime;
    Date startDate;
}

/**
 * Like an Appointment, a Task adds a number of components to a generic
 * ScheduledItem.  A Task differs from an Appointment as follows: (1)
 * Appointments have StartTime, Duration, and Location; Tasks do not.  (2) For
 * Appointments, the priority is either 'Must' or 'Optional'; for Tasks,
 * priority is a positive integer indicating the relative priority of a task
 * compared to other tasks.  (3) For appointments, reminders can be set to
 * occur at hour or minute granularity; for tasks, the smallest granularity of
 * reminder is a day.  (4) Tasks have a completedFlag, and completionDate
 * components; appointments do not.
 *                                                                           <p>
 * The completedFlag is true if a Task has been completed, false if not.  The
 * system does not enforce any specific constraints on the setting of a task's
 * CompletedFlag.  That is, the user may set or clear it at will.  Hence the
 * meaning of the completedFlag is up to user interpretation, particularly for
 * recurring tasks.
 *                                                                           <p>
 * The completionDate is the date on which as task is completed.  The system
 * does not enforce any specific constraints on the setting of a task's
 * completionDate (other than it being a legal Date value).  As with the
 * completedFlag, the meaning of the completionDate value is up to user
 * interpretation, particularly for recurring tasks.
 *                                                                           <p>
 * This object is derived from Section 2.4.2 of the Milestone 6 requirements,
 * in particular Figure 47.
 */
abstract class Task extends ScheduledItem {
    RecurringInfo recurringInfo;
    Security security;
    TaskPriority priority;
    TaskRemindInfo remind;
    Text details;
    boolean completedFlag;
    Date completionDate;
}

/**
 * An Event is the simplest type of ScheduledItem.  The only component it adds
 * to is Location.
 *                                                                           <p>
 * This object is derived from Section 2.4.3 of the Milestone 6 requirements,
 * in particular Figure 48.
 */
abstract class Event extends ScheduledItem {
    Location location;
}

/**
 * An AppointmentPriority indicates whether an appointment is a must or if it
 * is optional.  This information is used to indicate the general importance of
 * an appointment to the user.  The operational use of AppointmentPriority is
 * in the ScheduleMeeting operation, where the meeting scheduler can elect to
 * consider optional appointments as allowable times for a meeting.
 */
enum AppointmentPriority {
    Must,
    Optional
}

/**
 * A TaskPriority is a positive integer that defines the priority of one
 * task relative to others.  It's defined as a separate class in case we want
 * to enforce the value range restriction within the class constructor.
 */
abstract class TaskPriority {
    int value;
}

/**
 * For now, a Date is just as string.  This definition will expand soon.
 */
abstract class Date {
    String value;

    /**
     * Aux function used in scheduleEvent specs.
     */
    abstract boolean isValid();
}

/**
 * Duration is the time length of a scheduled item, in hours and minutes.
 */
abstract class Duration {
    int Hours;
    int Minutes;
}

/**
 * As with Date, Time is for now just as string.  This definition will expand
 * soon.
 */
abstract class Time {
    String value;
}

/**
 * RecurringInfo has components to specify the nature of a recurring item.  The
 * isRecurring component is an on/off flag that indicates whether an item
 * recurs.  The interval is one of Weekly, Biweekly, Monthly, or Yearly.  The
 * IntervalDetails component defines the precise means to define recurrence for
 * the different interval levels.
 */
abstract class RecurringInfo {
    boolean isRecurring;
    Interval interval;
    IntervalDetails details;
}

/**
 * Interval specifies the granularity at which recurring items are defined.
 * The Weekly and Biweekly settings allow the user to specify recurrence on one
 * or more days of the week.  The Monthly setting allows the user to specify
 * recurrence on one or more days in one or more weeks of each month.  The
 * Yearly setting allows the user to specify recurrence on one or more specific
 * dates in the year.
 */
enum Interval {
    Weekly, Biweekly, Monthly, Yearly
}

/**
 * IntervalDetails are either weekly or monthly.  This parent class is used
 * generically for either kind of details.
 */
abstract class IntervalDetails {}

/**
 * WeeklyDetails has an on/off setting for each day of the week on which
 * an item recurs.  These details are also used for the BiWeekly setting
 * of the recurrence interval.
 */
abstract class WeeklyDetails extends IntervalDetails {
    int onSun;
    int onMon;
    int onTue;
    int onWed;
    int onThu;
    int onFri;
    int onSat;
}

/**
 * MonthlyDetails can be specified on a day-of-the-week basis or on specific
 * date(s) basis.  The two extending classes have the specific details for these
 * two types of settings.  This parent class is used generically for either
 * kind of details.
 */
abstract class MonthlyDetails {}


/*
 * MonthlyDayDetails contains a weekly details component for each possible week
 * of a month.  The First- through ThirdWeekDetails are distinct for all
 * possible months.  Depending on the configuration of a particular month in a
 * particular year, there is potential conflict in specifying recurrence in the
 * fourth, fifth, or last weeks.  The conflicts are resolved as follows:
 *                                                                           <p>
 * For months with 4 weeks only, the settings in FifthWeekDetails do not apply,
 * and the settings in LastWeekDetails, if present, override any settings in
 * FourthWeekDetails.  For months with 5 weeks only, the settings in
 * LastWeekDetails, if present, override any settings in FifthWeekDetails.
 * (For months with 6 weeks, the LastWeekDetails component applies to the 6th
 * week, and there are no conflicts.)
 */
abstract class MonthlyDayDetails extends MonthlyDetails {
    WeeklyDetails firstWeekDetails;
    WeeklyDetails secondWeekDetails;
    WeeklyDetails thirdWeekDetails;
    WeeklyDetails fourthWeekDetails;
    WeeklyDetails fifthWeekDetails;
    WeeklyDetails lastWeekDetails;
}

/**
 * MonthlyDateDetails is a collection of zero or more specific dates in a month
 * on which an item recurs.
 */
abstract class MonthlyDateDetails extends MonthlyDetails {
    Collection<DateNumber> dates;
}

/**
 * A DateNumber is a positive integer between 1 and 31.  It's defined as a
 * separate class in case we want to enforce the value range restriction within
 * the class constructor.
 */
abstract class DateNumber {
    int value;
}

/**
 * A Category has a name and StandardColor, which serve distinguish it from
 * other categories.  Colored-coded categories serve visual cues to the user
 * when viewing lists of scheduled items in some form.  Categories can also be
 * used in filtered viewing.
 */
abstract class Category {
    String name;
    StandardColor color;
}

/**
 * A StandardColor is one of a fixed set of possibilities, per the requirements
 * scenarios.
 */
enum StandardColor {
   Black, Brown, Red, Orange, Yellow, Green, Blue, Purple
}

/**
 * For now a Location is a free-form string indicating in what physical
 * location an item is scheduled.  It may be refined to something like
 * (building,room) pair.
 */
abstract class Location {
    String value;
}

/**
 * Security is one of four possible levels, each of which is described
 * individually in the body of the enum.  The selected level specifies the
 * degree of visibility a scheduled item has to other users.  For an
 * appointment, task, or event, "other users" are defined as all users other
 * than the user on whose calendar the scheduled item appears.  For a meeting,
 * "other users" are defined as all users not on the Attendee list of the
 * meeting.
 */
enum Security {

    /**
     * Public security means other users can see the scheduled item and all the
     * information about the item.
     */
    Public,

    /*
     * PublicTitle security means other users can see the title of the
     * scheduled item but none of the other information about the item.
     */
    PublicTitle,

    /**
     * Confidential security means other users can only see that a user is
     * unavailable for the time period of a scheduled item; no other
     * information about the scheduled item is visible.  Since confidential
     * security applies to a specific time period, it is meaningful only for
     * appointments and meetings, not for tasks or events; tasks and events do
     * not have specific time components.
     */
    Confidential,

    /**
     * Private security means other users see no information at all about a
     * scheduled item, not even that the item is scheduled.  Note that private
     * security hides a scheduled item from the ScheduleMeeting operation,
     * q.v., so that a meeting may be scheduled at the same time as a private
     * appointment.  It is up to the user to handle this situation by
     * accepting or refusing the scheduled meeting.  Given the nature of
     * private security, it does not apply to meetings.  I.e., only
     * appointments can have private security.
     */
    Private
}

/**
 * RemindInfo has a flag that indicates if a scheduled item will have a
 * reminder sent and defines one of three ways that the user is alerted when a
 * scheduled event is to occur.  OnScreen means the user is reminded with a
 * pop-up alert on her computer screen.  BeepOnly means the user is reminded
 * with a simple audible tone on the computer.  Email means the user is sent an
 * electronic mail message reminder.
 */
abstract class RemindInfo {
    boolean isReminded;
    HowReminded howReminded;
}

enum HowReminded {
  OnScreen,
  BeepOnly,
  Email
}

/**
 * AppointmentRemindInfo extends RemindInfo by adding information for how
 * soon before a scheduled item the reminder is to be sent.  For appointments,
 * the time units are minutes, hours, or days (cf. TaskRemindInfo).
 */
abstract class AppointmentRemindInfo extends RemindInfo {
    double howSoonBefore;
    AppointmentReminderUnits units;
}

/**
 * TaskRemindInfo extends RemindInfo by adding information for how soon before
 * a task the reminder is to be sent.  For tasks, the time unit is days.  A
 * fractional day can be used for smaller granularity if desired.
 */
abstract class TaskRemindInfo extends RemindInfo {
    double howSoonBefore;
}

/**
 * Appointment reminders can come minutes, hours, or days before an
 * appointment.  The units for these can be fractional, for maximum
 * flexibility.
 */
enum AppointmentReminderUnits {
    MinutesBefore, HoursBefore, DaysBefore
}

/**
 * Attendees is a collection of names of those who attend a meeting.
 */
abstract class Attendees {
    Collection<String> names;
}

/**
 * MeetingMinutes is current defined as the URL for the location of the minutes
 * of a meeting.  This definition may be refined in upcoming versions of the
 * requirements.
 */
abstract class MeetingMinutes {
    String url;
}

/**
 * The details of the Text object are TBD.  It may just turn out to be a
 * plain string.  Or it may a limited form of HTML, so we can include linkable
 * URLs in it.
 */
abstract class Text {}

Observations.
1. Inheritance is generally easier to derive bottom up, than top down.
2. Remember -- "what the user thinks" is the driving factor in determining model accuracy and correctness.

Another example -- viewing objects and operations from the Calendar Tool.

Based on the Milestone 6 excerpt from Lecture Notes 3, the following shows some initial object derivation.

/*
 *
 * This file defines the objects and operations related to the different
 * calendar views available to the user.  See Section 2.3 of the Milestone 6
 * requirements.
 *
 * The structural viewing levels are item, day week, month, and year.  There
 * are operations to go to the previous and next views at any level, as well as
 * an operation to go to a specific date.  Lists of scheduled items can be
 * viewed in a variety of ways.  A general view filter operation can be applied
 * to both structural and list views.  Operations are available to view other
 * users' calendars and to view a list of active viewing windows.
 *
 * NOTE: this is work in progress.  A good deal of objects are yet to be
 * defined.
 *
 */
import java.util.Collection;

/**
 * A DailyAgenda has a full day name and a list of time-slot descriptors.  The
 * FullDayName consists of the day name itself (e.g., Wednesday), the month,
 * the date, and the year.  Each item in the TimeSlotDescriptor list consists
 * of a starting time (e.g., 8 AM) and a list of zero or more scheduled items.
 */
abstract class DailyAgenda {
    FullDayName name;
    Collection<TimeSlotDescriptor> times;
}

/**
 * A FullDayName has the complete and unique designation of a calendar day.
 */
abstract class FullDayName {
    DayName day;
    MonthName month;
    DateNumber date;
    YearNumber year;
}

enum DayName {
    Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
}

enum MonthName {
    January, February, March, April, May, June,
    July, August, September, October, November, December
}

/**
 * A time slot descriptor represents one slot (physically, a row) in a daily
 * agenda.  The TimeSlotName component is the start time for the slot.  The
 * list of BriefItemDescriptors contains the items that begin within the slot,
 * where "within" is defined as the start time plus the current time increment.
 * The overlaps component is a list of items with start times that overlap with
 * an item in the BriefItemDescriptor list.
 */
abstract class TimeSlotDescriptor {
    TimeSlotName slotName;
    Collection<BriefItemDescriptor> itemDescriptors;
    Overlaps overlaps;
}

/**
 * A TimeSlotName consists of a numeric TimeValue and an AmOrPm indicator.
 * TO DO: this definition should be reconciled as appropriate with the
 * definition of Time in schedule.java.
 */
abstract class TimeSlotName {
    int timeValue;
    AMorPM amOrPm;
}

/**
 * A brief item descriptor contains a subset of the information for a full
 * scheduled item.  The information is a Title, StartTime, Duration, and
 * Category.
 */
abstract class BriefItemDescriptor {
    String title;
    Time startTime;
    Duration duration;
    Category category;
}

/**
 * Overlaps contain zero or more BriefItemDescriptors that overlap with with
 * the master item in a given time slot.  An overlapping item is one with a
 * start time within the same time slot as other items.  The "master" item in a
 * time slot is the item that is first in a sorted order based on start time,
 * duration, and alphabetic title as the primary, secondary, and tertiary sort
 * keys, respectively.
 */
abstract class Overlaps {
    Collection<BriefItemDescriptor> descriptors;
}

abstract class DailyFormatOptions {
    NormalTimeRangeOption normalTimeRangeOption;
    TimeIncrementOption timeIncrementOption;
    int incrementHeightOption;
    ShowOrHide showHide24HoursOption;
    ShowOrHide showHideExactTimeOption;
    ShowOrHide showHideDashedLinesOption;
    ShowOrHide showHideExtensionArrowsOption;
    OnOrOff proportionalSpacingOnOffOption;
    DisplayOverlapsOption displayOverlapsOption;
    DefaultHeightAndWidthOption defaultHeightAndWidthOption;
}

abstract class NormalTimeRangeOption {Time startTime; Time endTime;}
abstract class TimeIncrementOption {int hours; int minutes;}
enum ShowOrHide {Show, Hide}
enum OnOrOff {On, Off}
enum DisplayOverlapsOption {Horizontal, Vertical}
abstract class DefaultHeightAndWidthOption {int height; int Width;}


abstract class Hour {
    int value;   // Must be legal hour value
}

abstract class Minute {
    int value;   // Must be legal minute value
}

enum AMorPM { AM, PM }

abstract class WeeklyAgendaTable {
    FullWeekName name;
    Collection<WeeklyTimeSlot> slots;
}

abstract class FullWeekName {
    MonthName month;
    DateNumberRange dateRange;
    YearNumber year;
}

abstract class DateNumberRange {
    DateNumber start;
    DateNumber end;
}

abstract class WeeklyTimeSlot  {
    Collection<WeeklyItemDescription> items;
}

abstract class WeeklyItemDescription {
    DayName day;
    TimeRange range;
    String truncatedTitle;
}

abstract class TimeRange {
    Time start;
    Time end;
}

abstract class WeeklyAgendaList {
    FullWeekName name;
    Collection<DailyItemList> items;
}

abstract class DailyItemList {
    DayName name;
    DateNumber date;
    Collection<DailyItemDescription> items;
}

abstract class MonthlyAgenda {
    FullMonthName name;
    DayName firstDay;
    NumberOfDaysPerMonth numberOfDays;
    Collection<DailyItemDescription> items;
}

abstract class DailyItemDescription {
    String value;       // to be refined
}

abstract class FullMonthName {
    MonthName month;
    YearNumber year;
}

class NumberOfDaysPerMonth {
    int value;   // Must be between 28 and 31, inclusive
}

abstract class YearlyCalendar {
    YearNumber year;
    Collection<SmallMonthView> months;
}

abstract class SmallMonthView { /* ... */ }

/**
 * A YearNumber is a positive integer between 0 and 9999.  It's defined as a
 * separate class in case we want to enforce the value range restriction within
 * the class constructor.
 */
abstract class YearNumber {
    int value;
}

/*
 * Model operations to place in the appropriate class:
 *
DailyAgenda viewDay(Calendar);
WeeklyAgendaTable viewWeekTable(Calendar);
WeeklyAgendaList viewWeekList(Calendar);
MonthlyAgenda viewMonth(Calendar);
YearlyCalendar viewYear(Calendar);
 *
 */

Observations.
1. Models of the agenda at different levels have all necessary info, some of which may be filtered out from view based on option settings.
2. To get a complete model picture, all of the examples in the scenarios need to be examined.
  1. E.g., consider the components of object TimeSlotDescriptor:
```
String timeSlotName;
Collection<briefItemDescriptor> items;
Collection<briefItemDescriptor> overlaps;
```
  2. Figure 10 (in the Milestone 6 requirements excerpt) shows the first two components.
  3. Figure 13 clarifies that the third component (Overlaps) is necessary.
Questions:
1. Should the DailyAgenda object have a DailyFormatOptions component?
  1. Why or why not?
  2. If not, what object does have DailyFormatOptions as a component?
2. Is there any reason to consider a parent class from which the different level agenda objects inherit?

Summary observations about the analysis and specification phases of the software.
1. The goal of requirements modeling is to build an abstract model of the user-level requirements.
  1. Abstract means that certain details of the user-level description are left out.
  2. What is obviously left out is much of the English verbiage that is used to describe the system clearly in end-user terms.
  3. The other very important aspect of the abstraction is leaving out all concrete UI details, such as
    1. Buttons such as OK, Clear, and Cancel that are strictly GUI conveniences, not fundamental to the underlying model.
    2. Purely decorative aspects of the interface that make it "easy on the user eyes" but that do not represent fundamental properties of model objects or operations.
2. There is very beneficial feedback between the requirements analysis and specification phases of the software development process.
  1. Such feedback is a natural part of development since the user-level requirements, written in English prose and pictures, describe precisely the same system as the formal model, written in the formal specification language and graphical notations.
    1. The English requirements are understandable to human users and domain experts.
    2. The requirements model is understandable to the software analysts.
    3. It is very important that these two different representations are consistent with one another.
  2. This consistency is achieved by deriving the formal model from the user-level requirements, refining the model, and then transferring the refinements back to the user-level English and pictures.
  3. The "feedback loop" between English requirements and SpecL model specification continues until the user says the requirements are complete and the specification passes cleanly through the SpecL checker.
Modeling the concrete GUI?
1. Are things like menus and dialog windows objects?
  1. The CSC 308 answer to these questions is "no".
  2. The reason is that we are defining abstract model specifications in which only data that are directly manipulatable by the user are modeled.
  3. The tool's concrete interface is not modeled as an object.
2. This modeling decision relates to the nature of the tool UIs we are specifying in 308, namely direct manipulation user interfaces.
  1. The term "direct-manipulation" describes the style of interface that gives the human user direct control over the functions performed by a software system.
  2. Modern WIMP interfaces (Windows, Icons, Menus, Pointing) are almost always direct manipulation in style.
  3. Direct manipulation UIs are in contrast to older style UIs in which the system had more control over when commands could be performed by the user.
  4. With a direct manipulation interface, we view the user as being in control of the operations that are performed, not the system.
    1. The end user may invoke any command directly via menus, with no explicit prompting from the system.
    2. The user may generally cancel commands at will.
    3. Conceptually, the system is an invisible part of what is going on.
  5. When modeling a system with a direct manipulation UI, we can abstract out objects that the user does not change.
3. The UI structure of the tool does provide organizational guidance.
  1. In particular, the hierarchical structure of the UI provides a good basis for the modular organization of objects and operations.
  2. Hence, we define modules based on how the tool UI is organized.
4. Some observations about concrete UI modeling.
  1. It is not wrong to model a GUI itself as an object.
  2. In our case, we're following a convention to model only those objects that the user can change.
  3. Hence for us, it is not necessary to model the unchangeable parts of the tool as objects.
  4. There are cases where modeling a tool's UI is necessary.
    1. For example, some systems allow the user to do things like change the format of a toolbar, or define entirely new toolbars.
    2. In our 308 projects, we're not generally considering such tool features; if a 308 project does GUI building features, they need not be modeled formally.
Modeling the tool itself.
1. Is the Calendar Tool itself an object?, an operation?, a module?
2. There are a variety of ways to model the overall system itself.
3. One approach is not to model it at all.
  1. In this approach, we completely abstract out the tool structure from the model.
  2. This highly abstract view of the tool is consistent with the above convention to abstract out objects that the user does not change.
  3. I.e., if the user cannot change the tool itself, it need not be modeled.
4. If we do choose to model the overall tool, it can be modeled as either an object or an operation, depending on the kind of processing that it performs.
  1. There are two high-level models for an information processing tool such as we are building in 308 -- transform-oriented and transaction-oriented.
  2. In a transform-oriented system, processing is viewed as transforming a single large piece of data from one form into another, using a single large operation.
    1. In a transform-oriented system, the inputs and outputs are typically large pieces of data that are widely different in structure.
    2. The transform operation takes the input, with some additional operational parameters, and transforms it into the output.
    3. A report-generation system is a good example of transform-oriented; it takes as inputs like a large database plus some format parameters, and produces a large report.
    4. A transform-oriented systems is best modeled at the top level as an operation.
  3. A transaction-oriented system performs its work with a larger number of smaller operations, each one performing some form of incremental action.
    1. In transaction system, the difference between operation inputs and outputs is a typically small, incremental change.
    2. A database management system is an example of a transaction-oriented system, where operations to add, delete, and change database records make relatively small changes to the overall database.
    3. A transaction-oriented system is best modeled at the top level as an object.
5. In practice, most information processing systems are a hybrid of the two system types, comprised of both transformational and transactional components.
  1. At the top-level, the CSC 308 projects are transaction-oriented.
  2. There may be major operations within the systems that are transform-oriented.
6. As an example of top-level tool modeling, here is the outline for the Calendar Tool top-level module.
```
/****
 *
 * Class CalendarTool defines the top-level tool object that contains the
 * currently active calendar db, system state information, and an abstract file
 * space.
 *
 */
class CalendarTool {
    CalendarDB calendarDB;
    FileSpace fileSpace;
    SystemState systemState;
}

class CalendarDB { /* ... */ }
class FileSpace { /* ... */ }
class SystemState { /* ... */ }
```
7. We'll discuss top-level tool modeling further in upcoming lectures.
Compiling an abstract Java model.
1. Use the standard javac compiler to check a model.
2. The examples shown above are unconventional in that they have multiple top-level classes in one file.
  1. The javac compiler is OK with this.
  2. As we refine the model, we will move to the typical Java convention of one class per .java file.
3. When we use Java's Collection interface, we must import at the top of the file with
```
import java.util.Collection
```
  This is the only import you'll need at the current abstract level of modeling.
4. A common error in early model development is to leave objects undefined.
  1. The conventions in the 308 examples is to use this style for yet-to-be-defined objects
```
class Whatever { /* ... */ }
```
  2. The comment with ellipses is a place holder indicating that there's more work to do.
  3. Including the ellipses comment is a good practice, because the model will compile fine without them, but an undefined definition may be easier to overlook without some indication of its unfinished state.
5. You can use the standard javadoc documentation generator to produce a browsable version of the model.
  1. It's a good idea to put javadoc output is a separate sub-directory of the model, so all of the generated files do not crowd the specification directory.
  2. The convention used for the 308 examples is to have a javadoc sub- directory under the project specification directory.