DEV Community: Perry H

The Six Dimensions of Impedance Mismatch (Part 2 of 3): Granularity, Inheritance, and Identity

Perry H — Thu, 05 Feb 2026 18:24:39 +0000

Have you ever gotten a code review comment like this?

"You need to override equals() and hashCode() in your entity classes. Without them, your Set operations won't work correctly across sessions."

I remember getting this comment early in my career and thinking, "But it's just a simple Customer entity—why do I need to override those methods?" I added them to make the reviewer happy, but I didn't really understand why they mattered.

Months later, I ran into a subtle bug: customers were appearing twice in my HashSet, even though they represented the same customer from the database. That's when it clicked—this wasn't just a code style preference. It was about understanding how JPA manages object identity.

This is one of many issues that stem from the object-relational impedance mismatch—the fundamental incompatibility between how Java objects and relational databases represent data.

In my last post, I introduced the impedance mismatch and explained why it exists. In this post, we're diving into three specific dimensions where this mismatch creates real problems: Granularity, Inheritance, and Identity. Each one represents a decision you'll face when designing your entities, and understanding the trade-offs will help you write better code and understand your code reviews.

The next post will tackle Associations, Object Graph Navigation, and Polymorphism—where we'll address that infamous N+1 problem.

Granularity: Fine-Grained Objects vs. Flat Tables

Granularity refers to the relative size and complexity of the objects you're working with.

The problem: Java allows fine-grained object composition—an Address object can contain a Country object, which might contain a Region object, and so on. You can nest objects as deeply as your domain model requires. In SQL, we're limited to tables (entities) and columns (attributes). Any deeper nesting requires additional tables and foreign keys.

A Common Example: Company and Address

Consider a Company entity that has an Address. In Java, we'd naturally model this as two separate classes:

public class Company {
    private Long id;
    private String name;
    private Address address;  // Separate object
}

public class Address {
    private String street;
    private String city;
    private String state;
    private String zipCode;
}

But in SQL, there's no "Address" data type. We have several options:

Option 1: Single address column (not recommended)

CREATE TABLE companies (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255),
    address TEXT  -- "123 Main St, Springfield, IL 62701" as a string
);

Hard to query, hard to validate, hard to work with.

Option 2: Flatten address into company table

CREATE TABLE companies (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255),
    street VARCHAR(255),
    city VARCHAR(255),
    state VARCHAR(2),
    zip_code VARCHAR(10)
);

Works, but what if we need multiple addresses (billing vs. shipping)?

Option 3: Separate address table

CREATE TABLE companies (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255),
    address_id BIGINT,
    FOREIGN KEY (address_id) REFERENCES addresses(id)
);

CREATE TABLE addresses (
    id BIGINT PRIMARY KEY,
    street VARCHAR(255),
    city VARCHAR(255),
    state VARCHAR(2),
    zip_code VARCHAR(10)
);

More normalized, but now we need joins for every company query.

The JPA Solution: @embeddable

Spring JPA gives us @Embeddable, which lets us have our cake and eat it too—modular Java code with clear separation of concerns, mapped to a flat table structure that SQL understands:

@Entity
@Table(name = "companies")
public class Company {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @Embedded
    private Address address;  // Embedded, not a separate table!
}

@Embeddable
public class Address {
    private String street;
    private String city;
    private String state;

    @Column(name = "zip_code")
    private String zipCode;
}

This maps to the flattened table structure:

CREATE TABLE companies (
    id BIGINT PRIMARY KEY,
    name VARCHAR(255),
    street VARCHAR(255),      -- From Address
    city VARCHAR(255),        -- From Address
    state VARCHAR(2),         -- From Address
    zip_code VARCHAR(10)      -- From Address
);

Multiple Embedded Objects

What if a company has both a billing and shipping address? Use @AttributeOverrides:

@Entity
public class Company {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "street", column = @Column(name = "billing_street")),
        @AttributeOverride(name = "city", column = @Column(name = "billing_city")),
        @AttributeOverride(name = "state", column = @Column(name = "billing_state")),
        @AttributeOverride(name = "zipCode", column = @Column(name = "billing_zip_code"))
    })
    private Address billingAddress;

    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "street", column = @Column(name = "shipping_street")),
        @AttributeOverride(name = "city", column = @Column(name = "shipping_city")),
        @AttributeOverride(name = "state", column = @Column(name = "shipping_state")),
        @AttributeOverride(name = "zipCode", column = @Column(name = "shipping_zip_code"))
    })
    private Address shippingAddress;
}

The key insight: With @Embeddable, we maintain clean domain modeling in Java while respecting the limitations of SQL's two-level granularity (tables and columns).

Inheritance: "Is-A" Relationships Meet SQL

In object-oriented programming, we use inheritance to represent "is-a" relationships:

A Dog is an Animal
A CreditCard is a BillingDetails
A Manager is an Employee

SQL has no native concept of inheritance. It only understands tables, columns, and relationships (foreign keys). So how do we persist an inheritance hierarchy?

The Classic Example: Payment Methods

public abstract class BillingDetails {
    private Long id;
    private String owner;
    // Common behavior for all payment methods
    public abstract boolean validate();
}

public class CreditCard extends BillingDetails {
    private String cardNumber;
    private String expiryDate;
    private String cvv;

    @Override
    public boolean validate() {
        // Luhn algorithm, expiry check, etc.
    }
}

public class BankAccount extends BillingDetails {
    private String accountNumber;
    private String routingNumber;
    private String bankName;

    @Override
    public boolean validate() {
        // Routing number validation, account verification, etc.
    }
}

Each subclass has different data and different behavior. How do we store this in SQL tables?

JPA provides three strategies, each with different trade-offs. Let's explore them.

Strategy 1: Table Per Class Hierarchy (SINGLE_TABLE)

The idea: One table contains all columns for all classes in the hierarchy, with a discriminator column to identify the type.

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "billing_type", discriminatorType = DiscriminatorType.STRING)
public abstract class BillingDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String owner;
}

@Entity
@DiscriminatorValue("CREDIT_CARD")
public class CreditCard extends BillingDetails {
    @Column(name = "card_number")
    private String cardNumber;

    @Column(name = "expiry_date")
    private String expiryDate;

    private String cvv;
}

@Entity
@DiscriminatorValue("BANK_ACCOUNT")
public class BankAccount extends BillingDetails {
    @Column(name = "account_number")
    private String accountNumber;

    @Column(name = "routing_number")
    private String routingNumber;

    @Column(name = "bank_name")
    private String bankName;
}

The SQL schema:

CREATE TABLE billing_details (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    billing_type VARCHAR(20) NOT NULL,  -- Discriminator: 'CREDIT_CARD' or 'BANK_ACCOUNT'
    owner VARCHAR(255),

    -- CreditCard fields (NULL for BankAccount rows)
    card_number VARCHAR(20),
    expiry_date VARCHAR(7),
    cvv VARCHAR(4),

    -- BankAccount fields (NULL for CreditCard rows)
    account_number VARCHAR(20),
    routing_number VARCHAR(9),
    bank_name VARCHAR(255)
);

Sample data:

-- Credit card row
INSERT INTO billing_details (billing_type, owner, card_number, expiry_date, cvv, account_number, routing_number, bank_name)
VALUES ('CREDIT_CARD', 'John Doe', '4532123456789012', '12/25', '123', NULL, NULL, NULL);

-- Bank account row
INSERT INTO billing_details (billing_type, owner, card_number, expiry_date, cvv, account_number, routing_number, bank_name)
VALUES ('BANK_ACCOUNT', 'Jane Smith', NULL, NULL, NULL, '1234567890', '021000021', 'Chase Bank');

Trade-offs:

✅ Pros:

Simple schema (one table)
Fast polymorphic queries (no joins needed)
Fast inserts and updates
Easy to add new subclasses (just add columns)

❌ Cons:

Many NULL columns (denormalized)
Cannot enforce NOT NULL constraints on subclass-specific columns
Table can become very wide with many subclasses
Violates database normalization principles

When to use: When you need fast polymorphic queries and have a relatively small, stable class hierarchy.

Strategy 2: Table Per Subclass (JOINED)

The idea: One table for the base class, separate tables for each subclass, joined by foreign keys.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class BillingDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String owner;
}

@Entity
@Table(name = "credit_cards")
public class CreditCard extends BillingDetails {
    @Column(name = "card_number")
    private String cardNumber;

    @Column(name = "expiry_date")
    private String expiryDate;

    private String cvv;
}

@Entity
@Table(name = "bank_accounts")
public class BankAccount extends BillingDetails {
    @Column(name = "account_number")
    private String accountNumber;

    @Column(name = "routing_number")
    private String routingNumber;

    @Column(name = "bank_name")
    private String bankName;
}

The SQL schema:

-- Parent table
CREATE TABLE billing_details (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    owner VARCHAR(255) NOT NULL
);

-- Child table for credit cards
CREATE TABLE credit_cards (
    id BIGINT PRIMARY KEY,
    card_number VARCHAR(20) NOT NULL,
    expiry_date VARCHAR(7) NOT NULL,
    cvv VARCHAR(4) NOT NULL,
    FOREIGN KEY (id) REFERENCES billing_details(id) ON DELETE CASCADE
);

-- Child table for bank accounts
CREATE TABLE bank_accounts (
    id BIGINT PRIMARY KEY,
    account_number VARCHAR(20) NOT NULL,
    routing_number VARCHAR(9) NOT NULL,
    bank_name VARCHAR(255) NOT NULL,
    FOREIGN KEY (id) REFERENCES billing_details(id) ON DELETE CASCADE
);

Sample data:

-- Credit card
INSERT INTO billing_details (id, owner) VALUES (1, 'John Doe');
INSERT INTO credit_cards (id, card_number, expiry_date, cvv) 
VALUES (1, '4532123456789012', '12/25', '123');

-- Bank account
INSERT INTO billing_details (id, owner) VALUES (2, 'Jane Smith');
INSERT INTO bank_accounts (id, account_number, routing_number, bank_name)
VALUES (2, '1234567890', '021000021', 'Chase Bank');

How queries work:

// Fetch a specific credit card - requires JOIN
entityManager.find(CreditCard.class, 1L);

// SQL generated:
// SELECT bd.id, bd.owner, cc.card_number, cc.expiry_date, cc.cvv
// FROM billing_details bd
// INNER JOIN credit_cards cc ON bd.id = cc.id
// WHERE bd.id = 1;

// Fetch all billing details polymorphically - requires multiple JOINs
List<BillingDetails> all = entityManager
    .createQuery("SELECT b FROM BillingDetails b", BillingDetails.class)
    .getResultList();

// SQL generated:
// SELECT bd.id, bd.owner, 
//        cc.card_number, cc.expiry_date, cc.cvv,
//        ba.account_number, ba.routing_number, ba.bank_name
// FROM billing_details bd
// LEFT JOIN credit_cards cc ON bd.id = cc.id
// LEFT JOIN bank_accounts ba ON bd.id = ba.id;

Trade-offs:

✅ Pros:

Normalized schema (no NULLs except in polymorphic queries)
Can enforce NOT NULL constraints on all columns
Supports polymorphic associations cleanly
Easy to understand schema
Each table represents exactly one class

❌ Cons:

Requires joins for every query (slower reads)
More complex query execution plans
Multiple inserts required for one object
Can have performance issues with deep hierarchies

When to use: When data integrity and normalization are priorities, and you can accept the performance cost of joins.

Strategy 3: Table Per Concrete Class (TABLE_PER_CLASS)

The idea: Completely separate tables for each concrete class, duplicating parent class columns.

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public abstract class BillingDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.TABLE)  // Note: TABLE strategy
    private Long id;

    private String owner;
}

@Entity
@Table(name = "credit_cards")
public class CreditCard extends BillingDetails {
    @Column(name = "card_number")
    private String cardNumber;

    @Column(name = "expiry_date")
    private String expiryDate;

    private String cvv;
}

@Entity
@Table(name = "bank_accounts")
public class BankAccount extends BillingDetails {
    @Column(name = "account_number")
    private String accountNumber;

    @Column(name = "routing_number")
    private String routingNumber;

    @Column(name = "bank_name")
    private String bankName;
}

The SQL schema:

-- No parent table! Each concrete class has its own complete table

CREATE TABLE credit_cards (
    id BIGINT PRIMARY KEY,
    owner VARCHAR(255) NOT NULL,  -- Duplicated from parent
    card_number VARCHAR(20) NOT NULL,
    expiry_date VARCHAR(7) NOT NULL,
    cvv VARCHAR(4) NOT NULL
);

CREATE TABLE bank_accounts (
    id BIGINT PRIMARY KEY,
    owner VARCHAR(255) NOT NULL,  -- Duplicated from parent
    account_number VARCHAR(20) NOT NULL,
    routing_number VARCHAR(9) NOT NULL,
    bank_name VARCHAR(255) NOT NULL
);

How queries work:

// Fetch specific type - simple, no joins
entityManager.find(CreditCard.class, 1L);
// SELECT id, owner, card_number, expiry_date, cvv FROM credit_cards WHERE id = 1;

// Fetch polymorphically - requires UNION
List<BillingDetails> all = entityManager
    .createQuery("SELECT b FROM BillingDetails b", BillingDetails.class)
    .getResultList();

// SQL generated (inefficient!):
// SELECT id, owner, card_number, expiry_date, cvv, NULL as account_number, NULL as routing_number, NULL as bank_name
// FROM credit_cards
// UNION ALL
// SELECT id, owner, NULL, NULL, NULL, account_number, routing_number, bank_name
// FROM bank_accounts;

Trade-offs:

✅ Pros:

No NULLs (fully normalized for each type)
Fast queries for specific concrete types
Can enforce NOT NULL on all columns
Schema clearly shows concrete types

❌ Cons:

Polymorphic queries are very slow (UNION across all tables)
Changes to parent class require schema updates across all tables
Identity management is complex (need to ensure uniqueness across tables)
Poor support for polymorphic associations
Code duplication in schema

When to use: Rarely. Only when you never need polymorphic queries and mostly work with specific concrete types.

Strategy Comparison Table

Aspect	SINGLE_TABLE	JOINED	TABLE_PER_CLASS
Schema Complexity	Simple	Moderate	Simple
Query Performance	Fast	Moderate (joins required)	Fast for concrete types, very slow for polymorphic
Polymorphic Queries	Excellent	Good	Poor (UNION)
Normalization	Poor (many NULLs)	Excellent	Excellent per type
Schema Changes	Easy (add columns)	Moderate (add/modify tables)	Hard (update all tables)
Data Integrity	Cannot enforce NOT NULL on subclass columns	Full NOT NULL support	Full NOT NULL support
Recommended Use	Small hierarchies, frequent polymorphic queries	Well-normalized apps, complex hierarchies	Avoid (legacy codebases only)

In practice: Most Spring Boot applications use SINGLE_TABLE for simplicity and performance, or JOINED when data integrity is critical.

Identity: The "Identity Crisis" (The Most Critical Part)

In Java, we have two ways to check if objects are "the same":

Customer c1 = new Customer("John", "[email protected]");
Customer c2 = new Customer("John", "[email protected]");

c1 == c2;        // false (different objects in memory)
c1.equals(c2);   // depends on equals() implementation

In SQL, identity is defined by the primary key:

SELECT * FROM customers WHERE id = 123;  -- Identity is the primary key value

The problem arises when we map objects to database rows. Consider this scenario:

// Same JPA session - object identity is preserved
EntityManager em = entityManagerFactory.createEntityManager();
Customer c1 = em.find(Customer.class, 1L);
Customer c2 = em.find(Customer.class, 1L);

System.out.println(c1 == c2);  // true! (Hibernate returns the same instance)

// Different sessions - different object instances
EntityManager em1 = entityManagerFactory.createEntityManager();
EntityManager em2 = entityManagerFactory.createEntityManager();

Customer c3 = em1.find(Customer.class, 1L);
Customer c4 = em2.find(Customer.class, 1L);

System.out.println(c3 == c4);  // false! (different instances)
System.out.println(c3.equals(c4));  // ??? depends on equals() implementation

The Collection Problem

This becomes especially problematic with collections:

@Entity
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String email;

    // Using default equals() and hashCode() (BAD!)
}

// Later in code:
Set<Customer> customers = new HashSet<>();

EntityManager em1 = entityManagerFactory.createEntityManager();
Customer c1 = em1.find(Customer.class, 1L);
customers.add(c1);

EntityManager em2 = entityManagerFactory.createEntityManager();
Customer c2 = em2.find(Customer.class, 1L);

customers.contains(c2);  // FALSE! Even though it's the same database row!
customers.size();         // 2 if you add c2, even though they represent the same customer

The Solution: Override equals() and hashCode()

Every JPA entity should override equals() and hashCode(). There are three main approaches, each with important implementation details.

Important Implementation Details First

Before we look at the approaches, here are critical points that apply to all of them:

1. Use instanceof, not getClass()

// CORRECT - works with Hibernate proxies
if (!(o instanceof Customer)) return false;

// WRONG - fails with Hibernate proxies
if (this.getClass() != o.getClass()) return false;

Why? Hibernate often returns proxy objects (runtime-generated subclasses) for lazy-loaded entities. Using getClass() would make a proxy and the real entity unequal, even though they represent the same database row.

2. Use getters, not direct field access

// CORRECT - works with Hibernate proxies
return getId() != null && Objects.equals(getId(), other.getId());

// WRONG - may return null for uninitialized proxies
return id != null && Objects.equals(id, other.id);

Why? When other is a Hibernate proxy, accessing other.id directly might return null because the proxy hasn't been initialized yet. But other.getId() will trigger initialization and return the actual ID.

3. The hashCode() constant trade-off

@Override
public int hashCode() {
    return getClass().hashCode();  // or return 31;
}

This returns the same hash for all instances of the class. Yes, this turns a HashSet into effectively a linked list (O(n) lookups instead of O(1)). This is intentional.

Why? Because the hash must remain stable when an entity transitions from transient (no ID) to managed (has ID). If your hashCode() changes, entities already in a HashSet become unfindable.

The trade-off: Stability over performance. For most applications, this is the right choice—collections of entities are usually small enough that O(n) performance is acceptable.

Approach 1: ID-Based Equality (Use Getters!)

@Entity
@Table(name = "customers")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private String email;

    public Long getId() {
        return id;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Customer)) return false;  // Works with proxies

        Customer other = (Customer) o;

        // Use getters to handle proxies correctly
        return getId() != null && Objects.equals(getId(), other.getId());
    }

    @Override
    public int hashCode() {
        // Constant hash ensures stability across persistence states
        // Trade-off: O(n) HashSet performance for stability
        return getClass().hashCode();
    }
}

Pros:

Simple and straightforward
Works correctly with Hibernate proxies (via getter)
Uses the database's notion of identity

Cons:

Only works after persistence (when ID is assigned)
Two new (unsaved) entities with identical data won't be equal
Can't add transient entities to a Set and expect to find them after persistence

When to use: Most applications, especially when you don't have a natural business key.

Approach 2: Business Key (Natural ID)

@Entity
@Table(name = "customers")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(unique = true, nullable = false)
    private String email;  // Natural business key - must be immutable!

    private String name;

    public String getEmail() {
        return email;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Customer)) return false;

        Customer other = (Customer) o;

        // Use business key - works before AND after persistence
        return Objects.equals(getEmail(), other.getEmail());
    }

    @Override
    public int hashCode() {
        // Hash based on business key
        return Objects.hash(email);
    }
}

Pros:

Works for both transient and persistent entities
Matches business domain logic (two customers with same email are the same)
More intuitive for domain modeling

Cons:

Requires truly immutable business key - if email changes, entity becomes unfindable in collections
Not all entities have natural business keys
Business rules may change (what if email isn't unique anymore?)

When to use: When you have a genuinely immutable, unique business identifier (username, SSN, ISBN, etc.).

Approach 3: UUID Primary Keys (Recommended for Modern Apps)

@Entity
@Table(name = "customers")
public class Customer {
    @Id
    @GeneratedValue(generator = "UUID")
    @GenericGenerator(name = "UUID", strategy = "org.hibernate.id.UUIDGenerator")
    @Column(updatable = false, nullable = false)
    private UUID id;

    private String name;
    private String email;

    // Constructor assigns UUID immediately
    public Customer() {
        this.id = UUID.randomUUID();
    }

    public UUID getId() {
        return id;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Customer)) return false;

        Customer other = (Customer) o;

        // UUID is assigned at creation, so this always works
        return Objects.equals(getId(), other.getId());
    }

    @Override
    public int hashCode() {
        // Can safely hash the UUID since it's assigned in constructor
        return Objects.hash(id);
    }
}

Pros:

ID is assigned at object creation (not at persist time)
Works correctly for both transient and persistent entities
No need for business key
Works perfectly with HashSet and other collections
Distributed-system friendly (no database roundtrip for ID generation)

Cons:

UUIDs are larger than integers (16 bytes vs 4/8 bytes)
Slightly slower for database joins (though rarely noticeable)
Less human-readable in logs/debugging

When to use: Modern Spring Boot applications, especially microservices or distributed systems. This is increasingly becoming the default recommendation.

The Symmetry Violation Problem

You might be tempted to create a "hybrid" approach:

// DON'T DO THIS - it violates equals() symmetry!
@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Customer)) return false;

    Customer other = (Customer) o;

    // Use ID if both have IDs
    if (getId() != null && other.getId() != null) {
        return Objects.equals(getId(), other.getId());
    }

    // Otherwise fall back to business key
    return Objects.equals(getEmail(), other.getEmail());
}

The problem: This violates the symmetry contract of equals().

Customer c1 = new Customer("[email protected]");  // Transient, no ID yet
entityManager.persist(c1);  // Now has ID = 1

Customer c2 = new Customer("[email protected]");  // Transient, no ID

c1.equals(c2);  // Uses ID path -> false (one has ID, one doesn't)
c2.equals(c1);  // Uses business key path -> true (same email)

// Symmetry violated! c1.equals(c2) != c2.equals(c1)

This breaks the equals() contract and causes unpredictable behavior in collections.

The lesson: Pick one strategy and stick with it consistently.

Why This Matters

Without proper equals() and hashCode():

Collections don't work correctly

   Set<Customer> customers = new HashSet<>();
   customers.add(customerFromSession1);
   customers.add(customerFromSession2);  // Duplicate!

Cascade operations can fail

   order.setCustomer(customerFromDifferentSession);
   // Hibernate might think this is a different customer!

Caching breaks

   // Second-level cache might store duplicates

Lazy loading issues

   customer.getOrders().contains(orderFromDifferentSession);  // false!

Bottom line: Always override equals() and hashCode() in your JPA entities. When in doubt, use UUIDs as your primary key strategy.

What We've Learned

We've covered three of the six impedance mismatch dimensions:

Granularity: Solved with @Embeddable for composition without extra tables—letting us maintain clean domain models while respecting SQL's flat structure.
Inheritance: Three strategies with different trade-offs:
- SINGLE_TABLE: Fast, simple, but denormalized
- JOINED: Normalized, but requires joins
- TABLE_PER_CLASS: Rarely used, poor polymorphic query support

Choose based on your query patterns and data integrity requirements.

Identity: Always override equals() and hashCode() in entities. Use UUIDs for simple, robust identity management, or business keys when you have truly immutable natural identifiers.

Each of these represents a fundamental difference in how objects and relational databases model the world. JPA gives us tools to bridge the gap, but we need to understand the trade-offs to make good architectural decisions.

Coming up next: Associations, Object Graph Navigation, and Polymorphism—where we'll tackle the N+1 problem, lazy loading gotchas, LazyInitializationException, and polymorphic queries.

Key takeaway: Understanding these mismatches isn't just academic—it directly impacts your code reviews, performance optimization, and debugging sessions. The next time you see LazyInitializationException or get feedback about an N+1 problem, you'll understand why these issues exist and how to address them effectively.

Additional Resources:

Part of a series on understanding ORM fundamentals for modern Spring Boot developers. Based on lessons from "Hibernate in Action" (2005) synthesized with current best practices.

The Object-Relational Impedance Mismatch: Why Your Java Objects and Database Tables Don't Play Nice

Perry H — Thu, 29 Jan 2026 14:36:59 +0000

Have you seen this error?

org.hibernate.LazyInitializationException: failed to lazily initialize a collection of role: com.example.Customer.orders, could not initialize proxy - no Session

If you're a Spring Boot developer, you probably have. I know I have. A few times. Staring brutally back at me while debugging, as I frustratingly wonder why I can't just get a customer's orders.

To understand why, we need to go back to 1970—the year Edgar F. Codd published his paper on the relational model. In 1995, Java 1.0 was released with its object-oriented paradigm. Both were excellent innovations. But they were designed for different purposes, using different mathematical foundations, optimizing for different goals.

And we developers have been caught in the middle of these two paradigms.

Let's see what this means in practice:

In Java, you write something like:

customer.getOrders().get(0).getProduct().getName();

In SQL, the same task looks like:

SELECT p.name FROM customers c
JOIN orders o ON c.id = o.customer_id
JOIN order_items oi ON o.id = oi.order_id
JOIN products p ON oi.product_id = p.id
WHERE c.id = 123;

These two things accomplish the same task, but notice how different they are. The Java version navigates through objects. The SQL version joins tables. This
isn't just different syntax—it's fundamentally different ways of thinking about data. The first example is based on domain modeling, and the second relational modeling. This is one example of what we call the "object-relational impedance mismatch"—a fundamental incompatibility between how objects and relational databases represent data.

We often use relational databases, but use domain modeling in our Java code and we bridge this gap using Object-Relational Mappers (ORMs). In the Java world, we commonly use tools like Spring JPA and Hibernate (an ORM). But to use these tools effectively, we need to understand the impedance mismatch. Let's dive in and see why it matters for your daily work.

The Two Paradigms: A Tale of Two Models

A. The Relational Model: Sets and Tables

Let's dive into the relational side of things first.

Codd advocated that application software should not be affected by changes in how data is stored on a disk or how it is accessed internally by the system. This novel idea allowed for the introduction of treating data as mathematical relations rather than a series of linked lists or pointers. This, of course, allowed for better and easier queries (hello SQL).

The key insight? Making the data independent of the physical machine representation allowed for a transition from telling a computer how to find data to simply stating what data is needed. This shift also enabled the normalization of data for improved integrity.

Relational modeling essentially uses Set Theory to model data. If you have spent any time in a production SQL database, you have seen this type of modeling before.

Let's suppose we have a customers table and an orders table. There is a foreign key relationship between the customers table and the orders table.

Here is an example of a query, using relational thinking: "give me all active customers and their orders"

SELECT c.name, o.order_date, o.total
FROM customers c
JOIN orders o ON c.id = o.customer_id
WHERE c.status = 'ACTIVE';

Fun, right? In Codd's mathematical terms:

Set C (Active Customers)
Set O (Orders)
The Join Predicate: The ON c.id = o.customer_id acts as the predicate that defines which members of the two sets belong together in the resulting set.

This can be a wonderful way to reason with data and has its benefits. However, let's get into how most Spring Boot developers would like to reason with data.

B. The Object-Oriented Domain Model: Graphs and Behavior

Most developers are familiar with Object-Oriented Programming (OOP) and its core principles: encapsulation, inheritance, polymorphism, and abstraction. These principles enable the construction of clear, modular, and maintainable code.

In domain modeling, OOP allows us to represent a business domain as a living graph of interacting objects. Unlike rows in a database, these objects contain both data and the behavior that acts on that data.

Here is an example in code that will look familiar:

class Customer {
    private UUID id;
    private String name;
    private Status status; 
    private List<Order> orders; 

    public List<Order> getActiveOrders() {
        if (this.status != Status.ACTIVE) {
            return Collections.emptyList();
        }
        return this.orders;
    }
}

class Order {
    private LocalDateTime orderDate;
    private Money total;
}

// Navigate the object graph and leverage behavior 
Customer customer = customerRepository.findById(customerId); 
for (Order order : customer.getActiveOrders()) {
    System.out.println(order.getTotal());
}

Notice how natural this looks. By applying OOP principles—especially encapsulation—we can navigate from customers to orders to products by simply calling methods. No explicit JOINs needed. This makes our code more readable and keeps business logic (like filtering for active orders) right where it belongs: in the domain model.

The Core Tension

This object-oriented approach is intuitive and maintainable. But we still need to persist this data somewhere—and that somewhere is often a relational
database.

Object-Relational Mapping attempts to bridge this gap.

The mismatch breaks down into six dimensions: Granularity, Inheritance, Identity, Associations, Object Graph Navigation, and Polymorphism. Each dimension represents a challenge that ORMs must solve to help us with the impedance mismatch.

The impedance mismatch isn't a flaw—it's a result of different paradigms with different goals. Modern tools like JPA and Hibernate help us bridge the gap, but they don't eliminate the problem entirely.

Understanding this mismatch is crucial because it affects:

How you design your entities
The performance of your application
The bugs you'll encounter (hello, LazyInitializationException!)
The architectural decisions you make

In the next post, we'll dive deep into each of the six dimensions of mismatch, exploring real-world examples and how Spring Boot/JPA handles each one.

Next in this series: The Six Dimensions of Impedance Mismatch

Bachmanity Bytes: A Nod to Silicon Valley (And an Excuse to Mess Around with Kotlin)

Perry H — Sun, 07 Dec 2025 02:45:41 +0000

If you've worked in tech and watched Silicon Valley, you know it hits surprisingly close to home.

The VCs who love the vision more than the details? Familiar. The pivot meetings where everyone stays optimistic? They happen. Engineers having passionate debates about code style? Guilty.

Every time I rewatch an episode, I recognize moments from my own career. Gavin Belson's corporate speak? I've heard those presentations. The Hooli engineers building ambitious projects? That's just how innovation works. Russ Hanneman's energy at networking events? You've probably met someone similar.

The show ended in 2019, but somehow it captured something timeless about tech culture. So naturally, I decided to honor it the only way I know how: by building something completely unnecessary.

The Premise Nobody Asked For

You know what the world definitely doesn't need? Another quote website. You know what I built anyway? A Silicon Valley quote generator with a brutalist 80s terminal aesthetic that looks like it belongs in a museum exhibit called "Computers Were a Mistake."

Does anyone need daily Gavin Belson wisdom? No (well, maybe). Will this change anyone's life? Absolutely not. Did I deploy it to Google Cloud anyway? You bet.

Welcome to Bachmanity Bytes.

Why Kotlin? Because It's Actually Good

Typically, with a simple web app like this, one would generally reach for JavaScript. Instead, I chose Kotlin because it's genuinely enjoyable to work with. It's like Java went to therapy and came back a better person—all the power, none of the boilerplate.

The stack:

Kotlin - for that sweet, sweet null safety
Ktor - because Spring Boot felt like bringing a flamethrower to a candle-lighting ceremony
Kotlinx Serialization - JSON without wanting to throw my laptop out the window
Google App Engine - because I wanted to experience the joy of IAM permissions at 11pm

The Architecture (Using That Word Loosely)

┌─────────────────┐     ┌─────────────────┐
│   Ktor Server   │     │   Clikt CLI     │
├─────────────────┤     ├─────────────────┤
│  /api/daily     │     │  daily          │
│  /api/random    │     │  random         │
│  /              │     │  serve          │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     │
              ┌──────┴──────┐
              │ QuoteService │ ──→ 80 quotes of wisdom
              └─────────────┘

The daily quote uses LocalDate.now().toEpochDay() % quotes.size to pick a quote. This means everyone gets the same quote each day, which is either a feature or a bug depending on how you look at it. I'm calling it a feature.

Additionally, I wanted to build in the same functionality for the command line.

The CLI Nobody Asked For (But I Built Anyway)

Because a web app wasn't enough over-engineering, I also built a CLI using Clikt. Now you can get Gavin Belson wisdom without ever leaving your terminal.

# Get today's quote
bachmanity-bytes daily

# Feeling chaotic? Random quote
bachmanity-bytes random

# Want episode details? Be verbose about it
bachmanity-bytes daily -v

# Start the web server locally
bachmanity-bytes serve -p 3000

Output looks like this:

"Not hotdog!"

  — Jian-Yang

Add the -v flag and you get:

"Not hotdog!"

  — Jian-Yang (S4E4)

Is this practical? No. But there's something satisfying about typing bachmanity-bytes random and getting a bit of humor during a frustrating coding session.

The "Design" (Air Quotes Intentional)

I wanted a brutalist 80s aesthetic. You know, the kind of UI that embraces hard edges and terminal vibes.
cssbody {
background: #0a0a0a;
color: #00ff41;
font-family: 'VT323', 'Courier New', monospace;
}
Black background. Neon green text. CRT scanlines. Sharp, clean edges throughout. It looks like what would happen if a terminal and a rave had a baby, and honestly? I'm here for it.
I used AI (thanks Claude) for the styling and front-end functionality, because life's too short to wrestle with CSS when you just want to build something fun.

Deploying to App Engine: A Journey

Step 1: Run gcloud app deploy
Step 2: Get a permissions error about storage buckets
Step 3: Google the error
Step 4: Run some IAM command
Step 5: Paste the command wrong because of line breaks
Step 6: Finally get it working
Step 7: Realize you could have just used the Cloud Console UI

The deployment actually works now though. Scales to zero when nobody's using it (which is always), so it costs approximately nothing to run my monument to unnecessary engineering.

The Quotes

80 hand-curated gems including:

"This guy f***s!" - Russ Hanneman
"Not hotdog." - Jian-Yang
"I don't want to live in a world where someone else makes the world a better place better than we do." - Gavin Belson
"The bear is sticky with honey." - Jared Dunn

I have no idea what that last one means but it felt important to include.

Full disclosure: I used AI to generate these quotes. Are they all 100% accurate to the show? Probably not. Did I fact-check any of them? Absolutely not. If Jared never actually said "The bear is sticky with honey," I don't want to know. It's canon now.

This is either a testament to how memorable the show's writing is, or a demonstration of AI confidently making things up. Either way, they feel right, and that's basically the same as being right.

What I Actually Learned

Ktor is nice - Seriously, the HTML DSL is clean and embedding CSS/JS inline worked fine for this tiny project
App Engine is still a thing - And it's actually pretty simple once you figure out the permissions dance
Building useless things is fun - Sometimes you just want to see Gilfoyle quotes in neon green

Try It

Live at: https://bachmanity-bytes.uc.r.appspot.com

The code (here) is exactly as messy as you'd expect from a project built in one sitting. The CSS is inline. The JavaScript is inline. Everything is in a couple of Kotlin files. It compiles, which is basically the same as working, right?

Conclusion

Did I spend several hours building a quote website that nobody will use? Yes. Did I learn some Ktor and refresh my App Engine knowledge? Also yes. Would Erlich Bachman be proud?

He'd probably try to take 10% equity.

If you want to waste your time building something equally pointless, I highly recommend it. It's cheaper than therapy and slightly more productive than doomscrolling.

Java > Python for AI Agents? I Built a Surf-Forecasting Agent to Find Out

Perry H — Sat, 29 Nov 2025 01:30:34 +0000

StokeBroker: My Journey Building an AI Surf Agent with Java and Embabel

Shots fired! Sorry Python people, but let me explain. Only a couple of days after I wrote CodeBro, my AI agent written in Java, I discovered this post called You Can Build Better AI Agents in Java Than Python. Ha! I love it (hence the clickbait title).

The post was written by Rod Johnson (creator of Spring framework) and he introduced his framework for writing AI agents on the JVM. Granted he was using Kotlin, but since I've been a Java guy for most of my professional career, I think Java is the way I will roll. I'll dive into Kotlin later. The framework is called Embabel. So I figured I'd give it a run and see how it stacks up to my custom creation. Spoiler Alert: it's way better.

Anyhow, as always, I want to create something but this is just for fun so it will serve no real purpose and will probably have no practical use. Not everything has to be a startup idea.

One of my hobbies is surfing, so I decided to create an agent that gets my local surf conditions and tells me if it's good enough to call in sick (Don't tell). Mind you, you can get most of this info from Surfline, but like I said, I'm just messing around so chill.

I shall call it StokeBroker.

Embabel

First we have to figure out how Embabel works. They have some pretty nice docs but who has the time to read them? So naturally I jump straight to the quickstart.

Embabel docs recommend putting the token as an .env variable. This didn't work at first... wonderful. I took a look at the startup script and it was not loading the .env file. Fixed that by adding the proper configuration to the script.

Boom! That worked and I already see the demo running. It shows much more output than CodeBro, including detailed plan steps and even cost and token usage at the end. Slick.

Now I gotta figure out how to plan out StokeBroker. Crap, I may actually need to read the docs for this...

Unlike standard "chain" frameworks (like LangChain) that just string prompts together, Embabel uses GOAP (Goal-Oriented Action Planning).

Most AI agents work like a flowchart:

Step 1 -> Step 2 -> Step 3. (If Step 2 fails, the whole chain breaks).

Embabel works like a GPS:

Destination: "Find safe surf." Route: "I see a traffic jam (Bad Wind), so I will reroute to a different beach (Action B) to get to the destination."

It separates the "What" (Goal) from the "How" (Plan). I can see how this is useful.

Another interesting thing is that Embabel allows us to mix non-AI operations with AI operations seamlessly. This appeals to my inner Java developer who likes clean separation of concerns.

The Plan

Here's how I broke down the architecture:

   │
                              ├─── Agent Brain (Reasoning Layer)
                              │    ├─ Swell Energy Calculator
                              │    ├─ Wind Quality Analyzer
                              │    ├─ Spot Matcher (Rule Engine)
                              │    ├─ Board Recommender
                              │    └─ Alert Threshold Evaluator
                              │
                              ├─── Data Acquisition Layer
                              │    ├─ NOAA Buoy Service (Wave Data)
                              │    ├─ NOAA Tide Service (Tide Predictions)
                              │    ├─ NWS Marine Forecast Service
                              │    └─ Data Aggregator & Cache
                              │
                              ├─── Knowledge Base (In-Memory)
                              │    ├─ Spot Repository (Oak Island Breaks)
                              │    ├─ Wind Direction Rules per Spot
                              │    ├─ Tide Preferences per Spot
                              │    └─ Swell Window Configurations
                              │
                              └─── User Interface Layer
                                   ├─ CLI Shell (Spring Shell)
                                   └─ Report Generator

Basically, I think we need a reasoning layer; a data acquisition layer; a data layer or knowledge base (which for simplicity will be in memory); and finally a shell to interact. This is similar to CodeBro but with the additional complexity of getting external data and storing it.

Building the Beast (or trying to)

So, armed with my architecture diagram (which looks way more professional than the actual code), I started hacking away.

The cool thing about Embabel is that you define Actions. These are like the Lego blocks of your agent's brain. You just slap an @Action annotation on a method, and suddenly your AI knows how to do that thing.

I decided to build a Pipeline (fancy word for "doing things in order").

extractLocation: First, I need to know where we are going. I let the AI figure this out from my incoherent rambling (e.g., "How's the pier?").

fetchConditions: This is where the Java magic happens. I wrote a boring old service to fetch JSON from NOAA. No AI here, just cold, hard data.

analyzeQuality: Here's the kicker. I feed that raw data back into the AI, along with my "Knowledge Base" (a list of rules about wind direction and swell angle). The AI acts like a snobby local surfer and judges the conditions.

generateReport: The Goal. The Grand Finale. The AI takes all that info and writes me a poem... or a report.

Here is a snippet of the agent. Look how clean it is! (Ignore the imports I hid).

@Agent(description = "Analyzes surf conditions using buoy and tide data")
public class StokeBrokerAgent {

    // ... services injected here ...

    @Action(description = "Fetch current surf conditions")
    public SurfConditions fetchConditions(SurfLocation location) {
        // Calls NOAA API... returns data
    }

    @Action(description = "Analyze surf quality")
    public SurfQuality analyzeQuality(SurfConditions conditions, Ai ai) {
        // Asks the LLM: "Is this good?"
        return ai.withDefaultLlm().createObject(..., SurfQuality.class);
    }

    @AchievesGoal(description = "Generate final surf report")
    @Action
    public String generateReport(SurfLocation location, SurfConditions conditions, SurfQuality quality, Ai ai) {
        // The final output!
        return ai.withDefaultLlm().createObject("Write a funny report...", String.class);
    }
}

The "Wait, it actually works?" Moment

I fired up the shell. Yes, Embabel comes with a built-in shell, because why write a UI when you can look like a hacker from the 90s?

I typed: x "How is the surf at Oak Island?"

And then... nothing happened. Just kidding. The logs went crazy. Colossus (the AI personality, you can choose from a couple in Embabel) started "thinking."

It realized it needed a location. It extracted "Oak Island". It realized it needed to get conditions. It called my Java service. It realized it needed to judge the waves. It ran the analysis.

And then, it spit out this masterpiece:

THE BRUTAL TRUTH: FLATTER THAN A PANCAKE ON A GRIDDLE 🥞

Alright folks, gather 'round for the saddest surf report you'll read all week. We've got a big fat ZERO out there today. ... BOARD RECOMMENDATION: Your couch. Maybe a boogie board for the bathtub. DO NOT CALL OFF WORK. In fact, pick up an extra shift.

I mean, it hurts, but it's accurate (I checked Surfline, which kind of already does this...I already said this was pointless).

Under the Hood: Why Embabel Actually Rocks

Okay, let's geek out for a second. Why is this better than just writing a Python script with openai.chat.completions.create?

1. Structured Data is King 👑

In Python, you often get a blob of text back and hope your regex works (ok maybe this is an oversimplification). In Embabel, you define Java Records (or Kotlin Data Classes).

public record SurfQuality(double score, String boardRecommendation, String reasoning) {}

When I ask the AI to analyze the surf, I don't ask for text. I ask for an Object:

return ai.withDefaultLlm().createObject(prompt, SurfQuality.class);

Embabel handles the prompt engineering to force the LLM to output JSON, parses it, validates it, and hands me back a strongly-typed Java object. If the LLM hallucinates a field, Embabel throws an exception before it breaks my downstream code. That is peace of mind.

2. GOAP (Goal-Oriented Action Planning) 🗺️

This is the "GPS" feature I mentioned. I didn't tell the agent: "First call A, then call B."

I just said:

extractLocation takes UserInput -> returns SurfLocation
fetchConditions takes SurfLocation -> returns SurfConditions
analyzeQuality takes SurfConditions -> returns SurfQuality
generateReport takes SurfQuality -> Achieves Goal

The framework figured out the dependency graph. If I add a new step later (like checkCrowdLevels), I just drop in the @Action and the planner automatically wires it in. It's like Dependency Injection for logic.

3. The "Brain" vs. The "Body" 🧠💪

StokeBroker separates the LLM (Brain) from the Services (Body).

Body: NOAABuoyService knows how to make HTTP requests. It's dumb, reliable, and testable.

Brain: StokeBrokerAgent knows how to interpret that data.

This means I can unit test my services without paying OpenAI 5 cents every time.

Pro Tips for the Java Gang

If you want to try this (and you should), here's my advice:

Start with the Shell: Don't try to build a REST API or a React frontend immediately. Use the embabel-agent-starter-shell. It gives you that Colossus> prompt out of the box, which is invaluable for debugging what the agent is actually thinking.

Think in Records: Before you write a single prompt, define your data model. What exactly do you want the AI to give you? Define those Records first. It forces you to be clear about your intent.

Keep Actions Small: Don't write one giant "DoEverything" method. Break it down. One action to parse input, one to fetch data, one to make a decision. This makes the "Chain of Thought" visible and debuggable.

Don't Fear the Java: Yes, it's verbose compared to Python. But when your agent starts getting complex, you will thank the gods of static typing.

Conclusion

So, is Java better than Python for AI agents?

Look, I'm biased. But having type safety, real services, and a structured framework like Embabel feels... robust.

StokeBroker is alive. It's rude, it's honest, and it's running on the JVM. It might not save the world, but at least I won't drive 45 minutes to the beach just to look at a lake. You can check the code out here.

Now if you'll excuse me, the report says it's flat, so I have some refactoring to do.

Building "CodeBro": My (Pointless) Adventure into AI Agents with Java

Perry H — Sat, 15 Nov 2025 02:39:36 +0000

I'm at it again, playing with code in my spare time. I figured it was high time I started looking into all the fuss about AI agents. So naturally, I decided to build my own—in Java, because apparently, I like torturing myself.

I have no good reason for doing this, nor do I want to build anything "useful." I'm just having fun. But first (embarrassed), I had to learn what an AI agent even is.

So, What is an AI Agent, Anyway? Turns out, it's not just a simple API call. It's a system with a goal that can Sense (get a request), Think (plan steps, pick tools), and Act (run code, write files). The LLM is just the "brain" part of it. So something smarter than an API call. It's a loop through the Sense --> Think --> Act steps. Nice.

My (Pointless) Project: Meet CodeBro

Now that I had the theory, I needed a project. I decided to build an agent that takes a programming problem as its input, then returns the logic, implementation, and tests for how to solve it.

I shall call him CodeBro.

Does anyone need this? No. Like I said, I'm just messing around.

So, what do I need?

An LLM: I chose Claude, for no real reason. First problem solved.
The Flow: The initial concept is dead simple: Input → HTTP Request to Claude → Response.

To get something working, I'll need a few building blocks in Java:

An APIClient (preferably with an interface, because the person who has to maintain this might be me).
A PromptBuilder class to, well, build the prompt.
The main CodeBro "agent" or orchestrator class.
A Main class to actually run the thing (a CLI seems fancy enough).

Hitting the API

Okay, I have the basic idea. I need to figure out the API. As you'd expect, Anthropic has documentation, and I'll want the Messages API.

The curl command looks something like this:


curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

I could definitely hit this using Java's HttpClient, but in the docs, I see there's a Java SDK. Sick. Don't you just love popular languages?

To start, let's define an interface for the client. This will help with testing (if I get to that) and just in case I want to swap things out later.


public interface APIClient {
    String sendMessage(String prompt) throws Exception;
}

The API Client

Now let's implement this bad boy. Thanks to the Java SDK, I don't have to deal with manual JSON parsing (because let's be honest, string manipulation in Java is about as fun as a root canal).


public class AnthropicSDKClient implements APIClient {
    private final AnthropicClient client;
    private static final String MODEL = "claude-sonnet-4-20250514";

    public AnthropicSDKClient(String apiKey) {
        this.client = AnthropicOkHttpClient.builder()
            .apiKey(apiKey)
            .build();
    }

    @Override
    public String sendMessage(String userMessage) throws IOException, InterruptedException {
        try {
            TextBlock textBlock = TextBlock.builder()
                .text(userMessage)
                .build();

            MessageParam messageParam = MessageParam.builder()
                .role(MessageParam.Role.USER)
                .content(ContentBlock.ofText(textBlock))
                .build();

            MessageCreateParams params = MessageCreateParams.builder()
                .model(MODEL)
                .maxTokens(4096L)
                .messages(Collections.singletonList(messageParam))
                .build();

            Message message = client.messages().create(params);

            return message.content().stream()
                .filter(ContentBlock::isText)
                .map(block -> block.asText().text())
                .findFirst()
                .orElseThrow(() -> new IOException("No text content in response"));

        } catch (Exception e) {
            throw new IOException("SDK Error: " + e.getMessage(), e);
        }
    }
}

The Prompt Builder

Cool. So that's the API client sorted. But I want my prompts to be good, so let's make a dedicated class for that.


public class PromptBuilder {

    public String buildTutorialPrompt(String problemStatement) {
        return """
            You are an expert coding tutor. Analyze the following problem and provide a comprehensive tutorial.

            Structure your response with these sections:

            1. PROBLEM ANALYSIS
               - Restate the problem
               - Identify constraints
               - Determine inputs/outputs

            2. SOLUTION STRATEGY
               - Multiple approaches
               - Trade-offs
               - Best approach and why

            3. ALGORITHM DESIGN
               - Step-by-step algorithm
               - Time and space complexity

            4. IMPLEMENTATION
               - Complete working Java code
               - Comments and edge cases

            5. TEST CASES
               - JUnit test code
               - Example cases and edge cases

            Here's the problem:

            """ + problemStatement;
    }
}

The Orchestrator: CodeBro Himself

Now for the main orchestrator—CodeBro himself:


public class CodeBro {
    private final APIClient apiClient;
    private final PromptBuilder promptBuilder;

    public CodeBro(APIClient apiClient, PromptBuilder promptBuilder) {
        this.apiClient = apiClient;
        this.promptBuilder = promptBuilder;
    }

    public String solveProblem(String problemStatement) throws Exception {
        String prompt = promptBuilder.buildTutorialPrompt(problemStatement);
        String response = apiClient.sendMessage(prompt);
        return response;
    }
}

Look at that. Clean. Simple. Probably has bugs. But it compiles, which is basically the same as working, right?

Bringing CodeBro to Life (The CLI)

Now I need a way to actually use this thing. Let's throw together a CLI because I'm fancy like that:

public class Main {
    public static void main(String[] args) {
        try {
            // Load API key from config.properties (don't commit your keys, people)
            Properties props = new Properties();
            try (InputStream input = Main.class.getClassLoader()
                    .getResourceAsStream("config.properties")) {
                props.load(input);
            }
            String apiKey = props.getProperty("anthropic.api.key");

            APIClient apiClient = new AnthropicSDKClient(apiKey);
            CodeBro codeBro = new CodeBro(apiClient, new PromptBuilder());

            Scanner scanner = new Scanner(System.in);

            System.out.println("\n=================================");
            System.out.println("  Welcome to CodeBro! 🤝");
            System.out.println("  Your AI Coding Buddy");
            System.out.println("=================================\n");

            while (true) {
                System.out.println("Paste your coding problem below.");
                System.out.println("Type 'END' on a new line when done, or 'quit' to exit.\n");

                StringBuilder problemBuilder = new StringBuilder();
                while (true) {
                    String line = scanner.nextLine();

                    if (line.trim().equalsIgnoreCase("quit")) {
                        System.out.println("\nThanks for using CodeBro! Happy coding! 👋");
                        scanner.close();
                        return;
                    }

                    if (line.trim().equalsIgnoreCase("END")) {
                        break;
                    }

                    problemBuilder.append(line).append("\n");
                }

                String problem = problemBuilder.toString().trim();

                if (problem.isEmpty()) {
                    System.out.println("No problem entered. Try again.\n");
                    continue;
                }

                System.out.println("\n🤔 CodeBro is thinking...\n");

                String tutorial = codeBro.solveProblem(problem);
                System.out.println(tutorial);
                System.out.println("\n" + "=".repeat(50) + "\n");

                System.out.print("Solve another problem? (y/n): ");
                String answer = scanner.nextLine().trim().toLowerCase();

                if (!answer.equals("y") && !answer.equals("yes")) {
                    System.out.println("\nThanks for using CodeBro! Happy coding! 👋");
                    break;
                }

                System.out.println();
            }

            scanner.close();

        } catch (Exception e) {
            System.err.println("Something went horribly wrong: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

And... it works! I threw the classic Two Sum problem at it and got back a full tutorial with multiple approaches, complexity analysis, working code, and tests. Not too shabby.

But Wait, There's More

Now here's where it gets interesting. I started thinking: "What if CodeBro could actually do things?" Like, what if instead of just telling me the solution, it could create a full Maven project with the code and tests already set up?
This is where I need to clarify something because I got confused at first too.

Tools vs MCP (They're Not the Same Thing)

Tools are a feature baked into Claude's API. You tell Claude "hey, you can call these functions" and Claude decides when to use them. It's like giving Claude a toolbox:

// You define a tool
Tool writeFileTool = Tool.builder()
    .name("write_file")
    .description("Writes content to a file")
    .inputSchema(/* parameters */)
    .build();

// Claude can now use it
"I'll write that to a file for you" → calls write_file tool

MCP (Model Context Protocol) is Anthropic's open standard for organizing and sharing these tools. Think of it like this:

Tools = The concept of "Claude can call functions"
MCP = A standardized way to package and distribute those functions

Instead of everyone writing their own write_file tool from scratch, MCP gives you pre-built "servers" that provide common tools:

Filesystem server (read, write, list files)
Database server (query, insert, update)
Web server (fetch URLs, search)
Git server (commit, push, diff)

So MCP uses the tools feature, but adds structure and reusability. It's like the difference between writing your own HTTP library vs. just using an existing one.

Why This Matters for CodeBro

With tools alone, I'd have to manually define every file operation, every command execution, etc. With MCP, I can just plug into existing servers and boom—CodeBro can suddenly interact with the filesystem, run commands, whatever.

The flow would look like:

You: "Solve two-sum and create a project for it"
CodeBro: [generates solution]
CodeBro: [uses MCP filesystem server → write_file("pom.xml", ...)]
CodeBro: [uses MCP filesystem server → write_file("Solution.java", ...)]
CodeBro: [uses MCP filesystem server → write_file("SolutionTest.java", ...)]
CodeBro: [uses MCP command server → execute("mvn test")]
CodeBro: "✅ Project created at ./two-sum/ and all tests pass!"

Claude decides when to use these tools based on what you asked for. You don't explicitly tell it "now write this file"—it figures that out.

This is where I'm currently experimenting. Because an AI agent that goes from "here's a LeetCode problem" to "here's a fully tested, runnable Maven project" in seconds? That's the kind of useless thing I go for.

The Point

Look, CodeBro isn't revolutionary. It's not going to change the world. But, I had fun. I built something. I learned something. And now I'm writing about it, which means maybe you'll go build something too.

So go mess around with code. Build something useless. Torture yourself with Java if that's your thing. The best way to learn this stuff is to just... do it.

Full code on GitHub

Now if you'll excuse me, I'm going to go teach CodeBro how to commit its own solutions to Git. What could possibly go wrong?

Revisiting Java: Building a Simple Calculator using Functional Programming Techniques

Perry H — Sun, 09 Nov 2025 19:59:33 +0000

It's been a while since I've done any programming in Java. My day job has been all Javascript, Python, and Go. I found myself with about an hour to kill and decided to dust off the ol' Java skills.

Of course, as soon as I decided this, my brain stopped working and my mind went blank.

Because I had limited time and really just wanted to get back into the Java syntax, I thought: "just create anything, no matter how simple."

What's more simple than a calculator? Cool, don't have to think too much. Just have to get warmed up.

Part 1: The "Regular" Way (or the sane Java programmer way)

After figuring out which JVM I had on my MacBook, I opened up IntelliJ (been a minute for that, too) and quickly produced exactly what you might expect.

public class RegularCalculator {

    public RegularCalculator() {
    }

    public double add(double a, double b) {
        return a + b;
    }

    public double sub(double a, double b) {
        return a - b;
    }

    public double mul(double a, double b) {
        return a * b;
    }

    public double div(double a, double b) {
        return a / b;
    }

    public double pow(double a, double b) {
        return Math.pow(a, b);
    }
}

And of course, some tests. We're not animals.

class CalculatorTest {

    public Calculator calc;

    @BeforeEach
    void setUp() {
        calc = new Calculator();
    }

    @Test
    void add() {
        double a = 10;
        double b = 5;
        double expected = 15;
        double actual = calc.add(a, b);
        assertEquals(expected, actual);
    }

    // ... and so on for sub, mul, div, etc.
}

Amazing. I remember Java. The world's most basic program. (Let's just ignore the potential divide-by-zero error one could get into using this program.)

Part 2: Making it "Functional" (Because Why Not?)

If you've read any of my work from previous years, you know I like messing around with functional programming (in Java, because I am a glutton for punishment).

Let's start with a new class.

public FunctionalCalculator {
}

How would I implement this using Java's Functional Interfaces? After a brief search to refresh my memory, I found that Java has an interface already defined for this type of thing.

Meet the DoubleBinaryOperator. As the docs say, it represents an operation on two double values and returns the result as a double value. It's a functional interface, so it can be used for a lambda expression.

Its functional method is applyAsDouble(double left, double right).

OK, this should work.

Since we have this interface, we can picture a function that takes two doubles and returns a value. Simple enough. But how do we map this to the operation?

To solve this, I created a Map that stores a string operator (like * or +) as a key, with the value being the lambda function that does the appropriate operation.

public class FunctionalCalculator {
    // The key is the symbol (String), and the value is the operation.
    private final Map<String, DoubleBinaryOperator> operations = new HashMap<>();

    public FunctionalCalculator() {
        // short-hand method reference for (a, b) -> Double.sum(a, b)
        operations.put("+", Double::sum); 
        operations.put("-", (a, b) -> a - b);
        operations.put("*", (a, b) -> a * b);
        // let's fix the divide by zero problem
        operations.put("/", (a, b) -> {
            if (b == 0) {
                throw new ArithmeticException("Cannot divide by zero!");
            }
            return a / b;
        });
        operations.put("^", Math::pow);
    }
}

So now, all we need is a calculate function that accepts the operator and our values. I added that (and the error handling) to the class above.

// in our FunctionalCalculator class
    public double calculate(String operator, double a, double b) {
        if (!operations.containsKey(operator)) {
            throw new IllegalArgumentException("Unknown operator: " + operator);
        }

        // Get our lambda function that maps to the operator
        DoubleBinaryOperator op = operations.get(operator);

        // And return our implementation of applyAsDouble
        return op.applyAsDouble(a, b);
    }

Obviously, we need new tests. The great part is we can add tests for our new error handling.

class FunctionalCalculatorTest {
    private FunctionalCalculator calculator;

    @BeforeEach
    void setUp() {
        calculator = new FunctionalCalculator();
    }

    @Test
    void testAdd() {
        assertEquals(15, calculator.calculate("+", 10, 5));
    }

    @Test
    void testSubtract() {
        assertEquals(5, calculator.calculate("-", 10, 5));
    }

    // ... etc. ...

    @Test
    void testDivideByZero() {
        assertThrows(ArithmeticException.class, () -> {
            calculator.calculate("/", 10, 0);
        });
    }

    @Test
    void testInvalidOperator() {
        assertThrows(IllegalArgumentException.class, () -> {
            calculator.calculate("%", 10, 5); // % isn't defined
        });
    }
}

Tests pass. Nice.

So, What Did We Learn?

Nothing much, other than I convinced myself I still remember some Java syntax. I'm not sure my functional implementation is any "better" for this simple case, but I felt cool doing it.

Sometimes you gotta just mess around and "play."

Anyone else reach for functional interfaces even when they don't have to?

Image by StockSnap from Pixabay

Code Challenge: Longest Substring Without Repeating Characters - Java Edition

Perry H — Sat, 17 Jun 2023 15:43:26 +0000

This challenge asks you to find the longest substring without repeating characters in a given string.
Example Inputs and outputs

Input: s = "pwwkew"
Output: 3
The answer is "wke", with the length of 3.

Brute Force

The brute force approach to this kind of problem is pretty straight forward and includes nesting loops. Obviously, this is not an ideal solution, however if you need a quickly produce a solution, this might be it. We can optimize it after it works.

 public int lengthOfLongestSubstring(String s) {
   int n = s.length();

   int res = 0;
   for(int i = 0; i < n; i++){
     for(int j = i; j < n; j++){
       if(check(s, i, j)) {
        res = Math.max(res, j - i + 1);
       } 
      }
     }
    return res;
}

private boolean check(String s, int start, int end) {
  int[] chars = new int[128];

  for(int i = start; i <= end; i++) {
    char c = s.charAt(i);
    chars[c]++;
    if (chars[c] > 1) {
       return false;
    }
   }
  return true;
}

The technique above gives a runtime complexity of O(n^3) and a space complexity of O(min(n,m)). I think we can do better.

Optimized

There is a technique called "sliding window" and it is often used for this kind of problem. It generally works by maintaining a fixed window over the array, and then moving the window forward one element at a time. As the window moves, the algorithm calculates the answer to the problem for the current window. In this case our window isn't "fixed" but we use a similar concept.
We can use a HashSet to store the characters in the "window" [i, j] (where j = i initially). Then we move the index j to the right. If it is not in our HashSet, we bump j to the right. We do this until we find a character already in the HashSet. Now, we found the largest number of substrings without duplicates. Keep this up throughout the whole string i and you will get the answer. This idea can be further optimized by using a map to define a mapping of a character to its index. This allows us to skip characters when we find repeated characters.

Let's see how we might implement it here.

   public int lengthOfLongestSubstring(String s) {
      int ans = 0;
      // map to store character and its index
      Map<Character, Integer> map = new HashMap<>(); 
      for (int end = 0, start = 0; end < s.length(); end++) {
         // if it is in the map, its a duplicate
         if (map.containsKey(s.charAt(end))){
            // move start to new index
            start = Math.max(map.get(s.charAt(end)), start);
         }
         // not in map keep track of how long the window is
         ans = Math.max(ans, end - start + 1);
         // add char to map
         map.put(s.charAt(end), end + 1);
      }
      return ans;
   }

Now this one is much faster with a runtime complexity of O(n) and a space complexity of O(min(m,n)).

Another Optimized

In doing some research for this article, I discovered an even more optimized solution that makes some assumptions about the type of string input. According to this article, "If we know that the charset is rather small, we can mimic what a HashSet/HashMap does with a boolean/integer array as a direct access table. Though the time complexity of query or insertion is still O(1), the constant factor is smaller in an array than in a HashMap/HashSet."

So if we assume the string is ASCI, we can use an integer array with a length of 128.

   public int lengthOfLongestSubstring(String s) {
        Integer[] chars = new Integer[128];

        int left = 0;
        int right = 0;

        int res = 0;
        while (right < s.length()) {
            char r = s.charAt(right);

            Integer index = chars[r];
            if (index != null && index >= left && index < right) {
                left = index + 1;
            }

            res = Math.max(res, right - left + 1);

            chars[r] = right;
            right++;
        }

        return res;
    }

We see from this problem that the brute force technique to solve a problem can be very slow, however, it can help us reason about the problem. The sliding window technique was also introduced to reduce loops needed in these types of problems. Remember you can reach for the Sliding Window if you hear the following things in the problem: Array, String, Sub Array, Sub String, Largest Sum, Maximum Sum, Minimum Sum. We also see that data structures can help us optimize our code even more. Let me know in the comments if you have other examples of sliding windows.

Extra

I've been learning Scala code and I was looking into various Scala solutions. I found one on Leet Code that I thought was pretty cool by Imran Sarwar. His solution uses a function called scanLeft. Using scan left, also called prefix scan, you can calculate cumulative values over a sequence. Basically, it applies a binary operation to the current value and the next value. The scan left operation results in a new sequence of values, where each value is the cumulative result of the binary operation applied to the first n values. The key in his solution is the binary operator where it does the "windowing" until it finds a previously calculated character.

def lengthOfLongestSubstring(s: String): Int = {
    s.scanLeft("")((currStr: String, currChar: Char) => 
    currStr.substring(1 + currStr.indexOf(currChar)) + currChar)
    // Up to this point we would get vector like this
    // Vector(, a, ab, abc, bca, cab, abc, cb, b)
    // now if we take max of length would get the answer
    .map(_.length)
    .reduce(Math.max)
}

Photo by Sean Patrick: https://www.pexels.com/photo/brown-wood-dock-1057663/

Code Challenge: Check Permutation - Java edition

Perry H — Fri, 09 Jun 2023 13:38:07 +0000

Today's problem is a fun one.

Problem

Given two strings, write a method to decide if one is a permutation of the other.

Solution 1

Clarifying questions are: Does white space count? Is the comparison case sensitive? Is the string in ASCI (I explain ASCI in this post)? Once you have determined these answers, you can move on to solve the problem.

If the two strings are permutations we know they should have the same length. So one of the first things we can do is check if the strings are different lengths. We also know that permutations are the same characters but in a different order. If we sort the strings, we can simply compare the two strings.

// Sort the string
public static String sort(String a) {
    char[] c = a.toCharArray();
    Arrays.sort(c);
    return new String(c);
}

public static boolean checkPermutation(String a, String b) {
    // permutations should be equal length
    if (a.length() != b.length() ) {
       return false;
     }

     return sort(a).equals(sort(b));
}

This solution is clean and readable and easy to understand. The Time Complexity is O(nlogn) since Java's Arrays.sort uses a Quicksort when sorting primitives.

Solution 2

This solution is faster but less clear. We use an array data structure to store counts of all possible characters (assuming ASCI). We loop through the first string to load the counts of the numbers, then loop through the second string to decrement the counts of each character. We know that if that count falls below zero, a character doesn't match.

public static boolean checkPermutations(String a, String b) {
    if (a.length() != b.length()) {
        return false;
    }

    int[] letters = new int[128]; // assuming ASCI
    for (int i = 0; i < a.length(); i++){
        // for each position of ASCI length(128) keep a count of the characters.
        letters[a.charAt(i)]++;
    }
    for (int i = 0; i < b.length(); i++) {
        // find the position in our ASCI array and subtract 1
        letters[b.charAt(i)]--;
        // if it's less than zero, we can return false
        if (letters[b.charAt(i)] < 0) {
            return false;
        }
    }
    return true;
}

The above solution has a faster time of O(n).

If you know of some other clever ways to solve this problem, post in the comments and let me know.

Photo by Ann H: https://www.pexels.com/photo/yellow-jigsaw-puzzle-piece-3482442/

Check if all characters in a string are unique - Java edition

Perry H — Fri, 02 Jun 2023 01:18:19 +0000

Code challenges can be fun and I like doing them periodically to stay mentally sharp. The problem and solution are not unique; however, when I was learning, I appreciated posts like these. Seeing how others solved the problem helped me understand how to think when approaching problems.

The Problem:

Implement an algorithm to determine if all characters in a string are unique.

Solution 1:

As I started thinking about the problem, I remember reading about using sets to remove duplicates. Thinking along these lines, I came up with the following solution:

public static boolean isUnique(String str) {
    Set<Character> chars = new HashSet<>();
    // Load the Set
    for(int i = 0; i < str.length(); i++){
    // A set will not add a duplicate, in Java the add method
    // will simply return false if a duplicate is found
    chars.add(str.charAt(i));
    }
    // If the size of the Set is equal to the string length,
    // we know that all chars are unique. 
    return chars.size() == str.length();
}

This solution has a time complexity of O(n) where n is the length of the string because we have to loop through the string to load the Set.
The space complexity is O(n) where n is the set size.

Another Attempt:

The above solution felt a little like cheating to me, so I thought I would try an approach you would more likely see in blogs or books.

The below approach assumes the string is extended ASCI. To understand how this problem works, it helps to understand ASCI and its variations.

ASCI characters can be represented in a number of ways, including a 7 bit or 8 bit binary number. Initially, it used only 7 bits in an 8 bit number with the left most bit being 9. Later, it was extended to use all 8 bits. There are tables (like this one) that show the mapping between the binary number, its decimal counterpart, and the character represented. You can see in the link above, the first table's decimals goes to 128, and the extended table goes to 256.

Why is this significant? A string with only distinct characters would not have a length beyond that of the ASCI set. We can leverage this to our advantage by creating a data structure with a size of 256. Using this data structure we will add characters to the structure. If we find that the character already exists in the structure, we know the string does not contain only unique characters. The structure used below is a Boolean array.

Additionally, we need to check that the length is not greater than the ASCI set size (in this case we use 256 for extended ASCI). This is unlikely but is an excellent example of checking for an edge case.

public static boolean isUnique(String str) {
    // string length must be less than ASCI 256
    if (str.length() > 256) {
         return false;
    }

    boolean[] chars = new boolean[256];
    for(int i = 0; i < str.length(); i++){
    // casting to an int to check against our array
    int val = (int) str.charAt(i);
    // if we find this in our array, than it is a duplicate
    if (chars[val]) {
        return false;
    }
    // if the number is not in the array, mark true
    chars[val] = true;
    }
    // no duplicates found
    return true;
}

The time complexity for the above solution is O(n) where n is the length of the string. The space complexity will be O(1) because the array will always be the same size.

Another version:

The above attempt is solid and I'm sure many text books would recommend. However, I like declarative code and wanted to see if writing it in a declarative style would clean it up a bit.
The below solution uses Java Streams.

public static boolean isUnique(String str) {
    return str.chars().distinct().count() == str.length();
}

The chars method creates an IntStream of the character's Unicode codepoint value. We then use the distinct method to create a new stream with only distinct values. Utilizing the count method will allow us to compare stream size and string length. This is similar to the first solution where we compared the set size with the string length.

The time complexity here should be O(n) where n is the string input length. None of the stream operations will grow longer than the string length.

The storage of a stream is backed by the collection of the Stream source. Pipeline streams do not store anything. Therefore the space complexity will be 0(n) where n is the size of the sequence of characters in our string.

There are my attempts at solving this challenge in the best way I can. I hope that this can help someone else improve their problem-solving skills and become better coders. Please let me know if there are any other ways to solve this problem or if there are any ways to improve on my solutions.

Photo by Zac Frith: https://www.pexels.com/photo/red-blue-and-orange-umbrella-lot-918781/

Edit

I was reviewing this code and some other solutions and stumbled upon another solution that does not use an extra data structure.

public static boolean isUnique(String str) {
    char[] chArray = str.toCharArray();

    // Arrays.sort() uses binarySort in the background
    // for non-primitives which is of O(nlogn) time complexity
    Arrays.sort(chArray);

    for (int i = 0; i < chArray.length - 1; i++) {
        // if the adjacent elements are not
        // equal, move to next element
        if (chArray[i] != chArray[i + 1])
            continue;
        // if at any time, 2 adjacent elements
        // become equal, return false
        else
            return false;
    }
    return true;
}

The above solution's time complexity is O(nlogn) due to the sort and the auxiliary space is O(1).

Create a remote developer environment in GCP and manage with Github Actions

Perry H — Mon, 29 May 2023 15:45:47 +0000

Why a Remote Developer environment?

My laptop, which runs Linux, is an old machine that I use for side projects. There isn't much memory or processing power for running Docker containers or virtual machines. In order to avoid buying a costly laptop at this time, I have decided to set up a remote development environment. Remote environments offer several advantages including: the ability to access the environment from multiple machines; the ability to modify the OS, RAM, and CPU to meet your specific needs; and you don't have to install as many dev tools on your local machine, which helps if you have limited space. Furthermore, remote environments are often much cheaper to set up than buying a new laptop, making them a great option for budget-conscious developers.

GCP

The cloud provider I chose was Google Cloud Provider (GCP) since they offered 300 dollars in free credits to first-time users; but, you could set up a development environment in any cloud provider if you have a strong preference. I found the overall experience of using GCP to be really pleasant and GCP provides some really slick tools to streamline setup. The instructions below will be specific to GCP.

Get started with GCP

To get started you will need to create an account if you don't have one already. Once you have created an account, be sure to enter a credit card to be able to use all the features.

Next, create a project. I called my project DevEnv
In the newly created project, click on the navigation menu. Click on Compute Engine and select VM instances.
Click on Create an instance.
Name your instance whatever you like. I called mine dev.
Select the region and zone.
Configure the Memory and CPU to meet your needs.
For the boot disk I chose an Ubuntu Image and chose 50gb for the size. You can change this to suit your needs.
With everything configured, you can click on create and after a few minutes your newly created VM will come up.

Install GPC CLI

You will need to install the Google Cloud CLI on your local machine.
I followed these instructions.
When you run the initial gcloud init command, target the project you created and the instance you created.

Connect to your environment

In the VM instance dashboard,

Click the drop down SSH button and select the view gcloud command. This will bring up a command you can copy and paste into your terminal.
Connect to your VM using the command provided.

Inside your VM

If you want to customize your shell and install development tools on your VM, you may want root access. If so, please follow these instructions.

You can also add your user to the sudoers file. To do so, follow these steps:

Log in as root
Run vim /etc/sudoers
Replicate the line root ALL=(ALL:ALL) ALL, replace root with your username, and save the file. (You’ll need to save with :w! since the file is readonly.)
Log back in as your user.

Now you have a VM and know how to connect to it. You can install whatever development tools you like.

Remote connection through VS Code

To ease interaction with the VM I downloaded VS Code onto my local machine and installed the GCP plugin and the Remote .SSH plugin.

The GCP plugin provides some helpful tooling to help you quickly create cloud applications and makes developing Kubernetes Apps easier. If you plan on doing any of this type of development I would recommend you check it out here.

Remote SSH allows you to connect VS Code to your VM so you can edit code easily while using your preferred themes and plugins. To connect to your VM with Remote SSH do the following:

Open VSCode and press ⌘ + Shift + P for macOS or Ctrl + Shift + P for Linux/Window to open VSCode Command Palette.
Type in Remote-SSH and select Add New SSH Host.
In the "Enter SSH Connection" command prompt that pops up, type : ssh -i ~/.ssh/[KEY_FILENAME] [USERNAME]@[External IP] and press Enter. The [KEY_FILENAME] should be the key created by the gcloud CLI and the same one you used to originally connect to the VM.
You can now open the command palette and type remote-ssh again.
This time select Connect to host. The IP of your VM should pop up and you can click on it to open a new window connected to the VM file system.

If you do web development you may want to port forward so that changes in the code are reflected in the browser. To do this there is a small button that looks like a radio tower at the bottom of the VS Code console. Click on it and click "Forward a Port'. Type in the port number and the local address. I am forwarding port 1313 in this example. So when I type localhost:1313, my application will load in the browser.

Github Actions to manage VM

I can only work on my side projects sporadically and I don't want to keep the VM running when I'm not actively developing. To help me manage my VM I created a Github Action that suspends the VM every night if it's running. Suspending a VM will keep it around but you won't be charged for it. While the VM is suspended, Google only charges for the storage used to preserve its memory.

Below is the workflow I used.



name: Suspend VM

# Controls when the workflow will run
on:
  schedule:
    # Runs "at 10pm every day"
    - cron: '0 22  *'
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  suspend-vm:
    # Add "id-token" with the intended permissions.
    permissions:
      contents: 'read'
      id-token: 'write'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      # Configure Workload Identity Federation via a credentials file.
      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v1'
        with:
          workload_identity_provider: ${{ secrets.PROVIDER }}
          service_account: ${{ secrets.SERVICE_ACCOUNT }}
      # Install gcloud, `setup-gcloud` automatically picks up authentication from `auth`.
      - name: 'Set up Cloud SDK'
        uses: 'google-github-actions/setup-gcloud@v1'
      # Now you can run gcloud commands authenticated as the impersonated service account.
      - id: 'gcloud-describe'
        name: 'gcloud describe'
        run: |
             echo "status=$(gcloud compute instances describe 'dev' \
            --project ${{ vars.PROJECT }} \
            --zone ${{ vars.zone }} \
            --format='value(status)')" >> $GITHUB_OUTPUT

      # Only run suspend if the VM is running
      - if: steps.gcloud-describe.outputs.status == 'RUNNING'
        name: 'gcloud suspend'
        run: |
           gcloud compute instances suspend "dev" \
           --project ${{ vars.PROJECT }} \
           --zone ${{ vars.zone}}


      - if: steps.gcloud-describe.outputs.status != 'RUNNING'
        name: 'automation not needed'
        run: echo "Dev env is not running"

Let's break down what this file does.

First, we tell Github we want to run this on a schedule and manually.

We define one job, suspend-VM and give it the permissions needed for OIDC.

The first step is to check out the repository. We then use the google-github-actions/auth action.
This requires setting up OIDC on GitHub and Google Cloud. For more details, see here and here.

The next step uses the google-github-actions/setup-gcloud action. This action is handy because it automatically picks up the authentication setup in the last step.

Next we run a describe command to check if the VM is running. Note: We send the response to GITHUB_OUTPUT.

The next two steps use the if condition to determine if they should be run.
In the first case, suspend the VM if it is running.

The second case is if the VM is not running. Here we echo a message indicating there was no need to suspend the VM.

And there you have it. A nightly job make sure I'm not spending more money than I need to be.

Summary

This whole process was fairly easy. However, I had to spend some time understanding how GCP handles OIDC (a bit different from AWS). The docs here and here helped a lot. GCP also has this cool tool called Policy Troubleshooter that helped me identify that I had forgotten to add the suspend permission to my created role.

The remote environment, some handy plugins in VS Code, and Github Actions automation have made for a pretty enjoyable development experience for me. With all these tools at my disposal, I have been able to quickly and effectively address any development issues that arise. It has been a smooth and productive ride so far, and I'm thankful for the modern tools that I have to work with. If you are familiar with remote development environments or know of any other tooling that makes this experience better, let me know in the comments.

Photo by Rafael Cerqueira: https://www.pexels.com/photo/blue-and-white-sky-with-stars-4737484/z

Github Actions - Using a AWS ECR image as a container

Perry H — Thu, 18 May 2023 19:12:46 +0000

Recently, I've been migrating pipelines from Bitbucket to Github Actions, and I've encountered some issues due to the differences between Bitbucket pipelines and Github Actions. One of the things that slowed me down was using private images as pipeline containers. We use images from our AWS ECR private registry in some of our Bitbucket pipelines. As I couldn't find much documentation on how to use ECR and Github Actions and even found the official documentation lacking, I wanted to write down the steps I took so others could set them up easier.

Configuration

The first step is to configure your workflow to use a container with an ECR image.

build:
    runs-on: ubuntu-latest
    container:
      # your image from ecr goes here
      image: <aws-acount>.dkr.ecr.<region>.amazonaws.com/<my_image>:<version>
      # the credentials are specified below in a secret
      credentials:
        username: AWS
        # you can call the secret whatever you like
        password: ${{ secrets.AWS_ECR_PW }}

Automation

One thing to note, the ECR password is only valid for 12 hours. If you want to avoid manually updating the secret, you can set up automation using Github Actions similar to this post.

Here is a workflow that automatically updates the password every 11 hours.

name: Update ECR PW

on:
  schedule:
    # CodeArtifact token expires in 12 hours, update token every 11 hours
    - cron: 02 */11 * * *
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

jobs:
  update-ecr-pw:
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    env:
      # need an Github Access token with Admin access to update secret
      GH_TOKEN: ${{ secrets.GH_CLI }}
    steps:
      - uses: actions/checkout@v3
      - uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-region: <your_region>
          # should be the arn to your role created for oidc
          role-to-assume: arn:aws:iam::<your_aws-account>:role/<your-role-name>
      - name: Get pw and update secret
        run: |
          export ECR_PW=`aws ecr get-login-password --region <your_region> --output text`
          gh secret set <YOUR_SECRET> --org <your-org> --visibility all --body "$ECR_PW"

If you don't understand the code above or don't have OIDC setup for your Github Actions, the post mentioned above dives into more details and it provides documentation on how to set that up. It only takes a couple of minutes to get set up.

This is the way I set up a Github Action to use an image from a private ECR account. This is done by specifying the image, username, and password under the container key in the workflow file. I also showed how to add automation to update the password to reduce manual input. If you have other ways to automate these steps, let me know in the comments.

Photo by Digital Buggu: https://www.pexels.com/photo/colorful-toothed-wheels-171198/

Using Github's Dependabot with AWS CodeArtifact

Perry H — Tue, 16 May 2023 13:01:02 +0000

Recently I wanted to use Github's Dependabot in a repository with a private NPM registry in AWS CodeArtifact. I ran into a credentials problem and used automation with Github Actions to solve it. This was thanks to some great tooling from Github and AWS.

Running into trouble

To allow Dependabot access to your CodeArtifact repository, you need an authorization token. My first thought was that I could manually get the token and paste it into my organization's Dependabot secrets in the Github UI. I could then tell Dependabot to use it in the dependabot.yml file.

Below is an example of the dependabot.yml file. Replace the angle brackets with your appropriate values.

version: 2
registries:
  codeartifact:
    type: npm-registry
    url: https://<domain>-<account>.d.codeartifact.<region>.amazonaws.com
    # I called the secret CODEARTIFACT_TOKEN, you can call it whatever you want
    token: ${{secrets.CODEARTIFACT_TOKEN}}
updates:
 - package-ecosystem: "npm"
   directory: "/"
   schedule:
      interval: "weekly"
   registries:
     - codeartifact

But the idea didn't quite go as planned. I used the AWS CLI to get a token (see here for more about tokens), but the problem I ran into was that the token expired after 12 hours. This is helpful for security hardening but a pain in my situation. I would have to manually ensure that an updated token is in the Dependabot secret before Dependabot does it's checks.

Automation to the rescue

To solve this problem, I created a Github action that updated the Dependabot secret with a fresh token every 12 hours. I can do this using the AWS CLI to get the token (see here), and the Github CLI to update the secret (see here). I used OIDC and aws-actions/configure-aws-credentials@v2 action to assume the appropriate role. For more on OIDC in Github, click here for the official docs. If you are a newbie to AWS, this post shows how to set it up on AWS.

Below is the workflow file for the automation to update the token. Replace the angle brackets with your appropriate values.

name: Update CodeArtifact Token

on:
  schedule:
    # CodeArtifact token expires in 12 hours, update token every 11 hours
    - cron: 0 */11 * * *
  # run manually if needed
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    env:
      # need a token with admin access to update the secret
      GH_TOKEN: ${{ secrets.GH_CLI }}
    steps:
      - uses: actions/checkout@v3
      # using OIDC to assume the proper role 
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-region: <aws_region>
          # this should be the role arn that you created in AWS
          role-to-assume: arn:aws:iam::<account-number>:role/<your_role_name>
      - name: Get token and update secret
        run: |
          export CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain <my_domain> --domain-owner <account_number> --region <aws_region>  --query authorizationToken --output text`
# Remember we called the organization secret CODEARTIFACT_TOKEN, make sure the code below matches whatever you called your secret
          gh secret set CODEARTIFACT_TOKEN --org <my_org> --visibility all --app dependabot --body "$CODEARTIFACT_AUTH_TOKEN"

With this workflow running, I can rest assured that Dependabot will always have a valid token. I am also using secure practices since my automation uses OIDC to assume a role with limited scopes. In addition, there are no long-lived AWS tokens in the actions. The incredibly powerful CLI's from AWS and GH really make it easy to build this kind of automation. Understanding these kinds of tools and familiarizing yourself with Github Action capabilities will set you up to build all sorts of automation. This will make your code safer and your life easier.

Cover photo by Tara Winstead: https://www.pexels.com/photo/robot-pointing-on-a-wall-8386440/