PredicatedSortedBag.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.Comparator;

  19. import org.apache.commons.collections4.Predicate;
  20. import org.apache.commons.collections4.SortedBag;

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

  42.     /** Serialization version */
  43.     private static final long serialVersionUID = 3448581314086406616L;

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

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

  75.     @Override
  76.     public Comparator<? super E> comparator() {
  77.         return decorated().comparator();
  78.     }

  79.     /**
  80.      * Gets the decorated sorted bag.
  81.      *
  82.      * @return the decorated bag
  83.      */
  84.     @Override
  85.     protected SortedBag<E> decorated() {
  86.         return (SortedBag<E>) super.decorated();
  87.     }

  88.     @Override
  89.     public E first() {
  90.         return decorated().first();
  91.     }

  92.     @Override
  93.     public E last() {
  94.         return decorated().last();
  95.     }

  96. }