@FunctionalInterface & SAM Rule

## Starting from the ground up An **interface** in Java is a named contract: a list of method signatures (name, parameters, return type) that a class promises to provide. A method is **abstract** when it has a signature but no body — just `int compare(T a, T b);` with a semicolon and no braces. A class that implements the interface must supply the bodies. A **functional interface** is simply an interface that has **exactly one abstract method**. That single method is called the **SAM** — the **Single Abstract Method**. The phrase "SAM rule" just means: to be functional, an interface must have one and only one abstract method. ## Why "exactly one" matters A **lambda expression** is shorthand like `(a, b) -> a - b` and a **method reference** is shorthand like `Integer::compare`. Both are ways to write a tiny anonymous implementation without declaring a class. But for the compiler to accept `(a, b) -> a - b` as an implementation of some interface, it has to know *which method* you are implementing. If the interface had two abstract methods, the compiler could not tell which one your lambda is the body of. With **exactly one** abstract method, there is no ambiguity — the lambda is the body of that one method. This is the entire reason the SAM rule exists. ```java Comparator<Integer> c = (a, b) -> a - b; // lambda IS the body of compare(a, b) ``` Here `Comparator` is functional, its one abstract method is `compare`, and the lambda becomes `compare`'s implementation. ## What does NOT count toward the "one" Three categories of methods are exempt — an interface can have any number of them and still be functional: 1. **`default` methods** — interface methods that *do* have a body (introduced in Java 8), e.g. `Comparator` has `reversed()`, `thenComparing()`, etc. They are not abstract (they have an implementation), so they do not count. 2. **`static` methods** — methods that belong to the interface itself, not to instances, e.g. `Comparator.naturalOrder()`. Not abstract, not counted. 3. **Re-declared `public` methods of `java.lang.Object`** — every interface's implementations are objects, so they already inherit `equals`, `hashCode`, and `toString` from `Object`. If an interface re-declares one of these as abstract (as `Comparator` does with `equals`), it still does NOT count, because any implementing class already has a concrete version inherited from `Object`. So you could not implement it with a lambda anyway. This is why `Comparator` is a valid functional interface even though, reading its source, you see `compare`, `equals`, plus a dozen default and static methods: only `compare` is a counting abstract method. ```java @FunctionalInterface interface Transformer { String apply(String in); // the ONE SAM — counts default String twice(String in) { return apply(apply(in)); } // default — exempt static Transformer identity() { return x -> x; } // static — exempt boolean equals(Object o); // Object method — exempt } ``` ## The @FunctionalInterface annotation `@FunctionalInterface` is an **optional** marker annotation. You do not need it for an interface to be functional — any interface with one abstract method works with lambdas regardless. What the annotation adds is a **compile-time check**: if you mark an interface `@FunctionalInterface` and it has zero or two-or-more abstract methods, the code **does not compile**. It is a guardrail that documents your intent ("this is meant to be used with lambdas") and prevents a future maintainer from accidentally adding a second abstract method and silently breaking every lambda call site. ## Summary - Functional interface = interface with exactly one abstract method (the SAM). - The single method is what a lambda/method reference implements. - `default`, `static`, and `Object` public methods are exempt from the count. - `@FunctionalInterface` is optional; it only turns the rule into a compiler-enforced check.