Enums and Annotations

To create an enum with both constant-specific behavior and data:

public enum Operation {
    PLUS("+") {
        public double apply(double x, double y) { return x + y; }
    },
    MINUS("-") {
        public double apply(double x, double y) { return x - y; }
    },
    TIMES("*") {
        public double apply(double x, double y) { return x * y; }
    },
    DIVIDE("/") {
        public double apply(double x, double y) { return x / y; }
    };
    
    private final String symbol;
    
    // Constructor must come after all enum constants
    Operation(String symbol) { this.symbol = symbol; }
    
    // Common methods
    @Override public String toString() { return symbol; }
    
    // Abstract method enforces implementation for each constant
    public abstract double apply(double x, double y);
}

Constructor constraints:

1. Constructor parameters must appear in parentheses after each constant
2. Constructor cannot access the enum's static fields (except constant variables)
3. Enum constants cannot access one another from their constructors
4. All fields initialized by constructors should be final (enums are immutable)
5. Instance fields should generally be private with public accessors

Key insight: Enums are "instance-controlled" classes that export exactly one instance for each constant via public static final fields.

When you override toString() in an enum, you override the default string representation (the constant name) with a custom format.

Consequences:

1. The built-in valueOf(String) method still expects the exact constant name, not your custom string
2. You lose the automatic string-to-enum conversion for your custom string format

Solution: Implement a fromString method:

public enum Operation {
    PLUS("+"), MINUS("-"), TIMES("*"), DIVIDE("/");
    
    private final String symbol;
    
    Operation(String symbol) { this.symbol = symbol; }
    
    // Custom string representation
    @Override public String toString() { return symbol; }
    
    // Internal lookup map for reverse conversion
    private static final Map<String, Operation> stringToEnum =
        Stream.of(values()).collect(
            toMap(Object::toString, e -> e));
    
    // Custom string-to-enum conversion method
    public static Optional<Operation> fromString(String symbol) {
        return Optional.ofNullable(stringToEnum.get(symbol));
    }
}

Key implementation details:

1. Use a static map to store the reverse mapping
2. Initialize the map after all enum constants are created (not in constructors)
3. Return Optional<EnumType> to handle invalid input strings
4. For performance with many lookups, use an efficient map implementation
5. Ensure each constant has a unique string representation to avoid mapping conflicts

This pattern maintains bidirectional conversion even with custom string formats.

Key behavioral differences:

1. Empty categories:

   • EnumMap version always creates entries for all enum constants
   • Stream-based versions only create entries for constants that have associated values

2. Map contents:

   • Given a garden with annuals and perennials but no biennials:
     • EnumMap version: Map will have size 3 (entry for each lifecycle type)
     • Stream-based version: Map will have size 2 (only contains entries with plants)

3. Implementation:

   // EnumMap version - always contains all enum constants
   Map<Plant.LifeCycle, Set<Plant>> plantsByLifeCycle = 
       new EnumMap<>(Plant.LifeCycle.class);
   for (Plant.LifeCycle lc : Plant.LifeCycle.values())
       plantsByLifeCycle.put(lc, new HashSet<>());
   
   // Stream version - only contains enum constants with values
   Map<Plant.LifeCycle, Set<Plant>> plantsByLifeCycle =
       Arrays.stream(garden)
             .collect(groupingBy(p -> p.lifeCycle,
                      () -> new EnumMap<>(LifeCycle.class), toSet()));

This difference matters when you need to process all enum constants, even those with no associated values.

Approach 1: Using bounded type tokens with Class objects

// Client code
public static void main(String[] args) {
    double x = 4.0, y = 2.0;
    test(ExtendedOperation.class, x, y);
}

// Bounded type parameter ensures Class represents both enum and Operation
private static <T extends Enum<T> & Operation> void test(
        Class<T> opEnumType, double x, double y) {
    for (Operation op : opEnumType.getEnumConstants())
        System.out.printf("%f %s %f = %f%n", 
                         x, op, y, op.apply(x, y));
}

Approach 2: Using bounded wildcard types with Collection

// Client code
public static void main(String[] args) {
    double x = 4.0, y = 2.0;
    test(Arrays.asList(ExtendedOperation.values()), x, y);
}

// Using wildcard type for the collection
private static void test(Collection<? extends Operation> operations, 
                        double x, double y) {
    for (Operation op : operations)
        System.out.printf("%f %s %f = %f%n", 
                         x, op, y, op.apply(x, y));
}

Differences:

• Approach 1: Requires all operations to be from same enum type
• Approach 2: More flexible; allows mixing operations from different enum types
• Approach 1: Uses reflection and enforces enum type
• Approach 2: Simpler code but loses enum type constraints
• Approach 1: Could use EnumSet if limited to one enum type
• Approach 2: Cannot use EnumSet across different enum implementations

Disadvantages of naming patterns:

1. Silent failures from typographical errors

   • Example: Writing tsetSafetyOverride instead of testSafetyOverride
   • Result: Test never runs, but no compiler warning or runtime error
   • With annotations: Misspelled annotations cause compiler errors

2. No enforcement of appropriate usage locations

   • Example: Naming a class TestSafetyMechanisms hoping JUnit would run all its methods
   • Result: No error, but no tests run either
   • With annotations: @Target metadata restricts where annotations can be used

3. No way to associate parameter values with elements

   • Example: Wanting to test for specific exceptions
   • With naming pattern: Would need complex naming scheme like testNullPointerException_safeDivide
   • With annotations: Simply use parameters - @Test(expectedExceptions = NullPointerException.class)
   • Annotation parameters are type-checked by the compiler

These disadvantages make naming patterns error-prone and less powerful than annotations, which provide compile-time checking and richer metadata capabilities.

When a parameterized method is annotated with @Test:

1. Compilation succeeds - The compiler doesn't validate annotation semantics
2. Runtime failure - The test runner fails with an exception when trying to invoke the method:

   Invalid @Test: public void SampleClass.parameterizedMethod(String s)
   

Prevention approaches:

1. Documentation comments (weak)

   /**
    * Use only on parameterless static methods.
    */

2. Annotation processor (strong)

   // Create a compile-time validator
   @SupportedAnnotationTypes("Test")
   public class TestAnnotationProcessor extends AbstractProcessor {
       @Override
       public boolean process(Set<? extends TypeElement> annotations,
                            RoundEnvironment roundEnv) {
           for (Element element : roundEnv.getElementsAnnotatedWith(Test.class)) {
               if (element.getKind() != ElementKind.METHOD) {
                   processingEnv.getMessager().printError("@Test only allowed on methods", element);
                   return true;
               }
               ExecutableElement method = (ExecutableElement) element;
               if (!method.getParameters().isEmpty()) {
                   processingEnv.getMessager().printError("@Test methods must have no parameters", method);
               }
               if (!method.getModifiers().contains(Modifier.STATIC)) {
                   processingEnv.getMessager().printError("@Test methods must be static", method);
               }
           }
           return true;
       }
   }

The equals() overloading antipattern:

// WRONG: This overloads equals() instead of overriding it
public boolean equals(Bigram b) {  // Parameter should be Object
    return b.first == first && b.second == second;
}

Solution using @Override:

// CORRECT: Properly overrides Object.equals()
@Override
public boolean equals(Object o) {
    if (!(o instanceof Bigram))
        return false;
    Bigram b = (Bigram) o;
    return b.first == first && b.second == second;
}

Benefits of @Override:

• Compiler error if method doesn't actually override a superclass method
• Prevents subtle bugs where you accidentally overload instead of override
• Makes code intention clear to readers
• Catches method signature changes during refactoring

Common symptom of the bug: Collections behave incorrectly with your objects (sets don't eliminate duplicates, maps can't find elements).

The @Override annotation for equals() catches several subtle issues:

1. Parameter Type Problems:

   • Catches when you write equals(MyClass o) instead of equals(Object o)
   • Without @Override, you accidentally create an overloaded method, not an override

2. Method Coexistence Bugs:

   • Without @Override, both your equals() and Object.equals() exist simultaneously
   • Collection classes (HashSet, HashMap) call Object.equals(), not your version
   • Objects that should be considered equal are treated as distinct

3. Signature Deviations:

   • Catches misspellings (equal() vs equals())
   • Catches wrong return type (void or int instead of boolean)
   • Catches additional parameters

4. Inheritance Chain Issues:

   • Ensures your equals() properly participates in the inheritance chain
   • Prevents accidental hiding of superclass methods

These issues typically cause difficult-to-debug equality problems in collections, serialization, and comparison operations.

Compile-time Benefits of Marker Interfaces vs. Runtime Properties of Marker Annotations:

Marker Interfaces:

• Define a type in the type system
• Enable compile-time checking through method signatures
• Allow instanceof checks for type safety
• Prevent inappropriate objects from being passed to methods

Marker Annotations:

• Checked at runtime through reflection
• Require explicit code to verify annotations
• Cannot be used for method parameter type constraints
• Errors only detected during execution

Example Where Marker Interface Prevents a Bug:

// With marker interface
public interface Processable { /* marker interface */ }

public class Document implements Processable { /* ... */ }
public class Image implements Processable { /* ... */ }
public class Audio { /* doesn't implement Processable */ }

// Method requires Processable objects
public void process(Processable item) { /* ... */ }

// COMPILE ERROR: Audio doesn't implement Processable
process(new Audio());  // Caught at compile time!

// With marker annotation instead
@interface Processable { }

@Processable class Document { /* ... */ }
@Processable class Image { /* ... */ }
class Audio { /* not annotated */ }

// Method must check annotation at runtime
public void process(Object item) {
    if (!item.getClass().isAnnotationPresent(Processable.class)) {
        throw new IllegalArgumentException("Not processable");  // Runtime error!
    }
    // ...
}

// No compile error, fails at runtime
process(new Audio());  // Runtime exception!

Restricted Marker Interface Pattern:

A restricted marker interface is one that:

1. Extends a specific interface (the "target" interface)
2. Adds no additional methods
3. Restricts the marking to implementations of that target interface

Implementation Pattern:

// Target interface
public interface Collection<E> { ... }

// Restricted marker interface
public interface Set<E> extends Collection<E> {
    // No additional methods required
    // Implicitly restricts "Set-ness" to Collections only
}

Type Safety Benefits:

1. Compile-time Restriction:

   • Only classes that already implement Collection can implement Set
   • Compiler prevents non-Collection classes from being Sets

2. Hierarchy Enforcement:

   • The marker is automatically restricted to the proper type hierarchy
   • No need for runtime validation code

3. Improved Method Signatures:

   // With restricted marker interface:
   void processSet(Set<?> set) { ... }  // Only accepts Sets
   
   // With marker annotation (weaker):
   void processSet(Collection<?> collection) {
       if (!collection.getClass().isAnnotationPresent(SetAnnotation.class)) {
           throw new IllegalArgumentException("Not a set");
       }
       // ...
   }

This pattern creates stronger guarantees than annotations because the type system itself enforces the restriction, while annotations require explicit runtime checking code.