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 * https://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.multiset;
18
19 import java.util.Comparator;
20
21 import org.apache.commons.collections4.Predicate;
22 import org.apache.commons.collections4.SortedMultiSet;
23
24 /**
25 * Decorates another {@link SortedMultiSet} to validate that additions
26 * match a specified predicate.
27 * <p>
28 * This multiset exists to provide validation for the decorated multiset.
29 * It is normally created to decorate an empty multiset.
30 * If an object cannot be added to the multiset, an {@link IllegalArgumentException}
31 * is thrown.
32 * </p>
33 * <p>
34 * One usage would be to ensure that no null entries are added to the multiset.
35 * </p>
36 * <pre>
37 * SortedMultiSet<E> set =
38 * PredicatedSortedMultiSet.predicatedSortedMultiSet(new TreeMultiSet<E>(),
39 * NotNullPredicate.notNullPredicate());
40 * </pre>
41 *
42 * @param <E> The type held in the multiset
43 * @since 4.6.0
44 */
45 public class PredicatedSortedMultiSet<E> extends PredicatedMultiSet<E> implements SortedMultiSet<E> {
46
47 /** Serialization version */
48 private static final long serialVersionUID = 20260705L;
49
50 /**
51 * Factory method to create a predicated (validating) multiset.
52 * <p>
53 * If there are any elements already in the multiset being decorated, they
54 * are validated.
55 *
56 * @param <E> The type of the elements in the multiset
57 * @param multiset The multiset to decorate, must not be null
58 * @param predicate The predicate to use for validation, must not be null
59 * @return A new predicated SortedMultiSet
60 * @throws NullPointerException if multiset or predicate is null
61 * @throws IllegalArgumentException if the multiset contains invalid elements
62 */
63 public static <E> PredicatedSortedMultiSet<E> predicatedSortedMultiSet(final SortedMultiSet<E> multiset,
64 final Predicate<? super E> predicate) {
65 return new PredicatedSortedMultiSet<>(multiset, predicate);
66 }
67
68 /**
69 * Constructor that wraps (not copies).
70 * <p>
71 * If there are any elements already in the multiset being decorated, they
72 * are validated.
73 * </p>
74 *
75 * @param multiset The multiset to decorate, must not be null
76 * @param predicate The predicate to use for validation, must not be null
77 * @throws NullPointerException if multiset or predicate is null
78 * @throws IllegalArgumentException if the multiset contains invalid elements
79 */
80 protected PredicatedSortedMultiSet(final SortedMultiSet<E> multiset, final Predicate<? super E> predicate) {
81 super(multiset, predicate);
82 }
83
84 @Override
85 public Comparator<? super E> comparator() {
86 return decorated().comparator();
87 }
88
89 /**
90 * Gets the decorated sorted multiset.
91 *
92 * @return The decorated multiset
93 */
94 @Override
95 protected SortedMultiSet<E> decorated() {
96 return (SortedMultiSet<E>) super.decorated();
97 }
98
99 @Override
100 public E first() {
101 return decorated().first();
102 }
103
104 @Override
105 public E last() {
106 return decorated().last();
107 }
108
109 }