diff options
Diffstat (limited to 'website/templates')
| -rw-r--r-- | website/templates/features/experimental/StandardException.html | 53 | ||||
| -rw-r--r-- | website/templates/features/experimental/index.html | 4 |
2 files changed, 57 insertions, 0 deletions
diff --git a/website/templates/features/experimental/StandardException.html b/website/templates/features/experimental/StandardException.html new file mode 100644 index 00000000..1484154d --- /dev/null +++ b/website/templates/features/experimental/StandardException.html @@ -0,0 +1,53 @@ +<#import "../_features.html" as f> + +<@f.scaffold title="@StandardException" + logline="TODO"> + <@f.history> + <p> + <code>@StandardException</code> was introduced as an experimental feature in lombok v1.18.21. + </p> + </@f.history> + + <@f.overview> + <p> + Put this annotation on your own exception types (new classes that <code>extends Exception</code> or anything else that inherits from <code>Throwable</code>. This annotation will then generate up to 4 constructors: + </p><ul> + <li>A no-args constructor (<code>MyException()</code>), representing no message, and no cause.</li> + <li>A message-only constructor (<code>MyException(String message)</code>), representing the provided message, and no cause.</li> + <li>A cause-only constructor (<code>MyException(Throwable cause)</code>), which will copy the message from the cause, if there is one, and uses the provided cause.</li> + <li>A full constructor (<code>MyException(String message, Throwable cause)</code>).</li> + </ul> + <p> + Each constructor forwards to the full constructor; you can write any or all of these constructors manually in which case lombok + will not generate it. The full constructor, if it needs to be generated, will invoke <code>super(message);</code> and will then + invoke <code>super.initCause(cause);</code> if the cause is not null. + </p><p> + There are few reasons <em>not</em> to put this annotation on all your custom exceptions. + </p> + </@f.overview> + + <@f.snippets name="StandardException" /> + + <@f.confKeys> + <dt> + <code>lombok.standardException.addConstructorProperties</code> = [<code>true</code> | <code>false</code>] (default: <code>false</code>) + </dt><dt> + <code>lombok.standardException.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set) + </dt><dd> + Lombok will flag any usage of <code>@StandardException</code> as a warning or error if configured. + </dd> + </@f.confKeys> + + <@f.smallPrint> + <p> + Lombok will not check if you extend an actual exception type. + </p><p> + Lombok does not require that the class you inherit from has the <code>Throwable cause</code> variants, because not all exceptions + have these. However, the `<code>Parent(String message)</code>` constructor as well as the no-args constructor <em>must</em> exist. + </p><p> + There is a very slight functional difference: Normally, invoking <code>new SomeException(message, null)</code> will initialize + the cause to be <em>no cause</em>, and this cannot be later changed by invoking <code>initCause</code>. However, lombok's + standard exceptions <strong>do</strong> let you overwrite an explicit no-cause with <code>initCause</code> later. + </p> + </@f.smallPrint> +</@f.scaffold> diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html index 32590815..a8430d8d 100644 --- a/website/templates/features/experimental/index.html +++ b/website/templates/features/experimental/index.html @@ -75,6 +75,10 @@ <@main.feature title="@Jacksonized" href="Jacksonized"> Bob, meet Jackson. Lets make sure you become fast friends. </@main.feature> + + <@main.feature title="@StandardException" href="StandardException"> + Standard.. Exceptional? This is not just an oxymoron, it's convenient! + </@main.feature> </div> <@f.confKeys> |