Protocols CS 4311 Wirfs Brock et al., Designing Object-Oriented Software, Prentice Hall, 1990. (Chapter 8) Meyer, B., Applying design by contract, Computer, 25(10):40-51, October 1992. 1 1
Outline • Protocols: what and why? • Documenting protocols • Process and guidelines 2 2
Review • Responsibility? • Contract?
Definitions Signature: method name, input and output parameters and their types, and return type Protocol: set of signatures for methods to be implemented
Why Write Protocols? Define an interface to a class. (Why?)
Protocol Structure • Signature • Method name • Type of return value • Type of input and output parameters • Description of input, output, input-output parameters • Purpose • Pre-condition • Post-condition
Notation • Signature, a.k.a. syntactic interface • Language neutral declaration, e.g., UML and CRC draw(in g: Graphics): void • Language-specific declaration, e.g., Java and C++ void draw(Graphics g) • Strength and weakness?
Notation (Cont.) • Behavior, a.k.a. semantic interface • Informal description or stylized texts Example: Given a non-empty list of integers, determine if it is sorted. • Formal descriptions, e.g., OCL and Design-by-Contract notations pre: not c->isEmpty() post: c->incldues(result) and c->forAll(e: Integer | result >= e) • Strength and weakness?
Specifying Classes Class: Drawing Superclasses: DisplayableObject Subclasses: None Class Diagram: see Figure 2-1 Collaborations Diagram: see Figure 3-5 Description: Represents the structure of the elements … Contracts 2. Maintain the elements in a drawing Know which elements are contained in the drawing addElement(DrawingElement) uses List Adds a drawing element to the front of the list of drawing elements. Pre: The element is not already contained in the list. Post: The element is the first element of the list.
Specifying Classes (Cont.) elementAt(Point) returns DrawingElement uses List, DrawingElement (3) Returns the drawing element at the given point. Pre: none Post: if boundary rectangle contains Point then returned is the first drawing element in List else returned is a null object Maintain the ordering between elements elementAfter(DrawingElement) returns DrawingElement uses List …
Pre-condition • Capture the conditions that must be true before the method executes • Describe the required state of the ADT or object before entering the function • Written as an expression that is true or false • May consist of expressions connected by logical operators (AND, OR) • Use true when no pre-condition exists
Post-condition • Must clearly state what is true when the method completes execution • Describe the expected state upon exiting the function • Should be strong enough so that only correct implementations will satisfy the condition
What’s the Value of Pre- and Post-conditions? • (Pair) 2 minutes
Process for Writing Protocols For each class For each contract For each responsibility Specify complete protocol (set of signatures) to support the responsibility
Guidelines: Names • Use single name for single conceptual operation, regardless of where it is found • E.g., add vs. insert, remove vs. delete, contains vs. has vs. includes for collections • Associate a single conceptual aspect with each method name
Guidelines: Generality • Make protocols as generally useful as possible • The more general a responsibility, the more messages needed to support it. • E.g., size vs. enumerating elements for collections
Guidelines: Default Values • Define reasonable defaults • Provide most general message: user specifies all possible parameters • Provide defaults for any parameter for which it is reasonable • Let client specify subset of parameters
Example • display() • display(device) • display(region) • display(device, region) • display(device, region, rule) • display(device, region, rule, transform)
Exercise • Make the indexOf method of String more general and reusable. /** Returns the index of the first occurrence of the given character. */ int indexOf(int ch) • (Pair) 2 minutes
Guidelines: Pre and Post • State as assertions not as actions. • Why? • E.g., int String.indexOf(int c) pre: none post: if c appears in this string then return the index of the first occurrence of c else return -1 post:if c appears in this string then result is the index of the first occurrence of c else result is -1 20
Guidelines: Rework, rework, … • Generate protocols for main responsibilities • Protocols to public methods must be unambiguous since it is the interface with clients • Protocols to private methods are notes to developer • Common to discover holes in design at this point • Repeat earlier phases of design
Example: ADT Stack • Additions are restricted to one end identified as the top of the stack. • Deletions are restricted to the top of the stack. • Only the item at the top of the stack is accessible • A stack is often referred to as a LIFO(Last In First Out) list.
In-class • Identify operations for Stack • (Pair) 2 minutes
In-class • Specify protocols for isEmpty() and pop() • (Pair) 5 minutes
In-class (Pairs) Consider a class, say Contact Manager, that manage a contacts list, where a contact contains contact information such as name, phone number, email address, etc. Identify responsibilities for Contact Manager Define protocols for adding and search operations/responsibilities. 25