From 045bc9a60d7d97985791ec80b8b423a49e5c1a7a Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Mon, 9 May 2011 22:05:43 +0200 Subject: Updated Delegate docs now that we've changed how it works (it no longer detects that you've implemented a few to-be delegated methods yourself). --- usage_examples/DelegateExample_post.jpage | 66 ++++++++++++++++--------------- usage_examples/DelegateExample_pre.jpage | 34 ++++++++++------ website/features/Delegate.html | 23 ++++++++--- 3 files changed, 73 insertions(+), 50 deletions(-) diff --git a/usage_examples/DelegateExample_post.jpage b/usage_examples/DelegateExample_post.jpage index 28c1bbb7..af2acc1a 100644 --- a/usage_examples/DelegateExample_post.jpage +++ b/usage_examples/DelegateExample_post.jpage @@ -2,15 +2,45 @@ import java.util.ArrayList; import java.util.Collection; import lombok.Delegate; -public class DelegateExample { +public class DelegationExample { + private interface SimpleCollection { + boolean add(String item); + boolean remove(Object item); + } + + @Delegate(types=SimpleCollection.class) + private final Collection collection = new ArrayList(); + + @java.lang.SuppressWarnings("all") + public boolean add(final java.lang.String item) { + return this.collection.add(item); + } + @java.lang.SuppressWarnings("all") + public boolean remove(final java.lang.Object item) { + return this.collection.remove(item); + } +} + +class ExcludesDelegateExample { long counter = 0L; - @Delegate + + private interface Add { + boolean add(String x); + boolean addAll(Collection x); + } + + @Delegate(excludes=Add.class) private final Collection collection = new ArrayList(); - public boolean add(String name) { + public boolean add(String item) { counter++; - return collection.add(name); + return collection.add(item); + } + + public boolean addAll(Collection col) { + counter += col.size(); + return collection.addAll(col); } @java.lang.SuppressWarnings("all") @@ -53,11 +83,6 @@ public class DelegateExample { return this.collection.containsAll(arg0); } - @java.lang.SuppressWarnings("all") - public boolean addAll(final java.util.Collection arg0) { - return this.collection.addAll(arg0); - } - @java.lang.SuppressWarnings("all") public boolean removeAll(final java.util.Collection arg0) { return this.collection.removeAll(arg0); @@ -73,26 +98,3 @@ public class DelegateExample { this.collection.clear(); } } - -class PartialDelegationExample { - - @Delegate({SimpleCollection.class}) - private final Collection collection = new ArrayList(); - - private interface SimpleCollection { - - boolean add(String item); - - boolean remove(Object item); - } - - @java.lang.SuppressWarnings("all") - public boolean add(final java.lang.String item) { - return this.collection.add(item); - } - - @java.lang.SuppressWarnings("all") - public boolean remove(final java.lang.Object item) { - return this.collection.remove(item); - } -} \ No newline at end of file diff --git a/usage_examples/DelegateExample_pre.jpage b/usage_examples/DelegateExample_pre.jpage index b208c4ca..b6f05dfb 100644 --- a/usage_examples/DelegateExample_pre.jpage +++ b/usage_examples/DelegateExample_pre.jpage @@ -3,25 +3,35 @@ import java.util.Collection; import lombok.Delegate; +public class DelegationExample { + private interface SimpleCollection { + boolean add(String item); + boolean remove(Object item); + } + + @Delegate(types=SimpleCollection.class) + private final Collection collection = new ArrayList(); +} + -public class DelegateExample { +class ExcludesDelegateExample { long counter = 0L; - @Delegate + private interface Add { + boolean add(String x); + boolean addAll(Collection x); + } + + @Delegate(excludes=Add.class) private final Collection collection = new ArrayList(); - public boolean add(String name) { + public boolean add(String item) { counter++; - return collection.add(name); + return collection.add(item); } -} - -class PartialDelegationExample { - @Delegate({SimpleCollection.class}) - private final Collection collection = new ArrayList(); - private interface SimpleCollection { - boolean add(String item); - boolean remove(Object item); + public boolean addAll(Collection col) { + counter += col.size(); + return collection.addAll(col); } } diff --git a/website/features/Delegate.html b/website/features/Delegate.html index 52b1035d..99f8a559 100644 --- a/website/features/Delegate.html +++ b/website/features/Delegate.html @@ -20,12 +20,21 @@

Lombok delegates all public methods of the field's type, as well as those of its supertype except for all methods declared - in java.lang.Object. You can provide a specific implementation for a method by providing you own implementation, lombok will not - generate delegate methods for those already declared in the class. + in java.lang.Object.

- You can pass any number of classes into the @Delegate annotation. If you do that, then lombok will delegate all public - methods in those types (and their supertypes, except java.lang.Object) instead of looking at the field's type. + You can pass any number of classes into the @Delegate annotation's types parameter. + If you do that, then lombok will delegate all public methods in those types (and their supertypes, except + java.lang.Object) instead of looking at the field's type. +

+

+ All public non-Object methods that are part of the field's type (or, if you used types parameter, the methods of those types) 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 @Delegate(excludes=SomeType.class) parameter to exclude all public methods in the excluded type(s), and their supertypes. +

+

+ 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 @Delegate(types=PrivateInnerInterfaceWithIncludesList.class, excludes=SameForExcludes.class).

@@ -43,12 +52,14 @@

Small print

- When passing classes to the annotation, these cannot contain generics. This is a limitation of java that lombok cannot work around. + When passing classes to the annotation's types or excludes parameter, you cannot include generics. + This is a limitation of java. Use private inner interfaces or classes that extend the intended type including the + generics parameter to work around this problem.

When passing classes to the annotation, these classes do not need to be supertypes of the field. See the example.

-