    001    /*
    002     * Copyright (C) 2007 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.collect;
    018
    019    import com.google.common.annotations.Beta;
    020    import com.google.common.annotations.GwtCompatible;
    021    import com.google.common.base.Objects;
    022
    023    import java.util.Collection;
    024    import java.util.Iterator;
    025    import java.util.Set;
    026
    027    import javax.annotation.Nullable;
    028
    029    /**
    030     * A multiset which forwards all its method calls to another multiset.
    031     * Subclasses should override one or more methods to modify the behavior of the
    032     * backing multiset as desired per the <a
    033     * href="http://en.wikipedia.org/wiki/Decorator_pattern">decorator pattern</a>.
    034     *
    035     * <p><b>Warning:</b> The methods of {@code ForwardingMultiset} forward
    036     * <b>indiscriminately</b> to the methods of the delegate. For example,
    037     * overriding {@link #add(Object, int)} alone <b>will not</b> change the
    038     * behavior of {@link #add(Object)}, which can lead to unexpected behavior. In
    039     * this case, you should override {@code add(Object)} as well, either providing
    040     * your own implementation, or delegating to the provided {@code standardAdd}
    041     * method.
    042     *
    043     * <p>The {@code standard} methods and any collection views they return are not
    044     * guaranteed to be thread-safe, even when all of the methods that they depend
    045     * on are thread-safe.
    046     *
    047     * @author Kevin Bourrillion
    048     * @author Louis Wasserman
    049     * @since 2.0 (imported from Google Collections Library)
    050     */
    051    @GwtCompatible
    052    public abstract class ForwardingMultiset<E> extends ForwardingCollection<E>
    053        implements Multiset<E> {
    054
    055      /** Constructor for use by subclasses. */
    056      protected ForwardingMultiset() {}
    057
    058      @Override protected abstract Multiset<E> delegate();
    059
    060      @Override
    061      public int count(Object element) {
    062        return delegate().count(element);
    063      }
    064
    065      @Override
    066      public int add(E element, int occurrences) {
    067        return delegate().add(element, occurrences);
    068      }
    069
    070      @Override
    071      public int remove(Object element, int occurrences) {
    072        return delegate().remove(element, occurrences);
    073      }
    074
    075      @Override
    076      public Set<E> elementSet() {
    077        return delegate().elementSet();
    078      }
    079
    080      @Override
    081      public Set<Entry<E>> entrySet() {
    082        return delegate().entrySet();
    083      }
    084
    085      @Override public boolean equals(@Nullable Object object) {
    086        return object == this || delegate().equals(object);
    087      }
    088
    089      @Override public int hashCode() {
    090        return delegate().hashCode();
    091      }
    092
    093      @Override
    094      public int setCount(E element, int count) {
    095        return delegate().setCount(element, count);
    096      }
    097
    098      @Override
    099      public boolean setCount(E element, int oldCount, int newCount) {
    100        return delegate().setCount(element, oldCount, newCount);
    101      }
    102
    103      /**
    104       * A sensible definition of {@link #contains} in terms of {@link #count}. If
    105       * you override {@link #count}, you may wish to override {@link #contains} to
    106       * forward to this implementation.
    107       *
    108       * @since 7.0
    109       */
    110      @Override @Beta protected boolean standardContains(@Nullable Object object) {
    111        return count(object) > 0;
    112      }
    113
    114      /**
    115       * A sensible definition of {@link #clear} in terms of the {@code iterator}
    116       * method of {@link #entrySet}. If you override {@link #entrySet}, you may
    117       * wish to override {@link #clear} to forward to this implementation.
    118       *
    119       * @since 7.0
    120       */
    121      @Override @Beta protected void standardClear() {
    122        Iterator<Entry<E>> entryIterator = entrySet().iterator();
    123        while (entryIterator.hasNext()) {
    124          entryIterator.next();
    125          entryIterator.remove();
    126        }
    127      }
    128
    129      /**
    130       * A sensible, albeit inefficient, definition of {@link #count} in terms of
    131       * {@link #entrySet}. If you override {@link #entrySet}, you may wish to
    132       * override {@link #count} to forward to this implementation.
    133       *
    134       * @since 7.0
    135       */
    136      @Beta protected int standardCount(@Nullable Object object) {
    137        for (Entry<?> entry : this.entrySet()) {
    138          if (Objects.equal(entry.getElement(), object)) {
    139            return entry.getCount();
    140          }
    141        }
    142        return 0;
    143      }
    144
    145      /**
    146       * A sensible definition of {@link #add(Object)} in terms of {@link
    147       * #add(Object, int)}. If you override {@link #add(Object, int)}, you may
    148       * wish to override {@link #add(Object)} to forward to this implementation.
    149       *
    150       * @since 7.0
    151       */
    152      @Beta protected boolean standardAdd(E element) {
    153        add(element, 1);
    154        return true;
    155      }
    156
    157      /**
    158       * A sensible definition of {@link #addAll(Collection)} in terms of {@link
    159       * #add(Object)} and {@link #add(Object, int)}. If you override either of
    160       * these methods, you may wish to override {@link #addAll(Collection)} to
    161       * forward to this implementation.
    162       *
    163       * @since 7.0
    164       */
    165      @Beta @Override protected boolean standardAddAll(
    166          Collection<? extends E> elementsToAdd) {
    167        return Multisets.addAllImpl(this, elementsToAdd);
    168      }
    169
    170      /**
    171       * A sensible definition of {@link #remove(Object)} in terms of {@link
    172       * #remove(Object, int)}. If you override {@link #remove(Object, int)}, you
    173       * may wish to override {@link #remove(Object)} to forward to this
    174       * implementation.
    175       *
    176       * @since 7.0
    177       */
    178      @Beta @Override protected boolean standardRemove(Object element) {
    179        return remove(element, 1) > 0;
    180      }
    181
    182      /**
    183       * A sensible definition of {@link #removeAll} in terms of the {@code
    184       * removeAll} method of {@link #elementSet}. If you override {@link
    185       * #elementSet}, you may wish to override {@link #removeAll} to forward to
    186       * this implementation.
    187       *
    188       * @since 7.0
    189       */
    190      @Beta @Override protected boolean standardRemoveAll(
    191          Collection<?> elementsToRemove) {
    192        return Multisets.removeAllImpl(this, elementsToRemove);
    193      }
    194
    195      /**
    196       * A sensible definition of {@link #retainAll} in terms of the {@code
    197       * retainAll} method of {@link #elementSet}. If you override {@link
    198       * #elementSet}, you may wish to override {@link #retainAll} to forward to
    199       * this implementation.
    200       *
    201       * @since 7.0
    202       */
    203      @Beta @Override protected boolean standardRetainAll(
    204          Collection<?> elementsToRetain) {
    205        return Multisets.retainAllImpl(this, elementsToRetain);
    206      }
    207
    208      /**
    209       * A sensible definition of {@link #setCount(Object, int)} in terms of {@link
    210       * #count(Object)}, {@link #add(Object, int)}, and {@link #remove(Object,
    211       * int)}. {@link #entrySet()}. If you override any of these methods, you may
    212       * wish to override {@link #setCount(Object, int)} to forward to this
    213       * implementation.
    214       *
    215       * @since 7.0
    216       */
    217      @Beta protected int standardSetCount(E element, int count) {
    218        return Multisets.setCountImpl(this, element, count);
    219      }
    220
    221      /**
    222       * A sensible definition of {@link #setCount(Object, int, int)} in terms of
    223       * {@link #count(Object)} and {@link #setCount(Object, int)}. If you override
    224       * either of these methods, you may wish to override {@link #setCount(Object,
    225       * int, int)} to forward to this implementation.
    226       *
    227       * @since 7.0
    228       */
    229      @Beta protected boolean standardSetCount(
    230          E element, int oldCount, int newCount) {
    231        return Multisets.setCountImpl(this, element, oldCount, newCount);
    232      }
    233
    234      /**
    235       * A sensible definition of {@link #elementSet} in terms of the following
    236       * methods: {@link #clear}, {@link #contains}, {@link #containsAll},
    237       * {@link #count}, {@link #isEmpty}, the {@code size()} and {@code iterator()}
    238       * methods of {@link #entrySet}, and {@link #remove(Object, int)}.  In many
    239       * situations, you may wish to override {@link #elementSet} to forward to this
    240       * implementation.
    241       *
    242       * @since 7.0
    243       * @deprecated Use the {@code StandardElementSet} constructor instead.  This
    244       *             method will be removed from Guava in Guava release 11.0.
    245       */
    246      @Beta @Deprecated protected Set<E> standardElementSet() {
    247        return new StandardElementSet();
    248      }
    249
    250      /**
    251       * A sensible implementation of {@link Multiset#elementSet} in terms of the
    252       * following methods: {@link ForwardingMultiset#clear}, {@link
    253       * ForwardingMultiset#contains}, {@link ForwardingMultiset#containsAll},
    254       * {@link ForwardingMultiset#count}, {@link ForwardingMultiset#isEmpty}, the
    255       * {@link Set#size} and {@link Set#iterator} methods of {@link
    256       * ForwardingMultiset#entrySet}, and {@link ForwardingMultiset#remove(Object,
    257       * int)}.  In many situations, you may wish to override {@link
    258       * ForwardingMultiset#elementSet} to forward to this implementation or a
    259       * subclass thereof.
    260       *
    261       * @since 10.0
    262       */
    263      @Beta
    264      protected class StandardElementSet extends Multisets.ElementSet<E> {
    265        public StandardElementSet() {}
    266
    267        @Override
    268        Multiset<E> multiset() {
    269          return ForwardingMultiset.this;
    270        }
    271      }
    272
    273      /**
    274       * A sensible definition of {@link #iterator} in terms of {@link #entrySet}
    275       * and {@link #remove(Object)}. If you override either of these methods, you
    276       * may wish to override {@link #iterator} to forward to this implementation.
    277       *
    278       * @since 7.0
    279       */
    280      @Beta protected Iterator<E> standardIterator() {
    281        return Multisets.iteratorImpl(this);
    282      }
    283
    284      /**
    285       * A sensible, albeit inefficient, definition of {@link #size} in terms of
    286       * {@link #entrySet}. If you override {@link #entrySet}, you may wish to
    287       * override {@link #size} to forward to this implementation.
    288       *
    289       * @since 7.0
    290       */
    291      @Beta protected int standardSize() {
    292        return Multisets.sizeImpl(this);
    293      }
    294
    295      /**
    296       * A sensible, albeit inefficient, definition of {@link #size} in terms of
    297       * {@code entrySet().size()} and {@link #count}. If you override either of
    298       * these methods, you may wish to override {@link #size} to forward to this
    299       * implementation.
    300       *
    301       * @since 7.0
    302       */
    303      @Beta protected boolean standardEquals(@Nullable Object object) {
    304        return Multisets.equalsImpl(this, object);
    305      }
    306
    307      /**
    308       * A sensible definition of {@link #hashCode} as {@code entrySet().hashCode()}
    309       * . If you override {@link #entrySet}, you may wish to override {@link
    310       * #hashCode} to forward to this implementation.
    311       *
    312       * @since 7.0
    313       */
    314      @Beta protected int standardHashCode() {
    315        return entrySet().hashCode();
    316      }
    317
    318      /**
    319       * A sensible definition of {@link #toString} as {@code entrySet().toString()}
    320       * . If you override {@link #entrySet}, you may wish to override {@link
    321       * #toString} to forward to this implementation.
    322       *
    323       * @since 7.0
    324       */
    325      @Beta @Override protected String standardToString() {
    326        return entrySet().toString();
    327      }
    328    }