Contracts and Invariants

1
Contracts and Invariants

• Section 6.2 (JIAs)

2
Announcements

• What to turn in
• Thursday 02/14
• email Tar file for 2 components
• Monday 02/18
• email Tar file for remaining 3 components
• Wednesday 02/20
• email Tar file for driver all classes
• Report
• Class sequence diagrams from phase II Changes
• DIRECTIONS ONE HOW TO RUN
• Javadoc HTML output for all classes
• Assignments are individual work

3
Design by Contract --- DBC

• Each class interface defines a set of services
  via its public methods
• The declaration of a method
• what the user cares about in the API or javadoc
  documentation pages
• defines only the type and not behavior
• Behavior what happens when method is run
• When can I call it? What happens if I do?
• One should not write a class without a formal
  contract
• lists the internal consistency conditions that
  the class will maintain (the invariants)
• for each method
• the correctness conditions that are the
  responsibility of the client (the precondition)
• and those which the operation promises to
  establish in return (the postcondition)
• Missing contracts ?
• Silence on some aspects of behavior
• Multiple interpretations
• Contradictions

4
Design by Contract --- DBC

• Methods have preconditions and postconditions
  classes have invariants
• A precondition is a Boolean expression that must
  hold when the method is invoked
• i.e. a method may not be invoked when the
  preconditions is false
• preconditions are guaranteed by the caller
• When you call me, the following must be true
• A postcondition is a Boolean expression that must
  hold when the method invocation returns
• postconditions are guaranteed by the callee
• If the preconditions are satisfied, I guarantee
  the following will be true when I return

5
Contract of a Method

• Documented using special tags (most tags are not
  supported by JavaDoc)
• /
• JAVADOC Documentation
• _at_pre precondition
• _at_post postcondition
• /
• public someMethod()
• Those tags may occur multiple times for any
  single method
• in such cases, the conjunction of all Boolean
  expression would serve as the pre and post
  conditions

6
Contract of a Method

• The following special tags are used in pre- and
  post-conditions
• _at_result a variable holding the return value of a
  method
• _at_nochange a Boolean expression implying that the
  state of the object is not changed by the method
• in postconditions for accessors
• Can also use the following operators
• ? logical implication (a ? b is true iff a is
  false or both are true)
• ? logical equivalence (a?b is true iff both are
  either true or false)

7
Example 1

• /
• Returns the number of elements in
• an ArrayList
• OTHER JAVADOC TAGS
• _at_pre true
• _at_post _at_resultlist.size()
• _at_post _at_nochange //no change for the state of the
  object (i.e. an accessor or a getter method)
• /
• public int size()

8
Example 2

• /
• Returns true iff the list is empty
• OTHER JAVADOC TAGS
• _at_pre true
• _at_post _at_result ? (size() lt 0)
• _at_post _at_nochange
• /
• public boolean isEmpty ()

9
Example 3

• /
• Returns the 1st element in the list
• OTHER JAVADOC TAGS
• _at_pre !isEmpty()
• _at_post _at_result list(0) // this is a condition
  so that is why we use instead of
• _at_post _at_nochange
• /
• public Object head()
• Last()?

10
Example 4

• /
• Returns the last element in the list
• OTHER JAVADOC TAGS
• _at_pre !isEmpty()
• _at_post _at_result list(size()-1)
• _at_post _at_nochange //no change for the state of
  the object (i.e. an accessor or a getter method)
• /
• public Object last()

11
Mutators

• A mutator is a method that changes the state of
  the object (setter)
• _at_post _at_nochange for accessors
• Need to distinguish between the state of the
  object before and after the method invocation
• values of expressions in the postcondition are
  evaluated w.r.t. the after state of the object
  (i.e. after method returns)
• Add a new item at top and return it
• _at_post _at_result list(size()-1)
• To refer to object immediately before the method
  is invoked, we use the pre-state notation
• expression_at_pre
• Add a new item to list ? increase size
• E.g. _at_post size() size()_at_pre 1

12
Collections

• Contracts involving a collection of objects (i.e.
  list, vector, array, etc ) often require
  quantified expressions
• Universal quantification
• Holds on every object in the collection
• _at_forall x Range_at_Expression
• Existential quantification
• Holds on at least one object in the collection
• _at_exists x Range_at_Expression
• x is a variable over Range
• Range specifies the collection of objects
• Expression is a Boolean expression

13
Specifying Ranges

• m..n
• Where m and n are integer expressions
• _at_post _at_forall k0..size()-1)_at_SOME_COND
• ClassName
• Defines range of all instances of the class
• _at_post _at_forall kCAR_at_SOME_COND
• Expression
• Evaluates to a collection like a set, bag, list,
  etc
• _at_post _at_forall kRed,Green,Blue_at_SOME_COND

14
Example 5

• /
• Inserts a new element at the ith position
• OTHER JAVADOC TAGS
• _at_pre item !null igt0 iltsize()
• _at_post size() size()_at_pre 1
• _at_post _at_forall k0..size()-1_at_
• (klti ? list(k) list(k)_at_pre)
• (ki? list(k) item)
• (kgti? list(k) list(k-1)_at_pre)
• /
• public void insert(Object item, int i)
• Try
• public void insertHead(Object item) //i.e. at
  location 0
• public void insertTail(Object item) //i.e. at
  location size()-1

15
Example 6

• /
• Inserts a new element at the head
• OTHER JAVADOC TAGS
• _at_pre item !null
• _at_post size() size()_at_pre 1
• _at_post item list(0)
• _at_post _at_forall k 1..size()-1_at_
• list(k) list(k-1)_at_pre)
• /
• public void insertHead(Object item)

16
Example 7

• /
• Inserts a new element the tail
• OTHER JAVADOC TAGS
• _at_pre item !null
• _at_post size() size()_at_pre 1
• _at_post item list(size()-1)
• _at_post _at_forall k 0..size()-2_at_
• list(k) list(k)_at_pre )
• /
• public void insertTail(Object item)
• Try
• public Object remove(int i)
• public Object removeHead()
• public Object removeTail()

17
Example 8

• /
• Remove and return the element at the ith
  position
• OTHER JAVADOC TAGS
• _at_pre !isEmpty() igt0 iltsize()
• _at_post _at_result list(i)_at_pre
• _at_post size() size()_at_pre-1
• _at_post _at_forall k 0..size()-1 _at_
• (klti ? list(k)_at_prelist(k))
• (kgti? list(k1)_at_prelist(k)
• /
• public object remove(int i)

18
Example 9

• /
• Remove and return the Head item
• OTHER JAVADOC TAGS
• _at_pre !isEmpty()
• _at_post _at_result list(0)_at_pre
• _at_post size() size()_at_pre-1
• _at_post _at_forall k 1..size()-1 _at_
• list(k1)_at_prelist(k)
• /
• public Object removeHead()

19
Example 10

• /
• Remove and return the Tail item
• OTHER JAVADOC TAGS
• _at_pre size() gt 0
• _at_post _at_result list(size()-1)_at_pre
• _at_post size() size()_at_pre-1
• _at_post _at_forall k 0..size()-1 _at_
• list(k)_at_prelist(k)
• /
• public Object removeTail()