Lab Coding Exercise : APIs and Design Patterns

In this lab, you will explore the use of Design Patterns in Java and in the refactoring done in previous example projects to help you justify your design choices as well as direct your Refactoring.

In your project team, complete the following steps:

1. Practice Recovering from Mistakes in GIT (separate page)
2. Understanding Patterns
3. Practice Designing APIs
4. Submit Your Work

Please complete each step before moving onto the next.

Understanding Patterns

Technically, you already know how to implement Design Patterns since they use the basic Java skills and the SOLID Design Principles you have learned and practiced throughout the semester. In fact, you have likely already implemented at least one Design Pattern in your code without knowing there was a "name for it". Thus, Design Patterns are really just a good shorthand for referring to how a group of classes work together to achieve a design goal as well as describing the implementation's design trade-offs since just about any abstraction you create has a design goal. Still, learning explicitly about Design Patterns can often open up your thinking about different ways to solve a design problem you are having — even though, as you can see from the examples below, sometimes the final implementation can seem very simplistic.

Note, since that Java was created around the same time as Patterns were popular, it was heavily influenced by them and, in fact, used many of their names directly for interfaces and classes (making it very confusing since patterns are intended to describe how multiple classes interact rather than one single class or abstraction).

In a previous lab, the refactorings described were implementations of specific Design Patterns:

• Strategy: in Bins, the Consumer that was created using Java's lambda syntax serves to make the worst fit behavior a dynamic parameter instead of hardcoded in the class
• Factory: in Roulette, the BetFactory class hides its use of Java's reflection to create concrete subclasses dynamically instead of hardcoded in the class
• Iterator: in Matrix, implementing Java's expected Iterator methods allows users to loop directly over the collection without worrying about its implementation

Each person should examine two of the following Design Patterns in Java's code by identifying the methods that represent the Design Pattern and compare them to its standard description. Describe the pattern with the entire group and show how it is used in the Java classes.

• Iterator: Iterator and Iterable; or (built into the class) Scanner
• Factory: (static methods) LocalDate and OpenJFX Color; or (class) XML DocumentBuilderFactory
• Strategy: Comparator
• Template Method: AbstractList and AbstractSet
• Builder: Calendar.Builder and Locale.Builder
• Decorator: Readers and Writers
• Observer: Observer and Observable (now Deprecated), also OpenJFX's EventHandler

You can also look at their implementation (such as this Template Method or this Builder class).

As a team, discuss the following questions:

• Which patterns' use seems the most different from its general description?
• What did you learn about design while studying these patterns?
• Which patterns do you think you are already using?
• Which patterns seem most useful to use in your project to better support new changes?

Before Moving On: Add your names and summarize the group's discussion to the PATTERN_DISCUSSION.md file, then add, commit the file, and push to your lab_patterns repository.

Practice Designing APIs

As a reminder, even though APIs are simply the public classes and their public methods, your mindset is vital to clarify your design intentions about how you want them used and extended in response to changes.

When designing a set of services to be used by other developers (current and future team members), consider the following:

• Goal: how to encapsulate the implementation details while encouraging changes (extensions for as many different kinds of features as possible)
  • Such as: between the backend and frontend (e.g., between programmers in a project's other sub-groups to allow them to develop independently and in parallel)
  • Such as: between a platform and completely external developers (e.g., between iOS and app developers or between Unity and game developers)
• Contract: what services can you provide to encourage other programmers to build their own new functionality?
  • How do you plan to encapsulate them from implementation changes?
  • What objects will be used for communication, making clear:
    • how needed information will be delivered to where it is needed
    • what will be abstractions
    • what errors may be thrown
    • what things will be immutable
    • how to make the process as active as possible (not just giving out raw data)

Examine classes related to Configuration in your project from the perspective of APIs by categorizing each public method as:

• should not be part of the Configuration API (i.e., it should be made private)
• should be part of the API, but should be generalized or changed to better support new changes
• should be made internal (protected) because it primarily serves maintaining adding new Configuration features
• should declare likely Exceptions that might occur
• should be made immutable to remove the possibility that it could be used to corrupt the its internal state

A simplified view of only the public/protected methods for each team is available here.

Now that you have a sense of the kind of service your project actually provides to programmers, think about the kind of service you wish it provided. In other words, spend this time designing the API instead of just having it happen. Write a simplified (i.e., less than "one page" each) description and goals for the Simulation Model API. Note which classes are abstract/interface and which are concrete (and justify why an abstraction is not appropriate).

Then describe how to use your new Configuration API to do the following tasks:

• as a client, the Simulation gets its starting values from a data file
• as a client, the View selects a new style to apply to the running simulation, changing its state colors, edge policy, and turns on the grid outline

Your written explanation should include both English and Java descriptions of the task:

• English: how do you want programmers to think of the process of using the API to accomplish this task using metaphors or analogies (e.g., event-response paradigm), or standard programming ideas (e.g., step by step or substitution via polymorphism) beyond simply restating the procedural steps
• Java: list the actual Java methods you expect to use from the API to accomplish this task with a comment about how they would be used (e.g., call, implement, or change)
  Note, include any Exceptions you plan to throw because of errors that might occur within your methods.

Before Moving On: Add the following to the file doc/CONFIGURATION_API.md, and add, commit the file, and push it to your project repository:

• your categorized methods
• your "one-page" API design
• English and Java descriptions for the API tasks

Shared API Design

Pair up with another team, compare your APIs, and attempt to come up with a common API that could work for both of your projects.

This should require each team to justify their Design Contract, explore trade-offs between the two APIs, and then compromise on choosing one API to promote (a complete existing one or, more likely, a compromise between the two versions). Note, it is very reasonable that much discussion will focus primarily on class and method names! 

Before Moving On: Add your names and summary of your discussion to the file doc/SHARED_CONFIGURATION_API.md, then add, commit the file, and push it to each team's project repository.

Submitting your Work

At the end of lab, push your team's Markdown files to the doc folder on the main branch of your team repository to submit your notes about your teams' discussions.

• PATTERN_DISCUSSION.md
• CONFIGURATION_API.md
• SHARED_CONFIGURATION_API.md

Make sure the Title of your Merge Request is of the form "lab_patterns - everyone's NetIDs".