SyntaxPilot
Courses/Low-Level Design/Lesson 33
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Low-Level Design · Lesson 33 of 90

Flyweight pattern

Flyweight patternintrinsic stateextrinsic stateflyweight factorysharing objectsmemory optimizationString poolInteger cachetext editor glyph examplegame particles example

These are the notes for Low-Level Design (LLD) episode 33, the seventh and last structural pattern (with Adapter, Bridge, Composite, Decorator, Facade and Proxy). The Flyweight is about memory: what to do when a program needs a huge number of small objects and they don't fit. We start with a rubber stamp, watch Ravi's Diwali fireworks game crash with OutOfMemoryError, then invent the flyweight by splitting each object's state into a shared part and a unique part. Then we see the same idea inside Java itself: the Integer cache and the String pool. Every program was actually run with javac Main.java && java -cp . Main (Java 21). Outputs are real.

(The name comes from boxing: flyweight is the lightest weight class. These objects are very light.)

1. The real-life idea: one rubber stamp, many marks

At the office counter In code
One "PAID" stamp, used on a thousand bills a day A flyweight: one object shared by many users
The carved design: the same on every mark Intrinsic state: shared, stored inside, never changes
Where you press it: different on every page Extrinsic state: unique each time, passed in from outside
The stamp drawer: you ask for the PAID stamp, you don't carve one The flyweight factory: hands out the shared objects

Intrinsic means "belonging to the thing itself"; extrinsic means "coming from outside".

2. The problem: a million sparks

In Ravi's fireworks game, every spark is a Particle with a position, a colour and a sprite (the small picture drawn for it). The sprite is a 128 × 128 pixel picture at 4 bytes per pixel, 65,536 bytes (64 KB), and every particle has its own copy. A rocket bursts into a million sparks:

import java.util.*;

class Particle {                                         // one spark in a Diwali fireworks game
    final int x, y; final String colour;
    final byte[] sprite = new byte[65536];               // 128 x 128 picture: 64 KB, copied in EVERY spark
    Particle(int x, int y, String colour) { this.x = x; this.y = y; this.colour = colour; }
}
public class Main {
    public static void main(String[] args) {
        Runtime rt = Runtime.getRuntime();
        System.out.println("heap limit: " + rt.maxMemory() / 1_000_000 + " MB");
        List<Particle> sparks = new ArrayList<>();
        String[] colours = {"red", "gold", "green"};
        for (int i = 0; i < 1_000_000; i++) {
            sparks.add(new Particle(i % 1920, i % 1080, colours[i % 3]));
            if (i % 5_000 == 0) System.out.println(i + " sparks");
        }
        System.out.println("done: " + sparks.size());
    }
}
heap limit: 1566 MB
0 sparks
5000 sparks
10000 sparks
15000 sparks
20000 sparks
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
    at Particle.<init>(Main.java:5)
    at Main.main(Main.java:15)

The heap is the memory where Java keeps all objects; it has a maximum size (Runtime.getRuntime().maxMemory(); on this machine about 1.5 GB). A million sparks × 64 KB is about 65 GB, more than forty times the heap, so the program dies with java.lang.OutOfMemoryError: Java heap space: the heap is full. (1_000_000 is just 1000000; Java allows underscores in numbers for readability.)

Why it failed

Memory
Heap limit here about 1.5 GB
1,000,000 sprite copies × 64 KB about 65 GB
But only 3 different pictures (3 colours) × 64 KB 192 KB
What each spark really needs: x, y and a reference a few tens of MB in total
  • The same picture was copied into every object.
  • Split each spark's state: intrinsic (colour + sprite: only 3 kinds) and extrinsic (x and y: one per spark).
  • Store the shared part once and let a million sparks point to it.

3. The fix: share the heavy part

import java.util.*;
class SparkType {                                        // flyweight: the SHARED part
    final String colour; final byte[] sprite = new byte[65536];
    SparkType(String colour) { this.colour = colour; }
    void draw(int x, int y) { /* paint sprite at (x, y) */ }
}
class SparkTypes {                                       // flyweight factory
    private static final Map<String, SparkType> cache = new HashMap<>();
    static SparkType of(String colour) { return cache.computeIfAbsent(colour, SparkType::new); }
    static int count() { return cache.size(); }
}
class Particle {                                         // only the UNIQUE part
    final int x, y; final SparkType type;
    Particle(int x, int y, SparkType type) { this.x = x; this.y = y; this.type = type; }
}
public class Main {
    public static void main(String[] args) {
        Runtime rt = Runtime.getRuntime();
        List<Particle> sparks = new ArrayList<>();
        String[] colours = {"red", "gold", "green"};
        for (int i = 0; i < 1_000_000; i++)
            sparks.add(new Particle(i % 1920, i % 1080, SparkTypes.of(colours[i % 3])));
        System.gc();
        System.out.println("sparks: " + sparks.size() + ", SparkType objects: " + SparkTypes.count());
        System.out.println("memory used: about " + (rt.totalMemory() - rt.freeMemory()) / 1_000_000 + " MB");
        System.out.println("same object? " + (sparks.get(0).type == sparks.get(3).type));
    }
}
sparks: 1000000, SparkType objects: 3
memory used: about 31 MB
same object? true
  • SparkType is the flyweight: colour and sprite, the intrinsic state. Its draw(x, y) receives the extrinsic state as arguments when it is used.
  • SparkTypes is the flyweight factory. computeIfAbsent(colour, SparkType::new) means: if the map already has this colour, return that object; if not, create one with new SparkType(colour), store it and return it. So each colour is created exactly once. (SparkType::new is a constructor reference, a short way to say "call this constructor", episode 5.)
  • Particle now holds only the unique part: x, y and a reference to its shared SparkType. A reference is just the address of an object (a few bytes), not a copy of it.
  • System.gc() asks the garbage collector (the part of Java that frees memory no longer used) to run, so the memory figure is fairer. totalMemory() - freeMemory() is the heap in use.
  • sparks.get(0).type == sparks.get(3).type is true: both red sparks point at the same object (== on objects compares identity, not contents).

The exact memory number varies a little from run to run, but it stays in the tens of megabytes instead of 65 GB.

4. It has a name: the Flyweight pattern

Intent (SourceMaking, Flyweight): "Use sharing to support large numbers of fine-grained objects efficiently." Fine-grained means small and very many, like sparks or letters. The same page explains: "Intrinsic state is stored (shared) in the Flyweight object. Extrinsic state is stored or computed by client objects, and passed to the Flyweight when its operations are invoked."

Role Meaning In our code
Flyweight The shared object holding intrinsic state; gets extrinsic state as arguments SparkType, Glyph
Flyweight factory Creates flyweights once per key and hands out the same one each time SparkTypes, GlyphFactory
Context / client Holds the extrinsic state and a reference to its flyweight Particle

5. Letters in a text editor

A text editor could make every character on screen an object, a glyph (the drawn shape of one letter). A document has millions of characters but only a few dozen different letters.

import java.util.*;

class Glyph {                                                // flyweight: one per letter
    final char letter; final String font;                     // intrinsic: same everywhere
    Glyph(char letter) { this.letter = letter; this.font = "Serif 12"; }
    void draw(int row, int col) { /* paint at (row, col) */ } // extrinsic: passed in
}
class GlyphFactory {
    private static final Map<Character, Glyph> pool = new HashMap<>();
    static Glyph of(char c) { return pool.computeIfAbsent(c, Glyph::new); }
    static int created() { return pool.size(); }
}
public class Main {
    public static void main(String[] args) {
        String text = "chai chai chai, garam garam chai!";
        List<Glyph> line = new ArrayList<>();
        for (char c : text.toCharArray()) line.add(GlyphFactory.of(c));
        for (int col = 0; col < line.size(); col++) line.get(col).draw(0, col);
        System.out.println("characters on screen: " + line.size());
        System.out.println("Glyph objects created: " + GlyphFactory.created());
        System.out.println("every 'a' is one object? " + (line.get(2) == line.get(7)));
    }
}
characters on screen: 33
Glyph objects created: 10
every 'a' is one object? true

The letter and font are intrinsic; the row and column are extrinsic, passed to draw. 33 characters need only 10 Glyph objects (c h a i, space, comma, g r m, !), and every a is the same object. A book with a million characters would still need only a few dozen.

6. Java does it too: the Integer cache and the String pool

public class Main {
    public static void main(String[] args) {
        Integer a = 127, b = 127;                       // autoboxing calls Integer.valueOf
        Integer c = 128, d = 128;
        System.out.println("127 == 127 ? " + (a == b));
        System.out.println("128 == 128 ? " + (c == d));
        System.out.println("128 equals 128 ? " + c.equals(d));

        String s1 = "chai", s2 = "chai";                // literals come from the String pool
        String s3 = new String("chai");                 // a brand-new object
        System.out.println("s1 == s2 ? " + (s1 == s2));
        System.out.println("s1 == s3 ? " + (s1 == s3));
        System.out.println("s1 == s3.intern() ? " + (s1 == s3.intern()));
    }
}
127 == 127 ? true
128 == 128 ? false
128 equals 128 ? true
s1 == s2 ? true
s1 == s3 ? false
s1 == s3.intern() ? true
  • Autoboxing: Integer a = 127; turns the int into an Integer object by calling Integer.valueOf(127).
  • The Integer cache: the Integer.valueOf documentation says it "will always cache values in the range -128 to 127, inclusive", so those Integer objects are shared flyweights and 127 == 127 is true. 128 is outside the range, so you get two different objects and == is false. (The upper bound can be raised with the JVM option -XX:AutoBoxCacheMax.) equals compares values, so 128 equals 128 is true.
  • The String pool: string literals (text in double quotes in your code) are taken from a pool of shared String objects, so s1 == s2 is true. new String("chai") always makes a new object (false). intern() returns the pool's shared copy (true). Sharing is safe because String is immutable (episode 5).

Interview lesson: never compare Integer or String objects with ==. It works by luck for small numbers and literals and fails otherwise. Use equals.

7. The trap: changing shared state

A flyweight is shared, so changing it changes it for everyone:

import java.util.*;

class SparkType {                                        // shared by many sparks
    String colour;                                       // NOT final: anyone can change it
    SparkType(String colour) { this.colour = colour; }
}
class SparkTypes {
    private static final Map<String, SparkType> cache = new HashMap<>();
    static SparkType of(String colour) { return cache.computeIfAbsent(colour, SparkType::new); }
}
record Particle(int x, int y, SparkType type) { }
public class Main {
    public static void main(String[] args) {
        List<Particle> sparks = new ArrayList<>();
        String[] colours = {"red", "gold", "green"};
        for (int i = 0; i < 9; i++) sparks.add(new Particle(i, i, SparkTypes.of(colours[i % 3])));
        sparks.get(0).type().colour = "blue";            // "make just this one spark blue"
        long blue = sparks.stream().filter(p -> p.type().colour.equals("blue")).count();
        System.out.println("blue sparks: " + blue + " of " + sparks.size());
    }
}
blue sparks: 3 of 9

"Make just spark 0 blue" turned all three red sparks blue (with a million sparks, a third of the sky). (record Particle(int x, int y, SparkType type) is a record, a short class whose fields are set once, episode 3; type() reads its field.)

The fix: flyweights must be immutable (they can't change after creation). Make the field final, and the compiler stops the bug:

import java.util.*;

class SparkType {                                        // shared by many sparks
    final String colour;                                 // final: shared state is read-only
    SparkType(String colour) { this.colour = colour; }
}
class SparkTypes {
    private static final Map<String, SparkType> cache = new HashMap<>();
    static SparkType of(String colour) { return cache.computeIfAbsent(colour, SparkType::new); }
}
record Particle(int x, int y, SparkType type) { }
public class Main {
    public static void main(String[] args) {
        List<Particle> sparks = new ArrayList<>();
        String[] colours = {"red", "gold", "green"};
        for (int i = 0; i < 9; i++) sparks.add(new Particle(i, i, SparkTypes.of(colours[i % 3])));
        sparks.get(0).type().colour = "blue";            // "make just this one spark blue"
        long blue = sparks.stream().filter(p -> p.type().colour.equals("blue")).count();
        System.out.println("blue sparks: " + blue + " of " + sparks.size());
    }
}
Main.java:17: error: cannot assign a value to final variable colour
        sparks.get(0).type().colour = "blue";            // "make just this one spark blue"
                            ^
1 error

To make one spark blue, ask the factory for the blue type and give that spark a new Particle with it: sparks.set(0, new Particle(0, 0, SparkTypes.of("blue"))).

8. When a flyweight helps (and when it doesn't)

Use it when all of these hold:

  • there are very many objects (thousands to millions: sparks, letters, map tiles, trees in a game);
  • most of their state is the same, with only a few distinct kinds;
  • the unique part is small and can be passed in or kept outside.

Skip it for a few hundred objects: the extra code costs more than the memory it saves. Measure first.

Flyweight vs Object Pool (episode 26): a flyweight is used by many objects at the same time and never changes; a pooled object is lent to one user at a time, used, and returned.

Common mistakes

Mistake Exact message / symptom Why Fix
A 64 KB sprite inside every spark Exception in thread "main" java.lang.OutOfMemoryError: Java heap space Shared data copied a million times Move it into a shared flyweight
Flyweight fields not final no error: blue sparks: 3 of 9 Changing a shared object changes all its users final fields; immutable flyweights
Assigning to a final flyweight field error: cannot assign a value to final variable colour The compiler protecting shared state Get a different flyweight from the factory
Storing x, y inside the flyweight no error: every spark drawn at the same spot Extrinsic state was made shared Keep it in the context; pass it in
Comparing Integers with == no error: 128 == 128 ? false Only -128..127 are cached Use equals()
Creating flyweights with new instead of the factory no error: memory still huge Nothing is shared Always go through the factory

Mini project: a forest

A map game draws 1,000,000 trees of 5 species. Each species has a 2 KB texture. Build TreeType (flyweight), TreeTypes (factory) and Tree (context with x, y), plant the forest and print how many TreeType objects exist.

Solution
import java.util.*;

class TreeType {                                            // flyweight
    final String species; final byte[] texture = new byte[2048];
    TreeType(String species) { this.species = species; }
    void draw(int x, int y) { /* paint texture at (x, y) */ }
}
class TreeTypes {                                           // factory
    private static final Map<String, TreeType> cache = new HashMap<>();
    static TreeType of(String species) { return cache.computeIfAbsent(species, TreeType::new); }
    static int count() { return cache.size(); }
}
record Tree(int x, int y, TreeType type) { void draw() { type.draw(x, y); } }
public class Main {
    public static void main(String[] args) {
        String[] species = {"Neem", "Mango", "Peepal", "Banyan", "Ashoka"};
        List<Tree> forest = new ArrayList<>();
        for (int i = 0; i < 1_000_000; i++) forest.add(new Tree(i % 5000, i / 5000, TreeTypes.of(species[i % 5])));
        forest.forEach(Tree::draw);
        System.out.println("trees: " + forest.size() + ", TreeType objects: " + TreeTypes.count());
    }
}
trees: 1000000, TreeType objects: 5

Without sharing, the textures alone would be 1,000,000 × 2 KB, about 2 GB.

Practice

1. In a chess game app, which state of a piece is intrinsic and which is extrinsic?

Answer

Intrinsic (shared): the piece type, its colour, its image, how it moves. Extrinsic (unique): its square on the board. So only 12 flyweights (6 types × 2 colours) are needed for any number of games.

2. Why must a flyweight factory return the same object for the same key?

Answer

Because sharing is the whole point. If of("red") made a new SparkType each time, every spark would again have its own sprite and memory would not drop.

3. What does this print, and why? System.out.println(Integer.valueOf(100) == Integer.valueOf(100));

Answer

true: 100 is in the cached range -128..127, so both calls return the same shared Integer. With 1000 it would usually print false.

4. Is String a good flyweight? Why?

Answer

Yes: it is immutable, so sharing it is safe. That's why Java can keep a pool of literals and hand out the same object to every part of the program.

5. Your app has 200 Customer objects, each with a 1 KB profile photo. Flyweight?

Answer

No. 200 × 1 KB is 200 KB, nothing for a modern heap, and each photo is different (nothing to share). The pattern would only add code.

Quick quiz

class Tree {                  // a tree in a map game
    String species;          // "Neem", "Mango" ...
    byte[] bark;             // 2 MB texture
    byte[] leaves;           // 1 MB texture
    int x, y;                // where it stands
    int height, age;         // this tree's own
}
// Which fields go into the shared TreeType?

(a) x, y, height, age (b) species, bark and leaf textures (c) everything (d) nothing: copy it all

Answer

(b). Species and textures are the same for every tree of that kind: intrinsic. Position, height and age differ from tree to tree: extrinsic, kept in each Tree.

Interview questions

  1. What is the Flyweight pattern? A structural pattern that shares objects to support large numbers of fine-grained objects efficiently, by moving the common (intrinsic) state into shared objects.
  2. Intrinsic vs extrinsic state? Intrinsic is shared, stored in the flyweight and context-independent; extrinsic depends on the context, is kept by the client and passed in to the flyweight's methods.
  3. Why must flyweights be immutable? Many clients share one object; a change made for one client would affect all of them.
  4. What does the factory do? Caches flyweights by key and returns the existing one instead of creating a new one.
  5. Examples in the JDK? Integer.valueOf caching -128..127, the String pool and String.intern(), Boolean.TRUE/FALSE.
  6. Why is new Integer(127) == new Integer(127) false? new always creates a new object and bypasses the cache.
  7. Flyweight vs Singleton? A singleton is one instance of a class; a flyweight factory keeps one instance per key (many flyweights of the same class).
  8. Flyweight vs Object Pool? Flyweights are shared at the same time and never change; pooled objects are borrowed one at a time and returned.
  9. Costs? More complex code, extrinsic state passed around, possible thread-safety work in the factory (use ConcurrentHashMap when many threads create flyweights).
  10. When not to use it? Few objects, mostly unique state, or no measured memory problem.

Glossary

Term Meaning, with an example
Flyweight pattern Share one object across many users to save memory. One SparkType per colour
Flyweight The shared object holding intrinsic state. SparkType, Glyph
Intrinsic state Shared state stored in the flyweight that doesn't change. Colour + sprite
Extrinsic state Unique state kept outside and passed in. A spark's x and y
Flyweight factory Creates each flyweight once per key and returns the same one. SparkTypes.of("red")
Context The object holding extrinsic state plus a reference to a flyweight. Particle
Sharing objects Many references pointing at one object instead of many copies
Memory optimization Changing a design so it uses less memory
Fine-grained objects Small objects in very large numbers
Sprite A small picture drawn for a game object
Glyph The drawn shape of one character in a text editor
Heap The memory where Java keeps objects; it has a maximum size
OutOfMemoryError Thrown when the heap is full and no more objects fit
Garbage collector The part of Java that frees memory no longer used
Reference The address of an object; copying it doesn't copy the object
== on objects True only if both sides are the very same object
equals Compares values. c.equals(d)
Autoboxing Java turning an int into an Integer automatically. Integer a = 127;
Integer cache Integer.valueOf always shares the objects for -128 to 127
String pool Java's pool of shared String objects for literals
String literal Text in double quotes in source code. "chai"
intern() Returns the pool's shared copy of a string
Immutable Can't change after creation. String, a final-field flyweight
final field A field that can be assigned only once
computeIfAbsent Map method: return the value for a key, creating and storing it first if missing
Constructor reference SparkType::new: a short way to pass "call this constructor"
Record A short class whose fields are fixed at creation. record Particle(int x, int y, SparkType type)
KB / MB / GB About a thousand / a million / a billion bytes
Object Pool Objects lent out one at a time and returned (episode 26)

Summary

  • A huge number of objects that each carry the same heavy data can run out of heap: OutOfMemoryError.
  • Split the state: intrinsic (shared, inside the flyweight, immutable) and extrinsic (unique, kept outside, passed in).
  • A flyweight factory creates one object per key and hands out the same one every time.
  • Java does this with the Integer cache (-128..127) and the String pool; compare objects with equals, not ==.
  • Flyweights must be immutable. Use the pattern only when there are many objects and memory really is the problem.

Next episode: The Strategy pattern, the first behavioural pattern.