Methods

• Thread-safety: Always document the thread-safety level of a class or static method, as described in Item 82
• Serializability: If a class is serializable, document its serialized form, as described in Item 87

Example thread-safety documentation:

/**
 * This class is thread-safe. All public methods use internal synchronization
 * to ensure consistent state when accessed concurrently.
 */
public class ThreadSafeCounter {
    // Implementation...
}

Defensive copying can be omitted in these specific circumstances:

1. When there's an explicit trust relationship:

   • Class and client are in the same package
   • Class documentation explicitly states caller must not modify parameters

2. When the method/constructor indicates an explicit "handoff" of the object referenced by a parameter

   • The caller explicitly transfers ownership of the object to the method

3. When there are significant performance concerns and the overhead of defensive copying is problematic

   • This should be clearly documented as a requirement for callers

4. When using immutable parameters (preferred solution where possible)

Note: Even when omitting defensive copies, document the expectations clearly to prevent invariant violations.

Options for returning internal arrays while maintaining encapsulation:

1. Defensive Copy (Clone):

   private final Element[] elements;
   
   public Element[] getElements() {
       return elements.clone();  // Returns a copy
   }

   • ✓ Prevents modification of internal state
   • ✓ Clients can modify returned array without affecting original
   • ✗ Performance cost of copying entire array
   • ✗ If elements are mutable, their state can still be modified

2. Immutable View (Collections.unmodifiableList):

   private final Element[] elements;
   
   public List<Element> getElements() {
       return Collections.unmodifiableList(Arrays.asList(elements));
   }

   • ✓ Prevents structural modifications (add/remove)
   • ✓ Clearer API semantics (unmodifiable)
   • ✗ Conversion overhead
   • ✗ If elements are mutable, their state can still be modified

3. Deep Copy (for mutable elements):

   private final MutableElement[] elements;
   
   public MutableElement[] getElements() {
       MutableElement[] copy = new MutableElement[elements.length];
       for (int i = 0; i < elements.length; i++) {
           copy[i] = elements[i].copy();  // Deep copy each element
       }
       return copy;
   }

   • ✓ Complete isolation from internal state
   • ✗ Highest performance cost
   • ✗ Requires elements to support copying

4. Immutable Elements + Shallow Copy:

   private final ImmutableElement[] elements;
   
   public ImmutableElement[] getElements() {
       return elements.clone();  // Safe because elements can't be modified
   }

   • ✓ Best combination of safety and performance
   • ✓ No deep copying needed
   • ✗ Requires immutable element types

Tradeoffs primarily involve balancing:

• Performance (copying overhead)
• Memory usage (extra copies)
• API clarity (expectations about modifiability)
• Depth of defense (shallow vs. deep protection)

• Core Principle: When a class gets mutable components from clients, it must defensively copy these components before storing them.

• Vulnerability if Ignored: Time-of-check/time-of-use (TOCTOU) attack

  • Client can modify the object after validation but before use
  • Class invariants can be compromised
  • Object's internal state becomes unpredictable

• Implementation Approach:

  1. Create defensive copies of mutable input parameters
  2. Validate the copies (not the originals)
  3. Store the copies (never store references to client objects)

• Example:

public final class Period {
    private final Date start;
    private final Date end;
    
    public Period(Date start, Date end) {
        // Defensive copies first
        this.start = new Date(start.getTime());
        this.end = new Date(end.getTime());
        
        // Validation second (on the copies)
        if (this.start.compareTo(this.end) > 0)
            throw new IllegalArgumentException("Start after end");
    }
    
    // Also need defensive copies when returning
    public Date getStart() {
        return new Date(start.getTime());
    }
}

• Exception: Only skip defensive copying when:
  1. Performance cost is prohibitive AND
  2. Clients can be trusted not to modify components

• Core Conservative Policy: Never export two overloadings with the same number of parameters

• For Varargs Methods: Do not overload varargs methods at all (with few exceptions)

• Rationale: Ensures programmers are never in doubt about which overloading applies to any set of parameters

• Alternative Approach: Use different method names instead of overloading

  • Example: Instead of write(int), write(long), etc.
  • Use writeInt(int), writeLong(long), etc.

• Special Case for Constructors:

  • Constructors must be overloaded (can't have different names)
  • Consider using static factory methods as an alternative
  • With constructors, you don't need to worry about interactions between overloading and overriding

• Lambda Method Reference Issues:

  • Java 8 lambdas and method references increased overloading confusion
  • Example issue:

  // This works:
  new Thread(System.out::println).start();
  
  // This doesn't compile:
  exec.submit(System.out::println);  // Ambiguous between Runnable and Callable

To ensure consistent behavior across overloaded methods:

Use forwarding - have the more specific method forward to the more general method:

// Ensuring identical behavior by forwarding
public boolean contentEquals(StringBuffer sb) {
    // Forward from specific to general implementation
    return contentEquals((CharSequence) sb);
}

public boolean contentEquals(CharSequence cs) {
    // Primary implementation here
    // ...implementation logic...
}

This technique:

1. Centralizes logic in one place (the more general method)
2. Eliminates duplication that could lead to inconsistencies
3. Makes maintenance easier - changes only need to be made in one place
4. Ensures that identical input always produces identical output regardless of which overload is called
5. Preserves type-specific method signatures for backward compatibility

A common use case is when retrofitting existing classes to implement new interfaces or when evolving an API while maintaining backwards compatibility.

• orElse(T value):
  • Always evaluates its argument, regardless of whether the Optional is empty
  • Appropriate when default value is cheap to create or already available
• orElseGet(Supplier<T> supplier):
  • Lazily evaluates its argument only when the Optional is empty
  • Appropriate when default value is expensive to create

// Expensive computation only happens when needed
String result = optional.orElseGet(() -> expensiveOperation());

// vs. expensiveOperation() runs regardless if optional has value
String result = optional.orElse(expensiveOperation());

Key consideration: Choose orElseGet() when the default value requires significant computation that should be avoided if possible.

Appropriate use cases:

• When a field is genuinely optional within a class that has many non-required fields
• When implementing a builder pattern where some values are optional
• When the underlying field is of primitive type and "absence" is not easily represented
• When the getter for that field would naturally return an Optional

Example:

public class NutritionFacts {
    private final int servingSize;  // required
    private final OptionalInt calories;  // optional
    private final OptionalInt sodium;    // optional
    
    // Better to store as OptionalInt fields than use null or -1 as sentinel values
    
    public OptionalInt getCalories() {
        return calories;
    }
}

When to avoid:

• In serializable classes (Optional is not serializable)
• As method parameters (prefer overloaded methods instead)
• As keys or values in collections or maps
• When creating many instances where memory overhead is a concern
• When it introduces unnecessary complexity
• When a simple nullable field with clear documentation would suffice

Warning signs (code smells):

• Multiple Optional fields might indicate need for a subclass
• Complex Optional field nesting indicates design issues

HTML in Javadoc comments:

1. Arbitrary HTML is permissible within documentation comments
2. HTML metacharacters (<, >, &, etc.) must be escaped when used literally
3. Common HTML elements to consider:
   • <p> for paragraph breaks
   • <ul>, <ol>, <li> for lists
   • <code>, <pre> for code formatting
   • <em>, <strong> for emphasis
   • <a href="..."> for links

Example:

/**
 * Returns the element at the specified position.
 * <p>
 * This method may throw an {@link IndexOutOfBoundsException} if the
 * index is out of range (index &lt; 0 || index &gt;= size()).
 * 
 * @param index the index of the element to return
 * @return the element at the specified position
 * @throws IndexOutOfBoundsException if the index is out of range
 */
public E get(int index) {
    // Implementation
}

When using the Java module system (introduced in Java 9):

1. Place module-level documentation comments in the module-info.java file
2. Format the comments using the standard Javadoc comment style
3. Document the module's purpose, exported packages, and service providers
4. Include information about module dependencies when relevant

Example:

/**
 * A module providing core utility classes for the application.
 * <p>
 * This module exports various utility packages and provides
 * implementations of the logging service.
 */
module com.example.utilities {
    exports com.example.utilities.collections;
    exports com.example.utilities.concurrency;
    
    provides java.util.logging.LoggingProvider 
        with com.example.utilities.logging.LogProvider;
}