JML Specifications for StressFree classes

1
JML Specifications for StressFree classes

• Class design
• method identification
• Method specification in JML
• preconditions
• postconditions
• Class invariant specification in JML

2
More JML Language

• non-null - designates that a variable cannot be
  null for any object in this class.
• spec_public - required for private instance
  variables that are mentioned in JML method
  specifications (since methods themselves are
  public, so are their specs).
• pure - designates a method that has no local side
  effects (assignments to class variables) and no
  infinite loops
• assignable \nothing - designates that no
  variables can be assigned by the method (similar
  to pure).
• assignable v - designates that only variable v
  can be assigned by a method (default assignable
  \everything )

3
StressFree class design the Registrar view
4
Identifying methods

• Use cases suggest new methods in various classes.
  E.g., enrollInCourses suggests
• In class System
• getStatus (open or closed)
• In class CourseOffering
• isFull
• addStudent
• In class Schedule
• addCourse
• viewCourseOfferings

5
StressFree class design the course view
6
Writing method specifications E.g., TimeSlots
private /_at_spec_public _at_/ String days //
MTWHFSU Mon, Tue, Wed, Thu, Fri, Sat, Sun //
TBA undefined private /_at_spec_public _at_/
String startTime // Military time. E.g. 1330
means 130pm private /_at_spec_public _at_/ String
endTime // true if neither this nor other is
TBA, // this.days and other.days has a
day in common, and // this and other have
a time overlap. public boolean conflictsWith
(TimeSlot other) // true if other.startTime
precedes this.endTime public boolean timeOverlap
(TimeSlot other)
JML specs needed here
7
Specifying the conflictsWith method

• /_at_ ensures \result !days.equals("TBA")
  !other.days.equals("TBA")
  
• (\exists int i 0 lt i i lt
  days.length()
• (\exists int j 0 lt j j lt
  other.days.length() days.charAt(i)
  other.days.charAt(j)))
  this.timeOverlap(other)
• _at_/
• public /_at_ pure _at_/ boolean conflictsWith
  (TimeSlot other)

This means No local side effects. Also, days,
startTime, endTime must be declared spec-public.
8
StressFree class design Student view
9
Specifying prerequisite satisfaction
A Transcript satisfies all of a Courses
prerequisites if it has at least one
CourseRecord whose id is in the set defined by
each prerequisite. E.g., suppose the Course c
CSCI210 has prerequisites both CSCI107 and
either one of MATH200 or CSCI189. This shows as
the Java Vector of regular expressions CSCI107,
MATH200CSCI189 The Transcript t can satisfy
this by containing a CourseRecord that matches
each regular expression. JML specifications for
the method t.meetsPrerequisites(c) should be
added to the Transcript class before the code is
written.
10
What would the JML specifications look like?
In the Transcript class public HashMap
myRecords new HashMap() /_at_ requires
course ! null ensures result (\forall Regexp
p p course.getPrerequisites().next() (\exi
sts CourseRecord r r myRecords.next()
p.match (r.id)) _at_/ public boolean
meetsPrerequisites(Course course) //
your code here return false Note In
this case, the specs may be easier to write than
the code (these quantifiers suggest loops).
11
JML class invariant

• A class invariant defines all the valid states
  (values of the instance variables) of any object
  in the class.
• E.g. Consider the class Student, with instance
  variables id, name, and year. An invariant could
  embody the following ideas
• id an integer in the range 1..1620.
• name a nonempty string.
• year a valid graduation year (e.g., 2006).
• In JML, this can be written
• /_at_ invariant id.intValue() gt 0 id.intValue()
  lt1620
• name ! null name.length() gt 0
• (\exists int i 2006 lt i i lt 2009 i
  year)
• _at_/
• Notes A specification can be
• 1) too lenient (some instance variables can be
  null), or
• 2) too strict (what about next years students?)

12
Specifying Java collections

• A collection in Java can be any of several
  classes
• E.g., TreeSet, Vector, HashMap, ArrayList, etc.
• Picking the best collection for an implementation
  includes the following
• 1. Unique keys Some collections have the
  feature that each members key is distinct.
  E.g., Hashtable.
• 2. Ordering A collection may require that its
  members be sorted, in which case they must be
  Comparable. E.g., Students
• 3. Traversal An Iterator allows visiting the
  members of a collection, one at a time. E.g.,
  the TreeSet that contains the keys for
  CourseOfferings can be traversed using an
  Iterator.
• Note All these choices and operators can be used
  in JML specifications.

13
HashMaps and their keys

• Class Element Key Usage (in JML
  specs)
• Students Student (s) id s.getId()
• Courses Course (c) id c.getId()
• CourseOfferings CourseOffering (co)
  getCourse().idsectionlabsection
• co.getKey()
• Transcripts Transcript (t)
  student.id t.getId()
• TimeSlots TimeSlot (tm)
  id tm.getId()
• CourseRecords CourseRecord (cr)
  student.idcourseOffering.getKey()
• cr.getKey()
• Instructors Instructor (in)
  name in.getName()

14
Student vs. Students
Students can be a HashMap whose keys are
Student.ids. To retrieve a Student s from
Students ss, say ss.get(s.getId()) If ss has no
entry whose key is id, null is returned. To see
if an individual Student s appears in Students
ss, say ss.containsKey(s.getId()) If ss has
no entry with key id, false is returned. To
traverse the set of keys of a HashMap,
use ss.keySet() and contains. When writing JML
specs, assume all Java classes (e.g., HashMap,
String) are correct. So their methods can
appear in the specs.
15
Students vs. StudentDB the SQL interface

• Students is a HashMap. Its keys are
  Student.ids.
• It is not persistent. That is, it forgets all
  updates from past runs.
• StudentDB is an SQL Table. Its keys are
  Student.ids.
• It is persistent. That is, it remembers updates
  from past runs.
• To retrieve an individual Student s from
  StudentDB table sdb, we can define a method
  sdb.get(s.getId())
• If this fails, null is returned.
• To see if an individual Student s appears in
  StudentDB sdb, we can define a method
  sdb.containsKey(s.getId())
• If sdb has no entry with key id, false is
  returned.
• To add or replace Student s in the StudentDB
  table sdb, we can
• define a method sdb.put(s).

16
A Sketch of some important SQL Commands

• Statement stmt
• ResultSet rs
• Retrieval get Student s out of the StudentDB
  table
• rs stmt.executeQuery(select from StudentDB
  where id
• s.getId())
• If rs ! null then the query was successful, so
  you can retrieve all the instance variables for
  that student
• s.setName(rs.getString(name))
• s.setYear(rs.getInt(year))
• Query The above can also be used to query a
  Table, by testing if rs null.
• Update insert new values for Student s into a
  row of the StudentDB table.
• stmt.executeUpdate(insert into StudentDB(id,
  name, year) values(
• s.getId() , s.getName() ,
  s.getYear() ))

17
The Student class invariant

• public class Student
• private int id
• private String name
• private String year
• public Instructor advisor
• public Schedule schedule
• public Transcript transcript
• /_at_ id gt 0 id lt1620 name ! null
  name.length() gt 0
• (\exists int i 2006 lt i i lt 2009 i
  year)
• transcript ! null
• (schedule null
• (\forall CourseRecord cr
• schedule.getMyClasses().keySet().contains(cr)
• cr.getSchedule().getStud
  ent().getId().equals(id)))
• _at_/

18
Debugging conflictsWith
If this method is buggy, can our JML specs help
find the error?

• public boolean conflictsWith (TimeSlot other)
• if (this.days.equals("TBA")
  other.days.equals("TBA")) return false
• for (int i0 iltother.days.length() i)
• if (other.days.indexOf(this.days.substring(i
  , i)) gt 0)
• if (this.timeOverlap(other))
• return true // day in common
  and time ovelap
• else return false // day in common, no time
  overlap
• return false // no day in
  common

19
Recall Design by Contract

• The relation between a class (method) and its
  client (caller) is a formal agreement

20
Finding the contracts in StressFree

• Each use case has at least one contract
• Who is the client?
• Who is the supplier?
• What are the clients obligations?
• What are the suppliers obligations?
• (The benefits are usually implicit)
• Example the viewOfferings use case
• Client Student, Registrar, or Instructor class
• Supplier CourseOfferings class
• Client obligations to provide a valid set of
  course ids.
• Supplier obligations to display the id, title,
  time slot, prerequisites, distribution, capacity,
  and enrollment for all courses in the set.