Share rationale behind explicit throws RuntimeException clause

[skepticoitusInteruptus]

Context

I'm a Java™ programmer seeking guidance on best practice and recommended Java™ programming idioms. Ordinarily, my first inclination is to defer to the most authoritative references for the Java™ programming language.

However, library authors can sometimes offer compelling rationale to do otherwise.

Java™ SE 8 Javadoc for RuntimeException:

public class RuntimeException
extends Exception

…

RuntimeException and its subclasses are unchecked exceptions.
Unchecked exceptions do NOT need to be declared in a method
or constructor's throws clause if they can be thrown by the
execution of the method or constructor and propagate outside
the method or constructor boundary
…

Java™ Language Specification (JLS)

…
Run-time exception classes are exempted because, in the judgment of
the designers of the Java programming language, having to declare
such exceptions would not aid significantly in establishing the
correctness of programs. Many of the operations and constructs of
the Java programming language can result in exceptions at run time.
The information available to a Java compiler, and the level of analysis
a compiler performs, are usually not sufficient to establish that such
run-time exceptions cannot occur, even though this may be obvious to the
programmer. Requiring such exception classes to be declared would
simply be an irritation to programmers
…

The Issue

TL;DR — It's puzzling why some Java™ SDK for CloudEvents methods are declared with a throws RuntimeException clause.

To elaborate

I have tried to reason about what this library's API designers might have intended to communicate to callers by exposing the atypical public signatures in question. Several hypothetical questions arose. Here are three examples…

1. What does this project's authors intend callers to do when calling methods declared with throws RuntimeException?
2. What do you foresee would happen if callers ignore (don't handle) your methods' throws RuntimeExceptions?
3. What, originally, did you foresee would happen for callers if those throws RuntimeException were never declared?
4. …

Which methods?

All overloaded CloudEventContextWriter.withContextAttribute(...) methods have throws CloudEventRWException declarations…

…
CloudEventContextWriter withContextAttribute(String name, String value) throws CloudEventRWException;
…

Interestingly, the two methods CloudEventContextReaderAdapter.readAttributes() CloudEventContextReaderAdapter.readExtensions() are both declared with throws RuntimeException; the superclass of CloudEventRWException…

…
public void readAttributes(CloudEventContextWriter writer) throws RuntimeException 
…
public void readExtensions(CloudEventContextWriter writer) throws RuntimeException
            … 
            // This should never happen because we build that map only through our builders
            throw new IllegalStateException("Illegal value inside extensions map: " + key + " " + value);
            …

CloudEventContextReaderAdapter.readContext(CloudEventContextWriter) calls both of its sibling methods. However, it IS declared with throws CloudEventRWException…

public void readContext(CloudEventContextWriter writer) throws CloudEventRWException

Or is it just me?

The system I'm currently analyzing and will eventually implement, potentially may consume the public API of the Java™ SDK for CloudEvents.

For not only my project specifically, I imagine it would be helpful for all consuming projects in general to understand the rationale behind this SDK's atypical idiom of explicitly declaring public methods with throws RuntimeException.

Proposed Solution

There's more than one alternative that I presume would have value to the entire community. Here are just two examples…

1. Add clear explanations in the Java™ SDK for CloudEvents Javadoc
   • Nothing complicated; simply something that clarifies the methods in question's rationale for taking the road less traveled
   • Currently, there is nothing documenting why throws RuntimeException is necessary
2. Remove the explictly-declared throws RuntimeException clauses
   • But add Javadoc that uses the @throws annotation appropriately to document what callers of the method should expect
3. ???

[cardil]

3. As CloudEvents is a library, people consume, it makes sense it should have a nice hierarchy of checked exceptions. That would allow people to properly act upon failures.