From efe46f68a9d0363fd58222048ddfa9efaf1bc9cd Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Sat, 18 Jul 2009 00:25:09 +0200 Subject: Added Cleanup features text. --- build.xml | 3 ++ usage_examples/CleanupExample_post.jpage | 22 ++++++++++++ usage_examples/CleanupExample_pre.jpage | 15 ++++++++ website/features/Cleanup.html | 62 ++++++++++++++++++++++++++++++++ 4 files changed, 102 insertions(+) create mode 100644 usage_examples/CleanupExample_post.jpage create mode 100644 usage_examples/CleanupExample_pre.jpage create mode 100644 website/features/Cleanup.html diff --git a/build.xml b/build.xml index 0291a29b..c2933032 100644 --- a/build.xml +++ b/build.xml @@ -74,6 +74,9 @@ + + + diff --git a/usage_examples/CleanupExample_post.jpage b/usage_examples/CleanupExample_post.jpage new file mode 100644 index 00000000..91458459 --- /dev/null +++ b/usage_examples/CleanupExample_post.jpage @@ -0,0 +1,22 @@ +import java.io.*; + +public class CleanupExample { + public static void main(String[] args) throws IOException { + InputStream in = new FileInputStream(args[0]); + try { + OutputStream out = new FileOutputStream(args[1]); + try { + byte[] b = new byte[10000]; + while (true) { + int r = in.read(b); + if (r == -1) break; + out.write(b, 0, r); + } + } finally { + out.close(); + } + } finally { + in.close(); + } + } +} diff --git a/usage_examples/CleanupExample_pre.jpage b/usage_examples/CleanupExample_pre.jpage new file mode 100644 index 00000000..9f639171 --- /dev/null +++ b/usage_examples/CleanupExample_pre.jpage @@ -0,0 +1,15 @@ +import lombok.Cleanup; +import java.io.*; + +public class CleanupExample { + public static void main(String[] args) throws IOException { + @Cleanup InputStream in = new FileInputStream(args[0]); + @Cleanup OutputStream out = new FileOutputStream(args[1]); + byte[] b = new byte[10000]; + while (true) { + int r = in.read(b); + if (r == -1) break; + out.write(b, 0, r); + } + } +} diff --git a/website/features/Cleanup.html b/website/features/Cleanup.html new file mode 100644 index 00000000..53c94701 --- /dev/null +++ b/website/features/Cleanup.html @@ -0,0 +1,62 @@ + + + + + + + + @Cleanup + +
+
+
+ +

@Cleanup

+
+

Overview

+

+ You can use @Cleanup to ensure a given resource is automatically cleaned up before the code execution path exits your + current scope. You do this by annotating any local variable declaration with the @Cleanup annotation like so:
+ @Cleanup InputStream in = new FileInputStream("some/file");
+ As a result, at the end of the scope you're in, in.close() is called. This call is guaranteed to run by way of a + try/finally construct. Look at the example below to see how this works. +

+ If the type of object you'd like to cleanup does not have a close() method, but some other no-argument method, you can + specify the name of this method like so:
+ @Cleanup("dispose") org.eclipse.swt.widgets.CoolBar bar = new CoolBar(parent, 0);
+ By default, the cleanup method is presumed to be close(). A cleanup method that takes argument cannot be called via + @Cleanup. +

+
+
+
+

With Lombok

+
@HTML_PRE@
+
+
+
+

Vanilla Java

+
@HTML_POST@
+
+
+
+
+

Small print

+

+ If your code throws an exception, and the cleanup method call that is then triggered also throws an exception, then the original exception + is hidden by the exception thrown by the cleanup call. You should not rely on this 'feature'. Preferably, lombok would like to generate + code so that, if the main body has thrown an exception, any exception thrown by the close call is silently swallowed (but if the main body + exited in any other way, exceptions by the close call will not be swallowed). The authors of lombok do not currently know of a feasible way + to implement this scheme, but if java updates allow it, or we find a way, we'll fix it. +

+ You do still need to handle any exception that the cleanup method can generate! +

+
+
+ +
+
+
-- cgit