---
# System prepended metadata

title: Jam 05 - Exercise 1
tags: [uml, classes, "3 \U0001F9EA in testing", arraylist, documentation, "4 \U0001F973 done"]

---

---
title: "Jam 05 - Exercise 1"
tags: 
  - 3 🧪 in testing
  - 4 🥳 done
  - classes
  - uml
  - arraylist
  - documentation
---
<!-- markdownlint-disable line-length single-h1 no-inline-html -->
<!-- markdownlint-configure-file { "ul-indent": { "indent": 4 }, "link-fragments": {"ignore_case": true} } -->

{%hackmd dJZ5TulxSDKme-3fSY4Lbw %}

# Exercise 1 - Understanding Classes & UML Class Diagrams

## Overview of OOP concepts

Object-Oriented Programming (OOP) is a programming paradigm that organizes code into objects that contain both data and behavior. Let's explore the fundamental concepts we'll be using in this jam:

**Classes and Objects**
A class is like a blueprint that defines what something is and what it can do. Just as architects use blueprints to specify how to build houses, programmers use classes to specify how to create objects. Each object is an instance of a class - it has its own unique data but follows the structure defined by its class.

**Encapsulation**
One of the most powerful features of OOP is encapsulation - the bundling of data and the methods that operate on that data within a single unit. Think of it as a protective wrapper around an object's internals. In Java, we use access modifiers like `private` and `public` to control what parts of our objects are visible to other code.

**State and Behavior**
Objects have two main components:

- State: The data stored in the object (fields/attributes)
- Behavior: What the object can do (methods)

For example, if you think about your phone, its state includes things like battery level and screen brightness, while its behavior includes actions like making calls or taking photos.

**Object Relationships**
Objects rarely exist in isolation. They often need to work together and reference each other. Java provides several ways to manage relationships between objects, including:

- Direct references (one object containing another)
- Collections (storing groups of related objects)

**The Four Pillars of Object-Oriented Programming**
Object-oriented programming is built on four fundamental principles. In this jam, we'll focus on the first two, with the others coming in future jams:

1. ✅ **Encapsulation** - Bundling data with the methods that operate on it
    - Protecting object data and providing controlled access
    - Using access modifiers (`private`, `public`) appropriately

2. ✅ **Abstraction** - Hiding complex implementation details behind simple interfaces
    - Creating classes that present clear, simple-to-use interfaces
    - Separating what an object does from how it does it

3. 🔜 **Inheritance** - Creating new classes based on existing ones

    - Coming soon: You'll learn to build class hierarchies
    - This allows for code reuse and establishing "is-a" relationships

4. 🔜 **Polymorphism** - Treating different types of objects in a uniform way

    - Coming soon: You'll learn to write code that works with different object types
    - This enables flexible and extensible designs

:::info
💡 **Key Java Features**
Throughout this jam, we'll use several important Java features to implement these OOP concepts:

- Access modifiers (`public`, `private`) for encapsulation
- Constructors for object creation
- Method overriding for customizing behavior
- Collections for managing groups of objects

:::

Now that we understand the core concepts of object-oriented programming, we need a way to design and document our classes before implementing them. This is where UML (Unified Modeling Language) comes in.

## Understanding UML Class Diagrams

UML is an industry-standard visual modeling language used to document software systems. For this jam, we'll focus specifically on UML class diagrams - a powerful tool that helps us plan our classes by showing:

1. Classes and their names
2. Attributes (fields/properties)
3. Methods (operations)
4. Relationships between classes

Example:

```plantuml
@startuml
skinparam classAttributeIconSize 0

package jam05 {
    class Product {
      -String name
      -String sku
      -double price
      +Product(String name, String sku, double price)
      +String getName()
      +String getSku()
      +double getPrice()
      +String toString()
    }
}
@enduml
```

Note: This UML diagram is in a PlanetUML format.  You will see this format a lot in the lab writeups but you will use draw.io for your diagrams.  The biggest difference is the circle C icon in the ClassName section of the PlanetUML diagram.  This icon is not standard UML and is not used in the industry.  However, this is useful for you so you can see at a glance what type of class you are looking at.

- C - Represents a regular Class (as you've seen)
- Other types you will learn about soon:
    - I - Represents an Interface
    - A - Represents an Abstract class
    - E - Represents an Enumeration

:::info
🔑 **Key UML Concepts**

- Classes are represented as boxes with three sections:
  1. Class name at the top
  2. Attributes in the middle
  3. Methods at the bottom
- Visibility is shown with symbols:
    - `+` public
    - `-` private
    - `#` protected
- Relationships are shown with different types of lines
- Data types and return types are shown after a colon

:::

## Setting Up draw.io

Screenshot of most of the steps can be found below the instructions.

1. Visit [draw.io](https://app.diagrams.net/)
2. Select "Google Drive" to save digrams on your Bucknell Google Drive
3. Authenticate and authorize draw.io to access your Google Drive
4. Click Create New Diagram
5. Give your diagram a name like "Jam05.drawio"
6. In the search bar, search for "Class"
7. Select the first one (assuming the sort in the same order as mine did.  See the image for reference)
8. Click Create
9. Click Save (Change the Folder (in Where) if you want it saved somewhere other than your My Drive)

![drawio-setup](https://www.dropbox.com/scl/fi/pica7xxjj89uv42itfxu5/drawio-setup.png?rlkey=4iucj7aqewasxz5uwiwzlic38&raw=1)

:::warning
🚨 **Important**: You MUST use draw.io for this assignment. Screenshots or hand-drawn diagrams will not be accepted.
:::

## The Retail Store Project

Over the next few jams (Jam 05-07), you'll be building a retail store management system. This project will help you learn and apply object-oriented programming concepts while creating something practical and real-world focused.

### Project Overview

Core functionality needed for a retail store management system:

- Handle customer orders
    - Create new orders
    - Add/remove products
    - Calculate totals
    - Apply discounts
- Process sales and returns
    - Complete transactions
    - Handle different payment types
    - Process refunds
    - Generate receipts
- Track their product inventory
    - Define what a product is (name, SKU, price, etc.)
    - Organize products in a catalog
    - Track stock levels
- Manage product information
    - Search for products
    - Update product details
    - Handle price changes

To figure out where to begin, let's look at the core functionality and the relationships between the classes using a UML diagram called a "Component Diagram" (or Component-Based Diagram).  You won't need to know how to create this type of diagram in CS205, but it's a useful way to understand the relationships between the components of our system.  A class digram isn't useful yet, because we haven't identified any classes yet!

```plantuml
@startuml
skinparam component {
    BackgroundColor White
    BorderColor Black
    ArrowColor Black
}

package "Core Product Management" {
    [Products\nWhat we sell and track] as Products
    [Product Catalog\nHow we organize inventory] as Catalog
    Products --> Catalog
}

package "Order Processing" {
    [Customer Orders\nWhat customers request] as Orders
    [Transactions\nHow we track sales] as Trans
    [Payments\nHow money is handled] as Pay
    Orders --> Trans
    Trans --> Pay
}

package "Store Operations" {
    [Register\nPoint of Sale System] as Reg
    [Employees\nSystem Users] as Emp
    Reg --> Emp
}

Products --> Orders
Catalog --> Reg
Orders --> Reg
@enduml
```

When we look at all the components in this way, you can see it makes sense to start with the aspects that are related to `Products`.  This is because the `Product` is the foundation of the entire system.  It is the core entity that we are tracking and managing.  The other components are built on top of the `Product`.

In Jam 05, we'll start with the foundation:

1. Creating a `Product` class to represent individual items
2. Building a `ProductCatalog` to manage collections of products

In future jams, we'll add:

- Customer management
- Order processing
- Sales tracking
- And more!

### Starting with Products

Let's begin by designing our `Product` class. Here's the UML diagram in PlantUML format:

```plantuml
@startuml
skinparam classAttributeIconSize 0

class Product {
    -name: String
    -sku: String
    -price: double
    -description: String
    +Product(name: String, sku: String, price: double, description: String)
    +getName(): String
    +getSku(): String
    +getPrice(): double
    +getDescription(): String
    +toString(): String
    +equals(Object): boolean
}
@enduml
```

To create this in draw.io:

1. Go back to your empty draw.io diagram
2. Look at the tabs at the bottom  (like sheets on a Google Spreadsheet).  Double Click on "Page-1" and rename it to "Example"
3. Click on the plus next to your newly renamed "Example" tab.  This could be useful to you if you want to reference the example diagram in your own (or copy and paste various elements)
4. Click on the "Arrange" menu item*
5. Click on the "Insert" menu item
6. Click on "Advanced"
7. Click on "From Text"
8. Paste the following code:

```text
Product
-name: String
-sku: String
-price: double
--
+Product(name: String, sku: String, price: double)
+getName(): String
+getSku(): String
+getPrice(): double
+toString(): String
```

:::info

\*If you don't have an "Arrange" menu, your display is set to simple.  Click the theme switch and turn off simple

![image](https://hackmd.io/_uploads/rklIwdxH51l.png =50%x)

:::

Note: If you find it annoying that the background of the fields and the methods are transparent, you can select all of them by drawing a box around them and then clicking fill in the right sidebar.

![drawio-fill](https://www.dropbox.com/scl/fi/4yyt2lnyqavmyxgdzfxmf/drawio-fill.png?rlkey=fq0ljm1a74ba29j3sbanc8689&raw=1)

Now that you have created your first class diagram, let's understand its key elements:

1. **Class Name Box**
   - The top section contains just the class name `Product`
   - This identifies what we're modeling

2. **Fields/Attributes Box**
   - The middle section lists the class's data
   - Each field has:
     - Visibility modifier (`-` for private)
     - Name (like `name`, `sku`)
     - Type (like `String`, `double`)

3. **Methods Box**
   - The bottom section shows the class's behaviors
   - Each method has:
     - Visibility modifier (`+` for public)
     - Return type (or nothing for constructors)
     - Name
     - Parameters in parentheses

The diagram uses standard UML notation we've covered previously:

- `-` means private
- `+` means public
- Parameters are shown as `name : Type`
    - While UML diagrams often only show parameter types, including parameter names in some methods (like constructors) helps document the purpose of each parameter
    - This is especially useful when there are multiple parameters of the same type (like our Product constructor with multiple String parameters)
- Return types follow method names with `: Type`

This visual representation helps us:

- See the class structure at a glance
- Understand relationships between parts
- Plan before writing code
- Document our design decisions

:::info
💡 **UML Visibility Symbols**

- `+` public
- `-` private
- `#` protected
- `~` package/default

:::

### Your Task: Design the ProductCatalog

Now it's your turn! Design a UML class diagram for the `ProductCatalog` class that will:

- The catalog needs to maintain a collection of products ➔ *private ArrayList field*
- A new catalog should start empty ➔ *constructor*
- Products can be added to the catalog using an `addProduct` operation ➔ *add method*
- Products can be removed from the catalog using a `removeProduct` operation ➔ *remove method*
- A specific product can be located by calling `findBySku` with its SKU ➔ *find/search method*
- Products can be found by calling `findByName` with a product name ➔ *find/search method*
- Someone should be able to get all products via `getAllProducts` ➔ *getter method*
- The catalog should track its size with `getProductCount` ➔ *count method*
- Someone should be able to check if the catalog has any products with `isEmpty` ➔ *empty status method*

:::info
💡 **UML Design Tips**

When designing your ProductCatalog:

- Think about encapsulation (what should be public vs private)
- Consider the types for each field and method:
    - What type should the collection of products be?
    - What should methods return (void, Product, List, boolean, etc.)?
    - What parameter types do methods need?
- Plan for future extensibility

:::

Create this diagram in draw.io and save it - you'll need it for the implementation phase!

1. In the left sidebar, expand the "UML" section
2. Add a class box (the one with 3 sections divided by horizontal lines)
3. In the top section, write "ProductCatalog"
4. In the middle section, add your field(s)
5. In the bottom section, add your method(s)

You should end up with something that looks a LOT like this:

![drawio-afterCatalog](https://www.dropbox.com/scl/fi/y63tn3s4nvrbqn2pvervi/drawio-afterCatalog.png?rlkey=l6hoz8h8r8t15yc4ybxm4rngy&raw=1)

Now it's time to learn about relationships in UML! You have Product and ProductCatalog classes, but they need to show how they're connected. Let's explore the fundamental relationship type in UML - the Association relationship.

An Association relationship represents a basic connection where one class references or uses another class. In our case, ProductCatalog has a reference to Product objects through its collection - this is a good example of a simple association!

To show this in your UML diagram:

1. Draw a line from ProductCatalog to Product with an open arrow pointing to Product, showing that ProductCatalog references Products. You can draw arrows in three different ways
   1. UML Sidebar
      - Find in the UML section of the left sidebar
      - Find the correct arrow and drag to the main canvas
      - Move the ends into place
   2. Search Bar
      - Search for "association" in the search bar
      - Select the correct one (no arrowhead on one end and open arrowhead on the other)
         ![drawio-assoc](https://www.dropbox.com/scl/fi/ykgintlfr5ejz5pz2tu6q/drawio-assoc.png?rlkey=xd6vp1la5tmrigt5dkotdviyc&raw=1)
   3. Use the arrow button in the tool bar
      - Click on the button and drag from ProductCatalog pointing to Product.
      - Click on the arrow and set the arrow settings as preferred.  Here are the settings I used:
         ![drawio-arrowsettings](https://www.dropbox.com/scl/fi/4gtjlis4og5ck82qkcpp7/drawio-arrowsettings.png?rlkey=gc2uwa7bch9ngpemnundksh4u&raw=1)
   4. On the arrow, add "1" near the ProductCatalog end and "*" near the Product end to show that one ProductCatalog can reference many Products.  You can double click on the arrow to edit.

This creates what's called an "association" relationship - ProductCatalog has an association with Products. The numbers/symbols near each end of the relationship line are called "multiplicity indicators" or just "multiplicity". They specify how many objects can participate in the relationship:

- The "1" near ProductCatalog means that each Product must belong to exactly one ProductCatalog
- The "*" (read as "many" or "zero to many") near Product means a ProductCatalog can contain any number of Products - zero, one, or multiple Products

Other common multiplicity indicators include:

- "0..1" meaning zero or one
- "1..*" meaning one or more
- "2..4" meaning between 2 and 4

In our case, the "1" to "*" multiplicity shows that we have a one-to-many relationship between ProductCatalog and Product.

Note: You can place the boxes in whatever positions you find most aesthetically pleasing.  What is important is that the relationship is clear and the diagram is easy to understand.

Your diagram should now look like something like this:

![drawio-catalogRelationship](https://www.dropbox.com/scl/fi/lxubjquuur6o2we54a0uy/drawio-catalogRelationship.png?rlkey=niepokdzs6y11u08cnbxx57eq&raw=1)

Once you're happy with your UML diagram, it's time to export it as a PNG file:

1. Select File -> Export as -> PNG
2. In the export dialog:
   - In the "Include a copy of my digram" section, select "Current Page".  This is to ensure you don't end up with the example diagram in your export.
   - Click Export
3. In the Save As dialog:
   - Save the file as `Jam05-uml.drawio.png` in your `jam05` folder
   - In the "Where" box, select "Download"
   - Click OK
4. The file will be in your downloads folder.  Move it to your `src/main/java/jam05` folder.

In Exercise 2, we'll implement these designs in Java, but first, make sure your UML diagram is complete and well-thought-out!

> 🔍 **Checkpoint**
> Before moving on, verify your UML diagram includes:
>
> - UML diagram created in draw.io showing:
>     - Product class with all fields and methods
>     - ProductCatalog class with all operations
>     - Clear relationship between classes
>     - Proper visibility modifiers
>     - Complete method signatures
> - Diagram saved as `Jam05-uml.drawio.png`

## Save Your Work - Exercise 1

Verify what files are uncommitted:

```bash
git status
```

Stage your changes:

```bash
git add src/main/java/jam05/Jam05-uml.drawio.png
```

Note: If you saved the png file with any other name, you'll need to add that file instead.  You should be careful that if we give you an exact file name, you use it for grading purposes, but for this time, we will grade whatever png file you have in your `jam05` directory.

Commit your work:

```bash
git commit -m "jam05: Add UML class diagram for Product and ProductCatalog"
```

Your working directory should now be clean.
