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
SparkTypeis the flyweight: colour and sprite, the intrinsic state. Itsdraw(x, y)receives the extrinsic state as arguments when it is used.SparkTypesis the flyweight factory.computeIfAbsent(colour, SparkType::new)means: if the map already has this colour, return that object; if not, create one withnew SparkType(colour), store it and return it. So each colour is created exactly once. (SparkType::newis a constructor reference, a short way to say "call this constructor", episode 5.)Particlenow holds only the unique part:x,yand a reference to its sharedSparkType. 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).typeistrue: 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 theintinto anIntegerobject by callingInteger.valueOf(127). - The Integer cache: the
Integer.valueOfdocumentation says it "will always cache values in the range -128 to 127, inclusive", so thoseIntegerobjects are shared flyweights and127 == 127istrue. 128 is outside the range, so you get two different objects and==isfalse. (The upper bound can be raised with the JVM option-XX:AutoBoxCacheMax.)equalscompares values, so128 equals 128istrue. - The String pool: string literals (text in double quotes in your code) are taken from a pool of shared
Stringobjects, sos1 == s2istrue.new String("chai")always makes a new object (false).intern()returns the pool's shared copy (true). Sharing is safe becauseStringis 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
- 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.
- 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.
- Why must flyweights be immutable? Many clients share one object; a change made for one client would affect all of them.
- What does the factory do? Caches flyweights by key and returns the existing one instead of creating a new one.
- Examples in the JDK?
Integer.valueOfcaching -128..127, the String pool andString.intern(),Boolean.TRUE/FALSE. - Why is
new Integer(127) == new Integer(127)false?newalways creates a new object and bypasses the cache. - 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).
- Flyweight vs Object Pool? Flyweights are shared at the same time and never change; pooled objects are borrowed one at a time and returned.
- Costs? More complex code, extrinsic state passed around, possible thread-safety work in the factory (use
ConcurrentHashMapwhen many threads create flyweights). - 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.