1. Addition and Subtraction of Signed Numbers

1.1 The Half Adder and Full Adder

Let's start at the very bottom. The most primitive arithmetic circuit adds two single bits. A half adder produces a sum bit and a carry bit:

s = x XOR y
c = x AND y

Simple enough, right? But here's the thing -- in a multi-bit addition, every bit position (except the least significant) must also accept an incoming carry from the position to its right. That is the job of a full adder (FA).

1.2 Full Adder Truth Table

A full adder takes three inputs -- x_i, y_i, and the carry-in c_i -- and produces a sum s_i and carry-out c_{i+1}.

From the truth table we derive:

s_i     = x_i XOR y_i XOR c_i
c_{i+1} = x_i * y_i + x_i * c_i + y_i * c_i

The carry equation can also be written as:

c_{i+1} = x_i * y_i  +  (x_i XOR y_i) * c_i

This second form is important because it separates the carry into two pieces:

• A generate term G_i = x_i * y_i -- a carry is produced regardless of the incoming carry.

• A propagate term P_i = x_i XOR y_i -- an incoming carry is passed through to the next position.

Keep these in mind. They will become critically important when we build fast adders later.

1.3 The Ripple-Carry Adder

To add two n-bit numbers X and Y, the most straightforward approach is to cascade n full adders. The carry-out of stage i becomes the carry-in of stage i+1. This is called a ripple-carry adder, because the carry "ripples" from the least significant bit all the way to the most significant bit.

For an n-bit ripple-carry adder, the worst-case delay is 2n gate delays (each full adder contributes 2 gate delays for the carry chain). As we will see shortly, this becomes the primary bottleneck in high-speed processors.

1.4 Addition and Subtraction of 2's Complement Numbers

Here's where things get elegant. In the 2's complement system, subtraction is performed by adding the complement. To compute X - Y:

1. Take the 1's complement of Y (invert every bit).

2. Add 1 (this converts the 1's complement to the 2's complement).

3. Add the result to X.

The hardware achieves this beautifully using XOR gates controlled by a single Add/Sub signal:

When Add/Sub = 0 (addition): each XOR gate passes y_i unchanged, and c_0 = 0.

When Add/Sub = 1 (subtraction): each XOR gate inverts y_i (producing the 1's complement), and c_0 = 1 (adding 1 to convert to 2's complement).

Think about how clean this is -- the same n-bit adder handles both addition and subtraction with the flip of a single control line. No separate subtraction circuit needed.

1.5 Overflow Detection

When two numbers of the same sign are added and the result has the opposite sign, an overflow has occurred. The result is too large (or too negative) to fit in n bits.

The overflow condition is detected by:

Overflow = c_n XOR c_{n-1}

That is, overflow occurs when the carry into the sign-bit position differs from the carry out of the sign-bit position. Let me show you why with concrete examples:

Examples (4-bit 2's complement, range -8 to +7):

  0111  (+7)            1000  (-8)
+ 0001  (+1)          + 1111  (-1)
------                ------
  1000  (-8) ??        10111 --> 0111 (+7) ??

  c_4=0, c_3=1          c_4=1, c_3=0
  0 XOR 1 = 1           1 XOR 0 = 1
  OVERFLOW!              OVERFLOW!

In both cases the carries disagree, and the result is obviously wrong. The XOR of those two carries gives us a single-bit overflow flag.

Key Takeaway: A single n-bit adder, augmented with XOR gates on the Y input and a control signal fed to c_0, serves as a complete add/subtract unit for 2's complement numbers. Overflow is detected by XOR-ing the two most-significant carries.

2. Design of Fast Adders

2.1 The Problem with Ripple Carry

The ripple-carry adder is simple but slow. For n bits, the carry must propagate through all n stages. The worst-case delay is:

Ripple-carry delay = 2n gate delays

For a 32-bit adder, that is 64 gate delays -- far too slow for a modern processor running at GHz clock speeds. We need a way to compute all the carries in parallel. Let's figure out how.

2.2 Carry-Lookahead Principle

Here's where it gets interesting. The key insight is to express carries as functions of the inputs alone, without waiting for the previous carry to arrive. Remember the generate and propagate signals I mentioned earlier? Let's put them to work. We define two signals for each bit position i:

Generate:   G_i = x_i AND y_i
Propagate:  P_i = x_i XOR y_i

G_i = 1 means position i generates a carry regardless of any incoming carry. P_i = 1 means position i propagates an incoming carry to the next position.

The carry recurrence becomes:

c_{i+1} = G_i + P_i * c_i

Now here's the magic. Let's expand this for positions 0 through 3 (a 4-bit block), assuming the carry into the block is c_0:

c_1 = G_0 + P_0 * c_0

c_2 = G_1 + P_1 * c_1
    = G_1 + P_1 * G_0 + P_1 * P_0 * c_0

c_3 = G_2 + P_2 * c_2
    = G_2 + P_2 * G_1 + P_2 * P_1 * G_0 + P_2 * P_1 * P_0 * c_0

c_4 = G_3 + P_3 * c_3
    = G_3 + P_3 * G_2 + P_3 * P_2 * G_1 + P_3 * P_2 * P_1 * G_0
      + P_3 * P_2 * P_1 * P_0 * c_0

Look at what we have done. Every carry is now expressed purely in terms of G_i, P_i, and c_0 -- no dependency on any previous carry! Since G_i and P_i are computed from x_i and y_i in one gate delay (AND and XOR respectively), and the expanded carry expressions require only two more levels of logic (AND then OR), all four carries are available in just 3 gate delays.

The sum bits require one additional XOR:

s_i = P_i XOR c_i

So all four sum bits are available in 4 gate delays -- regardless of the adder width (within the 4-bit block). Compare that to the 8 gate delays a 4-bit ripple-carry adder would need!

2.3 The 4-Bit Carry-Lookahead Adder

Let me lay out the architecture:

2.4 Building a 16-Bit CLA Adder

Now let's scale up. We cascade four 4-bit CLA blocks. Each block also produces block-level generate and propagate signals:

Block 0 (bits 0-3):
  P'_0 = P_3 * P_2 * P_1 * P_0
  G'_0 = G_3 + P_3*G_2 + P_3*P_2*G_1 + P_3*P_2*P_1*G_0

Block 1 (bits 4-7):
  P'_1 = P_7 * P_6 * P_5 * P_4
  G'_1 = G_7 + P_7*G_6 + P_7*P_6*G_5 + P_7*P_6*P_5*G_4

Block 2 (bits 8-11):
  P'_2 = P_11 * P_10 * P_9 * P_8
  G'_2 = (same pattern for bits 8-11)

Block 3 (bits 12-15):
  P'_3 = P_15 * P_14 * P_13 * P_12
  G'_3 = (same pattern for bits 12-15)

A second-level CLA circuit takes G'_k and P'_k (k = 0,1,2,3) along with c_0 and produces the inter-block carries c_4, c_8, c_12, and c_16 using the exact same lookahead equations:

c_4  = G'_0 + P'_0 * c_0
c_8  = G'_1 + P'_1 * G'_0 + P'_1 * P'_0 * c_0
c_12 = G'_2 + P'_2 * G'_1 + P'_2 * P'_1 * G'_0 + P'_2 * P'_1 * P'_0 * c_0
c_16 = G'_3 + P'_3 * G'_2 + P'_3 * P'_2 * G'_1 + P'_3 * P'_2 * P'_1 * G'_0
       + P'_3 * P'_2 * P'_1 * P'_0 * c_0

Here is the full 16-bit structure:

Delay analysis for the 16-bit CLA:

The 16-bit CLA adder produces all outputs in 8 gate delays, compared to 32 gate delays for a 16-bit ripple-carry adder. That is a 4x speedup.

2.5 Building a 64-Bit CLA Adder

The same principle extends naturally to a third level. We group four 16-bit CLA blocks. Each produces third-level G'' and P'' signals. A third-level CLA circuit generates the carries c_16, c_32, c_48, and c_64.

64-bit CLA: 3 levels of lookahead

Level 1: Bit-level      G_i, P_i       --> 4-bit block carries
Level 2: Block-level     G'_k, P'_k    --> 16-bit section carries
Level 3: Section-level   G''_j, P''_j  --> 64-bit carries (c_16, c_32, c_48, c_64)

Delay: 12 gate delays for s_63
        7 gate delays for c_64

Compare this to a 64-bit ripple-carry adder: 128 gate delays. The three-level CLA is roughly an order of magnitude faster. The pattern is clear -- each additional level of lookahead doubles the width we can handle while adding only a constant delay.

Key Takeaway: Carry-Lookahead Adders eliminate the serial carry chain by expressing each carry as a sum-of-products function of generate and propagate signals. A 4-bit CLA takes 4 gate delays; a 16-bit CLA takes 8; a 64-bit CLA takes 12. The principle can be extended to any width by adding more levels of lookahead.

3. Multiplication of Positive Numbers

3.1 Manual Binary Multiplication

Let's explore multiplication. Binary multiplication follows the same longhand procedure as decimal multiplication, but it is simpler because each multiplier bit is either 0 or 1. No multiplication table needed -- you either copy the multiplicand or you write zero.

Example: 13 x 11 = 143

          1 1 0 1       (13)  Multiplicand M
        x 1 0 1 1       (11)  Multiplier Q
        ---------
          1 1 0 1       (M x q_0, q_0=1)
        1 1 0 1 .       (M x q_1, q_1=1, shifted left 1)
      0 0 0 0 . .       (M x q_2, q_2=0, shifted left 2)
    1 1 0 1 . . .       (M x q_3, q_3=1, shifted left 3)
    -----------------
    1 0 0 0 1 1 1 1     (143)  Product P

The product of two n-bit numbers can be up to 2n bits long. Each partial product row is just the multiplicand AND-ed with a single multiplier bit, shifted to the appropriate position. The final product is the sum of all partial products.

3.2 Array Multiplier

The manual algorithm maps directly to a combinational array multiplier. For an n x n multiplier, the main component in each cell is a full adder. The AND gate in each cell determines whether a multiplicand bit m_j is added to the incoming partial product, based on the value of multiplier bit q_i.

Array multiplier for 4-bit operands (M x Q = P):

  Partial product 0:     0      m3*q0   m2*q0   m1*q0   m0*q0
  Partial product 1:            m3*q1   m2*q1   m1*q1   m0*q1
  Partial product 2:     m3*q2  m2*q2   m1*q2   m0*q2
  Partial product 3:  m3*q3     m2*q3   m1*q3   m0*q3

  ──────────────────────────────────────────────────────────
  Product:             p7  p6   p5      p4      p3  p2  p1  p0

Each cell contains:

• An AND gate that computes m_j * q_i

• A full adder that adds this bit product to the incoming partial product bit and the carry from the right

The worst-case delay path runs diagonally from the upper right corner to the lower left (the staircase pattern), giving a total delay of approximately 6(n-1) - 1 gate delays for an n x n array.

3.3 Sequential Multiplication Hardware

For large operands (32-bit or 64-bit), a full array multiplier uses too many gates. Instead, multiplication is performed sequentially using a single n-bit adder and shift registers. Think of it this way: instead of building all the partial product rows at once, we process them one at a time.

Algorithm (n iterations):

1. Initialize: A = 0, C = 0, Q = multiplier, M = multiplicand

2. For i = 0 to n-1:

   • If q_0 = 1: Add M to A, store carry in C (i.e., C,A = A + M)

   • If q_0 = 0: No addition

   • Shift right C, A, Q (C goes into MSB of A, LSB of A goes into MSB of Q, LSB of Q is discarded)

3. After n iterations, the 2n-bit product is in A (high half) and Q (low half)

Notice the clever trick here: as Q is shifted right, its bits are consumed one by one (q_0 is examined then shifted out), and the high-order bits of the product fill in from the left. The multiplier is gradually replaced by the product!

3.4 Worked Example: 13 x 11 = 143

Using 4-bit registers (M = 1101, Q = 1011):

Key Takeaway: Sequential multiplication uses a single n-bit adder and performs n add-and-shift cycles. Each cycle examines the LSB of Q, conditionally adds M, then shifts the combined C-A-Q register right by one position. After n cycles, the 2n-bit product occupies registers A and Q.

4. Signed-Operand Multiplication

4.1 The Problem with Signed Numbers

The shift-and-add algorithm above works only for positive (unsigned) numbers. When one or both operands are negative (in 2's complement), we need a different approach.

Case 1: Positive multiplier, negative multiplicand. When adding a negative multiplicand to a partial product, we must sign-extend the multiplicand to the full 2n-bit width of the product to get the correct result.

Case 2: Negative multiplier. A straightforward solution is to complement both operands (making the multiplier positive) and proceed as before. But there is a much more elegant technique that handles all cases uniformly.

4.2 Booth's Algorithm

The Booth algorithm is one of those ideas that feels like magic the first time you see it. It generates a 2n-bit product and treats both positive and negative 2's-complement n-bit operands uniformly -- no special cases needed.

Core idea: Instead of scanning multiplier bits one at a time and always adding, Booth's algorithm scans pairs of consecutive bits (q_i and q_{i-1}) and decides whether to add, subtract, or do nothing.

The algorithm is based on a beautiful observation: a block of consecutive 1s in the multiplier can be replaced by a subtract at the beginning and an add at the end. For example:

0011110  can be rewritten as  0100000 - 0000010
  (30)                          (32)      (2)

This works because 30 = 32 - 2. Instead of four additions (one for each '1' bit), we perform just one subtraction and one addition. For long runs of 1s, the savings can be dramatic.

4.3 Booth Recoding Table

We scan the multiplier from right to left, examining bit pairs (q_i, q_{i-1}), starting with q_{-1} = 0:

Interpretation -- think of transitions:

• 0 -> 0: Middle of a block of 0s. Do nothing.

• 0 -> 1: End of a block of 1s (right-to-left transition from 1 to 0). Add M.

• 1 -> 0: Beginning of a block of 1s (right-to-left transition from 0 to 1). Subtract M.

• 1 -> 1: Middle of a block of 1s. Do nothing.

4.4 Booth's Algorithm Hardware

The hardware is similar to the basic sequential multiplier, with these additions:

• An extra flip-flop q_{-1} (initialized to 0) to hold the previous bit of Q

• The adder must be able to add or subtract M (2's complement subtraction)

• The shift is an arithmetic right shift (the sign bit is replicated, not filled with zero)

Algorithm steps (repeat n times):

1. Examine q_0 and q_{-1}:

   • (0, 0) or (1, 1): No arithmetic operation

   • (0, 1): A = A + M

   • (1, 0): A = A - M

2. Arithmetic shift right A, Q, q_{-1} (sign bit of A is preserved and replicated)

4.5 Worked Example: Booth's Algorithm

Example: (+5) x (-4) = -20 using Booth's Algorithm (4-bit operands)

M = 0101 (+5), Q = 1100 (-4), with q_{-1} = 0:

Verification: 11101100 in 8-bit 2's complement: = -128 + 64 + 32 + 0 + 8 + 4 + 0 + 0 = -128 + 108 = -20.

The important thing is that Booth's algorithm correctly handles all four sign combinations:

• Positive x Positive

• Positive x Negative

• Negative x Positive

• Negative x Negative

In all cases, the algorithm produces the correct 2n-bit 2's complement product without any special-case handling.

Key Takeaway: Booth's algorithm handles signed multiplication by scanning pairs of multiplier bits (q_i, q_{i-1}) and performing add, subtract, or no-op accordingly. It skips over blocks of consecutive 1s and 0s, potentially reducing the number of additions. It works correctly for both positive and negative operands in 2's complement.

5. Fast Multiplication

5.1 Bit-Pair Recoding (Modified Booth Algorithm)

Booth's algorithm has a weakness: in the worst case (alternating 1s and 0s like 010101...), every bit position requires an operation, giving no speedup over the basic algorithm.

Bit-pair recoding (also called Modified Booth or Booth-2) fixes this by grouping the Booth-recoded bits in pairs, guaranteeing that the number of summands is halved to at most n/2 for n-bit operands.

The bit-pair recoding table considers three consecutive bits (the pair at positions i+1 and i, plus the bit at i-1) to determine a single multiplicand selection:

The possible multiplicand selections are: 0, +M, -M, +2M, -2M

Since 2M is just M shifted left by one position, all five cases are easily implementable in hardware -- no actual multiplication needed!

5.2 Bit-Pair Recoding Example

Let's apply this to the multiplication (+13) x (-6):

M = 0 1 1 0 1    (+13)
Q = 1 1 0 1 0    (-6)

Step 1: Apply Booth recoding to Q (with implied q_{-1} = 0):

  Q bits:      1     1     0     1     0    [0]
  Booth:       0    -1    +1    -1      0

Step 2: Use the 3-bit grouping from the original multiplier:

  Group 1: q_1, q_0, q_{-1} = 1, 0, 0  -->  -2 x M  at position 0
  Group 2: q_3, q_2, q_1    = 1, 0, 1  -->  -1 x M  at position 2
  Remaining: (sign, q_4, q_3) = (1, 1, 1)  -->   0 x M  at position 4

Bit-pair recoded multiplier selects:  0,  -1,  -2
                          (at positions 4,   2,   0)

Step 3: Form the summands:

  At position 0:  -2 x M = -2 x 13 = -26
  Sign-extended:  1 1 1 1 1 0 0 1 1 0

  At position 2:  -1 x M = -1 x 13 = -13, shifted left 2
  Sign-extended:  1 1 1 1 0 0 1 1 0 0    (that is, -52)

  At position 4:   0 x M = 0
                   0 0 0 0 0 0 0 0 0 0

Step 4: Add the summands:

    1 1 1 1 1 0 0 1 1 0    (-26)
  + 1 1 1 1 0 0 1 1 0 0    (-52)
  + 0 0 0 0 0 0 0 0 0 0    (  0)
  ──────────────────────
    1 1 1 0 1 1 0 0 1 0    (-78)

Only n/2 = 2 non-zero summands instead of up to n with basic Booth!

Verification: -26 + (-52) = -78 = (+13) x (-6). Correct!

5.3 Carry-Save Addition (CSA)

Even with bit-pair recoding reducing the number of summands to n/2, we still need to add them together. In a straightforward approach, adding k summands with ripple-carry adders would take O(k * n) time. Carry-Save Addition dramatically reduces this.

Idea: Instead of letting carries ripple within each addition, we "save" the carries and pass them to the next level. A Carry-Save Adder takes three input vectors and produces two output vectors (a sum vector S and a carry vector C) in the time of a single full-adder delay.

Think of it this way: a CSA is really just a row of independent full adders -- no carry chain at all! Each full adder works independently, producing a sum and a carry that gets passed to the next level rather than to the next position.

5.4 CSA Tree for Multiple Summands

To add k summands using CSA:

1. Group summands in threes

2. Apply CSA to each group --> produces 2/3 as many vectors

3. Repeat until only 2 vectors remain

4. Add the final 2 vectors with a fast (CLA) adder

Delay analysis for 6 summands:

• 3 levels of CSA: 3 x 2 = 6 gate delays

• Final CLA addition: ~8 gate delays (for 12-bit result)

• Total: ~14 gate delays

Compare to the array multiplier for 6 x 6: 6(6-1)-1 = 29 gate delays. The CSA approach roughly halves the delay.

General formula: For k summands, the number of CSA levels is approximately 1.7 * log_2(k) - 1.7. With bit-pair recoding reducing summands to n/2, this becomes 1.7 * log_2(n) - 3.4 CSA levels.

For a 32 x 32 multiplication: 16 summands (after bit-pair recoding), approximately 8 CSA levels, then one CLA addition. Total delay of about 29 gate delays, compared to 185 gate delays for a 32 x 32 array multiplier. That is over 6x faster.

Key Takeaway: Bit-pair recoding halves the number of summands to n/2 by combining consecutive Booth-recoded bits. Carry-Save Addition then adds these summands in a tree structure, reducing k summands to 2 vectors in approximately 1.7*log2(k) levels. The final two vectors are added by a CLA adder. Together, these techniques make multiplication dramatically faster than the naive sequential or array approaches.

6. Integer Division

Division is the inverse of multiplication. Given a dividend X and a divisor M, we seek a quotient Q and a remainder R such that X = Q * M + R. Let's see how the hardware does this.

6.1 Longhand Division Example

Just like multiplication, let's start with the manual process:

  Decimal:                    Binary:

         21                          10101
    13 ) 274                  1101 ) 100010010
         26                          1101
         --                          ─────
         14                          10000
         13                          1101
         --                          ─────
          1                           1110
                                      1101
                                      ─────
                                         1

  274 / 13 = 21 remainder 1      100010010 / 1101 = 10101 remainder 1

In binary division, each quotient bit is either 0 or 1. We try to subtract the divisor from the current remainder. If the result is non-negative, the quotient bit is 1; otherwise, it is 0. Simpler than decimal, where you have to guess the right digit from 0-9.

6.2 Restoring Division

Restoring division is the straightforward hardware implementation of longhand division.

Restoring Division Algorithm:

Load the n-bit positive divisor into M and the n-bit positive dividend into Q. Set A = 0. Do the following n times:

1. Shift A and Q left one binary position.

2. Subtract M from A and place the result back in A.

3. If the sign of A is 1 (negative result):

   • Set q_0 = 0

   • Restore: Add M back to A (undo the subtraction)

4. Otherwise (A >= 0):

   • Set q_0 = 1

After n cycles, Q contains the quotient and A contains the remainder.

6.3 Restoring Division Worked Example

Let's divide 8 by 3: Dividend = 1000 (8), Divisor = 0011 (3).

6.4 Non-Restoring Division

The restoring step wastes time because we subtract M and then (if the result is negative) immediately add M back. Non-restoring division avoids this by modifying the next iteration instead.

Key insight: If A is negative after a subtraction, instead of restoring and then shifting and subtracting in the next cycle (which is equivalent to computing 2(A+M) - M = 2A + M), we can simply shift and add in the next cycle. The math works out to the same thing, but we save an entire add operation per cycle.

Non-Restoring Division Algorithm:

Step 1: Do the following n times:

1. If the sign of A is 0 (positive): shift A,Q left and subtract M from A. If the sign of A is 1 (negative): shift A,Q left and add M to A.

2. If the sign of A is now 0: set q_0 = 1. Otherwise: set q_0 = 0.

Step 2: If the sign of A is 1 (negative remainder), add M to A to get the correct positive remainder.

6.5 Non-Restoring Division Worked Example

Same example: Divide 8 by 3. M = 0011, Q = 1000, A = 00000.

Advantage of non-restoring division: Exactly one addition or subtraction per cycle (never both). The restoring algorithm requires up to 2 operations per cycle (subtract, then restore). Non-restoring division is therefore faster, at the cost of the single final correction step.

Key Takeaway: Restoring division subtracts the divisor and restores (adds back) if the result is negative. Non-restoring division skips the restore step; if the remainder is negative, the next cycle adds instead of subtracting. Non-restoring division performs exactly one add/subtract per cycle and requires at most one final correction.

7. Floating-Point Numbers and Operations

7.1 Why Floating-Point?

Let's shift gears and talk about real numbers. Fixed-point integers (with the binary point at the right end) can represent values in the range 0 to approximately 2^n for unsigned n-bit numbers. Even with 32 bits, the range is only about 0 to 4.3 billion. This is insufficient for scientific computing, which routinely encounters numbers like Avogadro's number (6.0247 x 10^23) or Planck's constant (6.6254 x 10^-27).

Floating-point representation solves this by allowing the binary point to "float." A number is represented by:

• A sign bit

• An exponent (the scale factor)

• A mantissa (the significant digits, also called the significand)

Value = (-1)^sign  x  mantissa  x  2^exponent

Think of it like scientific notation in binary. Just as we write 6.022 x 10^23 in decimal, we write something like 1.0110 x 2^5 in binary.

7.2 IEEE 754 Standard

The IEEE 754 standard (adopted in 1985, revised in 2008 and 2019) defines two primary formats that are used universally today:

Single Precision (32 bits)

Double Precision (64 bits)

7.3 Bias and Normalized Form

The exponent is stored in biased (also called "excess") notation. For single precision, the bias is 127. For double precision, the bias is 1023.

Stored exponent E_stored = E_actual + bias

Single: E_stored = E_actual + 127
Double: E_stored = E_actual + 1023

Why biased? Because it makes comparing floating-point numbers easier -- you can almost compare them as unsigned integers, which simplifies hardware.

The normalized form requires the mantissa to have the form 1.fraction. Since the leading bit is always 1 for a normalized number, it is not stored explicitly -- it is the hidden bit (also called the implied bit). This gives one extra bit of precision for free!

Value = (-1)^S  x  1.M  x  2^(E - bias)

where M is the 23-bit (or 52-bit) stored mantissa
and E is the 8-bit (or 11-bit) stored exponent

Example: Let's represent -12.625 in IEEE 754 single precision.

Step 1: Convert to binary
  12    = 1100 (binary)
  0.625 = 0.101 (binary):  0.625 x 2 = 1.25  --> 1
                            0.25  x 2 = 0.5   --> 0
                            0.5   x 2 = 1.0   --> 1
  So 12.625 = 1100.101

Step 2: Normalize
  1100.101 = 1.100101 x 2^3

Step 3: Determine fields
  Sign:     1 (negative)
  Exponent: 3 + 127 = 130 = 10000010
  Mantissa: 10010100000000000000000  (23 bits, dropping the leading 1)

Step 4: Assemble
  IEEE 754: 1  10000010  10010100000000000000000
          = C149 0000 (hex)

7.4 Ranges and Special Values

Single precision ranges:

Smallest normalized positive:  1.0 x 2^(-126)             ~ 1.18 x 10^(-38)
Largest normalized positive:   (2 - 2^(-23)) x 2^(127)    ~ 3.40 x 10^(38)
Precision:                     ~7 decimal digits

Double precision ranges:

Smallest normalized positive:  1.0 x 2^(-1022)            ~ 2.23 x 10^(-308)
Largest normalized positive:   (2 - 2^(-52)) x 2^(1023)   ~ 1.80 x 10^(308)
Precision:                     ~16 decimal digits

IEEE 754 reserves certain bit patterns for special values:

Let me explain each special case:

Denormalized numbers (also called subnormal numbers) fill the gap between zero and the smallest normalized number. They have the form 0.M x 2^(-126) (single) or 0.M x 2^(-1022) (double), where the implicit leading bit is 0 instead of 1. This provides gradual underflow rather than an abrupt jump to zero. Without denormals, the gap between zero and the smallest representable number would be much larger than the gaps between other neighboring representable numbers.

NaN (Not a Number) is the result of undefined operations like 0/0 or sqrt(-1). There are two kinds: signaling NaN (causes an exception when used) and quiet NaN (propagates silently through calculations).

Infinity results from overflow or division by zero. Arithmetic with infinity follows mathematical rules: infinity + finite = infinity, finite / infinity = 0, infinity / infinity = NaN, and so on.

7.5 Floating-Point Addition and Subtraction

Adding two floating-point numbers is considerably more complex than integer addition. You cannot just add the bit patterns. The algorithm involves four steps:

To compute A + B where A = M_A x 2^(E_A) and B = M_B x 2^(E_B):

Step 1: Compare exponents
  Compute d = E_A - E_B

Step 2: Align mantissas
  Shift the mantissa of the smaller number RIGHT by |d| positions
  (This aligns the binary points so we are adding like quantities)

Step 3: Add (or subtract) the aligned mantissas
  M_result = M_A +/- M_B (shifted)
  E_result = max(E_A, E_B)

Step 4: Normalize the result
  If the result mantissa is not in the form 1.xxxxx:
    - If >= 2: shift mantissa RIGHT, increment exponent
    - If < 1:  shift mantissa LEFT,  decrement exponent
  Also: check for exponent overflow/underflow
  Round the mantissa to fit in the available bits

Detailed Example: Add 1.5 + 0.4375 in IEEE 754

A = 1.5    = 1.1   x 2^0     -->  S=0, E=127, M=10000...
B = 0.4375 = 1.11  x 2^(-1)  -->  S=0, E=126, M=11000...

Step 1: Compare exponents
  d = 127 - 126 = 1
  B has the smaller exponent, so we shift B's mantissa

Step 2: Align mantissas (shift B right by 1)
  B mantissa: 1.110...  --> shifted right 1 --> 0.111...

Step 3: Add mantissas
      1.100 0000...     (A)
    + 0.111 0000...     (B, shifted)
    ────────────────
     10.011 0000...

Step 4: Normalize
  Result = 10.011 x 2^0 = 1.0011 x 2^1
  New exponent = 0 + 1 = 1, stored as 128

Final: S=0, E=128=10000000, M=00110000...0
Value = 1.0011 x 2^1 = 10.011 = 2 + 0.25 + 0.125 = 1.9375

Verify: 1.5 + 0.4375 = 1.9375   Correct!

7.6 Floating-Point Multiplication

Here's where it gets interesting -- floating-point multiplication is actually simpler than addition! No alignment step is needed.

To compute A x B:

Step 1: Multiply the mantissas
  M_result = M_A x M_B    (using integer multiplication techniques)

Step 2: Add the exponents
  E_result = E_A + E_B - bias
  (We subtract the bias once because both exponents include it)

Step 3: Determine the sign
  S_result = S_A XOR S_B

Step 4: Normalize
  If the mantissa product >= 2: shift right, increment exponent
  Round to fit available bits
  Check for exponent overflow/underflow

Example: Multiply 1.5 x 2.5

A = 1.5   = 1.1   x 2^0     -->  E_A = 127
B = 2.5   = 1.01  x 2^1     -->  E_B = 128

Step 1: Multiply mantissas
  1.1 x 1.01:
        1.1 0
      x 1.0 1
      -------
        1 1 0       (1.10 x 1)
      0 0 0 .       (1.10 x 0, shifted)
    1 1 0 . .       (1.10 x 1, shifted)
    ---------
    1.1 1 1 0       Result: 1.111

Step 2: Add exponents
  E = 127 + 128 - 127 = 128   (subtract bias once)

Step 3: Sign = 0 XOR 0 = 0 (positive)

Step 4: 1.111 is already normalized (between 1 and 2)

Result: 1.111 x 2^1 = 11.11 = 3.75

Verify: 1.5 x 2.5 = 3.75   Correct!

7.7 Guard Bits and Rounding

When shifting the mantissa during alignment or normalization, bits may be shifted off the right end and lost. To maintain accuracy, the hardware uses extra bits beyond the 23 (or 52) mantissa bits during computation.

The IEEE standard requires that the result of any arithmetic operation be the same as if it were computed with infinite precision and then rounded. To achieve this, implementations typically use:

• Guard bit (G): One extra bit immediately to the right of the mantissa

• Round bit (R): One more bit to the right of the guard bit

• Sticky bit (S): The OR of all bits shifted beyond the round bit position

The sticky bit is especially clever: it tells you whether ANY bits were lost during shifting, without needing to track all of them individually.

7.8 Rounding Methods

IEEE 754 defines four rounding modes:

1. Round to Nearest Even (default): The most commonly used mode. Round to the nearest representable value. In case of a tie (exactly halfway), round to the value whose least significant bit is 0 (i.e., even).

Examples (rounding to integer for simplicity):
  2.5 --> 2   (ties to even)
  3.5 --> 4   (ties to even)
  2.3 --> 2
  2.7 --> 3

This eliminates the systematic upward bias of the "round half up" rule that we learned in grade school.

2. Round toward Zero (Truncation / Chopping): Simply discard the extra bits. Always rounds toward zero.

  +2.7 --> +2
  -2.7 --> -2

3. Round toward +Infinity (Ceiling): Always round up (toward positive infinity).

  +2.1 --> +3
  -2.7 --> -2

4. Round toward -Infinity (Floor): Always round down (toward negative infinity).

  +2.7 --> +2
  -2.1 --> -3

7.9 Von Neumann Rounding (An Older Method)

An older rounding technique, sometimes called von Neumann rounding or jamming, works as follows: if any bits are shifted off (i.e., the truncated portion is nonzero), force the LSB of the retained result to 1. This does not bias the result but produces a slightly larger maximum error than round-to-nearest.

It is simple to implement (just OR the sticky bit into the LSB), but IEEE 754's round-to-nearest-even is more accurate and has become the universal default.

7.10 Implementing Rounding with G, R, S

Using the guard, round, and sticky bits, the round-to-nearest-even decision is:

Key Takeaway: IEEE 754 floating-point uses a sign, biased exponent, and normalized mantissa with an implicit leading 1. Addition requires exponent alignment and renormalization. Multiplication adds exponents and multiplies mantissas. Guard, round, and sticky bits ensure that intermediate results can be correctly rounded using one of four IEEE rounding modes. Round-to-nearest-even is the default and eliminates statistical bias.

8. Summary

Let's recap the complete landscape of computer arithmetic we have covered:

9. Key Formulas Reference

Adder Formulas

Full Adder:
  s_i     = x_i XOR y_i XOR c_i
  c_{i+1} = x_i * y_i + (x_i XOR y_i) * c_i

Overflow Detection:
  Overflow = c_n XOR c_{n-1}

Carry-Lookahead:
  G_i     = x_i AND y_i                 (Generate)
  P_i     = x_i XOR y_i                 (Propagate)
  c_{i+1} = G_i + P_i * c_i             (Carry recurrence)

Expanded carries (4-bit block):
  c_1 = G_0 + P_0*c_0
  c_2 = G_1 + P_1*G_0 + P_1*P_0*c_0
  c_3 = G_2 + P_2*G_1 + P_2*P_1*G_0 + P_2*P_1*P_0*c_0
  c_4 = G_3 + P_3*G_2 + P_3*P_2*G_1 + P_3*P_2*P_1*G_0
        + P_3*P_2*P_1*P_0*c_0

Block-level (second level):
  P'_0 = P_3 * P_2 * P_1 * P_0
  G'_0 = G_3 + P_3*G_2 + P_3*P_2*G_1 + P_3*P_2*P_1*G_0

Booth's Algorithm

Bit-Pair Recoding (Modified Booth)

Division Algorithms

Restoring Division (repeat n times):
  1. Shift A,Q left
  2. A <-- A - M
  3. If A < 0: set q_0 = 0, A <-- A + M   (restore)
     Else:     set q_0 = 1

Non-Restoring Division (repeat n times):
  1. If A >= 0: shift A,Q left, A <-- A - M
     If A < 0:  shift A,Q left, A <-- A + M
  2. If A >= 0: set q_0 = 1
     If A < 0:  set q_0 = 0
  Final: If A < 0, add M to A   (correct remainder)

IEEE 754 Floating-Point

Single Precision (32 bits):
  Value = (-1)^S  x  1.M  x  2^(E - 127)
  Sign: 1 bit, Exponent: 8 bits (bias 127), Mantissa: 23 bits
  Range: ~1.18 x 10^(-38) to ~3.40 x 10^38

Double Precision (64 bits):
  Value = (-1)^S  x  1.M  x  2^(E - 1023)
  Sign: 1 bit, Exponent: 11 bits (bias 1023), Mantissa: 52 bits
  Range: ~2.23 x 10^(-308) to ~1.80 x 10^308

Special Values:
  E=0,   M=0     -->  +/- 0
  E=0,   M!=0    -->  Denormalized: (-1)^S x 0.M x 2^(-126 or -1022)
  E=max, M=0     -->  +/- Infinity
  E=max, M!=0    -->  NaN

FP Addition Steps:
  1. Compare exponents
  2. Shift smaller mantissa right by |E_A - E_B|
  3. Add/subtract mantissas
  4. Normalize and round

FP Multiplication Steps:
  1. Multiply mantissas (integer multiplication)
  2. Add exponents, subtract bias
  3. Determine sign (XOR)
  4. Normalize and round

CSA Levels for k summands: ~1.7 * log_2(k) - 1.7

10. Concluding Remarks

Computer arithmetic is one of those topics where the hardware-software boundary becomes razor-thin. Every design choice -- whether to use a CLA or a ripple-carry adder, whether to apply Booth recoding or basic shift-and-add, whether to implement restoring or non-restoring division -- has measurable consequences for chip area, power consumption, and clock speed.

The principles we have covered are not historical curiosities. They are alive in every ALU shipping today:

• Carry-lookahead and its descendants (carry-select, carry-skip, conditional-sum adders) are used in all high-speed adders.

• Booth recoding and carry-save addition trees (often arranged as Wallace trees) are standard in multiplier designs.

• Non-restoring division forms the basis of the SRT division algorithm used in modern processors. (The famous Pentium FDIV bug of 1994 was caused by missing entries in an SRT division lookup table -- a spectacular reminder that getting these circuits right matters enormously.)

• IEEE 754 floating-point is the universal standard, implemented in hardware by every general-purpose processor and most GPUs.

Understanding these circuits at the gate level gives you the foundation to reason about performance, precision, and the occasional spectacular hardware bug. The next time you see a floating-point rounding error or wonder why your compiler chose a particular instruction, you will know exactly what is happening inside the silicon.

The Memory Hierarchy and Where Caches Fit

Computer systems organize memory into a hierarchy based on two competing factors: speed and cost. At the top of this hierarchy sit the processor registers, which are the fastest storage locations but extremely limited in number. At the bottom lies secondary storage like hard drives or SSDs, offering vast capacity but painfully slow access times. Between these extremes, we find main memory (RAM), which provides reasonable capacity at moderate speed but still cannot keep pace with modern processors.

Caches occupy the critical middle ground between registers and main memory. They are built using the same fast SRAM (Static Random Access Memory) technology as registers but in larger quantities. Main memory, in contrast, uses DRAM (Dynamic Random Access Memory), which is slower but cheaper and denser. The memory hierarchy typically includes multiple levels of cache, each progressively larger and slower as we move away from the processor. This hierarchical organization exploits the principle of locality: programs tend to access a relatively small portion of their address space at any given time.

The principle of temporal locality states that recently accessed memory locations are likely to be accessed again soon. Spatial locality suggests that memory locations near recently accessed addresses are also likely to be accessed. Caches leverage both forms of locality by storing not just individual bytes but entire blocks of contiguous memory. When a processor needs data, it first checks the fastest cache level. If the data resides there, we have a cache hit and the processor continues without delay. If not, we suffer a cache miss and must search the next level of the hierarchy, ultimately reaching main memory if necessary.

Memory Hierarchy (fastest to slowest):

Processor Core
     |
     v
+---------+  <-- Registers (few bytes, < 1 cycle)
|   CPU   |
|  Core   |
+---------+
     |
     v
+---------+
|   L1    |  <-- Level 1 Cache (32-64 KB, 1-3 cycles)
|  Cache  |      Split: I-Cache (instructions) + D-Cache (data)
+---------+
     |
     v
+---------+
|   L2    |  <-- Level 2 Cache (256 KB - 1 MB, 10-20 cycles)
|  Cache  |      Usually unified (instructions + data)
+---------+
     |
     v
+---------+
|   L3    |  <-- Level 3 Cache (8-32 MB, 30-70 cycles)
|  Cache  |      Shared across cores
+---------+
     |
     v
+---------+
|  Main   |  <-- DRAM (4-64 GB, 100-300 cycles)
| Memory  |
+---------+
     |
     v
+---------+
|Secondary|  <-- SSD/HDD (TB, millions of cycles)
| Storage |
+---------+

The Cache Hierarchy: L1, L2, and L3

Modern processors typically implement three levels of cache, each serving a distinct purpose in the performance optimization strategy. The Level 1 (L1) cache sits closest to the processor core and is the smallest and fastest. Most architectures split L1 into two separate caches: the instruction cache (I-Cache) holds program code, while the data cache (D-Cache) stores program data. This Harvard architecture split allows the processor to fetch instructions and data simultaneously without conflict. A typical L1 cache might be 32 or 64 kilobytes per core, accessible in just one to three processor cycles.

The Level 2 (L2) cache is larger but slower than L1, typically ranging from 256 kilobytes to 1 megabyte per core. Unlike L1, the L2 cache is usually unified, meaning it stores both instructions and data without distinction. When the processor misses in L1, it checks L2 before resorting to the even slower L3 cache. The access time for L2 might be ten to twenty cycles, still far better than accessing main memory but noticeably slower than L1. This intermediate level provides a critical buffer that catches many accesses that miss in the tiny L1 cache.

The Level 3 (L3) cache is the largest and slowest of the on-chip caches, often ranging from 8 to 32 megabytes or more. In multi-core processors, L3 is typically shared among all cores, serving as a common pool of fast memory that facilitates inter-core communication and reduces redundant storage. Accessing L3 might take thirty to seventy cycles, but this is still dramatically faster than the hundred to three hundred cycles required to fetch data from main memory. The large capacity of L3 means it can hold substantial portions of a program's working set, significantly reducing the frequency of expensive main memory accesses.

The Cost of Building Caches

The decision to implement caches and their specific configurations involves careful economic and engineering tradeoffs. SRAM, the technology underlying caches, requires six transistors per bit of storage, compared to just one transistor and one capacitor per bit for DRAM. This means SRAM occupies roughly six times the silicon area of DRAM for the same capacity. Silicon area directly translates to manufacturing cost, making large SRAM caches prohibitively expensive. Additionally, SRAM consumes more power than DRAM, and since caches must be fast, they often run at or near the processor's clock frequency, further increasing power consumption and heat generation.

The physical distance between the processor and the cache also matters tremendously. Even signals traveling at nearly the speed of light take measurable time to traverse the millimeters of silicon on a modern chip. This is why L1 caches are tiny and placed immediately adjacent to the processor core, while L3 caches can be larger because they are allowed to be farther away and slower. Every increase in cache size represents a tradeoff: more storage capacity means more silicon area, more power consumption, potentially longer access times due to increased complexity, and higher manufacturing costs.

These economic realities explain why we cannot simply make enormous caches to eliminate the memory hierarchy problem. A processor might have just 128 kilobytes of L1 cache total (split between instructions and data), perhaps 1 megabyte of L2, and 16 megabytes of L3. Meanwhile, main memory provides 16 gigabytes or more. The ratio between cache and main memory capacity is enormous, yet that tiny cache handles the vast majority of memory accesses because of locality. The art of cache design lies in finding the sweet spot where size, speed, cost, and power consumption balance to deliver optimal performance for typical workloads.

Cache Organization: Lines, Words, and Bytes

To understand how caches work, we must first understand their basic organizational units. The fundamental unit of cache storage is the cache line, also called a cache block. A cache line is not a single byte or word but rather a contiguous chunk of memory, typically 64 bytes in modern systems. When the processor needs a single byte from memory, the entire cache line containing that byte is fetched and stored in the cache. This design exploits spatial locality: if the program needs one byte, it probably needs the adjacent bytes soon.

Each cache line contains multiple words, and each word contains multiple bytes. The definition of a word is architecture-specific, but in modern systems, a word is typically 4 bytes (32 bits) or 8 bytes (64 bits). Consider a cache line of 64 bytes on a 64-bit architecture where a word is 8 bytes. This line contains eight words, and each word contains eight bytes. The internal structure looks like this:

Cache Line (64 bytes total):

+-------+-------+-------+-------+-------+-------+-------+-------+
| Word0 | Word1 | Word2 | Word3 | Word4 | Word5 | Word6 | Word7 |
+-------+-------+-------+-------+-------+-------+-------+-------+
| 8B    | 8B    | 8B    | 8B    | 8B    | 8B    | 8B    | 8B    |

Each Word (8 bytes):

Word = Byte0 + Byte1 + Byte2 + Byte3 + Byte4 + Byte5 + Byte6 + Byte7

The processor generates memory addresses to access specific bytes in main memory. These addresses must be decoded to locate data within the cache structure. The address breakdown depends on the cache's organizational parameters: the total cache size, the line size, and the associativity (which we will explore shortly). Understanding how addresses map to cache locations is fundamental to grasping cache behavior and performance.

Word-Addressable vs Byte-Addressable Memory

Memory addressing schemes come in two primary flavors: byte-addressable and word-addressable. This distinction affects how we interpret memory addresses and how we break them down to access cache contents. In a byte-addressable architecture, each individual byte has a unique address. Most modern architectures, including x86, ARM, and RISC-V, are byte-addressable. In a word-addressable architecture, each word has a unique address, and individual bytes within a word are accessed by specifying both the word address and a byte offset.

Consider a byte-addressable system with 8-byte words. Address 0 points to byte 0, address 1 points to byte 1, address 8 points to byte 8 (the first byte of the second word), and so on. Every byte has its own address from 0 to the maximum addressable memory. Now consider a word-addressable system with 8-byte words. Address 0 points to word 0 (bytes 0-7), address 1 points to word 1 (bytes 8-15), and so on. To access byte 5 in the word-addressable system, you would specify word address 0 and byte offset 5.

Byte-addressable systems are more flexible and align better with modern software paradigms where programs manipulate individual bytes, characters, and variable-length data structures. However, they require slightly more complex address decoding. When we break down a byte address to access a cache, we must identify which line contains the byte, which word within that line, and which byte within that word. In a word-addressable system, the address directly identifies the word, and we only need to determine the cache line and word position within that line.

Let us examine a concrete example for a byte-addressable system with 64-byte cache lines and 8-byte words. Consider address 156 (in decimal). First, we determine which cache line contains this address by dividing by the line size: 156 ÷ 64 = 2 remainder 28. This address resides in cache line 2 (the third line, counting from 0), at byte offset 28 within that line. To find the word within the line, we divide the byte offset by the word size: 28 ÷ 8 = 3 remainder 4. This means the address points to word 3 within the line, specifically byte 4 within that word.

Address 156 breakdown (byte-addressable, 64-byte lines, 8-byte words):

Address: 156 (decimal) = 0x9C (hex) = 10011100 (binary)

156 ÷ 64 = 2 remainder 28
  └─> Cache Line 2, Offset 28

Offset 28 ÷ 8 = 3 remainder 4
  └─> Word 3, Byte 4

Visual representation:
Cache Line 2: [0-63] contains addresses 128-191

Byte Offset:  0   8   16  24  32  40  48  56
              |   |   |   |   |   |   |   |
              v   v   v   v   v   v   v   v
Line 2:    [W0][W1][W2][W3][W4][W5][W6][W7]
                       ^
                       |
                    Offset 28 = Word 3, Byte 4

Sets, Ways, and Generic Cache Structure

Caches are organized into sets and ways, a structure that determines how memory addresses map to cache locations. A set is a group of cache lines, and a way is one of multiple possible locations within a set where a particular memory block can reside. The number of ways in each set defines the cache's associativity. If each set contains only one way, we have a direct-mapped cache. If each set contains multiple ways, we have a set-associative cache. If the entire cache is a single set with many ways, we have a fully-associative cache.

Consider a generic cache with S sets and W ways per set. The total number of cache lines is S × W. Each cache line stores one block of memory along with metadata. The metadata includes a tag that identifies which memory block is currently stored in that line, a valid bit indicating whether the line contains valid data, and potentially other bits for cache coherence and replacement policy tracking. When the processor generates a memory address, we must determine which set to check and then compare the address's tag against all ways in that set to see if the data is present.

The address breakdown for a set-associative cache divides the address into three fields: the tag, the set index, and the block offset. The block offset identifies the specific byte within the cache line. The set index identifies which set to search. The tag distinguishes between different memory blocks that could map to the same set. Let us examine the structure of a generic 2-way set-associative cache:

Generic 2-Way Set-Associative Cache Structure:

            Way 0                     Way 1
         +---+----+-------+      +---+----+-------+
Set 0:   | V | Tag| Data  |      | V | Tag| Data  |
         +---+----+-------+      +---+----+-------+
Set 1:   | V | Tag| Data  |      | V | Tag| Data  |
         +---+----+-------+      +---+----+-------+
Set 2:   | V | Tag| Data  |      | V | Tag| Data  |
         +---+----+-------+      +---+----+-------+
Set 3:   | V | Tag| Data  |      | V | Tag| Data  |
         +---+----+-------+      +---+----+-------+
   ...

V = Valid bit (1 bit)
Tag = Tag field (variable bits)
Data = Cache line data (typically 64 bytes)

Memory Address Breakdown:
+---------+-----------+--------------+
|   Tag   | Set Index | Block Offset |
+---------+-----------+--------------+
    |           |            |
    |           |            └─> Which byte in the line?
    |           └─> Which set to check?
    └─> Which specific memory block?

When accessing the cache, the processor uses the set index to select one set, then simultaneously compares the tag field of the address against the tags in all ways of that set. If any way's tag matches and its valid bit is set, we have a cache hit and retrieve data from that way's data field using the block offset. If no tags match, we have a cache miss and must fetch the data from the next level of memory hierarchy. The choice of how many sets and ways to implement represents a fundamental design decision that affects both performance and hardware complexity.

Direct-Mapped Caches: One Way Per Set

A direct-mapped cache represents the simplest mapping strategy. Each set contains exactly one way, meaning each memory block maps to exactly one location in the cache. For a direct-mapped cache with N lines, we have N sets and 1 way per set. This design offers the advantage of simplicity: determining whether a block is in the cache requires checking only one location, making the hardware fast and inexpensive. However, it suffers from high conflict miss rates when multiple frequently accessed memory blocks map to the same cache line.

The address breakdown for a direct-mapped cache is straightforward. We divide the address into three parts: the tag, the line index (since each set has one line, we can call it a line index rather than a set index), and the block offset. The number of bits in each field depends on the cache parameters. The block offset requires log₂(block_size) bits. The line index requires log₂(number_of_lines) bits. The remaining high-order bits form the tag.

Let us work through a detailed example. Consider a direct-mapped cache with the following specifications: total cache size of 1 KB (1024 bytes), block size of 16 bytes, and a 16-bit address space. First, we calculate the number of cache lines: 1024 bytes ÷ 16 bytes per line equals 64 lines. The block offset requires log₂(16) equals 4 bits to address any byte within the 16-byte block. The line index requires log₂(64) equals 6 bits to select among the 64 lines. The tag gets the remaining bits: 16 - 4 - 6 equals 6 bits.

Direct-Mapped Cache Example:
Cache size: 1 KB (1024 bytes)
Block size: 16 bytes
Address space: 16 bits (64 KB addressable)
Number of lines: 1024 / 16 = 64 lines

Address breakdown (16 bits):
+------+----------+--------------+
| Tag  |   Line   | Block Offset |
| 6b   | Index 6b |      4b      |
+------+----------+--------------+
15   10 9        4 3            0

Cache Structure (64 lines, 1 way):

        Way 0
     +---+----+-------+
L 0: | V | Tag| Data  |  16 bytes
     +---+----+-------+
L 1: | V | Tag| Data  |
     +---+----+-------+
L 2: | V | Tag| Data  |
     +---+----+-------+
     ...
     +---+----+-------+
L63: | V | Tag| Data  |
     +---+----+-------+

Now let us trace several memory accesses through this cache. Consider accessing address 0x0A34 (binary: 0000101000110100). Breaking down this address: bits [15:10] give tag equals 0b000010 (decimal 2), bits [9:4] give line index equals 0b100011 (decimal 35), and bits [3:0] give block offset equals 0b0100 (decimal 4). The processor checks line 35. If the valid bit is set and the stored tag equals 2, we have a hit and return byte 4 from that line's data block. If not, we have a miss.

Address 0x0A34 access:

Binary: 0000 10 | 10 0011 | 0100
        Tag: 2   Index: 35  Offset: 4

Check line 35:
     +---+----+-------+
L35: | 1 | 02 | Data  | <-- V=1, Tag matches (02), HIT!
     +---+----+-------+
                  ^
                  |
         Return byte at offset 4

Next, consider accessing address 0x4A34 (binary: 0100101000110100). The tag is 0b010010 (decimal 18), the line index is 0b100011 (decimal 35), and the block offset is 0b0100 (decimal 4). Notice that this address maps to the same line 35 as the previous access but has a different tag. If line 35 still contains the block from address 0x0A34 (tag 2), we have a conflict miss. The cache must evict the old block and load the new block with tag 18.

Address 0x4A34 access (conflict with previous):

Binary: 0100 10 | 10 0011 | 0100
        Tag: 18  Index: 35  Offset: 4

Check line 35:
     +---+----+-------+
L35: | 1 | 02 | Data  | <-- V=1, Tag doesn't match (02≠18), MISS!
     +---+----+-------+

After replacing:
     +---+----+-------+
L35: | 1 | 18 | Data  | <-- New block loaded, tag=18
     +---+----+-------+

This example illustrates the primary weakness of direct-mapped caches: conflict misses. If a program alternately accesses addresses 0x0A34 and 0x4A34, the cache will miss on every access because both addresses map to line 35 but have different tags. This thrashing behavior can severely degrade performance. Despite this limitation, direct-mapped caches are popular in practice because of their simplicity, speed, and low hardware cost. Many modern L1 caches use more complex associative designs, but direct mapping remains important in certain contexts and as a conceptual building block.

Set-Associative Caches: Multiple Ways Per Set

Set-associative caches strike a balance between the simplicity of direct-mapped caches and the flexibility of fully-associative caches. In an N-way set-associative cache, each set contains N ways (N cache lines). A memory block can reside in any of the N ways within its designated set, reducing conflict misses compared to direct mapping. The hardware must compare the address tag against all N ways in parallel, which increases complexity and power consumption but remains practical for moderate associativity levels.

The address breakdown for a set-associative cache is similar to direct mapping, but we now have fewer sets than total cache lines. For a cache with C total lines and N-way associativity, we have C/N sets. The set index field requires log₂(C/N) bits, the block offset remains log₂(block_size) bits, and the tag gets the remaining bits. The increased tag size compared to direct mapping (because we have fewer index bits) provides better disambiguation between different memory blocks.

Let us examine a concrete example: a 4-way set-associative cache with 2 KB total capacity, 32-byte blocks, and a 16-bit address space. The number of cache lines is 2048 bytes ÷ 32 bytes equals 64 lines. With 4-way associativity, we have 64 ÷ 4 equals 16 sets. The block offset requires log₂(32) equals 5 bits. The set index requires log₂(16) equals 4 bits. The tag requires 16 - 5 - 4 equals 7 bits.

4-Way Set-Associative Cache Example:
Cache size: 2 KB (2048 bytes)
Block size: 32 bytes
Associativity: 4-way
Address space: 16 bits
Number of lines: 2048 / 32 = 64 lines
Number of sets: 64 / 4 = 16 sets

Address breakdown (16 bits):
+-------+----------+--------------+
|  Tag  |   Set    | Block Offset |
|  7b   | Index 4b |      5b      |
+-------+----------+--------------+
15     9 8        5 4            0

Cache Structure (16 sets, 4 ways):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 0: | V | T | D | | V | T | D | | V | T | D | | V | T | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 1: | V | T | D | | V | T | D | | V | T | D | | V | T | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     ...
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S15: | V | T | D | | V | T | D | | V | T | D | | V | T | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+

V = Valid bit, T = Tag (7 bits), D = Data (32 bytes)

Let us trace memory accesses through this cache. Consider accessing address 0x15A8 (binary: 0001010110101000). The tag is bits [15:9] equals 0b0001010 (decimal 10), the set index is bits [8:5] equals 0b1101 (decimal 13), and the block offset is bits [4:0] equals 0b01000 (decimal 8). The processor checks all four ways of set 13 in parallel. If any way has valid equals 1 and tag equals 10, we hit. If not, we miss and must choose which way to replace.

Address 0x15A8 access:

Binary: 0001010 | 1101 | 01000
        Tag: 10   Set:13  Offset: 8

Check set 13 (all ways in parallel):
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S13: | 1 | 05| D | | 1 | 10| D | | 1 | 22| D | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
                      ^
                      |
                  Tag matches! HIT in Way 1
                  Return byte at offset 8

Now consider accessing address 0x8DA8 (binary: 1000110110101000). The tag is 0b1000110 (decimal 70), the set index is 0b1101 (decimal 13, same as before), and the block offset is 0b01000 (decimal 8). This address also maps to set 13 but has a different tag. The processor checks all four ways of set 13. Suppose none of the tags match. We have a miss and must load the block from memory.

Address 0x8DA8 access:

Binary: 1000110 | 1101 | 01000
        Tag: 70   Set:13  Offset: 8

Check set 13:
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S13: | 1 | 05| D | | 1 | 10| D | | 1 | 22| D | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+

No tag matches (05≠70, 10≠70, 22≠70), MISS!
Way 3 is invalid, use it for replacement:

After loading:
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S13: | 1 | 05| D | | 1 | 10| D | | 1 | 22| D | | 1 | 70| D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+

The beauty of set-associative caches becomes apparent when we compare them to direct-mapped caches. In our earlier direct-mapped example, addresses 0x0A34 and 0x4A34 conflicted because they mapped to the same line. In a set-associative cache, multiple addresses mapping to the same set can coexist peacefully as long as we have enough ways available. If a program alternates between four different memory blocks that all map to set 13, our 4-way cache can hold all of them simultaneously, while a direct-mapped cache would thrash miserably.

The choice of associativity level involves tradeoffs. Higher associativity reduces conflict misses but increases hardware complexity, power consumption, and access time. Each additional way requires another tag comparator and another multiplexer to select the correct data. Most modern processors use 4-way or 8-way set-associative L1 caches, while L2 and L3 caches often use 8-way or 16-way associativity. The specific choice depends on the target workload characteristics and the available silicon budget.

Fully-Associative Caches: Maximum Flexibility

A fully-associative cache represents the opposite extreme from direct mapping. The entire cache is a single set containing all cache lines as separate ways. Any memory block can reside in any cache line, providing maximum flexibility and eliminating conflict misses entirely. The only misses in a fully-associative cache are compulsory misses (first access to a block) and capacity misses (cache is full and a block must be evicted). However, this flexibility comes at a steep hardware cost.

In a fully-associative cache, the address breakdown has only two fields: the tag and the block offset. There is no index field because there is only one set. The tag must distinguish between all possible memory blocks that could fit in the cache, so it contains all address bits except the block offset bits. For every memory access, the cache must compare the tag against every single cache line in parallel, requiring many tag comparators and significantly more power than set-associative designs.

Consider a fully-associative cache with 32 KB capacity, 64-byte blocks, and a 32-bit address space. The number of cache lines is 32768 bytes ÷ 64 bytes equals 512 lines. All 512 lines exist in a single set (512-way associativity). The block offset requires log₂(64) equals 6 bits. There is no index field (or equivalently, 0 bits for the index). The tag requires 32 - 6 equals 26 bits.

Fully-Associative Cache Example:
Cache size: 32 KB (32768 bytes)
Block size: 64 bytes
Associativity: Fully associative (512-way)
Address space: 32 bits
Number of lines: 32768 / 64 = 512 lines
Number of sets: 1 set

Address breakdown (32 bits):
+--------------------+--------------+
|        Tag         | Block Offset |
|       26 bits      |    6 bits    |
+--------------------+--------------+
31                  6 5            0

Cache Structure (1 set, 512 ways):

Single Set with 512 Ways:

Way0   Way1   Way2          Way510 Way511
+---+ +---+ +---+          +---+ +---+
|V|T| |V|T| |V|T|   ...    |V|T| |V|T|
|D  | |D  | |D  |          |D  | |D  |
+---+ +---+ +---+          +---+ +---+

All tags compared in parallel!

V = Valid, T = Tag (26 bits), D = Data (64 bytes)

Let us trace a memory access through this fully-associative cache. Consider address 0x12345678 (binary: 00010010001101000101011001111000). The tag is bits [31:6] equals 0b00010010001101000101011001 (we keep this in hex for readability: 0x48D15E), and the block offset is bits [5:0] equals 0b111000 (decimal 56). The cache must check all 512 ways simultaneously to see if any valid line has a matching tag.

Address 0x12345678 access:

Binary: 00010010001101000101011001 | 111000
        Tag: 0x48D15E (26 bits)      Offset: 56 (6 bits)

Check all 512 ways in parallel:

Way0        Way1        Way2        ...    Way237      ...    Way511
+---+      +---+      +---+               +---+              +---+
|1|..|     |1|..|     |0|..|      ...     |1|0x48D15E|  ...  |1|..|
|...|      |...|      |...|               |Data block |       |...|
+---+      +---+      +---+               +---+              +---+
                                             ^
                                             |
                                      Tag matches! HIT in Way 237
                                      Return byte at offset 56

If no tag matches, we have a miss. The cache must decide which of the 512 lines to evict to make room for the new block. This is where replacement policies become critical, which we will explore in detail shortly. Unlike direct-mapped caches where replacement is forced (the single mapped line must be evicted) or low-associativity set-associative caches where the choice is among a few ways, fully-associative caches must choose among hundreds of candidates.

The hardware cost of fully-associative caches limits their practical use to small, specialized applications. Translation Lookaside Buffers (TLBs), which cache virtual-to-physical address translations, are often fully-associative because they are small (dozens to hundreds of entries) and the flexibility is valuable for reducing translation misses. Some victim caches and other specialized structures also use fully-associative organization. However, you will not find fully-associative designs in large L1, L2, or L3 caches due to the prohibitive cost of hundreds or thousands of parallel tag comparators.

The spectrum from direct-mapped to set-associative to fully-associative represents a fundamental tradeoff in computer architecture. Direct-mapped caches are fast, simple, and cheap but suffer from conflicts. Fully-associative caches eliminate conflicts but are expensive and slow. Set-associative caches provide the pragmatic middle ground, offering enough flexibility to reduce most conflicts while keeping hardware costs reasonable. The specific choice for any given cache depends on its position in the hierarchy, the workload characteristics, and the overall system design constraints.

Why Replacement Policies Matter

Replacement policies become necessary whenever a cache miss occurs and all available locations for the new block are already occupied. In a direct-mapped cache, replacement is trivial because there is only one possible location for each block. If that location is occupied, its contents must be evicted to make room for the new block. However, in set-associative and fully-associative caches, we have choices. When a miss occurs and all ways in the target set are valid, which way should we evict? This decision can significantly impact performance.

The fundamental challenge is predicting the future. The optimal replacement policy would evict the cache line that will not be needed for the longest time. Unfortunately, this requires knowing future memory access patterns, which is generally impossible. Instead, practical replacement policies use heuristics based on past behavior, making reasonable assumptions about which blocks are least likely to be needed soon. Different policies embody different assumptions and involve different implementation costs.

Consider a simple scenario: a 2-way set-associative cache where both ways of set 5 are occupied. A memory access requires loading a new block into set 5. Should we evict the block in way 0 or way 1? If we make the wrong choice and evict a block that will be accessed again soon, we will suffer another miss immediately. If we make the right choice and evict a block that will not be needed for a while, we avoid unnecessary misses. The quality of our replacement decisions directly affects the miss rate and overall system performance.

Common Replacement Policies

Several replacement policies have been developed and deployed in real systems, each with distinct characteristics. The Least Recently Used (LRU) policy evicts the cache line that has not been accessed for the longest time. LRU embodies the principle of temporal locality: if a line has not been used recently, it probably will not be needed soon. LRU typically provides good performance but requires tracking the access order of all lines in a set, which becomes expensive as associativity increases.

The First-In-First-Out (FIFO) policy evicts the oldest cache line regardless of its access pattern. FIFO is simpler than LRU because it only needs to track when each line was loaded, not every subsequent access. However, FIFO can perform poorly when a line loaded long ago continues to be accessed frequently. The Random replacement policy simply selects a victim at random from the available ways. Random replacement requires minimal hardware (just a random or pseudo-random number generator) and surprisingly performs reasonably well in many workloads, avoiding the pathological cases that can plague deterministic policies.

The Least Frequently Used (LFU) policy tracks how many times each line has been accessed and evicts the line with the lowest access count. LFU can identify truly cold data but struggles with changing access patterns. A block accessed many times in the distant past may have a high count even though it is no longer needed, while a newly loaded block that will be accessed frequently has a low count initially. The Not Recently Used (NRU) policy is a simplified approximation of LRU that requires less hardware. It uses a single reference bit per line, set when the line is accessed. Periodically, all reference bits are cleared. When replacement is needed, NRU evicts a line with reference bit equals zero, giving preference to recently accessed lines without tracking exact order.

LRU Replacement in Detail

Let us trace LRU replacement through a concrete example. Consider a 4-way set-associative cache with 64-byte blocks. We will focus on set 8 and observe how LRU manages the four ways as memory accesses occur. Initially, all four ways are invalid. We will use a simple encoding to track LRU order: each way has an age counter from 0 (most recently used) to 3 (least recently used). On every access to the set, we update the ages.

4-Way Set-Associative Cache - Set 8 LRU Example:

Initial state: All ways invalid

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 0 | --| - | | 0 | --| - | | 0 | --| - | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
       V   T   D     V   T   D     V   T   D     V   T   D
     Age: -        Age: -        Age: -        Age: -

Access 1: Load block with tag 0x1A into set 8. All ways are invalid, so we choose way 0. After loading, way 0 has age 0 (most recent).

After Access 1 (Tag 0x1A):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 0 | --| - | | 0 | --| - | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 0        Age: -        Age: -        Age: -

Access 2: Load block with tag 0x2B into set 8. Way 1 is invalid, use it. Way 0 ages to 1, way 1 becomes 0.

After Access 2 (Tag 0x2B):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 0 | --| - | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 1        Age: 0        Age: -        Age: -
     LRU order: Way1(0), Way0(1)

Access 3: Load block with tag 0x3C. Way 2 is used. Ages update: way 2 becomes 0, way 1 becomes 1, way 0 becomes 2.

After Access 3 (Tag 0x3C):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |3C | D | | 0 | --| - |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 2        Age: 1        Age: 0        Age: -
     LRU order: Way2(0), Way1(1), Way0(2)

Access 4: Load block with tag 0x4D. Way 3 is used, all ways now valid.

After Access 4 (Tag 0x4D):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 3        Age: 2        Age: 1        Age: 0
     LRU order: Way3(0), Way2(1), Way1(2), Way0(3) <- LRU victim

Access 5: Hit on tag 0x2B (way 1). No new load, but ages update. Way 1 becomes 0, ways 3 and 2 age.

After Access 5 (Tag 0x2B - HIT on Way 1):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 3        Age: 0        Age: 2        Age: 1
     LRU order: Way1(0), Way3(1), Way2(2), Way0(3) <- LRU victim

Access 6: Miss on tag 0x5E. All ways valid, must evict LRU. Way 0 has age 3 (LRU), evict it.

After Access 6 (Tag 0x5E - MISS, evict Way 0):

        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |5E | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Age: 0        Age: 1        Age: 3        Age: 2
     LRU order: Way0(0), Way1(1), Way3(2), Way2(3) <- LRU victim
     (Tag 0x1A evicted from Way 0)

This example demonstrates how LRU maintains an ordered list of cache lines by recency. Each access updates the order, ensuring the least recently used line is always identifiable. Implementing true LRU for high associativity is complex. For a 4-way cache, we need 2 bits per way to encode ages 0-3, and we must update multiple age values on every access. For an 8-way cache, we need 3 bits per way and even more complex update logic. This is why many practical implementations use pseudo-LRU approximations that provide similar behavior with less hardware.

FIFO and Random Replacement Examples

FIFO replacement maintains a simpler invariant: it tracks the order in which lines were loaded and always evicts the oldest. Let us examine the same sequence of accesses using FIFO on the same 4-way set.

4-Way Set-Associative Cache - Set 8 FIFO Example:

Access 1-4: Load tags 0x1A, 0x2B, 0x3C, 0x4D into ways 0, 1, 2, 3.

After Access 4:
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Load order: 1st      2nd       3rd       4th
     FIFO victim: Way0 (oldest)

Access 5: Hit on tag 0x2B. Unlike LRU, FIFO does not update the replacement order on hits. Way 0 remains the oldest.

After Access 5 (Tag 0x2B - HIT on Way 1):
Same as above, FIFO order unchanged.
     FIFO victim: Way0 (oldest)

Access 6: Miss on tag 0x5E. Evict way 0 (oldest), load new block into way 0. Way 1 is now oldest.

After Access 6 (Tag 0x5E - MISS, evict Way 0):
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |5E | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     Load order: 5th      2nd       3rd       4th
     FIFO victim: Way1 (oldest)
     (Tag 0x1A evicted from Way 0)

Notice that in access 5, both LRU and FIFO had way 0 as the victim before the access. However, LRU changed the victim to way 2 after hitting on way 1, while FIFO kept way 0 as the victim. If the next access after access 5 had been to tag 0x1A, LRU would have hit (because 0x1A is still in the cache), but then on access 6, FIFO evicted 0x1A anyway. This illustrates why LRU can perform better: it adapts to the actual access pattern rather than just the load order.

Random replacement is even simpler to demonstrate. At each replacement decision, we generate a random number to select the victim way. Suppose our random number generator produces the sequence: 2, 1, 3, 0, ...

4-Way Set-Associative Cache - Set 8 Random Replacement Example:

After Access 4 (all ways loaded):
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |3C | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+

Access 6: Miss on 0x5E. Random selection: way 2. Evict way 2.

After Access 6:
        Way 0         Way 1         Way 2         Way 3
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
S 8: | 1 |1A | D | | 1 |2B | D | | 1 |5E | D | | 1 |4D | D |
     +---+---+---+ +---+---+---+ +---+---+---+ +---+---+---+
     (Tag 0x3C evicted from Way 2)

Random replacement does not track access patterns or load order, so it makes no promises about optimality. However, it avoids systematic biases that can cause pathological behavior in certain access patterns. For instance, a program that repeatedly accesses N+1 different blocks that all map to an N-way set will thrash with FIFO but has a chance to hit with random replacement. Random policies are popular in large caches where tracking precise LRU information is too expensive.

Comparing Replacement Policies

Different replacement policies exhibit different strengths and weaknesses. LRU generally provides the best hit rate because it most accurately captures temporal locality. Programs tend to reuse recently accessed data, so evicting the least recently used line is usually a good heuristic. However, LRU struggles with certain pathological patterns like scanning through an array larger than the cache, where every access misses regardless of the replacement policy. The hardware cost of true LRU grows quickly with associativity, making it impractical for highly associative caches.

FIFO is simpler than LRU and works reasonably well when access patterns align with load order. If a program loads several blocks and then proceeds to use them in roughly the same order they were loaded, FIFO approximates LRU. However, FIFO fails when frequently accessed blocks happen to be old. A block loaded early that continues to be accessed will eventually be evicted simply because it is old, even though it is still hot. This makes FIFO less robust than LRU across diverse workloads.

Random replacement is the simplest to implement and surprisingly competitive. While it does not capture locality like LRU, it avoids the worst-case behaviors that can plague deterministic policies. Random replacement performs poorly on workloads with strong, consistent access patterns where LRU shines, but it handles pathological cases and mixed workloads more gracefully. Many large L3 caches use random or pseudo-random replacement because the hardware cost of tracking LRU for 16-way or higher associativity is prohibitive.

In practice, many caches use pseudo-LRU algorithms that approximate true LRU with less hardware. One common approach uses a binary tree of bits to track relative ages without storing exact ordering. For a 4-way set, a 3-bit tree can identify an approximate LRU victim with much simpler update logic than true LRU. These approximations sacrifice some hit rate improvement for significant hardware savings, representing yet another point in the vast space of cache design tradeoffs.

Memory Access Time Through the Cache Hierarchy

Understanding cache performance requires quantifying the time cost of memory accesses. The effective memory access time depends on whether each access hits or misses at each level of the cache hierarchy. When we have a hit at L1, the access completes quickly. When we miss at L1, we must check L2, incurring additional delay. If we miss at L2, we check L3, and so on, until we either hit or reach main memory. The cumulative effect of these hit and miss times determines overall system performance.

Let us establish some terminology and basic formulas. The hit time for a cache level is the time required to access that level and determine whether we have a hit or miss. The miss penalty is the additional time required when we miss at that level, which includes accessing the next level of the hierarchy. The hit rate is the fraction of accesses that hit at a given level. The miss rate is simply one minus the hit rate. Using these definitions, we can calculate the average memory access time.

For a simple single-level cache system with just L1 and main memory, the average memory access time follows a straightforward formula. We either hit in L1 (probability equals hit_rate_L1) and pay only the L1 hit time, or we miss in L1 (probability equals miss_rate_L1) and pay both the L1 hit time (we still had to check L1) and the main memory access time. The formula is:

Single-Level Cache Average Memory Access Time:

AMAT = hit_time_L1 + (miss_rate_L1 × memory_access_time)

Where:
  hit_time_L1 = time to access L1 cache
  miss_rate_L1 = fraction of accesses that miss in L1
  memory_access_time = time to access main memory on L1 miss

Example with realistic values:
  hit_time_L1 = 1 cycle
  miss_rate_L1 = 0.05 (5% miss rate, 95% hit rate)
  memory_access_time = 100 cycles

AMAT = 1 + (0.05 × 100)
     = 1 + 5
     = 6 cycles average per memory access

This example shows why even a small cache with a reasonable hit rate dramatically improves performance. With a 95% hit rate, the average access time is only 6 cycles instead of 100 cycles. The cache effectively hides the memory latency for the vast majority of accesses. However, real systems have multiple cache levels, which complicates the calculation but provides even better performance.

Multi-Level Cache Access Time

In a multi-level cache hierarchy with L1, L2, and L3, the access time calculation becomes recursive. When we miss at L1, we access L2. If we hit at L2, we pay the L1 hit time plus the L2 hit time. If we miss at L2, we must access L3, and so on. The key insight is that each level's miss penalty is the access time for the next level, which itself depends on that level's hit and miss rates.

Let us build this calculation step by step. Consider a system with L1, L2, L3, and main memory. Define the following parameters:

Cache Hierarchy Parameters:

L1: hit_time = 1 cycle,   miss_rate = 0.05 (5%)
L2: hit_time = 10 cycles, miss_rate = 0.20 (20% of L1 misses)
L3: hit_time = 40 cycles, miss_rate = 0.50 (50% of L2 misses)
Memory: access_time = 200 cycles

Note: L2 miss rate is the LOCAL miss rate (misses in L2 divided by
accesses to L2), not the GLOBAL miss rate (misses in L2 divided by
all memory accesses).

First, we calculate the effective access time for L3. When we access L3, we either hit there or miss and go to main memory:

L3 effective access time:
  = L3_hit_time + (L3_miss_rate × memory_access_time)
  = 40 + (0.50 × 200)
  = 40 + 100
  = 140 cycles

Next, we calculate the effective access time for L2. When we access L2, we either hit there or miss and proceed to L3:

L2 effective access time:
  = L2_hit_time + (L2_miss_rate × L3_effective_access_time)
  = 10 + (0.20 × 140)
  = 10 + 28
  = 38 cycles

Finally, we calculate the overall average memory access time. When we access memory, we always check L1 first. We either hit in L1 or miss and proceed to L2:

Overall AMAT:
  = L1_hit_time + (L1_miss_rate × L2_effective_access_time)
  = 1 + (0.05 × 38)
  = 1 + 1.9
  = 2.9 cycles average per memory access

This is remarkable. Despite main memory requiring 200 cycles to access, the average memory access completes in under 3 cycles thanks to the multi-level cache hierarchy. The three cache levels work together to hide the memory latency for nearly all accesses. Let us trace through some specific access scenarios to see how this plays out in practice.

Detailed Access Time Examples

Consider a sequence of memory accesses through our three-level cache hierarchy. We will calculate the actual time cost for each access based on where it hits or misses. This concrete example will illustrate how the average access time emerges from the distribution of hits and misses across the hierarchy.

Access Scenario 1: L1 Hit

Access: Read from address 0x1000
L1: Check cache, tag matches → HIT!
Total time: 1 cycle

The best case: data found immediately in L1.

Access Scenario 2: L1 Miss, L2 Hit

Access: Read from address 0x2000
L1: Check cache, tag doesn't match → MISS (1 cycle)
L2: Check cache, tag matches → HIT! (10 cycles)
Total time: 1 + 10 = 11 cycles

Common case for data recently evicted from L1 but still in L2.

Access Scenario 3: L1 Miss, L2 Miss, L3 Hit

Access: Read from address 0x3000
L1: Check cache, tag doesn't match → MISS (1 cycle)
L2: Check cache, tag doesn't match → MISS (10 cycles)
L3: Check cache, tag matches → HIT! (40 cycles)
Total time: 1 + 10 + 40 = 51 cycles

Less common, but still much faster than going to main memory.

Access Scenario 4: L1 Miss, L2 Miss, L3 Miss, Memory Access

Access: Read from address 0x4000
L1: Check cache, tag doesn't match → MISS (1 cycle)
L2: Check cache, tag doesn't match → MISS (10 cycles)
L3: Check cache, tag doesn't match → MISS (40 cycles)
Memory: Fetch from DRAM (200 cycles)
Total time: 1 + 10 + 40 + 200 = 251 cycles

Worst case: data must be fetched all the way from main memory.
This is why we desperately want high hit rates!

Now let us consider a realistic access sequence and compute the overall average. Suppose we have 1000 memory accesses with the following distribution based on our hit and miss rates:

Distribution of 1000 memory accesses:

L1 hits: 950 accesses (95% of 1000)
  Cost: 950 × 1 = 950 cycles

L1 misses, L2 hits: 40 accesses (80% of the 50 L1 misses)
  Cost: 40 × 11 = 440 cycles

L1 misses, L2 misses, L3 hits: 5 accesses (50% of the 10 L2 misses)
  Cost: 5 × 51 = 255 cycles

L1 misses, L2 misses, L3 misses: 5 accesses (50% of the 10 L2 misses)
  Cost: 5 × 251 = 1255 cycles

Total time for 1000 accesses: 950 + 440 + 255 + 1255 = 2900 cycles
Average time per access: 2900 / 1000 = 2.9 cycles

This matches our calculated average memory access time of 2.9 cycles from the formula. The majority of accesses (950 out of 1000) hit in L1 and complete in just 1 cycle each. The 40 accesses that miss in L1 but hit in L2 add some overhead but remain relatively fast. The rare accesses that miss in both L1 and L2 contribute disproportionately to the total time, but because they are so infrequent, they do not dominate the average.

Impact of Cache Parameters on Performance

The effective memory access time is highly sensitive to cache hit rates. Even small changes in miss rates can significantly impact performance. Let us examine how varying the L1 miss rate affects the overall average memory access time, keeping other parameters constant.

Impact of L1 Miss Rate on AMAT:

L1 miss rate = 0.01 (1%):
  AMAT = 1 + (0.01 × 38) = 1.38 cycles

L1 miss rate = 0.05 (5%):
  AMAT = 1 + (0.05 × 38) = 2.90 cycles

L1 miss rate = 0.10 (10%):
  AMAT = 1 + (0.10 × 38) = 4.80 cycles

L1 miss rate = 0.20 (20%):
  AMAT = 1 + (0.20 × 38) = 8.60 cycles

The difference between a 1% and 20% L1 miss rate is a factor of 6×
in average memory access time! This demonstrates why cache optimization
is critical for performance.

Similarly, the size and associativity of caches affect miss rates and thus performance. A larger cache can hold more data, reducing capacity misses. Higher associativity reduces conflict misses. However, both come at the cost of increased access time and hardware complexity. Consider the tradeoff between cache size and access time:

Tradeoff: Larger L1 Cache vs. Access Time

Configuration A: 32 KB L1, 1-cycle access, 5% miss rate
  AMAT = 1 + (0.05 × 38) = 2.90 cycles

Configuration B: 64 KB L1, 2-cycle access, 3% miss rate
  AMAT = 2 + (0.03 × 38) = 3.14 cycles

Configuration C: 128 KB L1, 3-cycle access, 2% miss rate
  AMAT = 3 + (0.02 × 38) = 3.76 cycles

In this example, doubling the L1 size reduces miss rate but increases
access time. Configuration A (smaller, faster cache) actually provides
better average performance than the larger caches despite higher miss
rates. This illustrates why most processors use small, fast L1 caches.

The interplay between cache levels also matters. If L2 is very large and fast, a higher L1 miss rate becomes more tolerable. Conversely, if L2 is slow or has a high miss rate, L1 performance becomes critical. System designers must consider the entire hierarchy when optimizing performance, balancing the characteristics of each level to achieve the best overall result for the target workload.

Semiconductor RAM Memories: SRAM and DRAM

Understanding caches requires understanding the underlying memory technologies. Random Access Memory comes in two primary forms: Static RAM (SRAM) and Dynamic RAM (DRAM). These technologies differ fundamentally in how they store information, their speed characteristics, their density, and their cost. The choice between SRAM and DRAM for a particular application involves weighing these competing factors.

Static RAM stores each bit using a bistable circuit typically composed of six transistors arranged as cross-coupled inverters. Once written, an SRAM cell maintains its state indefinitely as long as power is applied. No refresh is needed because the cell actively maintains its state through feedback. The six-transistor configuration provides two stable states corresponding to logic 0 and logic 1. Reading from SRAM is non-destructive; the cell retains its value after being read. Writing involves forcing the cell into the desired state by driving the bit lines.

SRAM Cell Structure (6-Transistor):

         VDD
          |
      +---+---+
      |       |
     Q1      Q3
      |       |
      +---+---+
      |       |
    Q +       + Q'  (Cross-coupled inverters)
      |       |
      +---+---+
      |       |
     Q2      Q4
      |       |
      +---+---+
          |
         GND

Word Line (WL) controls Q5 and Q6 (access transistors)
Bit Lines (BL, BL') carry data in/out

Read Operation:
- WL activated, connects cell to bit lines
- Cell drives bit lines to stored value
- Sense amplifier detects voltage difference
- Cell retains value (non-destructive)

Write Operation:
- Bit lines driven to desired value
- WL activated
- Bit lines overpower cell, forcing new state
- WL deactivated, cell holds new value

Dynamic RAM stores each bit as charge on a tiny capacitor. A DRAM cell consists of just one transistor and one capacitor, making it much denser than SRAM. However, the capacitor leaks charge over time, typically losing its state within milliseconds. This requires periodic refresh operations where the memory controller reads each cell and writes the value back, restoring the full charge. Refresh adds complexity and consumes power but enables much higher density.

DRAM Cell Structure (1-Transistor, 1-Capacitor):

Word Line (WL)
     |
    Q1 (Access Transistor)
     |
    ===  C (Storage Capacitor)
     |
    GND

Read Operation:
- Bit line precharged to VDD/2
- WL activated, connects capacitor to bit line
- Charge sharing occurs between C and bit line
- Sense amplifier detects small voltage change
- Cell must be refreshed after read (destructive)

Write Operation:
- Bit line driven high (logic 1) or low (logic 0)
- WL activated
- Capacitor charges or discharges through transistor
- WL deactivated, capacitor holds charge

Refresh Operation (must occur every few milliseconds):
- Each row read and written back sequentially
- Restores full charge on capacitors
- Prevents data loss from leakage

The access time characteristics differ significantly between SRAM and DRAM. SRAM access is straightforward: activate the word line, and the cell immediately drives the bit lines to the stored value. Sense amplifiers detect the voltage, and the read completes in a few nanoseconds. DRAM access is more complex because the charge sharing between the tiny capacitor and the bit line produces only a small voltage swing that must be amplified. Additionally, DRAM reads are destructive, requiring the value to be written back. A DRAM access might take 50 to 100 nanoseconds, roughly ten times slower than SRAM.

The density and cost differences are dramatic. An SRAM cell requires six transistors plus the area for routing word lines and bit lines. A DRAM cell requires one transistor and one capacitor, which can be stacked vertically to minimize area. This means DRAM achieves roughly six times the density of SRAM for the same silicon area. Since silicon area directly determines cost, DRAM costs significantly less per bit than SRAM. A modern DRAM chip might provide 8 gigabits in a package costing a few dollars, while an SRAM chip of similar capacity would be prohibitively expensive.

Technology Comparison:

                 SRAM                DRAM
Cell Size:       6 transistors       1T + 1C (6× smaller)
Access Time:     1-10 ns             50-100 ns
Refresh:         Not required        Required (every 2-64 ms)
Read:            Non-destructive     Destructive
Power:           Higher (always on)  Lower (except refresh)
Cost/bit:        High                Low
Density:         Low                 High (6× better)
Typical Use:     Caches, registers   Main memory

Memory Hierarchy Mapping:
+----------+--------+-------------+
| Level    | Type   | Technology  |
+----------+--------+-------------+
| L1 Cache | SRAM   | 6T cell     |
| L2 Cache | SRAM   | 6T cell     |
| L3 Cache | SRAM   | 6T cell     |
| Main Mem | DRAM   | 1T1C cell   |
+----------+--------+-------------+

Modern DRAM has evolved to improve performance through various techniques. Synchronous DRAM (SDRAM) synchronizes its operations with a clock signal, allowing the memory controller to pipeline requests. Double Data Rate (DDR) SDRAM transfers data on both rising and falling clock edges, doubling throughput. DDR has evolved through multiple generations (DDR2, DDR3, DDR4, DDR5), each improving speed and reducing power consumption. Despite these improvements, DRAM remains fundamentally slower than SRAM due to the physics of capacitive storage and charge sensing.

Read-Only Memories

While RAM provides read-write storage, Read-Only Memory (ROM) and its derivatives serve a different purpose: storing data that must persist without power and, in some cases, cannot or should not be modified during normal operation. ROM technologies range from truly immutable mask-programmed ROM to electrically erasable and reprogrammable Flash memory. Each variant offers different tradeoffs between permanence, programmability, and cost.

Mask-programmed ROM is manufactured with its contents fixed during fabrication. The data pattern determines which connections exist in the memory array, physically encoding the information in the silicon. Once manufactured, the contents cannot be changed. Mask ROM is economical only for very large production volumes because the custom mask costs are amortized over millions of units. Typical applications include storing firmware in consumer electronics where the code never changes and production volumes justify the manufacturing setup costs.

Programmable ROM (PROM) arrives from the factory blank and can be programmed once by the user using a special device called a PROM programmer. Programming involves blowing tiny fuses or creating permanent connections using high voltage or current pulses. Once programmed, a PROM cannot be erased or reprogrammed. PROMs were historically popular for small-volume production or prototyping where mask ROM economics did not apply. Modern usage has largely shifted to erasable alternatives.

ROM Technology Evolution:

Mask ROM:
  [Fabricated] → [Fixed Forever]
  + Low cost at high volume
  + Fast access
  - Cannot change after fabrication
  - High setup cost

PROM (Programmable ROM):
  [Blank] → [Program Once] → [Fixed]
  + User programmable
  + No setup cost
  - Cannot erase/reprogram
  - Requires PROM programmer

EPROM (Erasable Programmable ROM):
  [Blank] → [Program] → [Erase (UV)] → [Program] → ...
  + Reprogrammable (erase with UV light)
  + Retain data for years
  - Slow erase (20-30 min UV exposure)
  - Must remove from circuit to erase
  - Requires quartz window (expensive)

EEPROM (Electrically Erasable PROM):
  [Blank] → [Program] → [Erase (Electrical)] → [Program] → ...
  + Electrically erasable (in-circuit)
  + Byte-level erase
  + Fast erase (milliseconds)
  - Limited erase cycles (~100K-1M)
  - Higher cost per bit

Flash Memory:
  [Blank] → [Program] → [Erase (Block)] → [Program] → ...
  + Electrically erasable
  + High density
  + Low cost per bit
  - Block erase only (not byte-level)
  - Limited erase cycles (~10K-100K)
  + Common in SSDs, USB drives, memory cards

Erasable Programmable ROM (EPROM) can be programmed electrically and erased using ultraviolet light. EPROMs feature a quartz window through which UV light floods the chip during erasure. The UV light provides energy to discharge the floating gates where charge storage represents the programmed state. Erasure takes 20 to 30 minutes of UV exposure and erases the entire chip simultaneously. After erasure, the EPROM can be reprogrammed. EPROMs were workhorses of embedded system development, allowing engineers to iterate on firmware without manufacturing new chips.

Electrically Erasable Programmable ROM (EEPROM) improves on EPROM by enabling electrical erasure without removing the chip from the circuit. EEPROM can erase and reprogram individual bytes, making it suitable for storing configuration data that changes occasionally. The electrical erase mechanism uses quantum tunneling to remove charge from floating gates. EEPROMs typically endure 100,000 to 1 million erase cycles before wearing out. They are commonly used for storing calibration data, serial numbers, and small amounts of persistent configuration in embedded systems.

Flash memory represents the dominant modern non-volatile storage technology. Flash combines the density and cost advantages of DRAM-like cell structures with the non-volatility of EEPROM. Unlike EEPROM, Flash erases in blocks rather than individual bytes, sacrificing some flexibility for improved density and cost. There are two main Flash types: NOR Flash, which provides random access like traditional ROM and is used for code storage, and NAND Flash, which is optimized for sequential access and high density, making it ideal for solid-state drives and memory cards.

Flash Memory Architecture (NAND):

Block Structure:
+------------------+
| Block 0          |  Each block: 64-256 pages
|  Page 0 (4 KB)   |
|  Page 1          |  Erase granularity: Block
|  ...             |  Write granularity: Page
|  Page 127        |  Read granularity: Page
+------------------+
| Block 1          |
|  ...             |
+------------------+
| Block N          |
+------------------+

Operations:
- Read: Any page, ~25 µs
- Write: Entire page, ~200 µs (must be previously erased)
- Erase: Entire block, ~2 ms (sets all bits to 1)

Limitations:
- Must erase before writing
- Erase cycles limited (~10K-100K)
- Wear leveling required to distribute writes
- Error correction needed (bit errors increase with wear)

Memory Module Design and Organization

Main memory systems consist of multiple memory chips organized into modules and arrays to achieve the desired capacity and performance. Memory chips provide only a portion of the total system memory, so multiple chips must be combined. The organization of these chips determines the effective word width, total capacity, and access patterns. Understanding memory module design clarifies how the simple DRAM cells discussed earlier scale to gigabytes of system memory.

A memory chip has a specified organization, typically expressed as the number of words times the number of bits per word. For example, a "512K × 8" chip provides 524,288 addressable locations, each 8 bits wide. To build a memory system with a different word width or larger capacity, we combine multiple chips. If the processor requires 32-bit words but we have 8-bit chips, we use four chips in parallel, each providing one byte of the 32-bit word. Address lines connect to all four chips in parallel, data lines connect to different bytes of the data bus, and all chips are selected simultaneously.

Memory Chip Organization Example:

Single Chip (512K × 8):
        A0-A18 (19 address lines: 2^19 = 512K)
          |||||
    +-------------+
    |   512K×8    |
    |  DRAM Chip  |
    +-------------+
       ||||||||
    D0-D7 (8 data lines)

Building 512K × 32 using four 512K × 8 chips:

    A0-A18 ────┬────┬────┬────┐
               ↓    ↓    ↓    ↓
            +---+ +---+ +---+ +---+
            |512| |512| |512| |512|
            |K×8| |K×8| |K×8| |K×8|
            +---+ +---+ +---+ +---+
              ↓     ↓     ↓     ↓
    D0-D7  D8-D15 D16-23 D24-31
           \_________  _________/
                     \/
              32-bit data word

All chips receive same address
Each chip provides one byte of the 32-bit word
Chip enables all active simultaneously

To increase capacity beyond a single chip's addressing range, we use memory banks with chip select signals. Consider building a 2M × 32 memory system using 512K × 8 chips. We need four chips in parallel for the 32-bit width, and we need four such sets to reach 2M words. The higher-order address bits decode which bank (set of four chips) to activate. Only one bank is active at a time, with the lower address bits selecting the location within that bank.

Building 2M × 32 from 512K × 8 chips (requires 16 chips total):

Address breakdown (21 bits for 2M):
+--------+------------------+
| A19-20 | A0-A18           |
| 2 bits | 19 bits          |
+--------+------------------+
    |          |
    |          └─→ Chip address (512K locations)
    └─→ Bank select (4 banks)

Memory Organization:
                                A0-A18
                                  ↓
    Bank 0: [512K×8] [512K×8] [512K×8] [512K×8]  ← CS0 (A19-20 = 00)
            D0-D7    D8-D15   D16-D23  D24-D31

    Bank 1: [512K×8] [512K×8] [512K×8] [512K×8]  ← CS1 (A19-20 = 01)
            D0-D7    D8-D15   D16-D23  D24-D31

    Bank 2: [512K×8] [512K×8] [512K×8] [512K×8]  ← CS2 (A19-20 = 10)
            D0-D7    D8-D15   D16-D23  D24-D31

    Bank 3: [512K×8] [512K×8] [512K×8] [512K×8]  ← CS3 (A19-20 = 11)
            D0-D7    D8-D15   D16-D23  D24-D31

2-to-4 Decoder:
  A19-A20 → Activates one of CS0, CS1, CS2, CS3
  Only selected bank responds to addresses A0-A18

Modern memory modules like DIMMs (Dual Inline Memory Modules) package multiple chips on a small circuit board. A typical DDR4 DIMM might contain eight or sixteen DRAM chips, each providing a portion of the total data width and capacity. The module includes addressing and control logic, buffering, and standardized connectors. Memory controllers on the motherboard interact with DIMMs through standardized interfaces, abstracting the details of the individual chips.

The internal organization of DRAM chips uses a two-dimensional array structure to minimize the number of address pins required. Instead of providing all address bits simultaneously, DRAM uses row and column multiplexing. The row address is latched first (RAS - Row Address Strobe), selecting one row of the array. Then the column address is latched (CAS - Column Address Strobe), selecting the specific bit or word within that row. This halves the number of address pins needed, reducing package cost and complexity.

DRAM Internal Organization (Example: 4M × 1):

2048 rows × 2048 columns = 4M bits

Step 1: Row Address (A0-A10, 11 bits → 2048 rows)
         ┌───────────────────────────┐
         │   Row                      │
         │  Decoder                   │
         └────┬──────────────────────┘
              ├─ Row 0 ─→ [2048 columns]
              ├─ Row 1 ─→ [2048 columns]
              ├─ Row 2 ─→ [2048 columns]
              │   ...
              └─ Row 2047 → [2048 columns]

Step 2: Column Address (A0-A10, 11 bits → 2048 columns)
         Selected row → Column Mux → Data Out

Timing Diagram:
         ___                    ___
RAS:  __|   |__________________|   |__
              ___            ___
CAS:  _______|   |__________|   |_____

Address: [Row Addr][Col Addr]
              ↓        ↓
            Latch    Latch

Total pins: 11 address (multiplexed) vs. 22 (non-multiplexed)

Memory Interleaving

Memory interleaving is a technique to increase memory bandwidth by distributing consecutive addresses across multiple memory modules or banks that can operate concurrently. While a single memory module may have a significant access latency, multiple modules can be accessed in a pipelined fashion, dramatically increasing throughput. Interleaving exploits the spatial locality of memory accesses: programs often access consecutive or nearby memory locations, allowing multiple concurrent accesses to proceed simultaneously.

The fundamental idea behind interleaving is simple. Instead of placing consecutive addresses in the same memory bank, we distribute them across multiple banks. When the processor issues a burst of sequential memory requests, each request goes to a different bank. While one bank is busy accessing its data, other banks can begin processing their requests. By the time the first bank completes its access, we can start another request to it, creating a pipeline of memory operations. The effective bandwidth approaches the number of banks multiplied by the bandwidth of a single bank.

Consider a memory system without interleaving where all addresses reside in a single bank. If each memory access requires 100 nanoseconds, the system can complete at most 10 million accesses per second regardless of how many requests are pending. Now consider a system with four interleaved banks. The first access goes to bank 0 and requires 100 ns. However, we can start the second access (to bank 1) immediately, the third access (to bank 2) 25 ns later, and the fourth access (to bank 3) another 25 ns later. After 100 ns, the first access completes and we can issue another access to bank 0. The effective access time becomes 25 ns per access instead of 100 ns, quadrupling the bandwidth.

Memory Access Timing Without Interleaving (Single Bank):

Time:     0      100     200     300     400  (nanoseconds)
          |       |       |       |       |
Bank 0: [Acc 0][Acc 1][Acc 2][Acc 3]

Each access: 100 ns
Throughput: 1 access / 100 ns = 10M accesses/sec


Memory Access Timing With 4-Way Interleaving:

Time:     0   25  50  75  100 125 150 175 200  (nanoseconds)
          |   |   |   |   |   |   |   |   |
Bank 0: [Acc 0  ][Acc 4  ]...
Bank 1:     [Acc 1  ][Acc 5  ]...
Bank 2:         [Acc 2  ][Acc 6  ]...
Bank 3:             [Acc 3  ][Acc 7  ]...

Each access: 100 ns (same latency)
But one completes every 25 ns (pipelined)
Throughput: 1 access / 25 ns = 40M accesses/sec (4× improvement)

There are two primary interleaving schemes: low-order interleaving and high-order interleaving. Low-order interleaving uses the lowest address bits to select the bank, distributing consecutive addresses across banks. High-order interleaving uses the highest address bits to select the bank, keeping consecutive addresses in the same bank. The choice between these schemes depends on the access patterns of the workload.

Low-order interleaving maximizes bandwidth for sequential access patterns. When a program reads an array or executes consecutive instructions, each access goes to a different bank automatically. This is the most common interleaving scheme because sequential access is prevalent in typical programs. The bank select bits are the lowest bits of the address that are not used for byte selection within a word. For a system with four banks and 4-byte words, bits [3:2] of the address select the bank, ensuring that consecutive words go to different banks.

Low-Order Interleaving (4 banks, 4-byte words):

Address breakdown:
+------------------+------+----+
| Higher bits      | Bank | BO |
| (word in bank)   | [3:2]| [1:0] |
+------------------+------+----+
                      ↓
                   Selects bank

Address Distribution:
Address    Bank    Word within Bank
0x0000  →  Bank 0  Word 0
0x0004  →  Bank 1  Word 0
0x0008  →  Bank 2  Word 0
0x000C  →  Bank 3  Word 0
0x0010  →  Bank 0  Word 1
0x0014  →  Bank 1  Word 1
0x0018  →  Bank 2  Word 1
0x001C  →  Bank 3  Word 1

Sequential access pattern:
  0x0000, 0x0004, 0x0008, 0x000C, 0x0010, ...
   Bank0   Bank1   Bank2   Bank3   Bank0   ...

Perfect distribution → Maximum bandwidth for sequential access

High-order interleaving uses the highest address bits to select the bank, grouping consecutive addresses together. This scheme benefits workloads that access large contiguous blocks from one area of memory before moving to another area. However, for sequential access across the entire address space, high-order interleaving provides no concurrency benefit because all consecutive accesses go to the same bank until that bank's address range is exhausted.

High-Order Interleaving (4 banks, 1 MB per bank, 4 MB total):

Address breakdown (assuming 22-bit addresses for 4 MB):
+------+------------------+----+
| Bank |  Address in Bank | BO |
|[21:20]| [19:2]           |[1:0] |
+------+------------------+----+
   ↓
Selects bank

Address Distribution:
0x000000 - 0x0FFFFC  →  Bank 0 (1 MB)
0x100000 - 0x1FFFFC  →  Bank 1 (1 MB)
0x200000 - 0x2FFFFC  →  Bank 2 (1 MB)
0x300000 - 0x3FFFFC  →  Bank 3 (1 MB)

Sequential access within Bank 0:
  0x000000, 0x000004, 0x000008, ...
   Bank0     Bank0     Bank0     ...

No interleaving benefit → Sequential bottleneck

But accessing four separate regions concurrently works well:
  Thread 1: Bank 0 (0x000000-0x0FFFFC)
  Thread 2: Bank 1 (0x100000-0x1FFFFC)
  Thread 3: Bank 2 (0x200000-0x2FFFFC)
  Thread 4: Bank 3 (0x300000-0x3FFFFC)

Interleaving introduces dependencies between banks that can cause conflicts. If two consecutive accesses target the same bank, the second access must wait for the first to complete before beginning. This occurs naturally with low-order interleaving when the stride of memory accesses equals a multiple of the number of banks. For example, in a 4-bank system with low-order interleaving, accessing every fourth word (stride 4) causes all accesses to hit the same bank, eliminating the interleaving benefit.

Bank Conflicts in Low-Order Interleaving:

4-bank system, 4-byte words, stride-4 access pattern:

Access addresses: 0x0000, 0x0010, 0x0020, 0x0030, ...
                   ↓       ↓       ↓       ↓
Bank bits [3:2]:   00      00      00      00
                   ↓       ↓       ↓       ↓
All hit Bank 0:  [Acc 0][Acc 1][Acc 2][Acc 3]

No concurrency! Same performance as non-interleaved memory.

This happens when: stride (in words) = k × number_of_banks
For this example: stride = 4 words, banks = 4, k = 1

Solution: Use prime number of banks or carefully choose stride

Modern memory systems often use more sophisticated interleaving schemes. DRAM modules themselves internally interleave across multiple chips on the module. Memory controllers may support multiple channels, each channel effectively acting as an independent interleaved bank. Processors with multiple memory controllers can interleave across controllers. These nested levels of interleaving provide massive aggregate bandwidth, which is essential for feeding the data-hungry cores of modern processors.

Virtual Memory: Abstraction and Protection

Virtual memory is one of the most important abstractions in computer architecture, providing each program with the illusion of a large, private address space while efficiently sharing the physical memory among multiple programs. Virtual memory decouples the addresses that programs use (virtual addresses) from the actual locations in physical memory (physical addresses). This abstraction enables powerful operating system features: memory protection between processes, efficient sharing of memory, simplified memory allocation, and the ability to run programs larger than physical memory by storing portions on disk.

The fundamental concept is address translation. When a program accesses memory using a virtual address, the hardware translates that address to a physical address where the data actually resides. This translation is transparent to the program; the program believes it is directly accessing memory at the virtual address. The translation mechanism checks permissions and can trigger page faults if the requested data is not currently in physical memory, allowing the operating system to load the data from disk and retry the access.

Virtual memory divides the address space into fixed-size blocks called pages. Typical page sizes are 4 KB, though larger pages (2 MB, 1 GB) are also common for specific applications. The virtual address space consists of virtual pages, numbered from 0 to the maximum virtual page number. Physical memory consists of page frames, which are physical page-sized blocks numbered from 0 to the maximum physical page number. The page table, maintained by the operating system, maps virtual page numbers to physical page frame numbers.

Virtual Memory Concepts:

Virtual Address Space (per process):
+------------------+  Virtual Page 0
|    4 KB          |
+------------------+  Virtual Page 1
|    4 KB          |
+------------------+  Virtual Page 2
|    4 KB          |
+------------------+
|    ...           |
+------------------+  Virtual Page N
|    4 KB          |
+------------------+

Physical Memory (shared):
+------------------+  Physical Frame 0
|    4 KB          |
+------------------+  Physical Frame 1
|    4 KB          |
+------------------+  Physical Frame 2
|    4 KB          |
+------------------+
|    ...           |
+------------------+  Physical Frame M
|    4 KB          |
+------------------+

Note: Virtual pages >> Physical frames
      Many virtual pages may not be in physical memory (stored on disk)

The address translation process begins with splitting the virtual address into two parts: the virtual page number (VPN) and the page offset. For a 4 KB page, the offset requires 12 bits (2^12 = 4096 bytes per page), so the lower 12 bits of the address form the offset. The remaining upper bits form the virtual page number. The page table is indexed by the VPN to retrieve the physical page number (PPN), also called the physical frame number (PFN). The physical address is then constructed by concatenating the PPN with the unchanged page offset.

Virtual to Physical Address Translation:

Virtual Address (32-bit, 4 KB pages):
+--------------------+------------------+
| Virtual Page Number|  Page Offset    |
|     (VPN)          |      (PO)       |
|    20 bits         |    12 bits      |
+--------------------+------------------+
31                  12 11              0

                      ↓
              Look up in Page Table
                      ↓
               +-------------+
               | Page Table  |
               | VPN → PPN   |
               +-------------+
                      ↓
        Physical Page Number (PPN)
                      ↓

Physical Address:
+--------------------+------------------+
| Physical Page Number|  Page Offset   |
|      (PPN)          |      (PO)      |
|  variable bits      |    12 bits     |
+--------------------+------------------+

Note: Page offset is NOT translated (direct copy from virtual to physical)
      Only the page number is translated via the page table

Let us trace a concrete example of address translation. Assume a system with 32-bit virtual addresses, 30-bit physical addresses, and 4 KB pages. The page offset requires 12 bits, leaving 20 bits for the VPN and 18 bits for the PPN. Consider virtual address 0x00403A04. In binary, this is 00000000010000000011101000000100. The VPN is the upper 20 bits: 0x00403 (decimal 1027). The offset is the lower 12 bits: 0xA04 (decimal 2564).

Address Translation Example:

Virtual Address: 0x00403A04
Binary: 0000 0000 0100 0000 0011 1010 0000 0100

Split into VPN and Offset:
+-------------------------+--------------+
|         VPN             |    Offset    |
| 0000 0000 0100 0000 0011| 1010 0000 0100|
|      0x00403            |    0xA04     |
|    (decimal 1027)       | (decimal 2564)|
+-------------------------+--------------+

Look up VPN 1027 in page table:
Page Table[1027] = 0x2C3A8  (PPN = decimal 180,136)

Construct Physical Address:
+-------------------------+--------------+
|         PPN             |    Offset    |
|  ...10 1100 0011 1010 1000| 1010 0000 0100|
+-------------------------+--------------+
         (0x2C3A8)               (0xA04)

Physical Address: 0x2C3A8A04

Verification:
Virtual:  Page 1027, byte 2564 within page
Physical: Frame 180136, byte 2564 within frame
Offset unchanged ✓

Each page table entry contains more than just the physical page number. Control bits specify whether the page is valid (present in physical memory), whether it has been modified (dirty bit), whether it has been accessed recently (reference bit), and what permissions apply (read, write, execute). When a program tries to access a page that is not valid, a page fault exception occurs. The operating system's page fault handler then decides what to do: perhaps the page must be loaded from disk, or perhaps the access is illegal and the program should be terminated.

Page Table Entry Structure:

Typical PTE format (assuming 32-bit PTE for clarity):
+-----+---+---+---+---+---+-----------------------+
|  V  | D | R | W | X | OS|    Physical Page#     |
+-----+---+---+---+---+---+-----------------------+
 31   30  29  28  27  26  25                      0

V = Valid (1 = page present in memory, 0 = page fault)
D = Dirty (1 = page modified since loaded)
R = Referenced (1 = page accessed recently)
W = Writable (1 = writes allowed, 0 = read-only)
X = Executable (1 = can execute code from this page)
OS = Operating system bits (various uses)
Physical Page# = Physical frame number when V=1

Example PTEs:

Valid, clean, read-write page:
+---+---+---+---+---+---+-----------+
| 1 | 0 | 1 | 1 | 0 | 00| 0x01234   |
+---+---+---+---+---+---+-----------+
Maps to physical frame 0x01234, read-write, not dirty

Invalid page (on disk or never allocated):
+---+---+---+---+---+---+-----------+
| 0 | x | x | x | x | xx| xDisk Loc |
+---+---+---+---+---+---+-----------+
Access → Page Fault → OS loads from disk

Paging and Page Tables in Detail

Page tables can become very large. A 32-bit address space with 4 KB pages requires 2^20 page table entries (1,048,576 entries). If each PTE is 4 bytes, the page table consumes 4 MB of memory per process. On a 64-bit system with 4 KB pages, a single-level page table would require 2^52 entries (assuming 64-bit virtual addresses with 12-bit offset), which is completely impractical. Several techniques address this problem: multi-level page tables, inverted page tables, and Translation Lookaside Buffers (TLBs).

Multi-level page tables solve the space problem by organizing the page table hierarchically. Instead of one large flat array, we create a tree of smaller page tables. For a two-level scheme, the virtual page number is split into two parts: a page directory index and a page table index. The page directory is a single page containing pointers to second-level page tables. Each second-level page table contains the actual PTEs mapping to physical frames. Crucially, second-level page tables are allocated only for regions of the virtual address space actually in use.

Two-Level Page Table:

Virtual Address (32-bit, 4 KB pages):
+-----------+-----------+--------------+
|   Dir     |   Table   |    Offset    |
|  Index    |   Index   |              |
|  10 bits  |  10 bits  |   12 bits    |
+-----------+-----------+--------------+
31        22 21        12 11           0

Page Directory (1 page = 4 KB = 1024 PTEs):
+-----+
|PTE 0|  → Page Table 0 (if allocated)
+-----+
|PTE 1|  → Page Table 1 (if allocated)
+-----+
| ... |
+-----+
|1023 |  → Page Table 1023 (if allocated)
+-----+

Each Page Table (1 page = 4 KB = 1024 PTEs):
+-----+
|PTE 0|  → Physical Frame
+-----+
|PTE 1|  → Physical Frame
+-----+
| ... |
+-----+
|1023 |  → Physical Frame
+-----+

Address Translation Steps:
1. Extract Dir Index from VA
2. Read Page Directory[Dir Index] → get Page Table address
3. If Page Table not present → Page Fault
4. Extract Table Index from VA
5. Read Page Table[Table Index] → get PPN
6. If PTE invalid → Page Fault
7. Combine PPN with Offset → Physical Address

Let us trace an address translation through a two-level page table. Consider virtual address 0x003FF004 with the two-level structure described above. The directory index is bits [31:22]: 0x000 (decimal 0). The table index is bits [21:12]: 0x3FF (decimal 1023). The offset is bits [11:0]: 0x004. We first read the page directory at index 0, which gives us the address of page table 0. Then we read page table 0 at index 1023, which gives us the PPN. Finally, we concatenate the PPN with the offset.

Two-Level Translation Example:

Virtual Address: 0x003FF004
Binary: 00 0000 0000 | 11 1111 1111 | 0000 0000 0100

Parse address:
Dir Index  = bits [31:22] = 0x000 (0)
Table Index = bits [21:12] = 0x3FF (1023)
Offset      = bits [11:0]  = 0x004 (4)

Step 1: Access Page Directory
  Page Directory base = 0x10000000 (from CPU register)
  PDE address = 0x10000000 + (Dir Index × 4)
              = 0x10000000 + 0 = 0x10000000
  Read PDE[0] → 0x20000001 (V=1, Page Table at 0x20000000)

Step 2: Access Page Table
  Page Table base = 0x20000000 (from PDE)
  PTE address = 0x20000000 + (Table Index × 4)
              = 0x20000000 + (1023 × 4)
              = 0x20000000 + 4092 = 0x20000FFC
  Read PTE[1023] → 0xABCDE001 (V=1, PPN=0xABCDE)

Step 3: Construct Physical Address
  Physical Address = (PPN << 12) | Offset
                   = (0xABCDE << 12) | 0x004
                   = 0xABCDE004

Result: VA 0x003FF004 → PA 0xABCDE004

Memory Accesses Required: 3 total
  1. Page Directory Entry
  2. Page Table Entry
  3. Actual Data

Modern 64-bit systems use three, four, or even five levels of page tables to manage the vast virtual address space without consuming excessive memory. Each level adds another memory access to the translation process, but caching the translation in a TLB (discussed next) mitigates this overhead. The key advantage of multi-level tables is that huge portions of the virtual address space do not require any page table memory because the corresponding upper-level entries can simply be marked invalid.

The Translation Lookaside Buffer (TLB) is a small, fast cache dedicated to storing recent address translations. The TLB sits between the processor and the main page table in memory. When a memory access occurs, the TLB is checked first. If the translation is found (TLB hit), the physical address is available immediately without accessing the page table in memory. If the translation is not found (TLB miss), the page table walk occurs, and the resulting translation is inserted into the TLB for future use.

TLB Structure and Operation:

TLB (Fully or Set-Associative, ~64-512 entries):
+--------+--------+-------+-------+
|  VPN   |  PPN   |  V  D |R  W  X|
+--------+--------+-------+-------+
| 0x00403| 0x2C3A8|  1  0 |1  1  0|
+--------+--------+-------+-------+
| 0x00C00| 0x15678|  1  1 |1  1  1|
+--------+--------+-------+-------+
|  ...   |  ...   | ...   |  ...  |
+--------+--------+-------+-------+

Memory Access with TLB:

Virtual Address
      ↓
  +-------+
  |  TLB  |
  +-------+
      ↓
  Hit?
   / \
 Yes   No (TLB Miss)
  ↓     ↓
  |   Page Table Walk
  |   (1, 2, or more memory accesses)
  |     ↓
  |   Insert into TLB
  |     ↓
  └─────┘
      ↓
Physical Address

TLB Hit: 0 extra memory accesses (< 1 cycle)
TLB Miss: 1-4 extra memory accesses (10-40 cycles)

Typical TLB hit rates: 95-99%
Effective address translation overhead ≈ 1-2 cycles

TLB reach refers to the amount of memory that can be referenced without a TLB miss, calculated as the number of TLB entries multiplied by the page size. A TLB with 128 entries and 4 KB pages has a reach of 512 KB. If a program's working set exceeds the TLB reach, frequent TLB misses will occur, degrading performance. Using larger pages increases TLB reach; a 2 MB page size increases the reach to 256 MB with the same 128 entries. Many systems support multiple page sizes simultaneously to optimize TLB reach for different access patterns.

TLB Reach Calculation:

Configuration 1: 128 entries, 4 KB pages
  TLB reach = 128 × 4 KB = 512 KB

Configuration 2: 128 entries, 2 MB pages
  TLB reach = 128 × 2 MB = 256 MB

Impact on performance:
  Working set = 100 KB  → Both configs: ~100% hit rate
  Working set = 1 MB    → Config 1: ~50% hit rate
                        → Config 2: ~100% hit rate
  Working set = 512 MB  → Config 1: ~0.1% hit rate
                        → Config 2: ~50% hit rate

Virtual Memory Performance Considerations

Virtual memory performance depends on several factors: the TLB hit rate, the number of page table levels, whether pages are in memory or on disk, and the frequency of page faults. When operating in the common case with high TLB hit rates and all pages in memory, virtual memory overhead is minimal. However, pathological cases with frequent TLB misses or page faults can cripple performance.

The effective memory access time with virtual memory builds on our earlier cache analysis but adds the overhead of address translation. For a TLB hit, translation is nearly free (less than one cycle). For a TLB miss, we must walk the page table, requiring one memory access per level of the page table hierarchy. If the page table entries are themselves cached, these accesses may be fast, but a complete miss to main memory is expensive.

Effective Access Time with Virtual Memory:

Assumptions:
  TLB hit rate: 98%
  TLB hit time: 0.5 cycles (negligible)
  Page table levels: 2
  Page table in cache: 90% hit rate
  Cache hit time: 3 cycles
  Memory access time: 100 cycles
  All pages in physical memory (no disk access)

TLB Hit Path (98% of accesses):
  Translation: 0.5 cycles
  Data access: AMAT from cache hierarchy (assume 3 cycles)
  Total: 3.5 cycles

TLB Miss Path (2% of accesses):
  Translation: Walk 2-level page table
    Level 1: 0.9 × 3 + 0.1 × 100 = 12.7 cycles
    Level 2: 0.9 × 3 + 0.1 × 100 = 12.7 cycles
    Total translation: 25.4 cycles
  Data access: 3 cycles
  Total: 28.4 cycles

Effective Access Time:
  EAT = 0.98 × 3.5 + 0.02 × 28.4
      = 3.43 + 0.568
      = 3.998 ≈ 4 cycles

With high TLB hit rate, overhead is modest (~14% increase over cache alone)

Page faults introduce far more severe overhead. When a page fault occurs, the operating system must locate the page on disk, select a victim page to evict from physical memory (if memory is full), write the victim page to disk if it is dirty, read the required page from disk, and update page tables. Disk access times are measured in milliseconds, corresponding to millions of processor cycles. A single page fault can cost as much as a million normal memory accesses.

Page Fault Overhead:

Disk access time: 10 milliseconds (typical SSD)
Processor cycle time: 0.5 nanoseconds (2 GHz CPU)
Page fault cost: 10 ms / 0.5 ns = 20,000,000 cycles

Normal memory access: ~200 cycles (cache miss to DRAM)
Page fault cost: ~100,000× normal access

If page fault rate = 0.01% (1 fault per 10,000 accesses):
  EAT = 9,999 × 200 + 1 × 20,000,000
      = 1,999,800 + 20,000,000
      = 21,999,800 cycles / 10,000 accesses
      = 2,200 cycles per access
  (11× slowdown from 0.01% fault rate!)

This demonstrates why page fault rates must be kept extremely low
Target: < 0.0001% (< 1 fault per million accesses)

The working set model provides insight into paging performance. A program's working set is the collection of pages it accesses within a time window. If physical memory can hold the working set, page faults occur only when transitioning between phases of execution. If physical memory is smaller than the working set, thrashing occurs: the system constantly pages data in and out, spending more time on page faults than useful work. Operating systems attempt to allocate enough physical memory per process to contain its working set.

Demand paging, the most common virtual memory strategy, loads pages only when they are accessed, not in advance. When a process starts, none of its pages are in memory. As the program executes and touches pages, page faults bring them in. This lazy approach avoids loading pages that may never be used. Prepaging attempts to predict which pages will be needed and load them before they are accessed, reducing fault rates but risking wasted effort if predictions are wrong.

Bringing It All Together

The memory system of a modern computer is a marvel of engineering, spanning multiple technologies and abstraction layers that work in concert to provide the illusion of fast, large, and cheap memory. From the six-transistor SRAM cells in caches to the single-transistor DRAM cells in main memory, from the persistent storage of Flash to the protection mechanisms of virtual memory, each component serves a specific purpose in the hierarchy. Understanding how these pieces fit together is essential for comprehending computer architecture and writing efficient software.

At the foundation lie the semiconductor memory technologies. SRAM provides the speed necessary for caches, with its six-transistor cells maintaining state through active feedback, enabling access times of a few nanoseconds. DRAM trades speed for density, using single-transistor capacitive storage that requires periodic refresh but enables gigabytes of capacity at reasonable cost. Read-only memories from mask ROM through Flash provide persistent storage with varying degrees of programmability and performance. Each technology occupies its niche in the hierarchy based on its speed, density, cost, and volatility characteristics.

Memory organization transforms individual chips into functional systems. Chips combine in parallel to provide the required word width and in series to provide the required capacity. Bank selection and chip enables route addresses to the appropriate devices. Memory modules like DIMMs package these components into standardized, replaceable units. Inside DRAM chips, row and column multiplexing reduces pin count while organizing storage as two-dimensional arrays. These organizational details determine how the theoretical capabilities of memory technologies translate into practical system performance.

Caching bridges the processor-memory speed gap through careful exploitation of locality. The cache hierarchy with L1, L2, and L3 levels provides progressively larger but slower storage, with each level catching accesses that miss at the level above. Cache organization into lines, sets, and ways determines how addresses map to storage locations. Direct-mapped caches offer simplicity at the cost of conflicts. Set-associative caches provide flexibility with moderate hardware complexity. Fully-associative caches eliminate conflict misses but require expensive parallel tag comparison. Address breakdown into tag, index, and offset fields enables efficient lookup and data retrieval.

Replacement policies become critical when all available cache locations are occupied. LRU provides excellent performance by tracking access recency but requires complex hardware for high associativity. FIFO simplifies implementation by tracking only load order but fails to adapt to access patterns. Random replacement provides robustness with minimal hardware. Pseudo-LRU algorithms approximate true LRU with reduced cost. The choice of replacement policy reflects the tradeoff between hit rate optimization and implementation complexity.

Performance analysis quantifies the value of caching. Average memory access time calculations combine hit times, miss rates, and miss penalties across cache levels. A well-designed cache hierarchy reduces effective access time from hundreds of cycles to just a few cycles. Small changes in miss rates can dramatically impact overall performance, making cache optimization crucial. The interaction between cache parameters like size, associativity, block size, and replacement policy determines the hit rate for a given workload.

Memory interleaving increases bandwidth by distributing consecutive addresses across multiple banks that operate concurrently. Low-order interleaving spreads sequential accesses across banks automatically, maximizing throughput for common access patterns. High-order interleaving groups consecutive addresses together, benefiting workloads that access large contiguous blocks. The choice of interleaving scheme depends on expected access patterns and must consider bank conflicts when stride equals multiples of the bank count.

Virtual memory provides the abstraction that makes modern operating systems possible. Each process receives a private virtual address space that is mapped to physical memory through page tables. Address translation via the MMU converts virtual addresses to physical addresses transparently. Page table entries contain not just physical frame numbers but also protection bits and status flags. Multi-level page tables solve the size problem by allocating intermediate tables only for used regions of the virtual address space.

The Translation Lookaside Buffer caches recent address translations, eliminating the overhead of page table walks for most memory accesses. TLB reach, determined by the number of entries and page size, defines how much memory can be referenced without misses. High TLB hit rates keep virtual memory overhead low, while TLB misses trigger multi-level page table walks. Page faults when accessing non-resident pages involve disk access and cost millions of cycles, making page fault rates critical to system performance.

Every component of the memory hierarchy involves fundamental tradeoffs. SRAM versus DRAM trades speed for density. Cache size versus access time trades capacity for latency. Associativity versus complexity trades flexibility for implementation cost. Page size versus table size trades TLB reach for internal fragmentation. These engineering decisions shape the performance characteristics of every modern computer system.

The journey from understanding what caches are to analyzing virtual memory performance reveals the elegance and complexity of memory system design. Whether you are optimizing a tight inner loop to maximize cache hits, configuring page sizes for large scientific applications, debugging a performance problem caused by TLB thrashing, or designing the next generation of processors, deep knowledge of the entire memory hierarchy is essential. As processors continue to grow faster while memory speeds lag behind, the memory system will remain the critical bottleneck and the site of ongoing innovation in computer architecture.

Welcome to the most comprehensive Spring Boot guide you'll find! This isn't just another tutorial that skims the surface. We're going to dive deep into every concept, explain every annotation, walk through every line of code, and understand the "why" behind the "how."

By the end of this guide, you'll understand:

• The revolutionary changes Spring Boot brought to Java development

• How auto-configuration works under the hood

• The complete bean lifecycle from creation to destruction

• How to build production-grade REST APIs

• How to implement JWT authentication from scratch

• How to handle exceptions like a pro

• And much, much more!

Understanding Spring Framework

What is Spring? - A Historical Perspective

Back in the early 2000s, Java Enterprise Edition (J2EE) was the standard for building enterprise applications. However, it was notoriously complex, required extensive XML configuration, and forced developers to write tons of boilerplate code.

In 2003, Rod Johnson published his book "Expert One-on-One J2EE Design and Development" which included code for what would become Spring Framework. The framework emerged as a breath of fresh air, offering a simpler, more elegant approach to enterprise Java development.

At its core, Spring is an Inversion of Control (IoC) container - but what does that really mean?

Core Concepts - Understanding IoC and DI

Inversion of Control (IoC) - The Big Picture

Traditional programming follows this pattern:

1. Your class needs a dependency

2. Your class creates that dependency using new

3. Your class manages the dependency's lifecycle

// Traditional approach - YOU control everything
public class OrderService {
    private EmailService emailService;
    private PaymentService paymentService;
    private InventoryService inventoryService;

    // You create the dependencies
    public OrderService() {
        this.emailService = new EmailService();
        this.paymentService = new PaymentService();
        this.inventoryService = new InventoryService();
    }

    public void createOrder(Order order) {
        // Process order...
        emailService.sendConfirmation(order);
        paymentService.processPayment(order);
        inventoryService.updateStock(order);
    }
}

Problems with this approach:

1. Tight Coupling: OrderService is tightly coupled to specific implementations of EmailService, PaymentService, etc.

2. Hard to Test: You can't easily mock dependencies for unit testing

3. Inflexible: Changing implementations requires changing OrderService code

4. Resource Management: You're responsible for managing object lifecycle

IoC inverts this control - instead of YOU creating and managing dependencies, the Spring container does it for you:

// Spring approach - SPRING controls object creation
public class OrderService {
    // These dependencies will be provided BY SPRING
    private final EmailService emailService;
    private final PaymentService paymentService;
    private final InventoryService inventoryService;

    // Spring will call this constructor and provide the dependencies
    public OrderService(EmailService emailService,
                       PaymentService paymentService,
                       InventoryService inventoryService) {
        this.emailService = emailService;
        this.paymentService = paymentService;
        this.inventoryService = inventoryService;
    }

    public void createOrder(Order order) {
        // Same logic, but dependencies are managed by Spring
        emailService.sendConfirmation(order);
        paymentService.processPayment(order);
        inventoryService.updateStock(order);
    }
}

Benefits of IoC:

1. Loose Coupling: OrderService doesn't know or care about concrete implementations

2. Easy Testing: You can pass mock objects in tests

3. Flexible: Change implementations without touching OrderService

4. Centralized Configuration: Spring manages all object lifecycles

Dependency Injection (DI) - The How of IoC

Dependency Injection is the pattern/technique used to achieve IoC. There are three main types:

1. Constructor Injection (Recommended)

@Service  // Tells Spring this is a service bean
public class UserService {
    // Mark fields as final for immutability
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    // Spring will automatically call this constructor
    // and inject the required dependencies
    public UserService(UserRepository userRepository,
                      PasswordEncoder passwordEncoder) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
    }
}

Why constructor injection is best:

• Fields can be final (immutable)

• Dependencies are required (constructor won't compile without them)

• Easy to test (just call constructor with mocks)

• Prevents circular dependencies

• Clear at compile-time what dependencies exist

2. Setter Injection (For Optional Dependencies)

@Service
public class NotificationService {
    private EmailService emailService;  // Optional
    private SmsService smsService;      // Optional

    // Spring will call these setters if beans are available
    @Autowired(required = false)
    public void setEmailService(EmailService emailService) {
        this.emailService = emailService;
    }

    @Autowired(required = false)
    public void setSmsService(SmsService smsService) {
        this.smsService = smsService;
    }

    public void sendNotification(String message) {
        // Use whichever services are available
        if (emailService != null) {
            emailService.send(message);
        }
        if (smsService != null) {
            smsService.send(message);
        }
    }
}

3. Field Injection (Not Recommended - Included for Completeness)

@Service
public class ProductService {
    @Autowired  // Spring injects directly into the field
    private ProductRepository productRepository;

    // No constructor needed, but this is BAD PRACTICE
    // - Can't make fields final
    // - Hard to test (need Spring context)
    // - Hidden dependencies
}

The "Spring Problem" - Why Spring Boot Was Needed

Traditional Spring (pre-Boot) required extensive XML configuration. Let's see what configuring a simple database connection looked like:

<!-- applicationContext.xml - The old nightmare -->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <!-- Step 1: Configure the database connection pool -->
    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
        <property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
        <property name="username" value="root"/>
        <property name="password" value="password"/>
        <property name="initialSize" value="5"/>
        <property name="maxActive" value="10"/>
    </bean>

    <!-- Step 2: Configure JPA/Hibernate -->
    <bean id="sessionFactory"
          class="org.springframework.orm.hibernate4.LocalSessionFactoryBean">
        <property name="dataSource" ref="dataSource"/>
        <property name="packagesToScan" value="com.example.model"/>
        <property name="hibernateProperties">
            <props>
                <prop key="hibernate.dialect">org.hibernate.dialect.MySQL5Dialect</prop>
                <prop key="hibernate.show_sql">true</prop>
                <prop key="hibernate.hbm2ddl.auto">update</prop>
            </props>
        </property>
    </bean>

    <!-- Step 3: Configure transaction manager -->
    <bean id="transactionManager"
          class="org.springframework.orm.hibernate4.HibernateTransactionManager">
        <property name="sessionFactory" ref="sessionFactory"/>
    </bean>

    <!-- Step 4: Enable transaction annotations -->
    <tx:annotation-driven transaction-manager="transactionManager"/>

    <!-- Step 5: Configure component scanning -->
    <context:component-scan base-package="com.example"/>

    <!-- ... hundreds more lines for other beans -->
</beans>

Additionally, you needed:

• web.xml for servlet configuration

• Multiple property files

• Manual dependency version management

• Complex deployment descriptors

This led to:

• Configuration Bloat: More XML than actual code

• Difficult Maintenance: Changes required editing multiple XML files

• Steep Learning Curve: New developers spent weeks just understanding configuration

• Boilerplate Everywhere: Same configuration repeated across projects

• Version Conflicts: Managing compatible dependency versions was a nightmare

Why Spring Boot is Revolutionary

Spring Boot, released in April 2014, fundamentally changed how we build Spring applications. The key principle: Convention over Configuration.

The Three Pillars of Spring Boot

1. Auto-Configuration - The Magic

Spring Boot automatically configures your application based on:

• JARs present in your classpath

• Existing beans you've defined

• Properties you've configured

Example: The Simplest Spring Boot Application

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication  // This ONE annotation does it all!
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Let's break down what @SpringBootApplication does:

// @SpringBootApplication is actually a meta-annotation combining three annotations:

@SpringBootConfiguration  // 1. Marks this as a configuration class
@EnableAutoConfiguration  // 2. Enables Spring Boot's auto-configuration
@ComponentScan           // 3. Scans for components in this package and sub-packages
public class DemoApplication {
    // Application entry point
}

Detailed explanation of each component:

1. @SpringBootConfiguration

• Extends Spring's @Configuration annotation

• Indicates that this class contains Spring bean definitions

• Allows you to define @Bean methods if needed

2. @EnableAutoConfiguration - The Real Magic

This annotation tells Spring Boot to:

1. Look at your classpath

2. Check what libraries are present

3. Intelligently configure beans based on what it finds

Example auto-configuration logic (simplified):

// This is what Spring Boot does internally
@Configuration
@ConditionalOnClass(DataSource.class)  // Only if DataSource class exists
@ConditionalOnMissingBean(DataSource.class)  // Only if you haven't defined one
public class DataSourceAutoConfiguration {

    @Bean
    public DataSource dataSource() {
        // If H2 is in classpath, configure H2
        // If MySQL driver in classpath, configure MySQL
        // Use application.properties for connection details
        return configuredDataSource;
    }
}

Let's see auto-configuration in action:

<!-- If you add this dependency to pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Spring Boot automatically configures:

• Embedded Tomcat server (no need to install Tomcat separately)

• Spring MVC (DispatcherServlet, ViewResolvers, etc.)

• Jackson for JSON serialization/deserialization

• HTTP message converters

• Error handling with sensible defaults

• Static resource handling (for /static, /public, /resources)

All from ONE dependency! In traditional Spring, this would require:

• 20+ separate dependencies

• Careful version matching

• Extensive XML configuration

• Manual server setup

3. @ComponentScan

• Automatically scans the package of the annotated class and all sub-packages

• Finds all classes annotated with @Component, @Service, @Repository, @Controller

• Registers them as Spring beans

com.example.demo/              <- @SpringBootApplication scans from here
├── DemoApplication.java
├── controller/                <- All classes here are scanned
│   └── UserController.java    <- @RestController found and registered
├── service/                   <- All classes here are scanned
│   └── UserService.java       <- @Service found and registered
└── repository/                <- All classes here are scanned
    └── UserRepository.java    <- @Repository found and registered

2. Starter Dependencies - Dependency Management Made Easy

The Old Way: Dependency Hell

<!-- Before Spring Boot - you had to manage all this manually -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.10</version>  <!-- Make sure version matches! -->
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>5.3.10</version>  <!-- Same version! -->
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.12.5</version>  <!-- Compatible version? -->
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.12.5</version>  <!-- Must match jackson-databind! -->
</dependency>
<!-- ... 20+ more dependencies, all with potential version conflicts -->

The Spring Boot Way:

<!-- One starter dependency = everything you need -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- No version needed! Inherited from spring-boot-starter-parent -->
</dependency>

This ONE dependency brings:

• Spring Web

• Spring MVC

• Jackson (all modules)

• Tomcat (embedded)

• Validation

• All in compatible versions!

Common Starter Dependencies:

3. Embedded Servers - No External Server Needed

Traditional Deployment:

1. Install Tomcat/JBoss/WebLogic separately

2. Configure server

3. Package app as WAR

4. Deploy WAR to server

5. Configure server to run WAR

6. Pray it works

Spring Boot Approach:

// Just run your main method!
public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
}

Your application becomes a self-contained executable JAR:

# Build
mvn clean package

# Run anywhere (just needs Java)
java -jar myapp.jar

# Application starts with embedded Tomcat on port 8080

How it works:

• Spring Boot packages an embedded servlet container (Tomcat by default) inside your JAR

• When you run the JAR, it starts the embedded Tomcat

• Your application is deployed to this embedded Tomcat

• Everything runs in a single process

Benefits:

• Consistent development and production environments

• Easy horizontal scaling (just run more JARs)

• No server configuration drift

• Cloud-friendly (containers, Kubernetes)

4. Production-Ready Features - Built-In Monitoring

Add one dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

You instantly get:

• Health checks: GET /actuator/health

• Metrics: GET /actuator/metrics

• Environment info: GET /actuator/env

• Bean info: GET /actuator/beans

• HTTP trace: GET /actuator/httptrace

• And many more!

Getting Started with Spring Boot

Using Spring Initializr - Your Project Bootstrap Tool

Spring Initializr (start.spring.io) is a web-based tool to bootstrap Spring Boot projects.

Step-by-Step Guide:

1. Navigate to https://start.spring.io

2. Choose Project Type:

   • Project: Maven (build tool)

     • Maven uses pom.xml for configuration

     • Gradle alternative uses build.gradle

3. Choose Language:

   • Java (most common)

   • Kotlin or Groovy are alternatives

4. Choose Spring Boot Version:

   • Select latest stable (avoid SNAPSHOT or M1/RC versions)

   • As of writing: 3.2.x is current

5. Project Metadata:

    Group: com.example          (your organization)
    Artifact: blog-api          (project name)
    Name: blog-api              (display name)
    Description: Blog REST API  (project description)
    Package name: com.example.blog  (base package)
    Packaging: Jar              (NOT War - we use embedded Tomcat)
    Java: 17 or 21              (LTS versions)
   

6. Add Dependencies (click "Add Dependencies"):

   • Spring Web: REST APIs and web applications

   • Spring Data JPA: Database persistence

   • H2 Database: In-memory database (for dev/testing)

   • PostgreSQL Driver: Production database

   • Spring Security: Authentication and authorization

   • Validation: Bean validation with Hibernate validator

   • Lombok: Reduces boilerplate (getters, setters, etc.)

7. Click "Generate" - downloads a ZIP file

8. Extract and Open:

    unzip blog-api.zip
    cd blog-api
    # Open in your IDE (IntelliJ IDEA, Eclipse, VS Code)
   

Understanding the Generated Project Structure

blog-api/
├── src/
│   ├── main/
│   │   ├── java/              <- Your Java source code
│   │   │   └── com/example/blog/
│   │   │       └── BlogApiApplication.java  <- Main application class
│   │   └── resources/         <- Configuration and static files
│   │       ├── application.properties  <- Configuration
│   │       ├── static/        <- Static web content (CSS, JS, images)
│   │       └── templates/     <- HTML templates (if using Thymeleaf)
│   └── test/
│       └── java/              <- Your test code
│           └── com/example/blog/
│               └── BlogApiApplicationTests.java
├── target/                    <- Compiled code (auto-generated)
├── pom.xml                    <- Maven configuration
└── README.md                  <- Project documentation

Recommended folder structure for a real project:

blog-api/
├── src/main/java/com/example/blog/
│   ├── BlogApiApplication.java       <- Main class
│   ├── config/                       <- Configuration classes
│   │   ├── SecurityConfig.java
│   │   ├── AppConfig.java
│   │   └── AppProperties.java
│   ├── controller/                   <- REST controllers
│   │   ├── AuthController.java
│   │   ├── UserController.java
│   │   └── ArticleController.java
│   ├── service/                      <- Business logic
│   │   ├── UserService.java
│   │   └── ArticleService.java
│   ├── repository/                   <- Database access
│   │   ├── UserRepository.java
│   │   └── ArticleRepository.java
│   ├── model/                        <- JPA entities
│   │   ├── User.java
│   │   ├── Article.java
│   │   └── Role.java
│   ├── dto/                          <- Data Transfer Objects
│   │   ├── request/
│   │   │   ├── CreateUserRequest.java
│   │   │   └── UpdateUserRequest.java
│   │   └── response/
│   │       ├── UserDTO.java
│   │       └── ArticleDTO.java
│   ├── exception/                    <- Custom exceptions
│   │   ├── ResourceNotFoundException.java
│   │   └── GlobalExceptionHandler.java
│   └── security/                     <- Security-related classes
│       ├── JwtTokenProvider.java
│       └── JwtAuthenticationFilter.java
└── src/main/resources/
    ├── application.yml               <- Main configuration
    ├── application-dev.yml           <- Dev environment config
    ├── application-prod.yml          <- Production config
    ├── schema.sql                    <- Database schema (optional)
    └── data.sql                      <- Seed data (optional)

The Heart of Spring Boot: @SpringBootApplication

Let's dissect the main application class:

package com.example.blog;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BlogApiApplication {

    public static void main(String[] args) {
        SpringApplication.run(BlogApiApplication.class, args);
    }
}

Line-by-line explanation:

@SpringBootApplication

• Meta-annotation that combines three annotations

• Acts as a convenience wrapper

• Equivalent to using @Configuration + @EnableAutoConfiguration + @ComponentScan

What it actually means:

// This is what @SpringBootApplication does behind the scenes:

@Configuration  // This class can define Spring beans using @Bean methods
@EnableAutoConfiguration  // Enable Spring Boot auto-configuration magic
@ComponentScan(basePackages = "com.example.blog")  // Scan this package for components
public class BlogApiApplication {
    // ...
}

Detailed breakdown:

1. @Configuration

   • Indicates this class contains bean definitions

   • Methods annotated with @Bean will create Spring-managed objects

   • Example:

    @SpringBootApplication
    public class BlogApiApplication {

        public static void main(String[] args) {
            SpringApplication.run(BlogApiApplication.class, args);
        }

        // You can define beans here if needed
        @Bean
        public RestTemplate restTemplate() {
            return new RestTemplate();
        }
    }

2. @EnableAutoConfiguration

   • The MAGIC of Spring Boot

   • Tells Spring Boot to automatically configure your application

   • Based on classpath contents and existing beans

   • Uses many conditional annotations internally

How Auto-Configuration Works - Deep Dive:

When you start a Spring Boot application:

1. Classpath Scanning: Spring Boot scans all JARs in your classpath

2. Checks META-INF/spring.factories in each JAR for auto-configuration classes

3. Evaluates Conditions: Each auto-configuration class has conditions

4. Registers Beans: If conditions pass, beans are registered

Example: DataSource Auto-Configuration

// Simplified version of Spring Boot's DataSourceAutoConfiguration
@Configuration
@ConditionalOnClass(DataSource.class)  // Only if DataSource.class is present
@EnableConfigurationProperties(DataSourceProperties.class)
public class DataSourceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean  // Only if user hasn't defined DataSource
    public DataSource dataSource(DataSourceProperties properties) {
        // Creates DataSource using properties from application.properties
        // Example: spring.datasource.url, spring.datasource.username, etc.
        return properties.initializeDataSourceBuilder().build();
    }
}

Key Conditional Annotations:

Real Example - Web MVC Auto-Configuration:

When you add spring-boot-starter-web:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Spring Boot automatically configures:

// WebMvcAutoConfiguration (simplified)
@Configuration
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class })
@ConditionalOnWebApplication(type = Type.SERVLET)
public class WebMvcAutoConfiguration {

    @Bean
    public DispatcherServlet dispatcherServlet() {
        // The front controller for Spring MVC
        return new DispatcherServlet();
    }

    @Bean
    public ViewResolver viewResolver() {
        // Resolves view names to actual views
        return new InternalResourceViewResolver();
    }

    @Bean
    public RequestMappingHandlerMapping requestMappingHandlerMapping() {
        // Maps HTTP requests to @RequestMapping methods
        return new RequestMappingHandlerMapping();
    }

    @Bean
    public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {
        // Handles request execution
        return new RequestMappingHandlerAdapter();
    }

    // Many more beans...
}

You get ALL of this without writing a single line of configuration!

3. @ComponentScan

   • Scans for Spring components in current package and sub-packages

   • Registers classes annotated with stereotype annotations:

     • @Component - generic Spring-managed component

     • @Service - service layer component

     • @Repository - data access component

     • @Controller - web controller

     • @RestController - REST API controller

     • @Configuration - configuration class

Example of component scanning:

// Assume this structure:
com.example.blog/
├── BlogApiApplication.java  <- @SpringBootApplication here
├── controller/
│   └── UserController.java  <- @RestController
├── service/
│   └── UserService.java     <- @Service
└── repository/
    └── UserRepository.java  <- @Repository

// All classes in controller/, service/, repository/ are automatically found and registered!

The main() Method:

public static void main(String[] args) {
    SpringApplication.run(BlogApiApplication.class, args);
}

What SpringApplication.run() does:

1. Creates Application Context: The IoC container

2. Registers All Beans: Scans and creates all Spring beans

3. Runs Auto-Configuration: Applies all auto-configuration

4. Starts Embedded Server: Launches Tomcat/Jetty/Undertow

5. Makes Application Ready: Ready to handle requests

You can customize startup:

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(BlogApiApplication.class);

    // Customize
    app.setBannerMode(Banner.Mode.OFF);  // Disable Spring Boot banner
    app.setAdditionalProfiles("dev");    // Activate dev profile

    // Run
    app.run(args);
}

Spring Beans and Dependency Injection

What are Spring Beans? - The Building Blocks

A Spring Bean is simply a Java object that is managed by the Spring IoC container.

Think of it this way:

• Regular Java Object: You create it with new, you manage it, you destroy it

• Spring Bean: Spring creates it, Spring manages it, Spring destroys it

Why use beans?

1. Dependency Management: Spring handles object dependencies

2. Lifecycle Management: Spring controls creation and destruction

3. Configuration Management: Centralized configuration

4. Singleton Pattern: By default, beans are singletons (one instance per application)

Bean Lifecycle - Complete Journey

The lifecycle of a Spring bean is complex. Let's understand every phase:

┌─────────────────────────────────────────────────┐
│          Spring Container Startup                │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 1: Bean Definition Loading               │
│  - Spring scans @Component classes              │
│  - Reads @Configuration classes                 │
│  - Loads bean definitions                       │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 2: Bean Instantiation                    │
│  - Constructor is called                        │
│  - Bean object created in memory                │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 3: Dependency Injection                  │
│  - @Autowired fields set                        │
│  - @Autowired setters called                    │
│  - Constructor injection already done            │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 4: Awareness Interfaces (if implemented) │
│  - BeanNameAware.setBeanName()                  │
│  - BeanFactoryAware.setBeanFactory()            │
│  - ApplicationContextAware.setApplicationContext()│
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 5: Pre-Initialization                    │
│  - BeanPostProcessor.postProcessBeforeInitialization()│
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 6: Initialization                        │
│  - @PostConstruct method called                 │
│  - InitializingBean.afterPropertiesSet() called │
│  - Custom init-method called                    │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 7: Post-Initialization                   │
│  - BeanPostProcessor.postProcessAfterInitialization()│
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 8: Bean Ready to Use                     │
│  - Bean is fully initialized                    │
│  - Available for dependency injection           │
│  - Can service requests                         │
└─────────────────────────────────────────────────┘
                     ↓
            (Application runs)
                     ↓
┌─────────────────────────────────────────────────┐
│  Phase 9: Destruction (shutdown)                │
│  - @PreDestroy method called                    │
│  - DisposableBean.destroy() called              │
│  - Custom destroy-method called                 │
└─────────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────┐
│          Spring Container Shutdown               │
└─────────────────────────────────────────────────┘

Complete Example Demonstrating Lifecycle:

package com.example.lifecycle;

import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.beans.factory.BeanNameAware;
import org.springframework.beans.factory.BeanFactoryAware;
import org.springframework.beans.factory.BeanFactory;
import org.springframework.context.ApplicationContextAware;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;

@Component  // Tell Spring this is a bean
public class LifecycleBean implements BeanNameAware, BeanFactoryAware,
                                     ApplicationContextAware, InitializingBean,
                                     DisposableBean {

    // Dependencies will be injected here
    private SomeDependency dependency;

    // 1. Constructor - FIRST method called
    public LifecycleBean() {
        System.out.println("1. Constructor called - Bean instantiated");
    }

    // 2. Dependency Injection - Dependencies are set
    @Autowired
    public void setDependency(SomeDependency dependency) {
        this.dependency = dependency;
        System.out.println("2. Dependency injected - SomeDependency set");
    }

    // 3. BeanNameAware - Spring tells bean its name
    @Override
    public void setBeanName(String name) {
        System.out.println("3. BeanNameAware.setBeanName() - Bean name is: " + name);
    }

    // 4. BeanFactoryAware - Spring passes BeanFactory reference
    @Override
    public void setBeanFactory(BeanFactory beanFactory) {
        System.out.println("4. BeanFactoryAware.setBeanFactory() - BeanFactory available");
    }

    // 5. ApplicationContextAware - Spring passes ApplicationContext
    @Override
    public void setApplicationContext(ApplicationContext applicationContext) {
        System.out.println("5. ApplicationContextAware.setApplicationContext() - Context available");
    }

    // 6. @PostConstruct - Custom initialization logic
    @PostConstruct
    public void postConstruct() {
        System.out.println("6. @PostConstruct called - Performing custom initialization");
        // Perfect place for:
        // - Opening resources
        // - Starting background threads
        // - Loading cache data
    }

    // 7. InitializingBean - Alternative to @PostConstruct
    @Override
    public void afterPropertiesSet() throws Exception {
        System.out.println("7. InitializingBean.afterPropertiesSet() called");
    }

    // Bean is now READY and can be used

    public void doSomething() {
        System.out.println("Bean is working! Using dependency: " + dependency);
    }

    // DESTRUCTION PHASE (when application shuts down)

    // 8. @PreDestroy - Called before bean is destroyed
    @PreDestroy
    public void preDestroy() {
        System.out.println("8. @PreDestroy called - Cleaning up resources");
        // Perfect place for:
        // - Closing file handles
        // - Closing database connections
        // - Stopping background threads
    }

    // 9. DisposableBean - Alternative to @PreDestroy
    @Override
    public void destroy() throws Exception {
        System.out.println("9. DisposableBean.destroy() called");
    }
}

Console Output:

1. Constructor called - Bean instantiated
2. Dependency injected - SomeDependency set
3. BeanNameAware.setBeanName() - Bean name is: lifecycleBean
4. BeanFactoryAware.setBeanFactory() - BeanFactory available
5. ApplicationContextAware.setApplicationContext() - Context available
6. @PostConstruct called - Performing custom initialization
7. InitializingBean.afterPropertiesSet() called
(Application runs...)
8. @PreDestroy called - Cleaning up resources
9. DisposableBean.destroy() called

Best Practices:

• Use @PostConstruct instead of InitializingBean (more modern, less coupling)

• Use @PreDestroy instead of DisposableBean

• Awareness interfaces are rarely needed in modern Spring apps

Bean Scopes - Understanding Instance Management

Spring supports multiple bean scopes that control how many instances of a bean are created and how long they live.

1. Singleton Scope (Default)

Definition: ONE instance per Spring container (per application)

@Component
@Scope("singleton")  // This is the DEFAULT, so optional
public class SingletonBean {

    private int counter = 0;

    public void increment() {
        counter++;
    }

    public int getCounter() {
        return counter;
    }
}

Behavior:

@RestController
public class TestController {

    @Autowired
    private SingletonBean bean1;

    @Autowired
    private SingletonBean bean2;

    @GetMapping("/test")
    public String test() {
        bean1.increment();  // counter = 1
        bean2.increment();  // counter = 2 (same instance!)

        return "bean1 == bean2: " + (bean1 == bean2);  // true
        // Both references point to the SAME object
    }
}

When to use:

• Stateless services (most services)

• Repositories

• Controllers

• Any bean without state

Memory diagram:

┌─────────────────────┐
│  Spring Container   │
│                     │
│  SingletonBean ────┼────> [One Instance]
│  (only one exists) │           ↑
└─────────────────────┘           │
                                  │
              ┌──────────┬────────┴────────┬──────────┐
              │          │                 │          │
           bean1      bean2            bean3      bean4
         (all point to same instance)

2. Prototype Scope

Definition: NEW instance EVERY time the bean is requested

@Component
@Scope("prototype")  // New instance each time!
public class PrototypeBean {

    private int counter = 0;

    public void increment() {
        counter++;
    }

    public int getCounter() {
        return counter;
    }
}

Behavior:

@RestController
public class TestController {

    @Autowired
    private PrototypeBean bean1;

    @Autowired
    private PrototypeBean bean2;

    @GetMapping("/test")
    public String test() {
        bean1.increment();  // bean1 counter = 1
        bean2.increment();  // bean2 counter = 1 (different instance!)

        return "bean1 == bean2: " + (bean1 == bean2);  // false
        // Each is a different object
    }
}

When to use:

• Stateful beans (beans that hold user-specific data)

• Beans representing temporary operations

• When you need clean state for each operation

Important Note: Spring creates prototype beans but does NOT manage their destruction. You must clean them up yourself!

3. Request Scope (Web Applications Only)

Definition: ONE instance per HTTP request

@Component
@Scope(value = WebApplicationContext.SCOPE_REQUEST, proxyMode = ScopedProxyMode.TARGET_CLASS)
public class RequestScopedBean {

    private String userId;  // Different for each HTTP request

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUserId() {
        return userId;
    }
}

Why proxyMode = ScopedProxyMode.TARGET_CLASS?

When a singleton bean depends on a request-scoped bean, Spring needs to create a proxy. The proxy intercepts method calls and delegates to the correct request-scoped instance.

@Service  // Singleton by default
public class UserService {

    @Autowired
    private RequestScopedBean requestBean;  // Injected as proxy

    public void processRequest(String userId) {
        // Each HTTP request gets its own RequestScopedBean instance
        requestBean.setUserId(userId);
        String id = requestBean.getUserId();  // Same userId
    }
}

Request Flow:

HTTP Request 1 (User A)                    HTTP Request 2 (User B)
       ↓                                           ↓
RequestScopedBean instance A              RequestScopedBean instance B
userId = "userA"                          userId = "userB"
       ↓                                           ↓
(Instance destroyed after request)        (Instance destroyed after request)

4. Session Scope (Web Applications Only)

Definition: ONE instance per HTTP session (per user)

@Component
@Scope(value = WebApplicationContext.SCOPE_SESSION, proxyMode = ScopedProxyMode.TARGET_CLASS)
public class ShoppingCart {

    private List<Item> items = new ArrayList<>();

    public void addItem(Item item) {
        items.add(item);
    }

    public List<Item> getItems() {
        return items;
    }

    public void clear() {
        items.clear();
    }
}

Behavior:

@RestController
public class CartController {

    @Autowired
    private ShoppingCart cart;  // Different instance per user session

    @PostMapping("/cart/add")
    public void addToCart(@RequestBody Item item) {
        // User A's session → User A's ShoppingCart instance
        // User B's session → User B's ShoppingCart instance
        cart.addItem(item);
    }

    @GetMapping("/cart")
    public List<Item> getCart() {
        return cart.getItems();  // Returns user-specific cart
    }
}

Session Flow:

User A's Session (JSESSIONID=ABC123)
    ↓
ShoppingCart A
├── Item 1
├── Item 2
└── Item 3
(Lives until session expires)

User B's Session (JSESSIONID=XYZ789)
    ↓
ShoppingCart B
├── Item 5
└── Item 6
(Different instance, lives until session expires)

5. Application Scope

Definition: ONE instance per ServletContext (shared across all sessions)

@Component
@Scope(value = WebApplicationContext.SCOPE_APPLICATION, proxyMode = ScopedProxyMode.TARGET_CLASS)
public class ApplicationMetrics {

    private AtomicLong requestCount = new AtomicLong(0);
    private AtomicLong activeUsers = new AtomicLong(0);

    public void incrementRequests() {
        requestCount.incrementAndGet();
    }

    public long getRequestCount() {
        return requestCount.get();
    }
}

When to use:

• Application-wide metrics

• Shared caches

• Configuration that's the same for all users

Scope Comparison Table:

Creating Beans - Multiple Methods

Method 1: Stereotype Annotations

// 1. @Component - Generic bean
@Component
public class EmailUtil {
    public void sendEmail(String to, String message) {
        // Implementation
    }
}

// 2. @Service - Business logic layer
@Service  // Specialized @Component for services
public class UserService {

    @Autowired
    private UserRepository repository;

    public User createUser(User user) {
        // Business logic
        return repository.save(user);
    }
}

// 3. @Repository - Data access layer
@Repository  // Specialized @Component for repositories
public interface UserRepository extends JpaRepository<User, Long> {
    // Spring Data JPA generates implementation
}

// 4. @Controller - Web MVC controller
@Controller  // Specialized @Component for web controllers
public class HomeController {

    @GetMapping("/home")
    public String home(Model model) {
        return "home";  // Returns view name
    }
}

// 5. @RestController - REST API controller
@RestController  // @Controller + @ResponseBody
public class UserRestController {

    @GetMapping("/api/users")
    public List<User> getUsers() {
        return userService.getAllUsers();  // Returns JSON
    }
}

Why different annotations if they're all @Component?

1. Semantic Clarity: Code is more readable

2. Exception Translation: @Repository enables automatic exception translation

3. Future Enhancements: Spring might add special behavior to specific stereotypes

4. Tooling: IDEs can provide better support

Method 2: @Configuration and @Bean

@Configuration  // This class contains bean definitions
public class AppConfig {

    // Method 1: Simple bean creation
    @Bean
    public PasswordEncoder passwordEncoder() {
        // This object becomes a Spring bean
        return new BCryptPasswordEncoder();
    }

    // Method 2: Bean with dependencies
    @Bean
    public JwtTokenProvider jwtTokenProvider(
            @Value("${jwt.secret}") String secret,
            @Value("${jwt.expiration}") long expiration) {

        return new JwtTokenProvider(secret, expiration);
    }

    // Method 3: Conditional bean
    @Bean
    @ConditionalOnProperty(name = "cache.enabled", havingValue = "true")
    public CacheManager cacheManager() {
        return new ConcurrentMapCacheManager("users", "articles");
    }

    // Method 4: Bean with custom initialization
    @Bean(initMethod = "init", destroyMethod = "cleanup")
    public DataSource dataSource() {
        HikariDataSource ds = new HikariDataSource();
        ds.setJdbcUrl("jdbc:postgresql://localhost/mydb");
        // More config...
        return ds;
    }

    // Method 5: Primary bean (used when multiple candidates exist)
    @Bean
    @Primary  // This one will be used by default
    public RestTemplate primaryRestTemplate() {
        return new RestTemplate();
    }

    @Bean
    public RestTemplate alternativeRestTemplate() {
        RestTemplate template = new RestTemplate();
        // Different configuration
        return template;
    }
}

Dependency Injection Patterns - In-Depth

Constructor Injection (Recommended)

@Service
public class ArticleService {

    // 1. Declare dependencies as final (immutable)
    private final ArticleRepository articleRepository;
    private final UserRepository userRepository;
    private final NotificationService notificationService;

    // 2. Single constructor - @Autowired is optional (Spring auto-detects)
    public ArticleService(ArticleRepository articleRepository,
                         UserRepository userRepository,
                         NotificationService notificationService) {
        // 3. Assign dependencies
        this.articleRepository = articleRepository;
        this.userRepository = userRepository;
        this.notificationService = notificationService;
    }

    public Article createArticle(Long userId, String title, String content) {
        // All dependencies are guaranteed to be available
        User author = userRepository.findById(userId)
            .orElseThrow(() -> new UserNotFoundException());

        Article article = new Article();
        article.setTitle(title);
        article.setContent(content);
        article.setAuthor(author);

        Article saved = articleRepository.save(article);
        notificationService.notifyFollowers(author, saved);

        return saved;
    }
}

Why Constructor Injection is Best:

1. Immutability: Fields are final, can't be changed after creation

2. Required Dependencies: Constructor won't compile without all deps

3. Easy Testing: Just call constructor in tests

// Test example
@Test
public void testCreateArticle() {
    ArticleRepository mockRepo = mock(ArticleRepository.class);
    UserRepository mockUserRepo = mock(UserRepository.class);
    NotificationService mockNotif = mock(NotificationService.class);

    // Easy to create with mocks!
    ArticleService service = new ArticleService(mockRepo, mockUserRepo, mockNotif);

    // Test service...
}

4. Prevents Circular Dependencies: Spring will error at startup if circular

5. Null Safety: No risk of NullPointerException

Setter Injection (For Optional Dependencies)

@Service
public class NotificationService {

    // Required dependencies via constructor
    private final NotificationRepository repository;

    // Optional dependencies via setters
    private EmailService emailService;
    private SmsService smsService;
    private PushNotificationService pushService;

    // Constructor for required deps
    public NotificationService(NotificationRepository repository) {
        this.repository = repository;
    }

    // Setter for optional dependency
    @Autowired(required = false)  // Won't fail if EmailService doesn't exist
    public void setEmailService(EmailService emailService) {
        this.emailService = emailService;
    }

    @Autowired(required = false)
    public void setSmsService(SmsService smsService) {
        this.smsService = smsService;
    }

    @Autowired(required = false)
    public void setPushService(PushNotificationService pushService) {
        this.pushService = pushService;
    }

    public void sendNotification(User user, String message) {
        Notification notif = new Notification(user, message);
        repository.save(notif);

        // Use whichever services are available
        if (emailService != null) {
            emailService.send(user.getEmail(), message);
        }

        if (smsService != null) {
            smsService.send(user.getPhone(), message);
        }

        if (pushService != null) {
            pushService.send(user.getDeviceToken(), message);
        }
    }
}

Field Injection (Not Recommended - Shown for Completeness)

@Service
public class ProductService {

    // Spring injects directly into fields
    @Autowired
    private ProductRepository productRepository;

    @Autowired
    private InventoryService inventoryService;

    // NO CONSTRUCTOR NEEDED

    public Product createProduct(Product product) {
        // Looks clean but has problems:
        // 1. Can't make fields final
        // 2. Hard to test (need Spring context)
        // 3. Hidden dependencies
        // 4. Risk of NullPointerException
        return productRepository.save(product);
    }
}

Why Field Injection is Bad:

1. Can't use final: Fields are mutable

2. Testing Nightmare: Need Spring context or reflection to set fields

3. Hidden Dependencies: Not clear what class needs

4. Tight Coupling: Coupled to Spring

Practical Example: Complete Blog Application

Let's build a mini blog system showing all concepts:

1. Entity (Model Layer)

package com.example.blog.model;

import jakarta.persistence.*;
import org.hibernate.annotations.CreationTimestamp;
import java.time.LocalDateTime;

@Entity  // JPA annotation - this class maps to database table
@Table(name = "posts")  // Table name is "posts"
public class Post {

    @Id  // Primary key
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // Auto-increment
    private Long id;

    @Column(nullable = false, length = 200)  // NOT NULL column, max 200 chars
    private String title;

    @Column(columnDefinition = "TEXT")  // TEXT type for long content
    private String content;

    @CreationTimestamp  // Hibernate automatically sets timestamp on creation
    private LocalDateTime createdAt;

    @ManyToOne(fetch = FetchType.LAZY)  // Many posts belong to one author
    @JoinColumn(name = "author_id")  // Foreign key column
    private User author;

    // Constructors
    public Post() {
    }

    public Post(String title, String content, User author) {
        this.title = title;
        this.content = content;
        this.author = author;
    }

    // Getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }

    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }

    public LocalDateTime getCreatedAt() { return createdAt; }
    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }

    public User getAuthor() { return author; }
    public void setAuthor(User author) { this.author = author; }
}

2. Repository (Data Access Layer)

package com.example.blog.repository;

import com.example.blog.model.Post;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import java.util.List;

@Repository  // Marks this as a repository bean
public interface PostRepository extends JpaRepository<Post, Long> {
    // JpaRepository provides:
    // - save(entity)
    // - findById(id)
    // - findAll()
    // - deleteById(id)
    // - count()
    // And many more!

    // Custom query methods - Spring Data generates implementation
    List<Post> findByTitleContaining(String keyword);

    List<Post> findByAuthor_Username(String username);

    long countByAuthor_Id(Long authorId);
}

3. Service (Business Logic Layer)

package com.example.blog.service;

import com.example.blog.model.Post;
import com.example.blog.repository.PostRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.List;

@Service  // Marks this as a service bean
@Transactional  // All methods run in transactions
public class PostService {

    // Constructor injection - immutable, testable
    private final PostRepository postRepository;

    public PostService(PostRepository postRepository) {
        this.postRepository = postRepository;
    }

    // Read-only transaction (optimization)
    @Transactional(readOnly = true)
    public List<Post> getAllPosts() {
        return postRepository.findAll();
    }

    @Transactional(readOnly = true)
    public Post getPostById(Long id) {
        return postRepository.findById(id)
            .orElseThrow(() -> new PostNotFoundException("Post not found: " + id));
    }

    // Write transaction
    public Post createPost(Post post) {
        // Validation
        if (post.getTitle() == null || post.getTitle().trim().isEmpty()) {
            throw new IllegalArgumentException("Title cannot be empty");
        }

        // Save
        return postRepository.save(post);
    }

    public Post updatePost(Long id, Post updateData) {
        Post existing = getPostById(id);

        existing.setTitle(updateData.getTitle());
        existing.setContent(updateData.getContent());

        return postRepository.save(existing);
    }

    public void deletePost(Long id) {
        if (!postRepository.existsById(id)) {
            throw new PostNotFoundException("Post not found: " + id);
        }
        postRepository.deleteById(id);
    }

    @Transactional(readOnly = true)
    public List<Post> searchPosts(String keyword) {
        return postRepository.findByTitleContaining(keyword);
    }
}

4. Controller (Web Layer)

package com.example.blog.controller;

import com.example.blog.model.Post;
import com.example.blog.service.PostService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController  // @Controller + @ResponseBody (returns JSON)
@RequestMapping("/api/posts")  // Base path for all endpoints
public class PostController {

    private final PostService postService;

    public PostController(PostService postService) {
        this.postService = postService;
    }

    // GET /api/posts - Get all posts
    @GetMapping
    public ResponseEntity<List<Post>> getAllPosts() {
        List<Post> posts = postService.getAllPosts();
        return ResponseEntity.ok(posts);  // HTTP 200 with posts as JSON
    }

    // GET /api/posts/123 - Get specific post
    @GetMapping("/{id}")
    public ResponseEntity<Post> getPostById(@PathVariable Long id) {
        Post post = postService.getPostById(id);
        return ResponseEntity.ok(post);
    }

    // POST /api/posts - Create new post
    @PostMapping
    public ResponseEntity<Post> createPost(@RequestBody Post post) {
        Post created = postService.createPost(post);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);  // HTTP 201
    }

    // PUT /api/posts/123 - Update post
    @PutMapping("/{id}")
    public ResponseEntity<Post> updatePost(
            @PathVariable Long id,
            @RequestBody Post post) {
        Post updated = postService.updatePost(id, post);
        return ResponseEntity.ok(updated);
    }

    // DELETE /api/posts/123 - Delete post
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deletePost(@PathVariable Long id) {
        postService.deletePost(id);
        return ResponseEntity.noContent().build();  // HTTP 204
    }

    // GET /api/posts/search?q=spring - Search posts
    @GetMapping("/search")
    public ResponseEntity<List<Post>> searchPosts(@RequestParam("q") String keyword) {
        List<Post> results = postService.searchPosts(keyword);
        return ResponseEntity.ok(results);
    }
}

How They Work Together:

HTTP Request: GET /api/posts
       ↓
PostController.getAllPosts()
       ↓
PostService.getAllPosts()
       ↓
PostRepository.findAll()
       ↓
Database Query: SELECT * FROM posts
       ↓
Database Returns: List of Post rows
       ↓
PostRepository → List<Post> entities
       ↓
PostService → List<Post>
       ↓
PostController → ResponseEntity<List<Post>>
       ↓
Spring MVC → Convert to JSON
       ↓
HTTP Response: JSON array of posts

Working with SQL Databases - Complete Guide

Spring Data JPA - What and Why

JPA (Java Persistence API) is a specification for accessing, persisting, and managing data between Java objects and relational databases. Hibernate is the most popular implementation of JPA.

Spring Data JPA is a layer on top of JPA that provides:

• Repository interfaces (no need to write implementation!)

• Query methods generated from method names

• Pagination and sorting support

• Custom query support with @Query

• Auditing capabilities

• Much more!

Add Dependencies:

<dependencies>
    <!-- Spring Data JPA - includes Hibernate -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <!-- H2 Database - for development/testing -->
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- PostgreSQL - for production -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

Creating JPA Entities - Deep Dive

An Entity is a Java class that maps to a database table.

Complete Entity Example with Explanations:

package com.example.blog.model;

import jakarta.persistence.*;
import org.hibernate.annotations.CreationTimestamp;
import org.hibernate.annotations.UpdateTimestamp;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.HashSet;
import java.util.Set;

@Entity  // Marks this class as a JPA entity (maps to a table)
@Table(  // Customize table details
    name = "users",  // Table name (defaults to class name if not specified)
    uniqueConstraints = {
        @UniqueConstraint(columnNames = {"username"}),  // Unique constraint
        @UniqueConstraint(columnNames = {"email"})
    },
    indexes = {
        @Index(name = "idx_username", columnList = "username"),  // Index for performance
        @Index(name = "idx_email", columnList = "email")
    }
)
public class User {

    // PRIMARY KEY FIELD
    @Id  // Marks this as the primary key
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // Auto-increment strategy
    // Other strategies:
    // - GenerationType.AUTO - Let JPA choose
    // - GenerationType.SEQUENCE - Use database sequence
    // - GenerationType.TABLE - Use a table to generate IDs
    // - GenerationType.UUID - Generate UUID
    private Long id;

    // BASIC COLUMNS
    @Column(
        name = "username",  // Column name (defaults to field name)
        nullable = false,   // NOT NULL constraint
        unique = true,      // UNIQUE constraint
        length = 50         // VARCHAR(50)
    )
    private String username;

    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @Column(nullable = false)
    private String password;  // Should be encrypted!

    @Column(length = 500)  // Optional field
    private String bio;

    // ENUM FIELD
    @Enumerated(EnumType.STRING)  // Store enum as string in database
    // EnumType.ORDINAL stores as integer (0, 1, 2...) - NOT RECOMMENDED
    // EnumType.STRING stores actual enum name - RECOMMENDED
    @Column(nullable = false)
    private Role role;  // Enum: USER, ADMIN, MODERATOR

    @Column(name = "is_enabled", nullable = false)
    private boolean enabled = true;

    // TEMPORAL FIELDS
    @CreationTimestamp  // Hibernate sets this automatically on creation
    @Column(name = "created_at", updatable = false)  // Cannot be updated after creation
    private LocalDateTime createdAt;

    @UpdateTimestamp  // Hibernate updates this automatically on any update
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;

    // ONE-TO-MANY RELATIONSHIP
    // One user can have many articles
    @OneToMany(
        mappedBy = "author",  // Field name in Article entity that owns the relationship
        cascade = CascadeType.ALL,  // Operations on User cascade to Articles
        // CascadeType.PERSIST - cascade save
        // CascadeType.MERGE - cascade update
        // CascadeType.REMOVE - cascade delete
        // CascadeType.REFRESH - cascade refresh
        // CascadeType.DETACH - cascade detach
        // CascadeType.ALL - all of the above
        orphanRemoval = true,  // Delete articles if removed from collection
        fetch = FetchType.LAZY  // Don't load articles until accessed
        // FetchType.EAGER - load immediately (can cause N+1 problem)
        // FetchType.LAZY - load on demand (recommended)
    )
    private List<Article> articles = new ArrayList<>();

    // MANY-TO-MANY RELATIONSHIP
    // User can have many roles, role can be assigned to many users
    @ManyToMany(fetch = FetchType.EAGER)  // Eager because roles are usually small
    @JoinTable(
        name = "user_roles",  // Join table name
        joinColumns = @JoinColumn(name = "user_id"),  // FK to this entity
        inverseJoinColumns = @JoinColumn(name = "role_id")  // FK to other entity
    )
    private Set<RoleEntity> roles = new HashSet<>();

    // CONSTRUCTORS
    public User() {
        // JPA requires a no-arg constructor
    }

    public User(String username, String email, String password, Role role) {
        this.username = username;
        this.email = email;
        this.password = password;
        this.role = role;
    }

    // HELPER METHODS for bidirectional relationships
    public void addArticle(Article article) {
        articles.add(article);
        article.setAuthor(this);  // Maintain both sides of relationship
    }

    public void removeArticle(Article article) {
        articles.remove(article);
        article.setAuthor(null);
    }

    // GETTERS AND SETTERS
    public Long getId() { return id; }
    // Note: Typically no setId() - let database handle it

    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getBio() { return bio; }
    public void setBio(String bio) { this.bio = bio; }

    public Role getRole() { return role; }
    public void setRole(Role role) { this.role = role; }

    public boolean isEnabled() { return enabled; }
    public void setEnabled(boolean enabled) { this.enabled = enabled; }

    public LocalDateTime getCreatedAt() { return createdAt; }
    // Note: No setCreatedAt() - set automatically

    public LocalDateTime getUpdatedAt() { return updatedAt; }
    // Note: No setUpdatedAt() - set automatically

    public List<Article> getArticles() { return articles; }
    public void setArticles(List<Article> articles) { this.articles = articles; }

    public Set<RoleEntity> getRoles() { return roles; }
    public void setRoles(Set<RoleEntity> roles) { this.roles = roles; }

    // EQUALS AND HASHCODE (based on business key, not id)
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User)) return false;
        User user = (User) o;
        return username != null && username.equals(user.getUsername());
    }

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

    // TOSTRING (exclude collections to avoid lazy loading issues)
    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", username='" + username + '\'' +
                ", email='" + email + '\'' +
                ", role=" + role +
                ", enabled=" + enabled +
                '}';
    }
}

Article Entity - Demonstrating Relationships:

package com.example.blog.model;

import jakarta.persistence.*;
import org.hibernate.annotations.CreationTimestamp;
import java.time.LocalDateTime;
import java.util.HashSet;
import java.util.Set;

@Entity
@Table(name = "articles")
public class Article {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 255)
    private String title;

    @Column(columnDefinition = "TEXT")  // Use TEXT type for large content
    // columnDefinition lets you use database-specific types
    private String content;

    @Lob  // Large Object - for very large text/binary data
    private String fullContent;

    // MANY-TO-ONE (Article belongs to one User)
    @ManyToOne(
        fetch = FetchType.LAZY,  // Don't load author unless needed
        optional = false  // Author is required (NOT NULL)
    )
    @JoinColumn(
        name = "author_id",  // Foreign key column name
        nullable = false,
        foreignKey = @ForeignKey(name = "fk_article_author")  // FK constraint name
    )
    private User author;

    // MANY-TO-MANY (Article can have many tags, tag can be on many articles)
    @ManyToMany
    @JoinTable(
        name = "article_tags",
        joinColumns = @JoinColumn(name = "article_id"),
        inverseJoinColumns = @JoinColumn(name = "tag_id")
    )
    private Set<Tag> tags = new HashSet<>();

    // ONE-TO-MANY (Article can have many comments)
    @OneToMany(mappedBy = "article", cascade = CascadeType.ALL, orphanRemoval = true)
    private Set<Comment> comments = new HashSet<>();

    @Column(name = "view_count", nullable = false)
    private int viewCount = 0;

    @Column(name = "published", nullable = false)
    private boolean published = false;

    @CreationTimestamp
    @Column(name = "created_at", updatable = false)
    private LocalDateTime createdAt;

    @Column(name = "published_at")
    private LocalDateTime publishedAt;

    // EMBEDDABLE TYPE
    @Embedded  // Embed another class's fields into this table
    private ArticleMetadata metadata;

    // Constructors
    public Article() {}

    public Article(String title, String content, User author) {
        this.title = title;
        this.content = content;
        this.author = author;
    }

    // Helper methods
    public void addTag(Tag tag) {
        tags.add(tag);
        tag.getArticles().add(this);
    }

    public void removeTag(Tag tag) {
        tags.remove(tag);
        tag.getArticles().remove(this);
    }

    public void addComment(Comment comment) {
        comments.add(comment);
        comment.setArticle(this);
    }

    // Getters and setters...
    public Long getId() { return id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }
    public User getAuthor() { return author; }
    public void setAuthor(User author) { this.author = author; }
    public Set<Tag> getTags() { return tags; }
    public void setTags(Set<Tag> tags) { this.tags = tags; }
    public int getViewCount() { return viewCount; }
    public void setViewCount(int viewCount) { this.viewCount = viewCount; }
    public boolean isPublished() { return published; }
    public void setPublished(boolean published) { this.published = published; }
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getPublishedAt() { return publishedAt; }
    public void setPublishedAt(LocalDateTime publishedAt) { this.publishedAt = publishedAt; }
}

Embeddable Class Example:

package com.example.blog.model;

import jakarta.persistence.Embeddable;

@Embeddable  // This class's fields will be embedded in parent table
public class ArticleMetadata {

    private String metaTitle;
    private String metaDescription;
    private String metaKeywords;

    // These fields appear in articles table as:
    // meta_title, meta_description, meta_keywords

    public ArticleMetadata() {}

    public ArticleMetadata(String metaTitle, String metaDescription, String metaKeywords) {
        this.metaTitle = metaTitle;
        this.metaDescription = metaDescription;
        this.metaKeywords = metaKeywords;
    }

    // Getters and setters...
}

Generated Database Schema:

-- Users table
CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    bio VARCHAR(500),
    role VARCHAR(20) NOT NULL,
    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    INDEX idx_username (username),
    INDEX idx_email (email)
);

-- Articles table
CREATE TABLE articles (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    full_content LONGTEXT,
    author_id BIGINT NOT NULL,
    view_count INT NOT NULL DEFAULT 0,
    published BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP,
    published_at TIMESTAMP,
    meta_title VARCHAR(255),
    meta_description VARCHAR(255),
    meta_keywords VARCHAR(255),
    CONSTRAINT fk_article_author FOREIGN KEY (author_id) REFERENCES users(id)
);

-- Tags table
CREATE TABLE tags (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

-- Join table for Many-to-Many
CREATE TABLE article_tags (
    article_id BIGINT NOT NULL,
    tag_id BIGINT NOT NULL,
    PRIMARY KEY (article_id, tag_id),
    FOREIGN KEY (article_id) REFERENCES articles(id),
    FOREIGN KEY (tag_id) REFERENCES tags(id)
);

Spring Data JPA Repositories - No Implementation Needed!

Repository Hierarchy:

Repository (marker interface)
    ↓
CrudRepository (basic CRUD)
    ↓
PagingAndSortingRepository (pagination & sorting)
    ↓
JpaRepository (JPA-specific methods)

Basic Repository:

package com.example.blog.repository;

import com.example.blog.model.User;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

@Repository  // Optional - Spring Data auto-detects interfaces extending Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // JpaRepository<Entity, IDType>

    // Inherited methods from JpaRepository:
    // - save(entity) - insert or update
    // - saveAll(entities) - bulk insert/update
    // - findById(id) - returns Optional<Entity>
    // - findAll() - get all entities
    // - findAll(Sort) - get all with sorting
    // - findAll(Pageable) - get page of entities
    // - count() - count all entities
    // - deleteById(id) - delete by ID
    // - delete(entity) - delete entity
    // - deleteAll() - delete all
    // - existsById(id) - check if exists
    // - flush() - flush pending changes to DB
    // - saveAndFlush(entity) - save and flush immediately
    // - getOne(id) - get reference (lazy)
    // - getById(id) - get reference (lazy) - deprecated, use getReferenceById
    // - getReferenceById(id) - get reference without loading (lazy proxy)
}

Query Methods - Method Name Conventions

Spring Data JPA generates queries based on method names!

Complete Query Method Examples:

package com.example.blog.repository;

import com.example.blog.model.User;
import com.example.blog.model.Role;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    // ========== FIND BY SINGLE PROPERTY ==========

    // SELECT * FROM users WHERE username = ?
    Optional<User> findByUsername(String username);

    // SELECT * FROM users WHERE email = ?
    Optional<User> findByEmail(String email);

    // SELECT * FROM users WHERE role = ?
    List<User> findByRole(Role role);

    // SELECT * FROM users WHERE is_enabled = ?
    List<User> findByEnabled(boolean enabled);

    // ========== FIND WITH MULTIPLE CONDITIONS ==========

    // SELECT * FROM users WHERE username = ? AND email = ?
    Optional<User> findByUsernameAndEmail(String username, String email);

    // SELECT * FROM users WHERE username = ? OR email = ?
    List<User> findByUsernameOrEmail(String username, String email);

    // SELECT * FROM users WHERE role = ? AND is_enabled = ?
    List<User> findByRoleAndEnabled(Role role, boolean enabled);

    // ========== COMPARISON OPERATORS ==========

    // SELECT * FROM users WHERE created_at < ?
    List<User> findByCreatedAtBefore(LocalDateTime date);

    // SELECT * FROM users WHERE created_at > ?
    List<User> findByCreatedAtAfter(LocalDateTime date);

    // SELECT * FROM users WHERE created_at BETWEEN ? AND ?
    List<User> findByCreatedAtBetween(LocalDateTime start, LocalDateTime end);

    // SELECT * FROM users WHERE id < ?
    List<User> findByIdLessThan(Long id);

    // SELECT * FROM users WHERE id <= ?
    List<User> findByIdLessThanEqual(Long id);

    // SELECT * FROM users WHERE id > ?
    List<User> findByIdGreaterThan(Long id);

    // SELECT * FROM users WHERE id >= ?
    List<User> findByIdGreaterThanEqual(Long id);

    // ========== STRING OPERATIONS ==========

    // SELECT * FROM users WHERE username LIKE '%?%'
    List<User> findByUsernameContaining(String substring);

    // SELECT * FROM users WHERE username LIKE '?%'
    List<User> findByUsernameStartingWith(String prefix);

    // SELECT * FROM users WHERE username LIKE '%?'
    List<User> findByUsernameEndingWith(String suffix);

    // SELECT * FROM users WHERE LOWER(username) = LOWER(?)
    Optional<User> findByUsernameIgnoreCase(String username);

    // SELECT * FROM users WHERE LOWER(username) LIKE LOWER('%?%')
    List<User> findByUsernameContainingIgnoreCase(String substring);

    // SELECT * FROM users WHERE username LIKE ?
    // User must provide wildcards: findByUsernameLike("%john%")
    List<User> findByUsernameLike(String pattern);

    // SELECT * FROM users WHERE username NOT LIKE ?
    List<User> findByUsernameNotLike(String pattern);

    // ========== NULL CHECKS ==========

    // SELECT * FROM users WHERE bio IS NULL
    List<User> findByBioIsNull();

    // SELECT * FROM users WHERE bio IS NOT NULL
    List<User> findByBioIsNotNull();

    // ========== COLLECTION OPERATIONS ==========

    // SELECT * FROM users WHERE role IN (?)
    List<User> findByRoleIn(List<Role> roles);

    // SELECT * FROM users WHERE role NOT IN (?)
    List<User> findByRoleNotIn(List<Role> roles);

    // ========== BOOLEAN OPERATIONS ==========

    // SELECT * FROM users WHERE is_enabled = TRUE
    List<User> findByEnabledTrue();

    // SELECT * FROM users WHERE is_enabled = FALSE
    List<User> findByEnabledFalse();

    // ========== ORDERING ==========

    // SELECT * FROM users WHERE role = ? ORDER BY created_at DESC
    List<User> findByRoleOrderByCreatedAtDesc(Role role);

    // SELECT * FROM users WHERE role = ? ORDER BY username ASC
    List<User> findByRoleOrderByUsernameAsc(Role role);

    // SELECT * FROM users ORDER BY username ASC, created_at DESC
    List<User> findAllByOrderByUsernameAscCreatedAtDesc();

    // ========== LIMITING RESULTS ==========

    // SELECT * FROM users WHERE role = ? LIMIT 1
    Optional<User> findFirstByRole(Role role);
    Optional<User> findTopByRole(Role role);  // Same as above

    // SELECT * FROM users WHERE is_enabled = ? ORDER BY created_at DESC LIMIT 10
    List<User> findTop10ByEnabledOrderByCreatedAtDesc(boolean enabled);

    // SELECT * FROM users WHERE role = ? ORDER BY created_at DESC LIMIT 5
    List<User> findFirst5ByRoleOrderByCreatedAtDesc(Role role);

    // ========== DISTINCT ==========

    // SELECT DISTINCT * FROM users WHERE role = ?
    List<User> findDistinctByRole(Role role);

    // ========== COUNTING ==========

    // SELECT COUNT(*) FROM users WHERE role = ?
    long countByRole(Role role);

    // SELECT COUNT(*) FROM users WHERE is_enabled = ?
    long countByEnabled(boolean enabled);

    // SELECT COUNT(DISTINCT username) FROM users WHERE role = ?
    long countDistinctByRole(Role role);

    // ========== EXISTS ==========

    // SELECT EXISTS(SELECT 1 FROM users WHERE username = ?)
    boolean existsByUsername(String username);

    // SELECT EXISTS(SELECT 1 FROM users WHERE email = ?)
    boolean existsByEmail(String email);

    // SELECT EXISTS(SELECT 1 FROM users WHERE username = ? AND is_enabled = ?)
    boolean existsByUsernameAndEnabled(String username, boolean enabled);

    // ========== DELETE QUERIES ==========

    // DELETE FROM users WHERE username = ?
    // Note: Returns number of deleted rows
    long deleteByUsername(String username);

    // DELETE FROM users WHERE role = ?
    long deleteByRole(Role role);

    // DELETE FROM users WHERE is_enabled = ? AND created_at < ?
    long deleteByEnabledAndCreatedAtBefore(boolean enabled, LocalDateTime date);

    // Same as delete but returns deleted entities
    List<User> removeByRole(Role role);

    // ========== PAGINATION AND SORTING ==========

    // Pageable allows pagination and sorting
    // Usage: repository.findByRole(Role.USER, PageRequest.of(0, 10, Sort.by("username")))
    Page<User> findByRole(Role role, Pageable pageable);

    // Return List instead of Page (no count query)
    List<User> findByEnabled(boolean enabled, Pageable pageable);

    // Just sorting, no pagination
    List<User> findByRole(Role role, Sort sort);

    // ========== NESTED PROPERTY QUERIES ==========

    // If User has Address object with city field:
    // SELECT * FROM users WHERE address_city = ?
    // List<User> findByAddress_City(String city);

    // For relationships - query by related entity's property
    // SELECT * FROM users u JOIN articles a ON u.id = a.author_id WHERE a.title = ?
    List<User> findByArticles_Title(String articleTitle);

    // SELECT * FROM users u JOIN articles a ON u.id = a.author_id WHERE a.published = ?
    List<User> findByArticles_Published(boolean published);
}

Query Method Keywords Reference:

Custom Queries with @Query

For complex queries that can't be expressed with method names:

package com.example.blog.repository;

import com.example.blog.model.Article;
import com.example.blog.dto.ArticleSummary;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.repository.query.Param;
import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
import java.util.List;

public interface ArticleRepository extends JpaRepository<Article, Long> {

    // ========== JPQL QUERIES ==========

    // JPQL uses entity names and properties, not table/column names
    @Query("SELECT a FROM Article a WHERE a.author.username = :username")
    List<Article> findByAuthorUsername(@Param("username") String username);

    // Multiple parameters
    @Query("SELECT a FROM Article a WHERE a.published = :published AND a.viewCount > :minViews")
    List<Article> findPublishedWithMinViews(
        @Param("published") boolean published,
        @Param("minViews") int minViews
    );

    // JOIN queries
    @Query("SELECT a FROM Article a JOIN a.tags t WHERE t.name = :tagName")
    List<Article> findByTagName(@Param("tagName") String tagName);

    // LEFT JOIN
    @Query("SELECT a FROM Article a LEFT JOIN FETCH a.author WHERE a.published = true")
    // FETCH tells JPA to load the relationship immediately (avoid N+1)
    List<Article> findAllPublishedWithAuthors();

    // Aggregate functions
    @Query("SELECT COUNT(a) FROM Article a WHERE a.author.id = :authorId")
    long countArticlesByAuthor(@Param("authorId") Long authorId);

    @Query("SELECT SUM(a.viewCount) FROM Article a WHERE a.author.id = :authorId")
    long getTotalViewsByAuthor(@Param("authorId") Long authorId);

    @Query("SELECT AVG(a.viewCount) FROM Article a WHERE a.published = true")
    Double getAverageViewsForPublishedArticles();

    @Query("SELECT MAX(a.createdAt) FROM Article a WHERE a.author.id = :authorId")
    LocalDateTime getLatestArticleDate(@Param("authorId") Long authorId);

    // Pagination with JPQL
    @Query("SELECT a FROM Article a WHERE a.author.username = :username")
    Page<Article> findByAuthorUsername(@Param("username") String username, Pageable pageable);

    // DISTINCT
    @Query("SELECT DISTINCT a FROM Article a JOIN a.tags t WHERE t.name IN :tagNames")
    List<Article> findArticlesByTags(@Param("tagNames") List<String> tagNames);

    // Subquery
    @Query("SELECT a FROM Article a WHERE a.viewCount > " +
           "(SELECT AVG(a2.viewCount) FROM Article a2)")
    List<Article> findArticlesAboveAverageViews();

    // DTO Projection - fetch only specific fields
    @Query("SELECT new com.example.blog.dto.ArticleSummary(a.id, a.title, a.author.username, a.viewCount) " +
           "FROM Article a WHERE a.published = true")
    List<ArticleSummary> findPublishedArticleSummaries();

    // Constructor expression with functions
    @Query("SELECT new com.example.blog.dto.ArticleStats(a.author.username, COUNT(a), SUM(a.viewCount)) " +
           "FROM Article a GROUP BY a.author.username")
    List<ArticleStats> getArticleStatsByAuthor();

    // ========== NATIVE SQL QUERIES ==========

    // Use native SQL when JPQL is not enough
    @Query(
        value = "SELECT * FROM articles WHERE title LIKE %:keyword% OR content LIKE %:keyword%",
        nativeQuery = true
    )
    List<Article> fullTextSearch(@Param("keyword") String keyword);

    // Native query with pagination
    @Query(
        value = "SELECT * FROM articles WHERE published = true ORDER BY view_count DESC",
        countQuery = "SELECT COUNT(*) FROM articles WHERE published = true",
        nativeQuery = true
    )
    Page<Article> findMostPopular(Pageable pageable);

    // Database-specific features (PostgreSQL full-text search)
    @Query(
        value = "SELECT * FROM articles WHERE " +
                "to_tsvector('english', title || ' ' || content) @@ to_tsquery('english', :query)",
        nativeQuery = true
    )
    List<Article> fullTextSearchPostgres(@Param("query") String query);

    // Native query with named parameters
    @Query(
        value = "SELECT * FROM articles a " +
                "WHERE a.author_id = :authorId " +
                "AND a.created_at BETWEEN :startDate AND :endDate",
        nativeQuery = true
    )
    List<Article> findByAuthorAndDateRange(
        @Param("authorId") Long authorId,
        @Param("startDate") LocalDateTime startDate,
        @Param("endDate") LocalDateTime endDate
    );

    // ========== MODIFYING QUERIES (UPDATE/DELETE) ==========

    @Modifying  // Required for INSERT, UPDATE, DELETE
    @Transactional  // Must be in a transaction
    @Query("UPDATE Article a SET a.viewCount = a.viewCount + 1 WHERE a.id = :id")
    int incrementViewCount(@Param("id") Long id);
    // Returns number of affected rows

    @Modifying
    @Transactional
    @Query("UPDATE Article a SET a.published = true, a.publishedAt = :publishedAt WHERE a.id = :id")
    int publishArticle(@Param("id") Long id, @Param("publishedAt") LocalDateTime publishedAt);

    @Modifying
    @Transactional
    @Query("DELETE FROM Article a WHERE a.published = false AND a.createdAt < :date")
    int deleteUnpublishedOlderThan(@Param("date") LocalDateTime date);

    // Bulk update
    @Modifying
    @Transactional
    @Query("UPDATE Article a SET a.viewCount = 0 WHERE a.author.id = :authorId")
    int resetViewCountByAuthor(@Param("authorId") Long authorId);

    // Native modifying query
    @Modifying
    @Transactional
    @Query(
        value = "UPDATE articles SET view_count = view_count + :increment WHERE id IN :ids",
        nativeQuery = true
    )
    int bulkIncrementViewCount(@Param("ids") List<Long> ids, @Param("increment") int increment);

    // ========== NAMED QUERIES (defined in Entity class) ==========

    // Defined in Article entity:
    // @NamedQuery(name = "Article.findByTitleContaining",
    //             query = "SELECT a FROM Article a WHERE a.title LIKE %:title%")
    List<Article> findByTitleContaining(@Param("title") String title);
}

DTO Projection Class:

package com.example.blog.dto;

public class ArticleSummary {
    private Long id;
    private String title;
    private String authorUsername;
    private int viewCount;

    // Constructor matching @Query projection
    public ArticleSummary(Long id, String title, String authorUsername, int viewCount) {
        this.id = id;
        this.title = title;
        this.authorUsername = authorUsername;
        this.viewCount = viewCount;
    }

    // Getters
    public Long getId() { return id; }
    public String getTitle() { return title; }
    public String getAuthorUsername() { return authorUsername; }
    public int getViewCount() { return viewCount; }
}

Pagination and Sorting - In Detail

package com.example.blog.service;

import com.example.blog.model.Article;
import com.example.blog.repository.ArticleRepository;
import org.springframework.data.domain.*;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class ArticleService {

    private final ArticleRepository articleRepository;

    public ArticleService(ArticleRepository articleRepository) {
        this.articleRepository = articleRepository;
    }

    // ========== SIMPLE PAGINATION ==========

    public Page<Article> getArticles(int pageNumber, int pageSize) {
        // PageRequest.of(page, size)
        // Page numbers are 0-indexed: 0 = first page
        Pageable pageable = PageRequest.of(pageNumber, pageSize);

        Page<Article> page = articleRepository.findAll(pageable);

        // Page object provides:
        // page.getContent() - List of entities in current page
        // page.getTotalElements() - Total number of entities
        // page.getTotalPages() - Total number of pages
        // page.getNumber() - Current page number (0-indexed)
        // page.getSize() - Page size
        // page.hasNext() - Is there a next page?
        // page.hasPrevious() - Is there a previous page?
        // page.isFirst() - Is this the first page?
        // page.isLast() - Is this the last page?

        return page;
    }

    // ========== PAGINATION WITH SORTING ==========

    public Page<Article> getArticlesSorted(int pageNumber, int pageSize, String sortBy) {
        // Sort by single field, descending
        Sort sort = Sort.by(sortBy).descending();
        Pageable pageable = PageRequest.of(pageNumber, pageSize, sort);

        return articleRepository.findAll(pageable);
    }

    public Page<Article> getArticlesMultiSort(int pageNumber, int pageSize) {
        // Sort by multiple fields
        Sort sort = Sort.by(
            Sort.Order.desc("published"),      // First by published (desc)
            Sort.Order.desc("viewCount"),      // Then by viewCount (desc)
            Sort.Order.asc("title")            // Then by title (asc)
        );

        Pageable pageable = PageRequest.of(pageNumber, pageSize, sort);
        return articleRepository.findAll(pageable);
    }

    public Page<Article> getArticlesDynamicSort(int pageNumber, int pageSize,
                                                String sortBy, String direction) {
        // Dynamic sorting based on parameters
        Sort sort = direction.equalsIgnoreCase("asc")
            ? Sort.by(sortBy).ascending()
            : Sort.by(sortBy).descending();

        Pageable pageable = PageRequest.of(pageNumber, pageSize, sort);
        return articleRepository.findAll(pageable);
    }

    // ========== EXAMPLE: REST CONTROLLER USAGE ==========

    // This shows typical pagination in a controller
    public Page<Article> searchPublishedArticles(
            String keyword,
            int page,
            int size,
            String sortBy,
            String sortDir) {

        Sort sort = sortDir.equalsIgnoreCase(Sort.Direction.ASC.name())
            ? Sort.by(sortBy).ascending()
            : Sort.by(sortBy).descending();

        Pageable pageable = PageRequest.of(page, size, sort);

        // Use with custom query method
        return articleRepository.findByTitleContaining(keyword, pageable);
    }
}

REST Controller with Pagination:

@RestController
@RequestMapping("/api/articles")
public class ArticleController {

    private final ArticleService articleService;

    public ArticleController(ArticleService articleService) {
        this.articleService = articleService;
    }

    @GetMapping
    public ResponseEntity<Page<Article>> getArticles(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size,
            @RequestParam(defaultValue = "createdAt") String sortBy,
            @RequestParam(defaultValue = "desc") String sortDir) {

        Page<Article> articles = articleService.getArticlesDynamicSort(page, size, sortBy, sortDir);

        return ResponseEntity.ok(articles);
    }
}

// Example request: GET /api/articles?page=0&size=10&sortBy=viewCount&sortDir=desc
// Response:
// {
//   "content": [...],          // Array of articles
//   "pageable": {...},         // Pagination details
//   "totalPages": 5,          // Total number of pages
//   "totalElements": 47,      // Total number of articles
//   "last": false,            // Is this the last page?
//   "first": true,            // Is this the first page?
//   "size": 10,               // Page size
//   "number": 0,              // Current page number
//   "numberOfElements": 10,   // Number of elements in current page
//   "empty": false            // Is the page empty?
// }

Database Initialization - All Strategies Explained

Strategy 1: schema.sql and data.sql

When to use: Development, testing, simple applications

How it works: Spring Boot automatically executes SQL scripts on startup.

src/main/resources/schema.sql:

-- This file creates database schema
-- Runs BEFORE data.sql

-- Drop tables if they exist (for development)
DROP TABLE IF EXISTS article_tags;
DROP TABLE IF EXISTS articles;
DROP TABLE IF EXISTS users;

-- Create users table
CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    bio VARCHAR(500),
    role VARCHAR(20) NOT NULL DEFAULT 'USER',
    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Create articles table
CREATE TABLE articles (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    author_id BIGINT NOT NULL,
    view_count INT NOT NULL DEFAULT 0,
    published BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    published_at TIMESTAMP NULL,
    CONSTRAINT fk_article_author FOREIGN KEY (author_id)
        REFERENCES users(id) ON DELETE CASCADE
);

-- Create tags table
CREATE TABLE tags (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

-- Create join table
CREATE TABLE article_tags (
    article_id BIGINT NOT NULL,
    tag_id BIGINT NOT NULL,
    PRIMARY KEY (article_id, tag_id),
    CONSTRAINT fk_article_tags_article FOREIGN KEY (article_id)
        REFERENCES articles(id) ON DELETE CASCADE,
    CONSTRAINT fk_article_tags_tag FOREIGN KEY (tag_id)
        REFERENCES tags(id) ON DELETE CASCADE
);

-- Create indexes for performance
CREATE INDEX idx_articles_author ON articles(author_id);
CREATE INDEX idx_articles_published ON articles(published);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_email ON users(email);

src/main/resources/data.sql:

-- This file inserts seed data
-- Runs AFTER schema.sql

-- Insert users (passwords should be BCrypt hashed in real apps)
INSERT INTO users (username, email, password, role) VALUES
('john_doe', 'john@example.com', '$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG', 'USER'),
('jane_smith', 'jane@example.com', '$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG', 'USER'),
('admin', 'admin@example.com', '$2a$10$dXJ3SW6G7P50lGmMkkmwe.20cQQubK3.HZWzG3YB1tlRy.fqvM/BG', 'ADMIN');

-- Insert tags
INSERT INTO tags (name) VALUES
('Spring Boot'),
('Java'),
('Tutorial'),
('REST API'),
('Database');

-- Insert articles
INSERT INTO articles (title, content, author_id, published, view_count) VALUES
('Getting Started with Spring Boot', 'This is a comprehensive guide...', 1, TRUE, 150),
('REST API Best Practices', 'Learn how to build great APIs...', 1, TRUE, 200),
('JPA and Hibernate Deep Dive', 'Understanding ORM...', 2, TRUE, 300),
('Draft Article', 'Work in progress...', 2, FALSE, 0);

-- Link articles to tags
INSERT INTO article_tags (article_id, tag_id) VALUES
(1, 1), (1, 2), (1, 3),  -- Article 1 has tags 1, 2, 3
(2, 1), (2, 4),           -- Article 2 has tags 1, 4
(3, 1), (3, 2), (3, 5);   -- Article 3 has tags 1, 2, 5

Configuration (application.properties):

# ===== SQL SCRIPT EXECUTION =====

# Mode: always, embedded, never
# - always: Always run scripts
# - embedded: Only for embedded databases (H2, HSQL, Derby)
# - never: Never run scripts
spring.sql.init.mode=always

# Continue on error (useful for development)
spring.sql.init.continue-on-error=true

# Script encoding
spring.sql.init.encoding=UTF-8

# Platform-specific scripts
# Will look for schema-h2.sql, schema-postgresql.sql, etc.
spring.sql.init.platform=h2

# ===== IMPORTANT: Disable Hibernate DDL auto =====
# If using schema.sql, you must set this to 'none'
spring.jpa.hibernate.ddl-auto=none

Strategy 2: Hibernate DDL Auto

When to use: Development (NOT production!)

How it works: Hibernate generates/updates schema based on @Entity classes.

Configuration:

# ===== HIBERNATE DDL AUTO MODES =====

# CREATE - Drop existing schema, create new (DESTROYS DATA!)
spring.jpa.hibernate.ddl-auto=create
# Use case: Development, starting fresh each time
# What happens:
# 1. Application starts
# 2. Hibernate drops all tables
# 3. Hibernate creates tables from @Entity classes
# 4. All data is LOST

# CREATE-DROP - Create on start, drop on shutdown (DESTROYS DATA!)
spring.jpa.hibernate.ddl-auto=create-drop
# Use case: Integration tests
# What happens:
# 1. Application starts → Create tables
# 2. Application runs
# 3. Application stops → Drop all tables

# UPDATE - Update schema, keep data (CAN CAUSE ISSUES!)
spring.jpa.hibernate.ddl-auto=update
# Use case: Development (use with caution)
# What happens:
# - Adds new tables/columns
# - NEVER removes tables/columns
# - Can lead to inconsistent schema
# WARNING: Can create unexpected schema changes!

# VALIDATE - Validate schema, no changes (PRODUCTION SAFE)
spring.jpa.hibernate.ddl-auto=validate
# Use case: Production
# What happens:
# - Checks if schema matches entities
# - Throws error if mismatch
# - Makes NO changes to database

# NONE - Do nothing (PRODUCTION RECOMMENDED)
spring.jpa.hibernate.ddl-auto=none
# Use case: Production with migrations (Flyway/Liquibase)
# What happens: Nothing, you manage schema manually

# ===== ADDITIONAL HIBERNATE SETTINGS =====

# Show SQL queries in console
spring.jpa.show-sql=true

# Format SQL for readability
spring.jpa.properties.hibernate.format_sql=true

# Show bind parameter values
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

# Hibernate dialect (auto-detected usually)
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

Environment-Specific Configuration:

# application-dev.yml (Development)
spring:
  jpa:
    hibernate:
      ddl-auto: create-drop  # Fresh schema on each restart
    show-sql: true
  sql:
    init:
      mode: always  # Run data.sql for seed data

# application-test.yml (Testing)
spring:
  jpa:
    hibernate:
      ddl-auto: create-drop  # Fresh schema for each test
    show-sql: false  # Less noise in test output

# application-prod.yml (Production)
spring:
  jpa:
    hibernate:
      ddl-auto: validate  # Validate only, no changes
    show-sql: false
  sql:
    init:
      mode: never  # Never run SQL scripts in production

Strategy 3: Flyway Migrations (PRODUCTION RECOMMENDED!)

When to use: Production, team environments, version-controlled schemas

Why Flyway?

• Version-controlled database changes

• Repeatable, automated migrations

• Works across all environments

• Rollback support

• Team collaboration (no schema conflicts)

Add Dependency:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

Configuration:

# ===== FLYWAY CONFIGURATION =====

# Enable Flyway
spring.flyway.enabled=true

# Migration scripts location
spring.flyway.locations=classpath:db/migration

# Baseline on migrate (for existing databases)
spring.flyway.baseline-on-migrate=true

# Baseline version
spring.flyway.baseline-version=0

# Validate migrations on startup
spring.flyway.validate-on-migrate=true

# Clean database (DANGEROUS - development only!)
# spring.flyway.clean-on-validation-error=true

# Disable Hibernate DDL auto when using Flyway
spring.jpa.hibernate.ddl-auto=none

Migration File Naming Convention:

src/main/resources/db/migration/
├── V1__Create_users_table.sql
├── V2__Create_articles_table.sql
├── V3__Create_tags_and_join_table.sql
├── V4__Add_bio_column_to_users.sql
├── V5__Add_indexes.sql
└── V6__Insert_initial_data.sql

Format: V{version}__{description}.sql
- V = Versioned migration
- {version} = Numeric version (1, 2, 3 or 1.0, 1.1, etc.)
- __ = Double underscore separator
- {description} = Description with underscores

Example Migrations:

V1__Create_users_table.sql:

-- Flyway migration: Create users table
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,  -- PostgreSQL auto-increment
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    role VARCHAR(20) NOT NULL DEFAULT 'USER',
    is_enabled BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Create indexes
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_email ON users(email);

V2__Create_articles_table.sql:

-- Flyway migration: Create articles table
CREATE TABLE articles (
    id BIGSERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    author_id BIGINT NOT NULL,
    view_count INT NOT NULL DEFAULT 0,
    published BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    published_at TIMESTAMP,
    CONSTRAINT fk_article_author
        FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE INDEX idx_articles_author ON articles(author_id);
CREATE INDEX idx_articles_published ON articles(published);

V3__Add_bio_column.sql:

-- Flyway migration: Add bio column to users
ALTER TABLE users ADD COLUMN bio VARCHAR(500);

V4__Insert_seed_data.sql:

-- Flyway migration: Insert initial data
INSERT INTO users (username, email, password, role)
VALUES ('admin', 'admin@example.com', '$2a$10$...', 'ADMIN')
ON CONFLICT DO NOTHING;  -- PostgreSQL syntax

How Flyway Works:

1. Application Starts
   ↓
2. Flyway checks for flyway_schema_history table
   ↓
3. Creates table if it doesn't exist
   ↓
4. Reads all migration files (V1, V2, V3...)
   ↓
5. Checks which migrations already ran (from flyway_schema_history)
   ↓
6. Runs only NEW migrations in order
   ↓
7. Records each migration in flyway_schema_history
   ↓
8. Application Ready

flyway_schema_history table:

SELECT * FROM flyway_schema_history;

| installed_rank | version | description            | type | script                     | checksum    | installed_on        | success |
|----------------|---------|------------------------|------|----------------------------|-------------|---------------------|---------|
| 1              | 1       | Create users table     | SQL  | V1__Create_users_table.sql | 1234567890  | 2024-01-15 10:00:00 | true    |
| 2              | 2       | Create articles table  | SQL  | V2__Create_articles...     | 9876543210  | 2024-01-15 10:00:01 | true    |

Best Practices:

1. Never modify executed migrations - Create new migration instead

2. Always test migrations on dev/staging before production

3. Keep migrations small - One logical change per migration

4. Use transactions - Most changes should be in a transaction

5. Backup before migrating production databases

Comparison Table:

Working with NoSQL Databases - MongoDB Example

Why NoSQL?

NoSQL databases are designed for:

• Flexible schemas: No fixed table structure

• Horizontal scaling: Distribute data across many servers

• High performance: Optimized for specific use cases

• Document storage: Store complex nested data

MongoDB is a document-oriented NoSQL database that stores data in JSON-like documents.

Spring Data MongoDB

Spring Data MongoDB provides the same repository abstraction as Spring Data JPA, but for MongoDB.

Add Dependencies:

<dependencies>
    <!-- Spring Data MongoDB -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-mongodb</artifactId>
    </dependency>

    <!-- Embedded MongoDB for testing (optional) -->
    <dependency>
        <groupId>de.flapdoodle.embed</groupId>
        <artifactId>de.flapdoodle.embed.mongo</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Configuration (application.properties):

# ===== MONGODB CONNECTION =====

# Single MongoDB instance
spring.data.mongodb.host=localhost
spring.data.mongodb.port=27017
spring.data.mongodb.database=blogdb

# Or use connection URI (recommended for production)
spring.data.mongodb.uri=mongodb://localhost:27017/blogdb

# With authentication
spring.data.mongodb.uri=mongodb://username:password@localhost:27017/blogdb

# MongoDB Atlas (cloud)
spring.data.mongodb.uri=mongodb+srv://username:password@cluster0.mongodb.net/blogdb

# Connection pool settings
spring.data.mongodb.auto-index-creation=true  # Auto-create indexes from @Indexed

MongoDB Documents - Entity Classes

In MongoDB, entities are called Documents. They're stored as JSON-like BSON (Binary JSON).

Complete Document Example:

package com.example.blog.model;

import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.mongodb.core.mapping.Document;
import org.springframework.data.mongodb.core.mapping.Field;
import org.springframework.data.mongodb.core.mapping.DBRef;
import org.springframework.data.mongodb.core.index.Indexed;
import org.springframework.data.mongodb.core.index.CompoundIndex;
import org.springframework.data.mongodb.core.index.TextIndexed;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import java.util.ArrayList;
import java.util.HashMap;

@Document(collection = "users")  // Collection name (like table name in SQL)
// Compound index on multiple fields
@CompoundIndex(name = "username_email_idx", def = "{'username': 1, 'email': 1}")
public class User {

    @Id  // MongoDB uses String IDs (ObjectId internally)
    // MongoDB generates this automatically: "507f1f77bcf86cd799439011"
    private String id;

    @Indexed(unique = true)  // Create unique index on this field
    // Equivalent to SQL: CREATE UNIQUE INDEX ON users(username)
    private String username;

    @Indexed(unique = true)
    private String email;

    private String password;  // Store BCrypt hash

    @Field("bio")  // Custom field name in MongoDB (optional)
    // By default, field name matches property name
    private String biography;

    // Enum stored as string
    private Role role;  // Stored as "USER", "ADMIN", etc.

    // List of strings (native JSON array)
    private List<String> interests = new ArrayList<>();

    // Nested object (embedded document)
    private Address address;

    // Map (flexible key-value pairs)
    private Map<String, Object> metadata = new HashMap<>();

    @CreatedDate  // Automatically set on creation (requires @EnableMongoAuditing)
    private LocalDateTime createdAt;

    @LastModifiedDate  // Automatically updated on modification
    private LocalDateTime updatedAt;

    @DBRef  // Reference to another document (like foreign key)
    // Stores reference as: { "$ref": "articles", "$id": ObjectId("...") }
    private List<Article> articles = new ArrayList<>();

    @TextIndexed  // Enable text search on this field
    private String bio;

    // Transient field (not stored in MongoDB)
    @Transient
    private String temporaryData;

    // Constructors
    public User() {}

    public User(String username, String email, String password, Role role) {
        this.username = username;
        this.email = email;
        this.password = password;
        this.role = role;
    }

    // Getters and setters
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }

    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getBiography() { return biography; }
    public void setBiography(String biography) { this.biography = biography; }

    public Role getRole() { return role; }
    public void setRole(Role role) { this.role = role; }

    public List<String> getInterests() { return interests; }
    public void setInterests(List<String> interests) { this.interests = interests; }

    public Address getAddress() { return address; }
    public void setAddress(Address address) { this.address = address; }

    public Map<String, Object> getMetadata() { return metadata; }
    public void setMetadata(Map<String, Object> metadata) { this.metadata = metadata; }

    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }

    public List<Article> getArticles() { return articles; }
    public void setArticles(List<Article> articles) { this.articles = articles; }

    public String getBio() { return bio; }
    public void setBio(String bio) { this.bio = bio; }
}

// Embedded document (no @Document annotation)
// This will be stored inside the parent document
public class Address {
    private String street;
    private String city;
    private String state;
    private String zipCode;
    private String country;

    // Constructors, getters, setters
    public Address() {}

    public Address(String street, String city, String state, String zipCode, String country) {
        this.street = street;
        this.city = city;
        this.state = state;
        this.zipCode = zipCode;
        this.country = country;
    }

    // Getters and setters...
}

// Enum
public enum Role {
    USER, ADMIN, MODERATOR
}

How this looks in MongoDB:

{
  "_id": ObjectId("507f1f77bcf86cd799439011"),
  "username": "john_doe",
  "email": "john@example.com",
  "password": "$2a$10$dXJ3SW6G7P50lGmMkkmwe...",
  "bio": "Software developer passionate about Spring Boot",
  "role": "USER",
  "interests": ["Java", "Spring", "MongoDB"],
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "metadata": {
    "lastLogin": "2024-01-15T10:30:00",
    "loginCount": 42,
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  },
  "createdAt": ISODate("2024-01-01T00:00:00Z"),
  "updatedAt": ISODate("2024-01-15T10:30:00Z"),
  "articles": [
    { "$ref": "articles", "$id": ObjectId("507f1f77bcf86cd799439012") },
    { "$ref": "articles", "$id": ObjectId("507f1f77bcf86cd799439013") }
  ]
}

Article Document:

@Document(collection = "articles")
public class Article {

    @Id
    private String id;

    @Indexed  // Index for faster queries
    private String title;

    @TextIndexed(weight = 2)  // Higher weight for title in text search
    private String content;

    @DBRef(lazy = true)  // Lazy load author (not loaded until accessed)
    private User author;

    // Array of strings
    private List<String> tags = new ArrayList<>();

    // Embedded documents (comments stored inside article)
    private List<Comment> comments = new ArrayList<>();

    private int viewCount = 0;
    private boolean published = false;

    @CreatedDate
    private LocalDateTime createdAt;

    private LocalDateTime publishedAt;

    // Nested object for SEO metadata
    private SeoMetadata seo;

    // Constructors
    public Article() {}

    public Article(String title, String content, User author) {
        this.title = title;
        this.content = content;
        this.author = author;
    }

    // Getters and setters...
}

// Embedded comment (no separate collection)
public class Comment {
    private String authorName;
    private String content;
    private LocalDateTime createdAt;

    public Comment() {}

    public Comment(String authorName, String content) {
        this.authorName = authorName;
        this.content = content;
        this.createdAt = LocalDateTime.now();
    }

    // Getters and setters...
}

// Embedded SEO metadata
public class SeoMetadata {
    private String metaTitle;
    private String metaDescription;
    private List<String> keywords = new ArrayList<>();

    // Getters and setters...
}

MongoDB Article Document:

{
  "_id": ObjectId("507f1f77bcf86cd799439012"),
  "title": "Getting Started with Spring Boot",
  "content": "This is a comprehensive guide to Spring Boot...",
  "author": { "$ref": "users", "$id": ObjectId("507f1f77bcf86cd799439011") },
  "tags": ["Spring Boot", "Java", "Tutorial"],
  "comments": [
    {
      "authorName": "Jane Smith",
      "content": "Great article!",
      "createdAt": ISODate("2024-01-15T14:30:00Z")
    },
    {
      "authorName": "Bob Johnson",
      "content": "Very helpful, thanks!",
      "createdAt": ISODate("2024-01-16T09:15:00Z")
    }
  ],
  "viewCount": 150,
  "published": true,
  "createdAt": ISODate("2024-01-10T08:00:00Z"),
  "publishedAt": ISODate("2024-01-10T10:00:00Z"),
  "seo": {
    "metaTitle": "Complete Spring Boot Guide | Learn Spring Boot",
    "metaDescription": "A comprehensive guide to getting started with Spring Boot",
    "keywords": ["spring boot", "java", "tutorial", "beginner"]
  }
}

MongoDB Repositories

MongoDB repositories work similarly to JPA repositories:

package com.example.blog.repository;

import com.example.blog.model.User;
import com.example.blog.model.Role;
import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.data.mongodb.repository.Query;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.stereotype.Repository;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

@Repository
public interface UserRepository extends MongoRepository<User, String> {
    // MongoRepository<Entity, ID Type>
    // Note: ID is String for MongoDB (not Long like JPA)

    // Inherited methods (same as JPA):
    // - save(user)
    // - findById(id)
    // - findAll()
    // - deleteById(id)
    // - count()
    // - existsById(id)

    // ========== METHOD NAME QUERIES (similar to JPA) ==========

    // Find by single field
    Optional<User> findByUsername(String username);

    Optional<User> findByEmail(String email);

    List<User> findByRole(Role role);

    // Multiple conditions
    Optional<User> findByUsernameAndEmail(String username, String email);

    List<User> findByRoleAndCreatedAtAfter(Role role, LocalDateTime date);

    // String operations
    List<User> findByUsernameContaining(String substring);

    List<User> findByUsernameStartingWith(String prefix);

    List<User> findByUsernameIgnoreCase(String username);

    // Array operations (specific to MongoDB)
    // Find users who have "Java" in their interests array
    List<User> findByInterestsContaining(String interest);

    // Find users who have ANY of these interests
    List<User> findByInterestsIn(List<String> interests);

    // Nested field queries (query embedded documents)
    // Find users in a specific city
    List<User> findByAddress_City(String city);

    List<User> findByAddress_StateAndAddress_City(String state, String city);

    // Map queries (query flexible metadata)
    // Note: This requires custom query for complex map operations

    // Boolean operations
    List<User> findByMetadataExists(String key);  // Check if map key exists

    // Sorting and limiting
    List<User> findTop10ByRoleOrderByCreatedAtDesc(Role role);

    Optional<User> findFirstByRoleOrderByCreatedAtDesc(Role role);

    // Pagination
    Page<User> findByRole(Role role, Pageable pageable);

    // ========== CUSTOM MONGODB QUERIES ==========

    // MongoDB JSON query syntax
    @Query("{ 'username': ?0 }")
    Optional<User> findByUsernameCustom(String username);

    // Query with multiple conditions
    @Query("{ 'role': ?0, 'createdAt': { $gte: ?1 } }")
    List<User> findByRoleAndCreatedAfter(Role role, LocalDateTime date);

    // Query nested fields
    @Query("{ 'address.city': ?0 }")
    List<User> findByCityCustom(String city);

    // Query arrays - check if array contains value
    @Query("{ 'interests': ?0 }")
    List<User> findByInterest(String interest);

    // Query arrays - check if array contains ALL values
    @Query("{ 'interests': { $all: ?0 } }")
    List<User> findByAllInterests(List<String> interests);

    // Query maps - check if map has specific key-value
    @Query("{ 'metadata.?0': ?1 }")
    List<User> findByMetadataField(String key, Object value);

    // Regex query (pattern matching)
    @Query("{ 'username': { $regex: ?0, $options: 'i' } }")
    // $options: 'i' makes it case-insensitive
    List<User> findByUsernameRegex(String pattern);

    // Complex query with multiple operators
    @Query("{ $or: [ { 'username': ?0 }, { 'email': ?0 } ] }")
    Optional<User> findByUsernameOrEmail(String value);

    // Range query
    @Query("{ 'createdAt': { $gte: ?0, $lte: ?1 } }")
    List<User> findByCreatedAtBetween(LocalDateTime start, LocalDateTime end);

    // Projection - return only specific fields
    @Query(value = "{ 'role': ?0 }", fields = "{ 'username': 1, 'email': 1 }")
    // fields: 1 = include, 0 = exclude
    List<User> findUsernameAndEmailByRole(Role role);

    // Sort in query
    @Query(value = "{ 'role': ?0 }", sort = "{ 'createdAt': -1 }")
    // -1 = descending, 1 = ascending
    List<User> findByRoleSortedByCreatedAt(Role role);

    // Count query
    @Query(value = "{ 'role': ?0 }", count = true)
    long countByRoleCustom(Role role);

    // Delete query
    @Query(value = "{ 'createdAt': { $lt: ?0 } }", delete = true)
    List<User> deleteByCreatedAtBefore(LocalDateTime date);

    // Text search (requires text index)
    @Query("{ $text: { $search: ?0 } }")
    List<User> fullTextSearch(String searchTerm);

    // Aggregation-like query
    @Query("{ 'interests': { $size: { $gte: ?0 } } }")
    List<User> findByInterestsCountGreaterThan(int count);
}

Article Repository with MongoDB-specific queries:

@Repository
public interface ArticleRepository extends MongoRepository<Article, String> {

    // Method name queries
    List<Article> findByAuthor(User author);

    List<Article> findByTagsContaining(String tag);

    List<Article> findByPublishedTrue();

    List<Article> findByPublishedTrueAndViewCountGreaterThan(int minViews);

    // Query embedded array of objects
    // Find articles with comments by specific author
    @Query("{ 'comments.authorName': ?0 }")
    List<Article> findByCommentAuthor(String authorName);

    // Count embedded documents
    @Query("{ 'comments': { $exists: true, $not: { $size: 0 } } }")
    List<Article> findArticlesWithComments();

    // Query by array size
    @Query("{ 'tags': { $size: ?0 } }")
    List<Article> findByTagCount(int tagCount);

    // Update query (using MongoTemplate in service)
    // Note: @Query doesn't support updates directly
    // Use MongoTemplate for update operations

    // Text search on multiple fields
    @Query("{ $text: { $search: ?0 } }")
    List<Article> searchArticles(String keyword);

    // Geospatial query (if you have location data)
    // @Query("{ 'location': { $near: { $geometry: { type: 'Point', coordinates: [?0, ?1] }, $maxDistance: ?2 } } }")
    // List<Article> findNearLocation(double longitude, double latitude, double maxDistance);
}

MongoTemplate - For Advanced Operations

For operations not supported by repository methods, use MongoTemplate:

package com.example.blog.service;

import com.example.blog.model.Article;
import com.example.blog.model.User;
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.query.Query;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Update;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class MongoArticleService {

    private final MongoTemplate mongoTemplate;

    public MongoArticleService(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    // ========== FIND OPERATIONS ==========

    public List<Article> findPublishedArticles() {
        // Create query
        Query query = new Query();
        query.addCriteria(Criteria.where("published").is(true));

        // Execute query
        return mongoTemplate.find(query, Article.class);
    }

    public List<Article> findByMultipleCriteria(String tag, int minViews) {
        Query query = new Query();
        query.addCriteria(
            Criteria.where("tags").in(tag)
                .and("viewCount").gte(minViews)
                .and("published").is(true)
        );

        return mongoTemplate.find(query, Article.class);
    }

    public List<Article> findWithOrCondition(String tag1, String tag2) {
        Query query = new Query();
        query.addCriteria(
            new Criteria().orOperator(
                Criteria.where("tags").in(tag1),
                Criteria.where("tags").in(tag2)
            )
        );

        return mongoTemplate.find(query, Article.class);
    }

    // ========== UPDATE OPERATIONS ==========

    public void incrementViewCount(String articleId) {
        Query query = new Query(Criteria.where("_id").is(articleId));

        Update update = new Update();
        update.inc("viewCount", 1);  // Increment by 1

        mongoTemplate.updateFirst(query, update, Article.class);
        // updateFirst - updates first matching document
        // updateMulti - updates all matching documents
    }

    public void addTag(String articleId, String tag) {
        Query query = new Query(Criteria.where("_id").is(articleId));

        Update update = new Update();
        update.addToSet("tags", tag);  // Add to array if not exists

        mongoTemplate.updateFirst(query, update, Article.class);
    }

    public void removeTag(String articleId, String tag) {
        Query query = new Query(Criteria.where("_id").is(articleId));

        Update update = new Update();
        update.pull("tags", tag);  // Remove from array

        mongoTemplate.updateFirst(query, update, Article.class);
    }

    public void addComment(String articleId, String authorName, String content) {
        Query query = new Query(Criteria.where("_id").is(articleId));

        // Create comment object
        Comment comment = new Comment(authorName, content);

        Update update = new Update();
        update.push("comments", comment);  // Add to array

        mongoTemplate.updateFirst(query, update, Article.class);
    }

    public void updateNestedField(String userId, String newCity) {
        Query query = new Query(Criteria.where("_id").is(userId));

        Update update = new Update();
        update.set("address.city", newCity);  // Update nested field

        mongoTemplate.updateFirst(query, update, User.class);
    }

    // ========== AGGREGATION OPERATIONS ==========

    public long getTotalViewsByAuthor(User author) {
        Query query = new Query(Criteria.where("author.$id").is(author.getId()));

        List<Article> articles = mongoTemplate.find(query, Article.class);

        return articles.stream()
            .mapToLong(Article::getViewCount)
            .sum();
    }

    // ========== DELETE OPERATIONS ==========

    public void deleteUnpublishedOldArticles(LocalDateTime beforeDate) {
        Query query = new Query();
        query.addCriteria(
            Criteria.where("published").is(false)
                .and("createdAt").lt(beforeDate)
        );

        mongoTemplate.remove(query, Article.class);
    }
}

Key Differences: MongoDB vs SQL (JPA)

When to Use MongoDB vs SQL

Use MongoDB when:

• Schema changes frequently

• Need to store hierarchical/nested data

• Need horizontal scaling

• Working with semi-structured data

• High write throughput required

Use SQL when:

• Complex relationships between entities

• Need ACID transactions

• Data integrity is critical

• Complex queries with joins

• Structured data with fixed schema

Enable Auditing (Auto-set createdAt/updatedAt)

package com.example.blog.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.config.EnableMongoAuditing;

@Configuration
@EnableMongoAuditing  // Enable automatic auditing
public class MongoConfig {
    // This enables @CreatedDate and @LastModifiedDate annotations
}

Building REST APIs - Everything You Need

REST Fundamentals - Deep Understanding

REST (Representational State Transfer) is an architectural style for building web services.

Core Principles:

1. Client-Server Architecture: Separation of concerns

2. Stateless: Each request contains all information needed

3. Cacheable: Responses should indicate if they can be cached

4. Uniform Interface: Consistent way to interact with resources

5. Layered System: Client doesn't know if connected directly to server

6. Code on Demand (optional): Server can send executable code

Resources: Everything is a resource (user, article, comment)

• Identified by URIs: /api/users/123

• Manipulated through representations (JSON, XML)

• Self-descriptive messages

HTTP Methods (Verbs):

Idempotent: Multiple identical requests have same effect as single request Safe: Doesn't modify server state

HTTP Status Codes:

Creating REST Controllers - Complete Guide

Basic Controller Structure:

package com.example.blog.controller;

import com.example.blog.model.User;
import com.example.blog.dto.*;
import com.example.blog.service.UserService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

import jakarta.validation.Valid;
import java.net.URI;
import java.util.List;

@RestController  // @Controller + @ResponseBody
// @Controller: Marks this as a Spring MVC controller
// @ResponseBody: All methods return data (not view names)
// @RestController combines both
@RequestMapping("/api/users")  // Base path for all endpoints in this controller
// All methods will be prefixed with /api/users
@CrossOrigin(origins = "*")  // Enable CORS (Cross-Origin Resource Sharing)
// Allow requests from different origins (for frontend apps)
public class UserController {

    // Dependency injection (constructor injection - recommended)
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    // ========== GET REQUESTS ==========

    /**
     * GET /api/users
     * Get all users
     * Returns: 200 OK with list of users
     */
    @GetMapping  // Shortcut for @RequestMapping(method = RequestMethod.GET)
    public ResponseEntity<List<UserDTO>> getAllUsers() {
        // ResponseEntity allows you to control:
        // - HTTP status code
        // - Response headers
        // - Response body

        List<UserDTO> users = userService.getAllUsers();

        return ResponseEntity.ok(users);
        // ResponseEntity.ok() = 200 OK status
        // Equivalent to: new ResponseEntity<>(users, HttpStatus.OK)
    }

    /**
     * GET /api/users/123
     * Get user by ID
     * @param id - extracted from URL path
     * Returns: 200 OK with user, or 404 if not found
     */
    @GetMapping("/{id}")  // {id} is a path variable
    public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) {
        // @PathVariable extracts value from URL path
        // /api/users/123 → id = 123

        UserDTO user = userService.getUserById(id);
        return ResponseEntity.ok(user);
        // If user not found, service throws exception (handled globally)
    }

    /**
     * GET /api/users/username/john_doe
     * Get user by username
     */
    @GetMapping("/username/{username}")
    public ResponseEntity<UserDTO> getUserByUsername(@PathVariable String username) {
        UserDTO user = userService.getUserByUsername(username);
        return ResponseEntity.ok(user);
    }

    /**
     * GET /api/users/search?username=john&email=john@example.com
     * Search users with query parameters
     * @param username - optional query parameter
     * @param email - optional query parameter
     */
    @GetMapping("/search")
    public ResponseEntity<List<UserDTO>> searchUsers(
            @RequestParam(required = false) String username,
            // @RequestParam extracts from query string
            // required = false makes it optional
            // /api/users/search?username=john

            @RequestParam(required = false) String email) {

        List<UserDTO> results = userService.searchUsers(username, email);
        return ResponseEntity.ok(results);
    }

    /**
     * GET /api/users?page=0&size=10&sort=username
     * Get users with pagination
     */
    @GetMapping
    public ResponseEntity<Page<UserDTO>> getUsersPaginated(
            @RequestParam(defaultValue = "0") int page,
            // defaultValue used if parameter not provided
            @RequestParam(defaultValue = "10") int size,
            @RequestParam(defaultValue = "username") String sort) {

        Page<UserDTO> users = userService.getUsers(page, size, sort);
        return ResponseEntity.ok(users);
    }

    // ========== POST REQUESTS ==========

    /**
     * POST /api/users
     * Create new user
     * Request body: JSON representation of CreateUserRequest
     * Returns: 201 Created with created user and Location header
     */
    @PostMapping
    public ResponseEntity<UserDTO> createUser(
            @Valid @RequestBody CreateUserRequest request) {
        // @RequestBody: Deserialize JSON from request body to Java object
        // @Valid: Trigger Bean Validation on the request object
        // If validation fails, throws MethodArgumentNotValidException

        UserDTO created = userService.createUser(request);

        // Build Location header: /api/users/123
        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()  // Current request URI: /api/users
            .path("/{id}")  // Append /{id}
            .buildAndExpand(created.getId())  // Replace {id} with actual ID
            .toUri();  // Convert to URI object

        return ResponseEntity
            .created(location)  // 201 Created status with Location header
            .body(created);  // Response body
    }

    // ========== PUT REQUESTS ==========

    /**
     * PUT /api/users/123
     * Update user (full replacement)
     * Request body: Complete user data
     * Returns: 200 OK with updated user
     */
    @PutMapping("/{id}")
    public ResponseEntity<UserDTO> updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UpdateUserRequest request) {

        UserDTO updated = userService.updateUser(id, request);
        return ResponseEntity.ok(updated);
    }

    // ========== PATCH REQUESTS ==========

    /**
     * PATCH /api/users/123
     * Partial update (update only provided fields)
     * Request body: Fields to update
     * Returns: 200 OK with updated user
     */
    @PatchMapping("/{id}")
    public ResponseEntity<UserDTO> patchUser(
            @PathVariable Long id,
            @RequestBody Map<String, Object> updates) {
        // Map allows flexible updates
        // Client sends only fields to update:
        // { "email": "newemail@example.com", "bio": "New bio" }

        UserDTO patched = userService.patchUser(id, updates);
        return ResponseEntity.ok(patched);
    }

    // ========== DELETE REQUESTS ==========

    /**
     * DELETE /api/users/123
     * Delete user
     * Returns: 204 No Content (success with no response body)
     */
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);

        return ResponseEntity.noContent().build();
        // 204 No Content - successful deletion, no response body
        // Void type indicates no response body
    }

    // ========== CUSTOM OPERATIONS ==========

    /**
     * POST /api/users/123/activate
     * Custom action on resource
     */
    @PostMapping("/{id}/activate")
    public ResponseEntity<UserDTO> activateUser(@PathVariable Long id) {
        UserDTO activated = userService.activateUser(id);
        return ResponseEntity.ok(activated);
    }

    /**
     * POST /api/users/123/deactivate
     */
    @PostMapping("/{id}/deactivate")
    public ResponseEntity<UserDTO> deactivateUser(@PathVariable Long id) {
        UserDTO deactivated = userService.deactivateUser(id);
        return ResponseEntity.ok(deactivated);
    }

    // ========== REQUEST HEADER EXAMPLES ==========

    /**
     * Extract custom header from request
     */
    @GetMapping("/with-header")
    public ResponseEntity<String> handleWithHeader(
            @RequestHeader("X-Custom-Header") String customHeader) {
        // Extract value from request header
        return ResponseEntity.ok("Header value: " + customHeader);
    }

    /**
     * Extract authorization header
     */
    @GetMapping("/protected")
    public ResponseEntity<String> protectedEndpoint(
            @RequestHeader("Authorization") String authHeader) {
        // authHeader = "Bearer eyJhbGc..."
        return ResponseEntity.ok("Authorized");
    }

    // ========== COOKIE EXAMPLES ==========

    /**
     * Extract cookie value
     */
    @GetMapping("/with-cookie")
    public ResponseEntity<String> handleWithCookie(
            @CookieValue("sessionId") String sessionId) {
        return ResponseEntity.ok("Session ID: " + sessionId);
    }

    // ========== RESPONSE CUSTOMIZATION ==========

    /**
     * Custom response with headers
     */
    @GetMapping("/custom-response")
    public ResponseEntity<UserDTO> customResponse() {
        UserDTO user = userService.getSampleUser();

        return ResponseEntity
            .ok()  // 200 OK
            .header("X-Custom-Header", "Custom Value")  // Add custom header
            .header("X-Total-Count", "100")  // Add another header
            .body(user);  // Response body
    }

    /**
     * Different status codes based on condition
     */
    @GetMapping("/conditional/{id}")
    public ResponseEntity<UserDTO> conditionalResponse(@PathVariable Long id) {
        Optional<UserDTO> user = userService.findUserById(id);

        if (user.isPresent()) {
            return ResponseEntity.ok(user.get());  // 200 OK
        } else {
            return ResponseEntity.notFound().build();  // 404 Not Found
        }
    }

    // ========== FILE UPLOAD ==========

    /**
     * Upload user profile picture
     */
    @PostMapping("/{id}/profile-picture")
    public ResponseEntity<String> uploadProfilePicture(
            @PathVariable Long id,
            @RequestParam("file") MultipartFile file) {
        // MultipartFile handles file uploads

        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("File is empty");
        }

        String fileUrl = userService.uploadProfilePicture(id, file);
        return ResponseEntity.ok(fileUrl);
    }
}

Complete Article Controller Example

@RestController
@RequestMapping("/api/articles")
public class ArticleController {

    private final ArticleService articleService;

    public ArticleController(ArticleService articleService) {
        this.articleService = articleService;
    }

    /**
     * GET /api/articles?page=0&size=10&sort=createdAt&dir=desc
     */
    @GetMapping
    public ResponseEntity<Page<ArticleDTO>> getArticles(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size,
            @RequestParam(defaultValue = "createdAt") String sort,
            @RequestParam(defaultValue = "desc") String dir) {

        Page<ArticleDTO> articles = articleService.getArticles(page, size, sort, dir);
        return ResponseEntity.ok(articles);
    }

    /**
     * GET /api/articles/123
     */
    @GetMapping("/{id}")
    public ResponseEntity<ArticleDTO> getArticle(@PathVariable Long id) {
        ArticleDTO article = articleService.getArticleById(id);

        // Increment view count asynchronously
        articleService.incrementViewCountAsync(id);

        return ResponseEntity.ok(article);
    }

    /**
     * POST /api/articles
     */
    @PostMapping
    public ResponseEntity<ArticleDTO> createArticle(
            @Valid @RequestBody CreateArticleRequest request,
            @AuthenticationPrincipal UserDetails userDetails) {
        // @AuthenticationPrincipal extracts authenticated user from security context

        ArticleDTO created = articleService.createArticle(request, userDetails.getUsername());

        URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();

        return ResponseEntity.created(location).body(created);
    }

    /**
     * PUT /api/articles/123
     */
    @PutMapping("/{id}")
    public ResponseEntity<ArticleDTO> updateArticle(
            @PathVariable Long id,
            @Valid @RequestBody UpdateArticleRequest request,
            @AuthenticationPrincipal UserDetails userDetails) {

        ArticleDTO updated = articleService.updateArticle(id, request, userDetails.getUsername());
        return ResponseEntity.ok(updated);
    }

    /**
     * DELETE /api/articles/123
     */
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteArticle(
            @PathVariable Long id,
            @AuthenticationPrincipal UserDetails userDetails) {

        articleService.deleteArticle(id, userDetails.getUsername());
        return ResponseEntity.noContent().build();
    }

    /**
     * POST /api/articles/123/publish
     */
    @PostMapping("/{id}/publish")
    public ResponseEntity<ArticleDTO> publishArticle(
            @PathVariable Long id,
            @AuthenticationPrincipal UserDetails userDetails) {

        ArticleDTO published = articleService.publishArticle(id, userDetails.getUsername());
        return ResponseEntity.ok(published);
    }

    /**
     * GET /api/articles/search?q=spring boot
     */
    @GetMapping("/search")
    public ResponseEntity<List<ArticleDTO>> searchArticles(
            @RequestParam("q") String query) {

        List<ArticleDTO> results = articleService.searchArticles(query);
        return ResponseEntity.ok(results);
    }

    /**
     * GET /api/articles/tag/spring-boot
     */
    @GetMapping("/tag/{tagName}")
    public ResponseEntity<List<ArticleDTO>> getArticlesByTag(
            @PathVariable String tagName) {

        List<ArticleDTO> articles = articleService.getArticlesByTag(tagName);
        return ResponseEntity.ok(articles);
    }

    /**
     * GET /api/articles/author/123
     */
    @GetMapping("/author/{authorId}")
    public ResponseEntity<List<ArticleDTO>> getArticlesByAuthor(
            @PathVariable Long authorId) {

        List<ArticleDTO> articles = articleService.getArticlesByAuthor(authorId);
        return ResponseEntity.ok(articles);
    }
}

DTO Pattern and Bean Validation - Complete Guide

DTO (Data Transfer Object) is a pattern used to transfer data between layers.

Why use DTOs?

1. Separation of Concerns: API contract separate from database schema

2. Security: Don't expose internal entity structure

3. Flexibility: API can change independently from database

4. Validation: Centralized validation rules

5. Hide Sensitive Data: Never expose passwords, internal IDs, etc.

Complete DTO Examples:

package com.example.blog.dto.request;

import jakarta.validation.constraints.*;
import java.time.LocalDate;

/**
 * DTO for creating a new user
 * Used in POST /api/users
 */
public class CreateUserRequest {

    @NotBlank(message = "Username is required")
    // @NotBlank: String cannot be null, empty, or whitespace only
    // Different from @NotNull (allows empty) and @NotEmpty (allows whitespace)
    @Size(min = 3, max = 50, message = "Username must be between 3 and 50 characters")
    // @Size: Validates string length or collection size
    @Pattern(regexp = "^[a-zA-Z0-9_]+$",
             message = "Username can only contain letters, numbers, and underscores")
    // @Pattern: Regular expression validation
    private String username;

    @NotBlank(message = "Email is required")
    @Email(message = "Email must be valid")
    // @Email: Validates email format using RFC 5322 standard
    // Checks format like: user@domain.com
    private String email;

    @NotBlank(message = "Password is required")
    @Size(min = 8, max = 100, message = "Password must be between 8 and 100 characters")
    @Pattern(regexp = "^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%^&+=]).*$",
             message = "Password must contain at least one digit, one lowercase, one uppercase, and one special character")
    // Password strength validation
    private String password;

    @Size(max = 500, message = "Bio cannot exceed 500 characters")
    // Optional field - no @NotBlank
    private String bio;

    @Past(message = "Birth date must be in the past")
    // @Past: Date must be in the past
    // @Future: Date must be in the future
    private LocalDate birthDate;

    @Min(value = 18, message = "Must be at least 18 years old")
    @Max(value = 120, message = "Age cannot exceed 120")
    // @Min/@Max: Numeric range validation
    private Integer age;

    @NotNull(message = "Terms acceptance is required")
    @AssertTrue(message = "You must accept the terms and conditions")
    // @AssertTrue: Boolean must be true
    // @AssertFalse: Boolean must be false
    private Boolean acceptTerms;

    @NotEmpty(message = "At least one interest is required")
    // @NotEmpty: Collection/Array cannot be null or empty
    private List<String> interests;

    // Nested object validation
    @Valid  // IMPORTANT: Triggers validation on nested object
    @NotNull(message = "Address is required")
    private AddressDTO address;

    // Constructors
    public CreateUserRequest() {}

    // Getters and setters
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }

    public String getBio() { return bio; }
    public void setBio(String bio) { this.bio = bio; }

    public LocalDate getBirthDate() { return birthDate; }
    public void setBirthDate(LocalDate birthDate) { this.birthDate = birthDate; }

    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }

    public Boolean getAcceptTerms() { return acceptTerms; }
    public void setAcceptTerms(Boolean acceptTerms) { this.acceptTerms = acceptTerms; }

    public List<String> getInterests() { return interests; }
    public void setInterests(List<String> interests) { this.interests = interests; }

    public AddressDTO getAddress() { return address; }
    public void setAddress(AddressDTO address) { this.address = address; }
}

/**
 * Nested DTO for address
 */
public class AddressDTO {

    @NotBlank(message = "Street is required")
    private String street;

    @NotBlank(message = "City is required")
    private String city;

    @NotBlank(message = "State is required")
    @Size(min = 2, max = 2, message = "State must be 2 characters")
    private String state;

    @NotBlank(message = "Zip code is required")
    @Pattern(regexp = "^\\d{5}(-\\d{4})?$", message = "Invalid zip code format")
    // Matches: 12345 or 12345-6789
    private String zipCode;

    // Getters and setters...
}

/**
 * Response DTO - what the API returns
 * NEVER include sensitive data like passwords!
 */
public class UserDTO {

    private Long id;
    private String username;
    private String email;
    // NO password field - NEVER expose passwords
    private String bio;
    private LocalDate birthDate;
    private String role;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    private List<String> interests;
    private AddressDTO address;

    // Constructors
    public UserDTO() {}

    // Full constructor for easy creation
    public UserDTO(Long id, String username, String email, String bio,
                   LocalDate birthDate, String role, LocalDateTime createdAt) {
        this.id = id;
        this.username = username;
        this.email = email;
        this.bio = bio;
        this.birthDate = birthDate;
        this.role = role;
        this.createdAt = createdAt;
    }

    // Getters and setters...
}

/**
 * DTO for updating user
 * All fields optional - only update what's provided
 */
public class UpdateUserRequest {

    @Email(message = "Email must be valid")
    // No @NotBlank - email is optional in update
    private String email;

    @Size(max = 500, message = "Bio cannot exceed 500 characters")
    private String bio;

    @Past(message = "Birth date must be in the past")
    private LocalDate birthDate;

    @Valid
    private AddressDTO address;

    private List<String> interests;

    // Getters and setters...
}

Complete Validation Annotations Reference:

Custom Validation Annotation:

package com.example.blog.validation;

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

/**
 * Custom annotation to validate that username is unique
 */
@Documented
@Constraint(validatedBy = UniqueUsernameValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface UniqueUsername {

    String message() default "Username already exists";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

/**
 * Validator implementation
 */
@Component
public class UniqueUsernameValidator implements ConstraintValidator<UniqueUsername, String> {

    private final UserRepository userRepository;

    public UniqueUsernameValidator(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @Override
    public void initialize(UniqueUsername constraintAnnotation) {
        // Initialization logic if needed
    }

    @Override
    public boolean isValid(String username, ConstraintValidatorContext context) {
        if (username == null) {
            return true;  // Let @NotNull handle null validation
        }

        // Check if username exists in database
        return !userRepository.existsByUsername(username);
    }
}

// Usage:
public class CreateUserRequest {

    @NotBlank
    @UniqueUsername  // Custom validation
    private String username;

    // Other fields...
}

Validation Groups (Advanced):

/**
 * Marker interfaces for validation groups
 */
public interface ValidationGroups {
    interface Create {}
    interface Update {}
}

/**
 * DTO with group-specific validation
 */
public class UserRequest {

    @Null(groups = Create.class, message = "ID must be null when creating")
    // When creating, ID must be null (server generates it)
    @NotNull(groups = Update.class, message = "ID is required when updating")
    // When updating, ID must be provided
    private Long id;

    @NotBlank(groups = {Create.class, Update.class})
    private String username;

    @NotBlank(groups = Create.class, message = "Password required for new users")
    // Password required only when creating
    @Null(groups = Update.class, message = "Use password change endpoint")
    // Password cannot be updated via regular update
    private String password;

    // Getters and setters...
}

// Controller usage:
@PostMapping
public ResponseEntity<UserDTO> createUser(
        @Validated(Create.class) @RequestBody UserRequest request) {
    // Only Create.class validations are checked
}

@PutMapping("/{id}")
public ResponseEntity<UserDTO> updateUser(
        @PathVariable Long id,
        @Validated(Update.class) @RequestBody UserRequest request) {
    // Only Update.class validations are checked
}

Service Layer with DTO Conversion:

@Service
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final ModelMapper modelMapper;  // For DTO conversion

    public UserService(UserRepository userRepository,
                      PasswordEncoder passwordEncoder,
                      ModelMapper modelMapper) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
        this.modelMapper = modelMapper;
    }

    @Transactional
    public UserDTO createUser(CreateUserRequest request) {
        // 1. Check for duplicates
        if (userRepository.existsByUsername(request.getUsername())) {
            throw new DuplicateResourceException("Username already exists");
        }
        if (userRepository.existsByEmail(request.getEmail())) {
            throw new DuplicateResourceException("Email already exists");
        }

        // 2. Convert DTO to Entity
        User user = new User();
        user.setUsername(request.getUsername());
        user.setEmail(request.getEmail());
        user.setPassword(passwordEncoder.encode(request.getPassword()));
        user.setBio(request.getBio());
        user.setBirthDate(request.getBirthDate());
        user.setRole(Role.USER);

        // 3. Save entity
        User saved = userRepository.save(user);

        // 4. Convert Entity to DTO
        return convertToDTO(saved);
    }

    @Transactional(readOnly = true)
    public UserDTO getUserById(Long id) {
        User user = userRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("User not found: " + id));

        return convertToDTO(user);
    }

    @Transactional
    public UserDTO updateUser(Long id, UpdateUserRequest request) {
        User user = userRepository.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("User not found"));

        // Update only provided fields (null check)
        if (request.getEmail() != null) {
            user.setEmail(request.getEmail());
        }
        if (request.getBio() != null) {
            user.setBio(request.getBio());
        }
        if (request.getBirthDate() != null) {
            user.setBirthDate(request.getBirthDate());
        }

        User updated = userRepository.save(user);
        return convertToDTO(updated);
    }

    // Manual DTO conversion
    private UserDTO convertToDTO(User user) {
        UserDTO dto = new UserDTO();
        dto.setId(user.getId());
        dto.setUsername(user.getUsername());
        dto.setEmail(user.getEmail());
        dto.setBio(user.getBio());
        dto.setBirthDate(user.getBirthDate());
        dto.setRole(user.getRole().name());
        dto.setCreatedAt(user.getCreatedAt());
        dto.setUpdatedAt(user.getUpdatedAt());
        // Note: NO password field in DTO!
        return dto;
    }

    // Or use ModelMapper for automatic conversion
    private UserDTO convertToDTOWithMapper(User user) {
        return modelMapper.map(user, UserDTO.class);
    }
}

Application Configuration - Mastering Profiles

Configuration Files - application.properties vs application.yml

Spring Boot supports two formats for configuration:

application.properties:

# Simple key=value format
# Good for simple configurations

# Server configuration
server.port=8080
server.servlet.context-path=/api

# Database
spring.datasource.url=jdbc:postgresql://localhost:5432/blogdb
spring.datasource.username=postgres
spring.datasource.password=secret

# JPA
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=true

# Logging
logging.level.root=INFO
logging.level.com.example.blog=DEBUG

application.yml (YAML format - recommended for complex configs):

# Hierarchical structure
# More readable for complex configurations

server:
  port: 8080
  servlet:
    context-path: /api
  compression:
    enabled: true
    mime-types: application/json,application/xml,text/html
  error:
    include-message: always
    include-binding-errors: always

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/blogdb
    username: postgres
    password: secret
    hikari:
      maximum-pool-size: 10
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        format_sql: true
        use_sql_comments: true
    open-in-view: false  # Disable for better performance

  jackson:
    serialization:
      write-dates-as-timestamps: false
      indent-output: true
    time-zone: UTC
    default-property-inclusion: non_null

  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB

logging:
  level:
    root: INFO
    com.example.blog: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
  file:
    name: logs/application.log
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"

Configuration Profiles - Environment-Specific Settings

Profiles allow different configurations for different environments.

Profile naming convention:

• application.yml - Base configuration (always loaded)

• application-dev.yml - Development profile

• application-test.yml - Test profile

• application-prod.yml - Production profile

application.yml (Base configuration):

# Common configuration for all environments

spring:
  application:
    name: Blog API

  jackson:
    serialization:
      write-dates-as-timestamps: false
    time-zone: UTC

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"

# Default profile (if none specified)
spring:
  profiles:
    active: dev

application-dev.yml (Development):

# Development environment configuration

server:
  port: 8080

spring:
  datasource:
    url: jdbc:h2:mem:devdb
    # H2 in-memory database for development
    driver-class-name: org.h2.Driver
    username: sa
    password:

  h2:
    console:
      enabled: true  # Enable H2 web console
      path: /h2-console

  jpa:
    hibernate:
      ddl-auto: create-drop  # Recreate schema on each restart
    show-sql: true
    properties:
      hibernate:
        format_sql: true

  sql:
    init:
      mode: always  # Always run schema.sql and data.sql

logging:
  level:
    root: INFO
    com.example.blog: DEBUG
    org.springframework.web: DEBUG

# Custom application properties
app:
  security:
    jwt-secret: dev-secret-key-not-for-production
    jwt-expiration-ms: 86400000  # 24 hours
  cors:
    allowed-origins: http://localhost:3000,http://localhost:4200

application-test.yml (Testing):

# Test environment configuration

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password:

  jpa:
    hibernate:
      ddl-auto: create-drop  # Fresh database for each test
    show-sql: false  # Less noise in test output

  sql:
    init:
      mode: never  # Don't run SQL scripts in tests

logging:
  level:
    root: WARN
    com.example.blog: INFO

app:
  security:
    jwt-secret: test-secret-key
    jwt-expiration-ms: 3600000  # 1 hour

application-prod.yml (Production):

# Production environment configuration

server:
  port: ${SERVER_PORT:8080}  # Use environment variable or default to 8080
  compression:
    enabled: true

spring:
  datasource:
    url: ${DATABASE_URL}  # Read from environment variable
    username: ${DATABASE_USERNAME}
    password: ${DATABASE_PASSWORD}
    hikari:
      maximum-pool-size: 20
      minimum-idle: 10

  jpa:
    hibernate:
      ddl-auto: validate  # NEVER auto-generate in production!
    show-sql: false
    properties:
      hibernate:
        format_sql: false
    open-in-view: false

  sql:
    init:
      mode: never  # NEVER run SQL scripts in production

logging:
  level:
    root: WARN
    com.example.blog: INFO
  file:
    name: /var/log/blog-api/application.log

app:
  security:
    jwt-secret: ${JWT_SECRET}  # MUST be environment variable in production
    jwt-expiration-ms: 3600000  # 1 hour
  cors:
    allowed-origins: https://yourdomain.com,https://www.yourdomain.com

Activating Profiles:

# Method 1: Command line argument
java -jar app.jar --spring.profiles.active=prod

# Method 2: Environment variable
export SPRING_PROFILES_ACTIVE=prod
java -jar app.jar

# Method 3: In application.yml
spring:
  profiles:
    active: dev

# Method 4: Multiple profiles
java -jar app.jar --spring.profiles.active=prod,monitoring

# Method 5: In IDE (IntelliJ IDEA)
# Run Configuration → Environment Variables → SPRING_PROFILES_ACTIVE=dev

Type-Safe Configuration with @ConfigurationProperties

Instead of using @Value for every property, use @ConfigurationProperties for type-safe configuration:

package com.example.blog.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.validation.annotation.Validated;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;
import java.util.List;
import java.util.Map;

/**
 * Type-safe configuration properties
 * Maps to properties with prefix "app"
 */
@Configuration
@ConfigurationProperties(prefix = "app")
@Validated  // Enable validation on configuration properties
public class AppProperties {

    private String name;
    private String version;

    @NotNull
    private Security security = new Security();

    @NotNull
    private Storage storage = new Storage();

    @NotNull
    private Cors cors = new Cors();

    private Pagination pagination = new Pagination();

    // Nested class for security properties
    public static class Security {

        @NotBlank(message = "JWT secret is required")
        private String jwtSecret;

        @Min(value = 3600000, message = "JWT expiration must be at least 1 hour")
        @Max(value = 604800000, message = "JWT expiration cannot exceed 7 days")
        private long jwtExpirationMs;

        private boolean enableCsrf = false;

        // Getters and setters
        public String getJwtSecret() { return jwtSecret; }
        public void setJwtSecret(String jwtSecret) { this.jwtSecret = jwtSecret; }

        public long getJwtExpirationMs() { return jwtExpirationMs; }
        public void setJwtExpirationMs(long jwtExpirationMs) { this.jwtExpirationMs = jwtExpirationMs; }

        public boolean isEnableCsrf() { return enableCsrf; }
        public void setEnableCsrf(boolean enableCsrf) { this.enableCsrf = enableCsrf; }
    }

    // Nested class for storage properties
    public static class Storage {

        @NotBlank(message = "Upload directory is required")
        private String uploadDir = "./uploads";

        @Min(1024)  // Minimum 1KB
        @Max(10485760)  // Maximum 10MB
        private long maxFileSize = 5242880;  // 5MB default

        private List<String> allowedExtensions = List.of("jpg", "jpeg", "png", "pdf");

        // Getters and setters
        public String getUploadDir() { return uploadDir; }
        public void setUploadDir(String uploadDir) { this.uploadDir = uploadDir; }

        public long getMaxFileSize() { return maxFileSize; }
        public void setMaxFileSize(long maxFileSize) { this.maxFileSize = maxFileSize; }

        public List<String> getAllowedExtensions() { return allowedExtensions; }
        public void setAllowedExtensions(List<String> allowedExtensions) {
            this.allowedExtensions = allowedExtensions;
        }
    }

    // Nested class for CORS properties
    public static class Cors {

        private List<String> allowedOrigins = List.of("http://localhost:3000");
        private List<String> allowedMethods = List.of("GET", "POST", "PUT", "PATCH", "DELETE");
        private List<String> allowedHeaders = List.of("*");
        private boolean allowCredentials = true;
        private long maxAge = 3600;

        // Getters and setters...
    }

    // Nested class for pagination
    public static class Pagination {

        @Min(1)
        @Max(100)
        private int defaultPageSize = 10;

        @Min(1)
        @Max(1000)
        private int maxPageSize = 100;

        // Getters and setters...
    }

    // Main class getters and setters
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    public String getVersion() { return version; }
    public void setVersion(String version) { this.version = version; }

    public Security getSecurity() { return security; }
    public void setSecurity(Security security) { this.security = security; }

    public Storage getStorage() { return storage; }
    public void setStorage(Storage storage) { this.storage = storage; }

    public Cors getCors() { return cors; }
    public void setCors(Cors cors) { this.cors = cors; }

    public Pagination getPagination() { return pagination; }
    public void setPagination(Pagination pagination) { this.pagination = pagination; }
}

application.yml configuration:

app:
  name: Blog API
  version: 1.0.0
  security:
    jwt-secret: mySecretKey123456789012345678901234567890
    jwt-expiration-ms: 86400000  # 24 hours
    enable-csrf: false
  storage:
    upload-dir: ./uploads
    max-file-size: 5242880  # 5MB
    allowed-extensions:
      - jpg
      - jpeg
      - png
      - pdf
      - doc
      - docx
  cors:
    allowed-origins:
      - http://localhost:3000
      - http://localhost:4200
    allowed-methods:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE
    allowed-headers: "*"
    allow-credentials: true
    max-age: 3600
  pagination:
    default-page-size: 10
    max-page-size: 100

Using Configuration Properties:

@Service
public class FileUploadService {

    private final AppProperties appProperties;

    public FileUploadService(AppProperties appProperties) {
        this.appProperties = appProperties;
    }

    public String uploadFile(MultipartFile file) {
        // Access configuration
        String uploadDir = appProperties.getStorage().getUploadDir();
        long maxSize = appProperties.getStorage().getMaxFileSize();
        List<String> allowedExt = appProperties.getStorage().getAllowedExtensions();

        // Validate file size
        if (file.getSize() > maxSize) {
            throw new FileTooLargeException("File exceeds maximum size of " + maxSize);
        }

        // Validate file extension
        String filename = file.getOriginalFilename();
        String extension = filename.substring(filename.lastIndexOf(".") + 1);
        if (!allowedExt.contains(extension.toLowerCase())) {
            throw new InvalidFileTypeException("File type not allowed: " + extension);
        }

        // Save file
        Path uploadPath = Paths.get(uploadDir);
        // ... save logic
    }
}