Exceptions

This code abuses exceptions for ordinary control flow - a serious anti-pattern because:

1. It's drastically less efficient (roughly 2x slower) than standard loops
2. It obfuscates the code's purpose, making it unreadable
3. It prevents JVM optimizations that would normally occur in try-catch blocks
4. It can mask real bugs by catching and ignoring legitimate errors

The proper alternative is a standard loop:

for (Mountain m : range)
    m.climb();

Exceptions should only be used for exceptional conditions, not regular control flow.

The three types of throwables are:

1. Checked exceptions (subclasses of Exception but not RuntimeException)
   • For recoverable conditions
   • Force caller to handle or propagate
2. Runtime exceptions (subclasses of RuntimeException)
   • For programming errors (precondition violations)
   • Needn't be caught or declared
3. Errors (subclasses of Error)
   • For serious JVM problems
   • Not meant for application use

When implementing custom exceptions:

• All your unchecked exceptions should subclass RuntimeException
• Never implement new Error subclasses
• Don't create throwables that aren't exceptions or errors
• Only use checked exceptions when recovery is possible

Note: With rare exceptions like AssertionError, you shouldn't throw Errors either.

Cardinal rule: Use checked exceptions for conditions from which the caller can reasonably be expected to recover.

Decision factors:

• Use checked exceptions when:

  • Recovery is possible
  • You want to force callers to handle the condition
  • The condition is a legitimate outcome (not a bug)
  • You can provide methods to help with recovery

• Use runtime exceptions when:

  • The condition represents a programming error
  • Recovery is impossible or unlikely
  • Forcing exception handling would be burdensome
  • The condition results from precondition violations

If it's unclear whether recovery is possible, favor unchecked exceptions.

Remember: Checked exceptions increase API complexity but enhance reliability when used appropriately.

Problems with overusing checked exceptions:

• Forces clients to use try-catch blocks or propagate exceptions
• Makes APIs less pleasant to use
• Creates compatibility issues with functional interfaces and streams in Java 8+
• Increases code verbosity
• May force handling of conditions from which recovery is impractical

Two conversion techniques:

1. Return an Optional:

// Instead of:
public FileData readFile(File f) throws IOException { /*...*/ }

// Consider:
public Optional<FileData> readFile(File f) { 
    try {
        // Read file
        return Optional.of(fileData);
    } catch (IOException e) {
        return Optional.empty();
    }
}

2. Split into a state-testing method + action method:

// Instead of one method throwing checked exception:
public void action(Args args) throws CheckedException { /*...*/ }

// Create two methods:
public boolean actionPermitted(Args args) { /*...*/ }
public void action(Args args) { // throws unchecked exception if needed
    if (!actionPermitted(args)) {
        throw new UncheckedExceptionVariant();
    }
    // Perform action
}

The second approach is inappropriate for concurrent access without synchronization.

Exception translation is when higher layers catch lower-level exceptions and throw exceptions that can be explained in terms of the higher-level abstraction.

Use it when:

• A method would otherwise propagate exceptions from lower-level abstractions
• The original exception has no apparent connection to the task performed
• To prevent API pollution with implementation details

Code pattern:

// Exception Translation
try {
    // Use lower-level abstraction to do our bidding
} catch (LowerLevelException e) {
    throw new HigherLevelException(...);
}

This prevents breaking client code if implementation changes and maintains abstraction integrity.

Exception chaining is a special form of exception translation where the lower-level exception is preserved as the "cause" of the higher-level exception.

Implementation:

// Exception Chaining
try {
    // Use lower-level abstraction to do our bidding
} catch (LowerLevelException cause) {
    throw new HigherLevelException(cause);
}

// Creating a chaining-aware exception class
class HigherLevelException extends Exception {
    HigherLevelException(Throwable cause) {
        super(cause);
    }
}

Benefits:

• Preserves lower-level exception details for debugging
• Integrates the cause's stack trace into the higher-level exception
• Allows programmatic access to the cause (via getCause())
• Provides both abstraction integrity and debugging information
• Useful when the lower-level exception might help diagnose the problem

For maximum diagnostic value, exception detail messages should:

1. Contain values of all parameters and fields that contributed to the exception

   • Example: For IndexOutOfBoundsException, include lower bound, upper bound, and index

2. Avoid including security-sensitive information

   • No passwords, encryption keys, etc.

3. Focus on information content over prose readability

   • The message is primarily for programmers/engineers, not end users

4. Centralize detail message generation in constructors

   • Better than relying on each caller to generate proper messages

Example implementation:

public IndexOutOfBoundsException(int lowerBound, int upperBound, int index) {
    // Generate a detail message that captures the failure
    super(String.format("Lower bound: %d, Upper bound: %d, Index: %d", 
                         lowerBound, upperBound, index));
    
    // Save failure information for programmatic access
    this.lowerBound = lowerBound;
    this.upperBound = upperBound;
    this.index = index;
}

Remember: The stack trace may be the ONLY information available when diagnosing production issues.

Best practices for documenting exceptions:

1. Document all exceptions, both checked and unchecked

   • Use Javadoc @throws tags for all possible exceptions

2. Declare each checked exception individually in the throws clause

   • Never declare superclasses like Exception or Throwable
   • Don't declare unchecked exceptions in throws clause

3. Document precisely when each exception is thrown

   • Clearly specify conditions that trigger each exception

4. For interface methods, document unchecked exceptions thoroughly

   • This forms part of the interface's general contract

5. For multiple methods throwing the same exception for the same reason:

   • Document the exception in the class's documentation comment
   • Example: "All methods in this class throw NullPointerException if a null object reference is passed in any parameter"

6. Distinguish between checked and unchecked exceptions in documentation

   • The @throws tag without a throws clause provides a visual cue that an exception is unchecked

Remember: Undocumented exceptions make it difficult or impossible for others to effectively use your classes and interfaces.

Critical do's and don'ts to avoid leaking implementation details:

DO:

• Catch lower-level exceptions and translate them to higher-level abstractions
• Design exception hierarchies that match your API's abstraction level
• Use exception chaining to preserve debugging information
• Create custom exceptions that reflect your domain concepts
• Document exceptions as part of your API contract
• Think about exceptions as part of your API design upfront

DON'T:

• Allow exceptions from libraries and lower-level components to propagate directly
• Throw exceptions that have no apparent connection to the task being performed
• Let implementation details like database errors or networking issues leak through your API
• Change which exceptions you throw when implementation changes
• Declare overly general exception types (like Exception or Throwable)
• Ignore or swallow exceptions without proper handling

Example of implementation leakage:

// BAD: Leaks implementation details
public void saveUser(User user) throws SQLException { // Leaks database implementation
    // database operations...
}

// GOOD: Maintains abstraction
public void saveUser(User user) throws UserStorageException {
    try {
        // database operations...
    } catch (SQLException e) {
        throw new UserStorageException("Failed to store user", e);
    }
}

This approach preserves implementation flexibility while providing meaningful exceptions.

Recovery Code Approach Tradeoffs:

Advantages:

• Can handle failures that occur partway through operations
• Useful for complex, multi-step operations where other approaches aren't feasible
• Particularly valuable for durable (disk-based) data structures

Disadvantages:

• Significantly increases code complexity
• Requires careful tracking of all state changes
• Higher performance overhead (recording state for potential rollback)
• May require transaction-like semantics
• More prone to bugs in the recovery mechanism itself
• Less common and often overkill for in-memory data structures

This approach is generally reserved for persistent data structures where durability is critical, such as databases and file systems.