Lesson 2: Decorator Usage

Object decorators, Java I/O decorators, functional wrappers, wrapper order, side effects, blocklists, truncation, counting, and composition.

scripts/run.sh lesson_2 demo
scripts/run.sh lesson_2 exercise
scripts/apply_answers.sh lesson_2
scripts/run.sh lesson_2 verify
scripts/reset_exercises.sh lesson_2

Lesson README

Lesson 2: Decorator Usage

This lesson focuses on adding behavior by wrapping objects rather than modifying their concrete classes.

120-Minute Plan

Exercise

Use workbook.md for the full two-hour learner path. It includes call-stack tracing, wrapper-order experiments, and side-effect edge cases.

Edit src/exercise/java/tutorial/lesson2/exercise/NotificationDecorators.java.

Functions to implement:

• withPrefix
• withSuffix
• withMessageTransform
• withRateLimitNote
• withAuditTrail
• withBlocklist
• withTruncation
• withCounting
• compose

The stubs return a usable channel, so the lesson compiles and runs before completion.

After applying answers, run scripts/run.sh lesson_2 verify to check prefix/suffix behavior, audit ordering, blocklist short-circuiting, truncation, counting, and decorator composition.

Learner Workbook

Learner Workbook: Lesson 2 Decorator Usage

This workbook is designed to take about two hours. The goal is to understand wrapper behavior deeply enough that you can predict output before running code.

What You Should Understand By The End

• A decorator implements the same interface as the object it wraps.
• A decorator can transform before delegation, after delegation, or both.
• Wrapper order changes behavior.
• Side effects such as audit logs and counters must be placed deliberately.
• Java lambdas can implement single-method interfaces.

0-15 Minutes: Run And Predict

Run:

scripts/reset_exercises.sh lesson_2
scripts/run.sh lesson_2 demo
scripts/run.sh lesson_2 exercise

Before reading the code, predict:

• Which decorator trims text?
• Which decorator lowercases text?
• Which decorator adds metrics?
• Why does the exercise audit log start empty?

15-35 Minutes: Trace The Demo Stack

Open src/demo/java/tutorial/lesson2/demo/DecoratorDemo.java.

Draw this stack on paper:

MetricsDecorator
ProfanityMaskDecorator
LowercaseDecorator
TrimDecorator
PlainTextProcessor

For the input " BUG reports become design signals ", write the value after each wrapper. Then open each decorator class and verify your trace.

Now inspect the Java I/O example:

BufferedReader
InputStreamReader
ByteArrayInputStream

Identify what behavior each layer adds.

35-50 Minutes: Read The Exercise API

Open src/exercise/java/tutorial/lesson2/exercise/NotificationDecorators.java.

Group functions by behavior:

• Message before delegate: withPrefix, withSuffix, withMessageTransform, withTruncation
• Result after delegate: withRateLimitNote
• Side effects: withAuditTrail, withCounting
• Control flow: withBlocklist
• Higher-order composition: compose

For each function, answer: does it call base.send every time, sometimes, or never?

50-95 Minutes: Implement In Rounds

Round 1:

• Implement withPrefix and withSuffix.
• Run scripts/run.sh lesson_2 exercise.

Round 2:

• Implement withMessageTransform.
• Use it with String::trim or message -> message.toUpperCase(Locale.ROOT).

Round 3:

• Implement withRateLimitNote.
• Notice this modifies the returned result, not the original message.

Round 4:

• Implement withAuditTrail.
• Decide whether it records the message before or after another decorator transforms it. The answer depends on where it sits in the wrapper stack.

Round 5:

• Implement withBlocklist.
• Blocked users should not call the base channel.

Round 6:

• Implement withTruncation.
• Test max length 0, exact length, shorter messages, longer messages, and -1.

Round 7:

• Implement withCounting.
• Decide whether blocked sends should count by changing where the counter decorator is placed.

Round 8:

• Implement compose.
• Use the exercise runner to see how listed decorators become nested wrappers.

95-110 Minutes: Verify Answers

Run:

scripts/apply_answers.sh lesson_2
scripts/run.sh lesson_2 verify
scripts/reset_exercises.sh lesson_2

Read any failed assertion as a precise edge-case description. If your code behaves differently, trace wrapper order rather than guessing.

110-120 Minutes: Edge-Case Drill

Try these variations:

• Put audit before prefix, then after prefix. Compare the log.
• Put counting outside blocklist, then inside blocklist. Compare the count.
• Put truncation before suffix, then after suffix. Compare output.
• Use compose with an empty decorator list.
• Block a user and confirm the base channel is not reached.

Reset when done:

scripts/reset_exercises.sh lesson_2

Instructor Notes

Instructor Notes: Lesson 2 Decorator Usage

Session Goal

Teach decorators as object composition: behavior is added by wrapping an object that satisfies the same contract. Learners should be able to trace wrapper order, implement custom decorators, recognize Java I/O decorators, and compare object decorators with functional decorators.

Learning Outcomes

By the end of 120 minutes, learners should be able to:

• Explain the difference between inheritance and wrapping.
• Trace a call through nested decorators in the order Java actually executes it.
• Implement decorators around a NotificationChannel interface.
• Explain why wrapper order can change output and side effects.
• Recognize decorator patterns in Java standard library I/O.

Before Class

Run:

scripts/reset_exercises.sh lesson_2
scripts/run.sh lesson_2 demo
scripts/run.sh lesson_2 exercise

Know the key files:

• src/demo/java/tutorial/lesson2/demo/DecoratorDemo.java
• src/demo/java/tutorial/lesson2/demo/TextProcessorDecorator.java
• src/demo/java/tutorial/lesson2/demo/MetricsDecorator.java
• src/exercise/java/tutorial/lesson2/exercise/NotificationDecorators.java

Minute-By-Minute Plan

Teaching Script

Use this framing:

"A decorator implements the same interface as the object it wraps. That lets callers keep using the same type while behavior accumulates around the base object."

Draw this call stack:

caller
  -> MetricsDecorator
      -> ProfanityMaskDecorator
          -> LowercaseDecorator
              -> TrimDecorator
                  -> PlainTextProcessor

Then explain the subtlety:

"The call enters from the outside, but each decorator chooses whether to transform before delegation, after delegation, or both. That is why order matters."

For the Java I/O example:

• ByteArrayInputStream supplies bytes.
• InputStreamReader decodes bytes into characters.
• BufferedReader adds efficient line reading.

This gives learners a standard-library anchor for the same pattern used in the custom demo.

Exercise Facilitation

Learners edit NotificationDecorators.java.

Recommended order:

• Implement withPrefix because it is pure transformation before delegation.
• Implement withSuffix and withMessageTransform.
• Implement withRateLimitNote because it transforms after delegation.
• Implement withAuditTrail because it adds side effects before delegation.
• Implement withBlocklist, withTruncation, withCounting, and compose.

Hints to give:

• "Each method should return a new NotificationChannel."
• "A lambda can implement a functional interface."
• "Preserve the same userId unless the TODO says otherwise."
• "Audit should record the original message before prefixing because of where it is placed in the exercise runner."

Expected Answer Behavior

After applying answers:

scripts/apply_answers.sh lesson_2
scripts/run.sh lesson_2 verify

Expected important lines:

lesson_2 answers verified

Common Mistakes

• Returning base.send(...) immediately instead of returning a new channel.
• Changing userId when only the message should change.
• Recording audit after delegation and accidentally logging transformed output.
• Mutating prefix or storing unnecessary state.
• Assuming decorators must be classes; lambdas are valid for functional interfaces.

Discussion Prompts

• Should decorators log before or after failures?
• Should wrapper order be configured manually or through a builder?
• When does inheritance solve the problem more directly?
• Can too many decorators hide behavior from readers?
• How do web middleware stacks relate to this example?

Extension Challenge

Ask learners to write a withRedaction decorator that replaces email addresses with [redacted]. Have them decide whether redaction should happen before audit, after audit, or both. The answer depends on whether audit logs are allowed to contain sensitive data.

Functions In This Lesson

private NotificationDecorators() {

public static NotificationChannel withPrefix(NotificationChannel base, String prefix) {

public static NotificationChannel withSuffix(NotificationChannel base, String suffix) {

public static NotificationChannel withMessageTransform(NotificationChannel base, UnaryOperator<String> transform) {

public static NotificationChannel withRateLimitNote(NotificationChannel base) {

public static NotificationChannel withAuditTrail(NotificationChannel base, List<String> auditLog) {

public static NotificationChannel withBlocklist(NotificationChannel base, Set<String> blockedUserIds) {

public static NotificationChannel withTruncation(NotificationChannel base, int maxChars) {

public static NotificationChannel withCounting(NotificationChannel base, AtomicInteger attempts) {

public static NotificationChannel compose( NotificationChannel base, List<UnaryOperator<NotificationChannel>> decorators) {

private DecoratorDemo() {

public static void main(String[] args) throws IOException {

public LowercaseDecorator(TextProcessor next) {

public String process(String input) {

public MetricsDecorator(TextProcessor next) {

public String process(String input) {

public String process(String input) {

public ProfanityMaskDecorator(TextProcessor next) {

public String process(String input) {

String process(String input);

protected TextProcessorDecorator(TextProcessor next) {

public TrimDecorator(TextProcessor next) {

public String process(String input) {

private AnswerVerifier() {

public static void main(String[] args) {

private static void expectEquals(Object expected, Object actual, String label) {

private static void expectThrows(Runnable action, String label) {

public String send(String userId, String message) {

private ExerciseRunner() {

public static void main(String[] args) {

String send(String userId, String message);

private NotificationDecorators() {

public static NotificationChannel withPrefix(NotificationChannel base, String prefix) {

public static NotificationChannel withSuffix(NotificationChannel base, String suffix) {

public static NotificationChannel withMessageTransform(NotificationChannel base, UnaryOperator<String> transform) {

public static NotificationChannel withRateLimitNote(NotificationChannel base) {

public static NotificationChannel withAuditTrail(NotificationChannel base, List<String> auditLog) {

public static NotificationChannel withBlocklist(NotificationChannel base, Set<String> blockedUserIds) {

public static NotificationChannel withTruncation(NotificationChannel base, int maxChars) {

public static NotificationChannel withCounting(NotificationChannel base, AtomicInteger attempts) {

public static NotificationChannel compose( NotificationChannel base, List<UnaryOperator<NotificationChannel>> decorators) {

private NotificationDecorators() {

public static NotificationChannel withPrefix(NotificationChannel base, String prefix) {

public static NotificationChannel withSuffix(NotificationChannel base, String suffix) {

public static NotificationChannel withMessageTransform(NotificationChannel base, UnaryOperator<String> transform) {

public static NotificationChannel withRateLimitNote(NotificationChannel base) {

public static NotificationChannel withAuditTrail(NotificationChannel base, List<String> auditLog) {

public static NotificationChannel withBlocklist(NotificationChannel base, Set<String> blockedUserIds) {

public static NotificationChannel withTruncation(NotificationChannel base, int maxChars) {

public static NotificationChannel withCounting(NotificationChannel base, AtomicInteger attempts) {

public static NotificationChannel compose( NotificationChannel base, List<UnaryOperator<NotificationChannel>> decorators) {