Revisit exception handling for customizations, listeners and callbacks

[cruftex]

JCache 1.0 defines a couple of customizations for example, CacheLoader, CacheWriter, event listeners and the EntryProcessor. These allow the user to register custom code. Alongside the customization interface exceptions are defined.

For example the signature of the cache loader is:

  /**
   * Loads an object. Application developers should implement this
   * method to customize the loading of a value for a cache entry. [ ..... ]
   *
   * @throws CacheLoaderException if there is problem executing the loader.
   */
  V load(K key) throws CacheLoaderException;

However, in the cache loader exception the Java Doc the following sentence can be found:

A Caching Implementation must wrap any {@link Exception} thrown by a {@link CacheLoader} in this exception.

This means that applications need to wrap a checked exception which happens in there cache loader into a CacheLoaderException. The cache implementation needs to catch every exception from the cache loader as well and wrap it into a CacheLoaderException. Following the spec literally the also a CacheLoaderException from the application needs to be wrapped into a CacheLoaderException by the cache implementation.

In case there are checked exceptions in the loader, the specified method signature leads to boiler plate code in the application, looking always like this:

  Value load(Key key) throws CacheLoaderException {
    try {
      return doTheReadLoadWhichMayThrowAnException(key);
    } catch (Exception ex) {
      throw new CacheLoaderException(ex);
    }
  }

The TCK 1.0 also has a special test for the EntryProcessorException, which requires cache implementations to add a special condition not to wrap and EntryProcessorException if it is already of that type. This sould be relaxed in the TCK 1.1 and is addressed by: https://github.com/jsr107/jsr107tck/issues/85.

Another problem area is the callback interface declaration CompletionListener:

  /**
   * Notifies the application that the operation failed.
   *
   * @param e the Exception that occurred
   */
  void onException(Exception e);

This requires cache implementations to wrap to an Exception in case a Throwable was caught.

Proposed changes:

• Cuostomizations may throw any checked exception, the method signature should look: xy() throws Exception;
• Listeners may receive any throwable, the method signature should look: onException(Throwable e)
• Implementations may wrap the original exception arbitrary times to document processing boundaries (different threads, JVMs, hosts)