PredicatedBag.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.collections4.bag;

  18. import java.util.Set;

  19. import org.apache.commons.collections4.Bag;
  20. import org.apache.commons.collections4.Predicate;
  21. import org.apache.commons.collections4.collection.PredicatedCollection;

  22. /**
  23.  * Decorates another {@link Bag} to validate that additions
  24.  * match a specified predicate.
  25.  * <p>
  26.  * This bag exists to provide validation for the decorated bag.
  27.  * It is normally created to decorate an empty bag.
  28.  * If an object cannot be added to the bag, an {@link IllegalArgumentException} is thrown.
  29.  * </p>
  30.  * <p>
  31.  * One usage would be to ensure that no null entries are added to the bag.
  32.  * </p>
  33.  * <pre>
  34.  * Bag bag = PredicatedBag.predicatedBag(new HashBag(), NotNullPredicate.INSTANCE);
  35.  * </pre>
  36.  * <p>
  37.  * This class is Serializable from Commons Collections 3.1.
  38.  * </p>
  39.  *
  40.  * @param <E> the type of elements in this bag
  41.  * @since 3.0
  42.  */
  43. public class PredicatedBag<E> extends PredicatedCollection<E> implements Bag<E> {

  44.     /** Serialization version */
  45.     private static final long serialVersionUID = -2575833140344736876L;

  46.     /**
  47.      * Factory method to create a predicated (validating) bag.
  48.      * <p>
  49.      * If there are any elements already in the bag being decorated, they
  50.      * are validated.
  51.      *
  52.      * @param <E> the type of the elements in the bag
  53.      * @param bag  the bag to decorate, must not be null
  54.      * @param predicate  the predicate to use for validation, must not be null
  55.      * @return a new predicated Bag
  56.      * @throws NullPointerException if bag or predicate is null
  57.      * @throws IllegalArgumentException if the bag contains invalid elements
  58.      * @since 4.0
  59.      */
  60.     public static <E> PredicatedBag<E> predicatedBag(final Bag<E> bag, final Predicate<? super E> predicate) {
  61.         return new PredicatedBag<>(bag, predicate);
  62.     }

  63.     /**
  64.      * Constructor that wraps (not copies).
  65.      * <p>
  66.      * If there are any elements already in the bag being decorated, they
  67.      * are validated.
  68.      *
  69.      * @param bag  the bag to decorate, must not be null
  70.      * @param predicate  the predicate to use for validation, must not be null
  71.      * @throws NullPointerException if bag or predicate is null
  72.      * @throws IllegalArgumentException if the bag contains invalid elements
  73.      */
  74.     protected PredicatedBag(final Bag<E> bag, final Predicate<? super E> predicate) {
  75.         super(bag, predicate);
  76.     }

  77.     @Override
  78.     public boolean add(final E object, final int count) {
  79.         validate(object);
  80.         return decorated().add(object, count);
  81.     }

  82.     /**
  83.      * Gets the decorated bag.
  84.      *
  85.      * @return the decorated bag
  86.      */
  87.     @Override
  88.     protected Bag<E> decorated() {
  89.         return (Bag<E>) super.decorated();
  90.     }

  91.     @Override
  92.     public boolean equals(final Object object) {
  93.         return object == this || decorated().equals(object);
  94.     }

  95.     @Override
  96.     public int getCount(final Object object) {
  97.         return decorated().getCount(object);
  98.     }

  99.     @Override
  100.     public int hashCode() {
  101.         return decorated().hashCode();
  102.     }

  103.     @Override
  104.     public boolean remove(final Object object, final int count) {
  105.         return decorated().remove(object, count);
  106.     }

  107.     @Override
  108.     public Set<E> uniqueSet() {
  109.         return decorated().uniqueSet();
  110.     }

  111. }