From cee9942d5ac735d8d143dad9cee019670f3b8ada Mon Sep 17 00:00:00 2001 From: cpovirk Date: Wed, 8 Jun 2016 11:00:10 -0700 Subject: [PATCH] Document that we don't forward calls to default methods, except when we do. Also, standardize on for Warnings. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=124370400 --- .../com/google/common/collect/ForwardingBlockingDeque.java | 4 ++++ .../com/google/common/collect/ForwardingCollection.java | 4 ++++ .../com/google/common/collect/ForwardingConcurrentMap.java | 7 +++++++ guava/src/com/google/common/collect/ForwardingDeque.java | 4 ++++ .../src/com/google/common/collect/ForwardingIterator.java | 7 +++++++ guava/src/com/google/common/collect/ForwardingList.java | 4 ++++ .../com/google/common/collect/ForwardingListIterator.java | 7 +++++++ guava/src/com/google/common/collect/ForwardingMap.java | 6 +++++- .../src/com/google/common/collect/ForwardingMapEntry.java | 2 +- .../src/com/google/common/collect/ForwardingMultiset.java | 4 ++++ .../com/google/common/collect/ForwardingNavigableMap.java | 6 +++++- .../com/google/common/collect/ForwardingNavigableSet.java | 6 +++++- guava/src/com/google/common/collect/ForwardingQueue.java | 4 ++++ guava/src/com/google/common/collect/ForwardingSet.java | 4 ++++ .../src/com/google/common/collect/ForwardingSortedMap.java | 6 +++++- .../google/common/collect/ForwardingSortedMultiset.java | 4 ++++ .../src/com/google/common/collect/ForwardingSortedSet.java | 6 +++++- .../common/util/concurrent/ForwardingBlockingQueue.java | 4 ++++ 18 files changed, 83 insertions(+), 6 deletions(-) diff --git a/guava/src/com/google/common/collect/ForwardingBlockingDeque.java b/guava/src/com/google/common/collect/ForwardingBlockingDeque.java index 489228ba6b27..4e54cd49f904 100644 --- a/guava/src/com/google/common/collect/ForwardingBlockingDeque.java +++ b/guava/src/com/google/common/collect/ForwardingBlockingDeque.java @@ -33,6 +33,10 @@ * behaviour. In this case, you should override {@code offer} as well, either providing your own * implementation, or delegating to the provided {@code standardOffer} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingBlockingDeque}. + * *

* The {@code standard} methods are not guaranteed to be thread-safe, even when all of the methods * that they depend on are thread-safe. diff --git a/guava/src/com/google/common/collect/ForwardingCollection.java b/guava/src/com/google/common/collect/ForwardingCollection.java index 0c20ffba8b5a..281e8739ff09 100644 --- a/guava/src/com/google/common/collect/ForwardingCollection.java +++ b/guava/src/com/google/common/collect/ForwardingCollection.java @@ -38,6 +38,10 @@ * override {@code addAll} as well, either providing your own implementation, or * delegating to the provided {@code standardAddAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingCollection}. + * *

The {@code standard} methods are not guaranteed to be thread-safe, even * when all of the methods that they depend on are thread-safe. * diff --git a/guava/src/com/google/common/collect/ForwardingConcurrentMap.java b/guava/src/com/google/common/collect/ForwardingConcurrentMap.java index 510a98a96770..e2eea926a120 100644 --- a/guava/src/com/google/common/collect/ForwardingConcurrentMap.java +++ b/guava/src/com/google/common/collect/ForwardingConcurrentMap.java @@ -27,6 +27,13 @@ * the backing map as desired per the decorator pattern. * + *

{@code default} method warning: This class forwards calls to only some {@code + * default} methods. Specifically, it forwards calls only for methods that existed before + * {@code default} methods were introduced. For newer methods, like {@code forEach}, it inherits + * their default implementations. When those implementations invoke methods, they invoke methods on + * the {@code ForwardingConcurrentMap}. + * * @author Charles Fry * @since 2.0 */ diff --git a/guava/src/com/google/common/collect/ForwardingDeque.java b/guava/src/com/google/common/collect/ForwardingDeque.java index 35d6a14cfa24..89b57550a97b 100644 --- a/guava/src/com/google/common/collect/ForwardingDeque.java +++ b/guava/src/com/google/common/collect/ForwardingDeque.java @@ -34,6 +34,10 @@ * #offer} which can lead to unexpected behavior. In this case, you should * override {@code offer} as well. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingDeque}. + * * @author Kurt Alfred Kluever * @since 12.0 */ diff --git a/guava/src/com/google/common/collect/ForwardingIterator.java b/guava/src/com/google/common/collect/ForwardingIterator.java index 918467ef4939..fe7b665d0efc 100644 --- a/guava/src/com/google/common/collect/ForwardingIterator.java +++ b/guava/src/com/google/common/collect/ForwardingIterator.java @@ -27,6 +27,13 @@ * backing iterator as desired per the decorator pattern. * + *

{@code default} method warning: This class forwards calls to only some {@code + * default} methods. Specifically, it forwards calls only for methods that existed before {@code default} + * methods were introduced. For newer methods, like {@code forEachRemaining}, it inherits their + * default implementations. When those implementations invoke methods, they invoke methods on the + * {@code ForwardingIterator}. + * * @author Kevin Bourrillion * @since 2.0 */ diff --git a/guava/src/com/google/common/collect/ForwardingList.java b/guava/src/com/google/common/collect/ForwardingList.java index 12762cef0c80..e4918bc2c7ab 100644 --- a/guava/src/com/google/common/collect/ForwardingList.java +++ b/guava/src/com/google/common/collect/ForwardingList.java @@ -44,6 +44,10 @@ * override {@code addAll} as well, either providing your own implementation, or * delegating to the provided {@code standardAddAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingList}. + * *

The {@code standard} methods and any collection views they return are not * guaranteed to be thread-safe, even when all of the methods that they depend * on are thread-safe. diff --git a/guava/src/com/google/common/collect/ForwardingListIterator.java b/guava/src/com/google/common/collect/ForwardingListIterator.java index c1615dfa7fd4..1ebc434e00e8 100644 --- a/guava/src/com/google/common/collect/ForwardingListIterator.java +++ b/guava/src/com/google/common/collect/ForwardingListIterator.java @@ -27,6 +27,13 @@ * behavior of the backing iterator as desired per the decorator pattern. * + *

{@code default} method warning: This class forwards calls to only some {@code + * default} methods. Specifically, it forwards calls only for methods that existed before {@code + * default} methods were introduced. For newer methods, like {@code forEachRemaining}, it + * inherits their default implementations. When those implementations invoke methods, they invoke + * methods on the {@code ForwardingListIterator}. + * * @author Mike Bostock * @since 2.0 */ diff --git a/guava/src/com/google/common/collect/ForwardingMap.java b/guava/src/com/google/common/collect/ForwardingMap.java index 1718fd9494b0..b082322c0ad4 100644 --- a/guava/src/com/google/common/collect/ForwardingMap.java +++ b/guava/src/com/google/common/collect/ForwardingMap.java @@ -34,13 +34,17 @@ * desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingMap} forward + *

Warning: The methods of {@code ForwardingMap} forward * indiscriminately to the methods of the delegate. For example, * overriding {@link #put} alone will not change the behavior of {@link * #putAll}, which can lead to unexpected behavior. In this case, you should * override {@code putAll} as well, either providing your own implementation, or * delegating to the provided {@code standardPutAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingMap}. + * *

Each of the {@code standard} methods, where appropriate, use {@link * Objects#equal} to test equality for both keys and values. This may not be * the desired behavior for map implementations that use non-standard notions of diff --git a/guava/src/com/google/common/collect/ForwardingMapEntry.java b/guava/src/com/google/common/collect/ForwardingMapEntry.java index 559f0bbc6bef..dce357e11b17 100644 --- a/guava/src/com/google/common/collect/ForwardingMapEntry.java +++ b/guava/src/com/google/common/collect/ForwardingMapEntry.java @@ -31,7 +31,7 @@ * backing map entry as desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingMapEntry} forward + *

Warning: The methods of {@code ForwardingMapEntry} forward * indiscriminately to the methods of the delegate. For example, * overriding {@link #getValue} alone will not change the behavior of * {@link #equals}, which can lead to unexpected behavior. In this case, you diff --git a/guava/src/com/google/common/collect/ForwardingMultiset.java b/guava/src/com/google/common/collect/ForwardingMultiset.java index da1ff2af8c63..cfeba77d0a47 100644 --- a/guava/src/com/google/common/collect/ForwardingMultiset.java +++ b/guava/src/com/google/common/collect/ForwardingMultiset.java @@ -41,6 +41,10 @@ * your own implementation, or delegating to the provided {@code standardAdd} * method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingMultiset}. + * *

The {@code standard} methods and any collection views they return are not * guaranteed to be thread-safe, even when all of the methods that they depend * on are thread-safe. diff --git a/guava/src/com/google/common/collect/ForwardingNavigableMap.java b/guava/src/com/google/common/collect/ForwardingNavigableMap.java index 9af6b94f4b97..e96cf5033ab0 100644 --- a/guava/src/com/google/common/collect/ForwardingNavigableMap.java +++ b/guava/src/com/google/common/collect/ForwardingNavigableMap.java @@ -33,12 +33,16 @@ * override one or more methods to modify the behavior of the backing map as desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingNavigableMap} forward indiscriminately + *

Warning: The methods of {@code ForwardingNavigableMap} forward indiscriminately * to the methods of the delegate. For example, overriding {@link #put} alone will not * change the behavior of {@link #putAll}, which can lead to unexpected behavior. In this case, you * should override {@code putAll} as well, either providing your own implementation, or delegating * to the provided {@code standardPutAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingNavigableMap}. + * *

Each of the {@code standard} methods uses the map's comparator (or the natural ordering of * the elements, if there is no comparator) to test element equality. As a result, if the comparator * is not consistent with equals, some of the standard implementations may violate the {@code Map} diff --git a/guava/src/com/google/common/collect/ForwardingNavigableSet.java b/guava/src/com/google/common/collect/ForwardingNavigableSet.java index ef67cb693ae2..bd741bc899ae 100644 --- a/guava/src/com/google/common/collect/ForwardingNavigableSet.java +++ b/guava/src/com/google/common/collect/ForwardingNavigableSet.java @@ -28,12 +28,16 @@ * override one or more methods to modify the behavior of the backing set as desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingNavigableSet} forward indiscriminately + *

Warning: The methods of {@code ForwardingNavigableSet} forward indiscriminately * to the methods of the delegate. For example, overriding {@link #add} alone will not * change the behavior of {@link #addAll}, which can lead to unexpected behavior. In this case, you * should override {@code addAll} as well, either providing your own implementation, or delegating * to the provided {@code standardAddAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingNavigableSet}. + * *

Each of the {@code standard} methods uses the set's comparator (or the natural ordering of * the elements, if there is no comparator) to test element equality. As a result, if the * comparator is not consistent with equals, some of the standard implementations may violate the diff --git a/guava/src/com/google/common/collect/ForwardingQueue.java b/guava/src/com/google/common/collect/ForwardingQueue.java index b03583efaf3f..1e1dd93abc3f 100644 --- a/guava/src/com/google/common/collect/ForwardingQueue.java +++ b/guava/src/com/google/common/collect/ForwardingQueue.java @@ -35,6 +35,10 @@ * override {@code offer} as well, either providing your own implementation, or * delegating to the provided {@code standardOffer} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingQueue}. + * *

The {@code standard} methods are not guaranteed to be thread-safe, even * when all of the methods that they depend on are thread-safe. * diff --git a/guava/src/com/google/common/collect/ForwardingSet.java b/guava/src/com/google/common/collect/ForwardingSet.java index 0430af8297e1..880bbfb76599 100644 --- a/guava/src/com/google/common/collect/ForwardingSet.java +++ b/guava/src/com/google/common/collect/ForwardingSet.java @@ -38,6 +38,10 @@ * override {@code addAll} as well, either providing your own implementation, or * delegating to the provided {@code standardAddAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingSet}. + * *

The {@code standard} methods are not guaranteed to be thread-safe, even * when all of the methods that they depend on are thread-safe. * diff --git a/guava/src/com/google/common/collect/ForwardingSortedMap.java b/guava/src/com/google/common/collect/ForwardingSortedMap.java index 5ccd45b2c742..fd72084622fa 100644 --- a/guava/src/com/google/common/collect/ForwardingSortedMap.java +++ b/guava/src/com/google/common/collect/ForwardingSortedMap.java @@ -33,13 +33,17 @@ * the backing sorted map as desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingSortedMap} forward + *

Warning: The methods of {@code ForwardingSortedMap} forward * indiscriminately to the methods of the delegate. For example, * overriding {@link #put} alone will not change the behavior of {@link * #putAll}, which can lead to unexpected behavior. In this case, you should * override {@code putAll} as well, either providing your own implementation, or * delegating to the provided {@code standardPutAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingSortedMap}. + * *

Each of the {@code standard} methods, where appropriate, use the * comparator of the map to test equality for both keys and values, unlike * {@code ForwardingMap}. diff --git a/guava/src/com/google/common/collect/ForwardingSortedMultiset.java b/guava/src/com/google/common/collect/ForwardingSortedMultiset.java index 2f0cbbe42fe1..162c6e427b74 100644 --- a/guava/src/com/google/common/collect/ForwardingSortedMultiset.java +++ b/guava/src/com/google/common/collect/ForwardingSortedMultiset.java @@ -33,6 +33,10 @@ * well, either providing your own implementation, or delegating to the provided {@code * standardAdd} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingSortedMultiset}. + * *

The {@code standard} methods and any collection views they return are not guaranteed to be * thread-safe, even when all of the methods that they depend on are thread-safe. * diff --git a/guava/src/com/google/common/collect/ForwardingSortedSet.java b/guava/src/com/google/common/collect/ForwardingSortedSet.java index 63ebec27d52a..b0cf6c154dfe 100644 --- a/guava/src/com/google/common/collect/ForwardingSortedSet.java +++ b/guava/src/com/google/common/collect/ForwardingSortedSet.java @@ -32,13 +32,17 @@ * backing sorted set as desired per the decorator pattern. * - *

Warning: The methods of {@code ForwardingSortedSet} forward + *

Warning: The methods of {@code ForwardingSortedSet} forward * indiscriminately to the methods of the delegate. For example, * overriding {@link #add} alone will not change the behavior of {@link * #addAll}, which can lead to unexpected behavior. In this case, you should * override {@code addAll} as well, either providing your own implementation, or * delegating to the provided {@code standardAddAll} method. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingSortedSet}. + * *

Each of the {@code standard} methods, where appropriate, uses the set's * comparator (or the natural ordering of the elements, if there is no * comparator) to test element equality. As a result, if the comparator is not diff --git a/guava/src/com/google/common/util/concurrent/ForwardingBlockingQueue.java b/guava/src/com/google/common/util/concurrent/ForwardingBlockingQueue.java index ea3efa0af693..2da90cab5d70 100644 --- a/guava/src/com/google/common/util/concurrent/ForwardingBlockingQueue.java +++ b/guava/src/com/google/common/util/concurrent/ForwardingBlockingQueue.java @@ -28,6 +28,10 @@ * as desired per the decorator * pattern. * + *

{@code default} method warning: This class does not forward calls to {@code + * default} methods. Instead, it inherits their default implementations. When those implementations + * invoke methods, they invoke methods on the {@code ForwardingBlockingQueue}. + * * @author Raimundo Mirisola * * @param the type of elements held in this collection