    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 implementation of {@link Multiset#elementSet} in terms of the
    236       * following methods: {@link ForwardingMultiset#clear}, {@link
    237       * ForwardingMultiset#contains}, {@link ForwardingMultiset#containsAll},
    238       * {@link ForwardingMultiset#count}, {@link ForwardingMultiset#isEmpty}, the
    239       * {@link Set#size} and {@link Set#iterator} methods of {@link
    240       * ForwardingMultiset#entrySet}, and {@link ForwardingMultiset#remove(Object,
    241       * int)}.  In many situations, you may wish to override {@link
    242       * ForwardingMultiset#elementSet} to forward to this implementation or a
    243       * subclass thereof.
    244       *
    245       * @since 10.0
    246       */
    247      @Beta
    248      protected class StandardElementSet extends Multisets.ElementSet<E> {
    249        /** Constructor for use by subclasses. */
    250        public StandardElementSet() {}
    251
    252        @Override
    253        Multiset<E> multiset() {
    254          return ForwardingMultiset.this;
    255        }
    256      }
    257
    258      /**
    259       * A sensible definition of {@link #iterator} in terms of {@link #entrySet}
    260       * and {@link #remove(Object)}. If you override either of these methods, you
    261       * may wish to override {@link #iterator} to forward to this implementation.
    262       *
    263       * @since 7.0
    264       */
    265      @Beta protected Iterator<E> standardIterator() {
    266        return Multisets.iteratorImpl(this);
    267      }
    268
    269      /**
    270       * A sensible, albeit inefficient, definition of {@link #size} in terms of
    271       * {@link #entrySet}. If you override {@link #entrySet}, you may wish to
    272       * override {@link #size} to forward to this implementation.
    273       *
    274       * @since 7.0
    275       */
    276      @Beta protected int standardSize() {
    277        return Multisets.sizeImpl(this);
    278      }
    279
    280      /**
    281       * A sensible, albeit inefficient, definition of {@link #size} in terms of
    282       * {@code entrySet().size()} and {@link #count}. If you override either of
    283       * these methods, you may wish to override {@link #size} to forward to this
    284       * implementation.
    285       *
    286       * @since 7.0
    287       */
    288      @Beta protected boolean standardEquals(@Nullable Object object) {
    289        return Multisets.equalsImpl(this, object);
    290      }
    291
    292      /**
    293       * A sensible definition of {@link #hashCode} as {@code entrySet().hashCode()}
    294       * . If you override {@link #entrySet}, you may wish to override {@link
    295       * #hashCode} to forward to this implementation.
    296       *
    297       * @since 7.0
    298       */
    299      @Beta protected int standardHashCode() {
    300        return entrySet().hashCode();
    301      }
    302
    303      /**
    304       * A sensible definition of {@link #toString} as {@code entrySet().toString()}
    305       * . If you override {@link #entrySet}, you may wish to override {@link
    306       * #toString} to forward to this implementation.
    307       *
    308       * @since 7.0
    309       */
    310      @Beta @Override protected String standardToString() {
    311        return entrySet().toString();
    312      }
    313    }