The docs talk about checked exceptions. These are exceptions that extend
Exception and not RuntimeException. A checked exception is part of the API
as you can not throw a checked exception without defining a throws clause
on a method. Also you must use a try catch block when you want to call a
method that throws a checked exception (or re-throw the exception). So if
an interface declares such a checked exception all implementations of that
interface can AT MOST throw this exception or dont throw an exception at
all. If the implementation does not throw the exception at all it also does
not have to declared it on its method because the interface has already
done so.
Example:
Imagine a NegativeNumberNotSupportedException extends Exception, so its a
checked exception
interface Calculator {
Integer add(Integer a, Integer b) throws
NegativeNumberNotSupportedException;
}
class DumbCalculator implements Calculator {
Integer add(Integer a, Integer b) throws
NegativeNumberNotSupportedException {
if(a == null || b == null {
throw new NullPointerException(); //Not declared at all. Thats
allowed because its an unchecked RuntimeException.
}
if(a < 0 || b < 0) {
throw new NegativeNumberNotSupportedException();
//Must be declared, otherwise you cant throw it. You cant throw
any other checked exception than NegativeNumberNotSupportedException
because the interface denies it.
}
//do calculation with positive integers
}
}
class IntelligentCalculator implements Calculator {
Integer add(Integer a, Integer b) {
if(a == null || b == null {
throw new NullPointerException(); //Not declared at all. Thats
allowed because its an unchecked RuntimeException.
}
//do calculation and support negative numbers too! No need to throw
anything here, so implementation do not have to declare it. The interface
has already declared it as part of its public API.
}
}
In contrast to checked exceptions you also have unchecked exceptions that
extend from RuntimeException (thats what you have used). These can always
be thrown everywhere without declaration (see NullPointerException
above). If you declare a RuntimeException in a throws clause then its only
for documentation. Typically a RuntimeException represents a state the
application can not recover from, so its a truly unexpected exception that
typically should not occur at all at runtime.
So documentation is not wrong. You just have to differentiate between
checked and unchecked exceptions.
For checked exceptions you can not declare different exceptions in the
implementation, only the one in the interface are allowed to be re-declared
in the implementation. Unchecked exceptions don't have to be declared at
all and thus Java does not check (hence the naming "unchecked exception")
if the declaration makes sense or not or if you use a try catch block or
not.
Obviously you should never use any concrete implementation of Calculator
directly (unless you know what you do) as the Calculator interface defines
the type and public API. Typically the Calculator is public while its
implementations are package private.
-- J.
