diff options
Diffstat (limited to 'website')
3 files changed, 26 insertions, 7 deletions
diff --git a/website/templates/features/experimental/StandardException.html b/website/templates/features/experimental/StandardException.html index 25324c4b..1484154d 100644 --- a/website/templates/features/experimental/StandardException.html +++ b/website/templates/features/experimental/StandardException.html @@ -10,9 +10,19 @@ <@f.overview> <p> - This annotation is intended to be used on subclasses of <code>java.util.Throwable</code>. For each of the four constructors in <code>Throwable</code>, it will generate a corresponding constructor in the target class, that simply forwards its argument to its super-counterpart. + 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> - If any of those constructors is manually overriden, it is simply skipped. This allows applying special treatment such as annotations. + There are few reasons <em>not</em> to put this annotation on all your custom exceptions. </p> </@f.overview> @@ -30,7 +40,14 @@ <@f.smallPrint> <p> - Although such situation is unlikely to occur, this annotation can technically be applied to any class for which all four expected constructors are defined in a superclass. + 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 34dd3bb4..a8430d8d 100644 --- a/website/templates/features/experimental/index.html +++ b/website/templates/features/experimental/index.html @@ -77,7 +77,7 @@ </@main.feature> <@main.feature title="@StandardException" href="StandardException"> - TODO + Standard.. Exceptional? This is not just an oxymoron, it's convenient! </@main.feature> </div> diff --git a/website/usageExamples/StandardExceptionExample_post.jpage b/website/usageExamples/StandardExceptionExample_post.jpage index 148603a9..950ca898 100644 --- a/website/usageExamples/StandardExceptionExample_post.jpage +++ b/website/usageExamples/StandardExceptionExample_post.jpage @@ -1,16 +1,18 @@ public class ExampleException extends Exception { public ExampleException() { + this(null, null); } public ExampleException(String message) { - super(message); + this(message, null); } public ExampleException(Throwable cause) { - super(cause); + this(cause != null ? cause.getMessage() : null, cause); } public ExampleException(String message, Throwable cause) { - super(message, cause); + super(message); + if (cause != null) super.initCause(cause); } }
\ No newline at end of file |