diff --git a/build.xml b/build.xml index ceb7ab21..2d9e2cd0 100644 --- a/build.xml +++ b/build.xml @@ -80,6 +80,9 @@ + + + diff --git a/usage_examples/SneakyThrowsExample_post.jpage b/usage_examples/SneakyThrowsExample_post.jpage new file mode 100644 index 00000000..916d94f0 --- /dev/null +++ b/usage_examples/SneakyThrowsExample_post.jpage @@ -0,0 +1,19 @@ +import lombok.Lombok; + +public class SneakyThrowsExample implements Runnable { + public String utf8ToString(byte[] bytes) { + try { + return new String(bytes, "UTF-8"); + } catch (UnsupportedEncodingException e) { + throw Lombok.sneakyThrow(e); + } + } + + public void run() { + try { + throw new Throwable(); + } catch (Throwable t) { + throw Lombok.sneakyThrow(t); + } + } +} diff --git a/usage_examples/SneakyThrowsExample_pre.jpage b/usage_examples/SneakyThrowsExample_pre.jpage new file mode 100644 index 00000000..be6d72d5 --- /dev/null +++ b/usage_examples/SneakyThrowsExample_pre.jpage @@ -0,0 +1,13 @@ +import lombok.SneakyThrows; + +public class SneakyThrowsExample implements Runnable { + @SneakyThrows(UnsupportedEncodingException.class) + public String utf8ToString(byte[] bytes) { + return new String(bytes, "UTF-8"); + } + + @SneakyThrows + public void run() { + throw new Throwable(); + } +} diff --git a/website/features/SneakyThrows.html b/website/features/SneakyThrows.html new file mode 100644 index 00000000..b5d3194a --- /dev/null +++ b/website/features/SneakyThrows.html @@ -0,0 +1,78 @@ + + + + + + + + @SneakyThrows + +
+
+
+
Project Lombok
+

@SneakyThrows

+
To boldly throw checked exceptions where no one has thrown them before!
+
+

Overview

+

+ @SneakyThrows can be used to sneakily throw checked exceptions without actually declaring this in your method's throws + clause. This somewhat contentious ability should be used carefully, of course. The code generated by lombok will not ignore, wrap, replace, + or otherwise modify the thrown checked exception; it simply fakes out the compiler. On the JVM (class file) level, all exceptions, checked or not, + can be thrown regardless of the throws clause of your methods, which is why this works. +

+ CAREFUL: Unlike other lombok transformations, you need to put lombok.jar on your classpath when + you run your program. +

+ Common use cases for when you want to opt out of the checked exception mechanism center around 2 situations:

  • +
      A needlessly strict interface, such as Runnable - whatever exception propagates out of your run() method, + checked or not, it will be passed to the Thread's unhandled exception handler. Catching a checked exception and wrapping it + in some sort of RuntimeException is only obscuring the real cause of the issue.
    +
      An 'impossible' exception. For example, new String(someByteArray, "UTF-8"); declares that it can throw an + UnsupportedEncodingException but according to the JVM specification, UTF-8 must always be available. An + UnsupportedEncodingException here is about as likely as a ClassNotFoundError when you use a String object, + and you don't catch those either!
    +

    + Be aware that it is impossible to catch sneakily thrown checked types directly, as javac will not let you write a catch block + for an exception type that no method call in the try body declares as thrown. This problem is not relevant in either of the use cases listed + above, so let this serve as a warning that you should not use the @SneakyThrows mechanism without some deliberation! +

    + You can pass any number of exceptions to the @SneakyThrows annotation. If you pass no exceptions, you may throw any + exception sneakily. +

    • +
    +
    +

    With Lombok

    +
    @HTML_PRE@
    +
    +
    +
    +

    Vanilla Java

    +
    @HTML_POST@
    +
    +
    +
    +
    +

    Small print

    +

    + Because @SneakyThrows is an implementation detail and not part of your method signature, it is an error if you try to + declare a checked exception as sneakily thrown when you don't call any methods that throw this exception. (Doing so is perfectly legal + for throws statements to accomodate subclasses). Similarly, @SneakyThrows does not inherit. +

    + For the nay-sayers in the crowd: Out of the box, Eclipse will offer a 'quick-fix' for uncaught exceptions that wraps the offending + statement in a try/catch block with just e.printStackTrace() in the catch block. This is so spectacularly non-productive + compared to just sneakily throwing the exception onwards, that Roel and Reinier feel more than justified in claiming that the + checked exception system is far from perfect, and thus an opt-out mechanism is warranted. +

    + Currently usage of @SneakyThrows requires you to have lombok.jar in the classpath at runtime. However, in the future + we will attempt to eliminate this requirement - when we figure out how we can do that. If anyone has a good idea on how to make that happen, let us know! +

    +
    +
    +
    + Back to features | Previous feature (@Synchronized) | Next feature
    + Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT licence. +
    +
    +
    +