@Delegate has moved to lombok.experimental.

Some work on the aliasing system to make that go smoothly.
author: Reinier Zwitserloot <reinier@zwitserloot.com> 2014-05-08 06:25:38 +0200
committer: Reinier Zwitserloot <reinier@zwitserloot.com> 2014-05-20 23:43:08 +0200
commit: 4996428ea12be7e381d76614e34a15ad1cc6d275 (patch)
tree: ca5067b7b8f63eff6adeed83f8ff9339128d8ca7 /website
parent: 05ca21b75e5c20e1e731d9141857f346bb3eca9f (diff)
download: lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.tar.gz
lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.tar.bz2
lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.zip
6 files changed, 38 insertions, 27 deletions
diff --git a/website/features/Log.html b/website/features/Log.html
index bc9e017e..f47835c1 100644
--- a/website/features/Log.html
+++ b/website/features/Log.html
@@ -59,7 +59,7 @@
 			</div>
 		</div>
 		<div class="footer">
-			<a href="index.html">Back to features</a> | <a href="GetterLazy.html">Previous feature (@Getter(lazy=true))</a> | <a href="Delegate.html">Next feature (@Delegate)</a><br />
+			<a href="index.html">Back to features</a> | <a href="GetterLazy.html">Previous feature (@Getter(lazy=true))</a> | <span class="disabled">Next feature</span><br />
 			<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
 		</div>
 		<div style="clear: both;"></div>
diff --git a/website/features/Delegate.html b/website/features/experimental/Delegate.html
index 02cdf290..6f745f31 100644
--- a/website/features/Delegate.html
+++ b/website/features/experimental/Delegate.html
@@ -1,38 +1,48 @@
 <!DOCTYPE html>
 <html><head>
 	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-	<link rel="stylesheet" type="text/css" href="../logi/reset.css" />
-	<link rel="stylesheet" type="text/css" href="features.css" />
-	<link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" />
+	<link rel="stylesheet" type="text/css" href="../../logi/reset.css" />
+	<link rel="stylesheet" type="text/css" href="../features.css" />
+	<link rel="shortcut icon" href="../../favicon.ico" type="image/x-icon" />
 	<meta name="description" content="Spice up your java" />
 	<title>@Delegate</title>
 </head><body><div id="pepper">
 	<div class="minimumHeight"></div>
 	<div class="meat">
-		<div class="header"><a href="../index.html">Project Lombok</a></div>
+		<div class="header"><a href="../../index.html">Project Lombok</a></div>
 		<h1>@Delegate</h1>
 		<div class="byline">Don't lose your composition.</div>
-		<div class="overview">
-			<h3>Overview</h3>
+		<div class="since">
+			<h3>Since</h3>
 			<p>
-			<em> NEW IN Lombok 0.10: </em> Any field or no-argument method can be annotated with <code>@Delegate</code> to let lombok generate delegate methods
-			that forward the call to this field (or the result of invoking this method).
+				@Delegate was introduced as feature in lombok v0.10. It was moved to the experimental package in lombok v1.14; the old version from the main lombok package is now deprecated.
 			</p>
+		</div>
+		<div class="experimental">
+			<h3>Experimental</h3>
 			<p>
-			Lombok delegates all <code>public</code> methods of the field's type (or method's return type), as well as those of its supertype except for all
-			methods declared in <code>java.lang.Object</code>.
-			</p>
+			Experimental because:
+			<ul>
+				<li>Not used that much</li>
+				<li>Difficult to support for edge cases, such as recursive delegation.</li>
+				<li>API is rather unfriendly; it would be a lot nicer if you can simply implement some methods and let <code>@Delegate</code> generate delegates for whatever you didn't manually implement, but due to issues with generics erasure this also can't be made to work without caveats.
+			</ul>
+			Current status: <em>negative</em> - Currently we feel this feature will not move out of experimental status anytime soon, and support for this feature may be dropped if future versions of javac or ecj make it difficult to continue to maintain the feature.
+		</div>
+		<div class="overview">
+			<h3>Overview</h3>
 			<p>
+			Any field or no-argument method can be annotated with <code>@Delegate</code> to let lombok generate delegate methods that forward the call to this field (or the result of invoking this method).
+			</p><p>
+			Lombok delegates all <code>public</code> methods of the field's type (or method's return type), as well as those of its supertypes except for all
+			methods declared in <code>java.lang.Object</code>.
+			</p><p>
 			You can pass any number of classes into the <code>@Delegate</code> annotation's <code>types</code> parameter.
-			If you do that, then lombok will delegate all <code>public</code> methods in those types (and their supertypes, except
-			<code>java.lang.Object</code>) instead of looking at the field/method's type.
-			</p>
-			<p>
-			All public non-<code>Object</code> methods that are part of the calculated type(s) are
-			copied, whether or not you also wrote implementations for those methods. That would thus result in duplicate method errors. You can avoid these
+			If you do that, then lombok will delegate all <code>public</code> methods in those types (and their supertypes, except <code>java.lang.Object</code>) instead of looking at the field/method's type.
+			</p><p>
+			All public non-<code>Object</code> methods that are part of the calculated type(s) are copied, whether or not you also wrote implementations for those methods. That would thus result in duplicate method errors. You can avoid these
 			by using the <code>@Delegate(excludes=SomeType.class)</code> parameter to exclude all public methods in the excluded type(s), and their supertypes.
-			</p>
-			<p>
+			</p><p>
 			To have very precise control over what is delegated and what isn't, write private inner interfaces with method signatures, then specify these
 			private inner interfaces as types in <code>@Delegate(types=PrivateInnerInterfaceWithIncludesList.class, excludes=SameForExcludes.class)</code>.
 			</p>
@@ -59,12 +69,13 @@
 			When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example.
 			</p><p>
 			<code>@Delegate</code> cannot be used on static fields or methods.
-			</p>
+			</p><p>
+			<code>@Delegate</code> cannot be used when the calculated type(s) to delegate / exclude themselves contain <code>@Delegate</code> annotations; in other words, <code>@Delegate</code> will error if you attempt to use it recursively.
 			</div>
 		</div>
 		<div class="footer">
-			<a href="index.html">Back to features</a> | <a href="Log.html">Previous feature (@Log)</a> | <span class="disabled">Next feature</span><br />
-			<a href="../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2010-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
+			<a href="index.html">Back to features</a> | <a href="FieldDefaults.html">Previous feature (@FieldDefaults)</a> | <a href="Wither.html">Next feature (@Wither)</a><br />
+			<a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2010-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
 		</div>
 		<div style="clear: both;"></div>
 	</div>
diff --git a/website/features/experimental/FieldDefaults.html b/website/features/experimental/FieldDefaults.html
index eff709ca..969da230 100644
--- a/website/features/experimental/FieldDefaults.html
+++ b/website/features/experimental/FieldDefaults.html
@@ -65,7 +65,7 @@
 			</div>
 		</div>
 		<div class="footer">
-			<a href="index.html">Back to experimental features</a> | <a href="ExtensionMethod.html">Previous feature (@ExtensionMethod)</a> | <a href="Wither.html">Next feature (@Wither)</a><br />
+			<a href="index.html">Back to experimental features</a> | <a href="ExtensionMethod.html">Previous feature (@ExtensionMethod)</a> | <a href="Delegate.html">Next feature (@Delegate)</a><br />
 			<a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
 		</div>
 		<div style="clear: both;"></div>
diff --git a/website/features/experimental/Wither.html b/website/features/experimental/Wither.html
index 46d3b08b..b6634be4 100644
--- a/website/features/experimental/Wither.html
+++ b/website/features/experimental/Wither.html
@@ -85,7 +85,7 @@
 			</div>
 		</div>
 		<div class="footer">
-			<a href="index.html">Back to experimental features</a> | <a href="FieldDefaults.html">Previous feature (@FieldDefaults)</a> | <a href="onX.html">Next feature (onX)</a><br />
+			<a href="index.html">Back to experimental features</a> | <a href="Delegate.html">Previous feature (@Delegate)</a> | <a href="onX.html">Next feature (onX)</a><br />
 			<a href="../../credits.html" class="creditsLink">credits</a> | <span class="copyright">Copyright &copy; 2009-2013 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</span>
 		</div>
 		<div style="clear: both;"></div>
diff --git a/website/features/experimental/index.html b/website/features/experimental/index.html
index 1128787c..9a1c505f 100644
--- a/website/features/experimental/index.html
+++ b/website/features/experimental/index.html
@@ -30,6 +30,8 @@
 				<dd>Annoying API? Fix it yourself: Add new methods to existing types!</dd>
 				<dt><a href="FieldDefaults.html"><code>@FieldDefaults</code></a></dt>
 				<dd>New default field modifiers for the 21st century.</dd>
+				<dt><a href="Delegate.html"><code>@Delegate</code></a></dt>
+				<dd>Don't lose your composition.</dd>
 				<dt><a href="Wither.html"><code>@Wither</code></a></dt>
 				<dd>Immutable 'setters' - methods that create a clone but with one changed field.</dd>
 				<dt><a href="onX.html"><code>onMethod= / onConstructor= / onParam=</code></a></dt>
diff --git a/website/features/index.html b/website/features/index.html
index f9b8cdfa..537ed166 100644
--- a/website/features/index.html
+++ b/website/features/index.html
@@ -40,8 +40,6 @@
 				<dd>Laziness is a virtue!</dd>
 				<dt><a href="Log.html"><code>@Log</code></a></dt>
 				<dd>Captain's Log, stardate 24435.7: &quot;What was that line again?&quot;</dd>
-				<dt><a href="Delegate.html"><code>@Delegate</code></a></dt>
-				<dd>Don't lose your composition.</dd>
 				<dt><a href="experimental/index.html">experimental features</a></dt>
 				<dd>Here be dragons: Extra features which aren't quite ready for prime time yet.</dd>
 			</dl>
author	Reinier Zwitserloot <reinier@zwitserloot.com>	2014-05-08 06:25:38 +0200
committer	Reinier Zwitserloot <reinier@zwitserloot.com>	2014-05-20 23:43:08 +0200
commit	4996428ea12be7e381d76614e34a15ad1cc6d275 (patch)
tree	ca5067b7b8f63eff6adeed83f8ff9339128d8ca7 /website
parent	05ca21b75e5c20e1e731d9141857f346bb3eca9f (diff)
download	lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.tar.gz lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.tar.bz2 lombok-4996428ea12be7e381d76614e34a15ad1cc6d275.zip